Browse the docs

Ask for input

Asks you for text, a choice from a list, or several fields in a form, and stores the answer.

Ask text

Keyboard Maestro: PromptForUserInput, PromptWithList, Alert

Details #

Opens a keyboard-first panel and waits. It takes the keyboard when it appears and gives it back to the app you were in when it closes. kind picks the shape:

  • text: one text field. The answer is a string. secure: true hides what is typed.

  • list: pick one item from items. Typing filters the list (every word must match), ↑ and ↓ move, Return picks, double-click picks. The answer is the chosen string.

  • form: several named fields, plus buttons from items. The answer is an object with one key per field.

  • pickRegion: no window; the screen dims and the pointer becomes a crosshair. Drag a box over what you want (a live size shows beside it), hold Space while dragging to move the box, click without dragging (or press Return) to pick the window under the pointer, ⎋ to cancel the run. The answer is a record {x, y, w, h, display, option, shift, window} in screen points from the top left, which Read text on screen takes as its region. option and shift say whether ⌥ or ⇧ was held when you let go. message is the one-line hint at the top of the screen. mode: point takes a click instead of a box.

Return presses the default (first) button, Escape cancels, and ⌘1 to ⌘9 press the first nine buttons.

The answer is the step's output. If into is set, it also goes into that variable. For a form, every field also becomes a variable of its own name, so {{email}} works right away. promptButton holds the title of the button pressed, whichever one it was.

A form field's type picks its control: text (the default), multiline (Return adds a line, ⌘Return answers), secure, menu (choose from its options), checkbox (the value is true or false), file or folder (a Choose button opens the file panel; the value is the path).

Parameters #

ParameterTypeRequiredValuesWhat it does
kindone ofYestext list form custom panel pickRegiontext, list, form, panel or pickRegion. panel is the Show a panel step spelled as a prompt, for extensions and old macros. custom is in the list but fails and points to panel.
aiyes / notrue adds the AI badge: a model wrote the question.
bodyrecord
buttonslist of text
defaulttextThe starting text for text, or the preselected item for list.
fieldslist of recordFor form: a list of {"name", "label", "default", "type", "options", "placeholder"} objects. name is required and becomes the key and the variable name. label defaults to the name. type is text, multiline, secure, menu, checkbox, file or folder. A menu needs options; its default is the first option.
idtext
intotextThe variable that receives the answer.
itemsany valueThe choices (for list) or the buttons (for form). Give an array, or one string with one choice per line, such as "{{lines}}". Blank lines are skipped. options is accepted as a synonym.
itemsFiletextA file with one choice per line, added to items. A leading ~ is expanded. Files over 2 MB are refused.
keepOpenyes / no
messagetextThe line of explanation above the field. text works as a synonym.
modeone ofregion pointFor pickRegion: region (drag a box, the default) or point (click).
optionslist of text
positionone ofcenter cursor top
secureyes / noFor text: hide what is typed.
texttext
titletextThe window title. Defaults to the macro's name.
waityes / no
widthnumber

Every step also accepts label, onFailure, timeout and dryRunSafe.

Examples #

Example
Do
  1. Ask for text
  2. Show “Hello, {{name}}”
Open in Switchboard to try it
Pick from a list and a form
Do
  1. Ask to choose from 0 options
  2. Ask for 2 fields
  3. Show “{{project}}: {{task}} by {{due}}”
Open in Switchboard to try it
A form with every kind of field
Do
  1. Ask for 5 fields
  2. Show “{{promptButton}}: {{headline}}”
Open in Switchboard to try it

Gotchas #

  • Every button returns its own title in promptButton; the fields come back the same whichever button was pressed. Cancel (Escape) is the only way out that fails the step.

  • A dry run does not open the dialog. It answers with the step's sample when there is one (a macro test gives it by step id under Samples), else with the defaults: the default text, the default item (or the first item), and each field's default. A form sample missing a field gets that field's default. Set sensible defaults so a dry run reaches the steps after it.

  • Cancelling the dialog fails the step with "cancelled by you", and the macro stops. Set the step's onFailure to continue or branch if cancelling is a normal answer.

  • A list prompt with no items fails. A form field with no name fails.

  • With no into, a text answer is shown in the trace but not kept. A list answer is still kept in promptWithListResult (and its position, counting from 1, in promptWithListIndex). Forms still set one variable per field.

  • It waits for you, so it has no 10 s default limit. The macro's own timeout (60 s unless changed) still ends it.

See also #

Set variable, If, Show message