Prompt For User Input allows you to design a form that will ask for user input, storing the results in Keyboard Maestro Variables.

You can prompt for variables with text, checkbox, popup menu, or password fields.

This action produces this Display:

The Prompt for User Input form (hereafter called “form”) provides form fields for the following:

The Form Title is plain text, provided to communicate the basic purpose, or the name of the macro, to the user. It may contain any of the Keyboard Maestro Tokens. It is for display only, and cannot be changed by the user when the form is displayed.

The Prompt is plain text, provided to provide instructions or data to the user. It may contain any of the Keyboard Maestro Tokens. It is for display only, and cannot be changed by the user when the form is displayed.

The Form may contain zero or more Variable lines, with each line providing two form fields:

1. Keyboard Maestro Variable Name (for display only)
2. Value of the Variable
   1. May optionally have a default value
   2. Can be edited by the User

Each Variable value may be displayed as any of the following:

• Text (single-line)
• Popup Menu
• Checkbox (value must be either “0” or “1”)
• Password Field
  • If the Variable name starts or ends with “Password” or “PW”, it will be displayed in a password field (typed characters are shown as bullets).

Simply enter a default value with the Popup Choices separated by a bar (|), like this: “Good|Better|Best”

• Then a popup menu will be used.
• The first value in the list of choices will be assigned to the Variable, unless the user chooses a different Popup Choice.
• You can assign a different default value for the Popup, by entering that value as the first choice listed (For example, if you would like “Better” to be the default Popup value, then use “Better|Good|Better|Best”).

To use a Variable for the popup choices, see:

• Dynamic Default List for Prompt for User Input (Example)

If a popup menu item is a dash (-), then a separator is displayed. For example, “Good|Better|Best|-|Terrible”

Sometimes you may want to display a “friendly” value as the default value, but store a different value (like a code) in the actual Variable. You can do this by using a prefix to the default value.

If a popup menu item starts with a prefix followed by two underscores, then the prefix will be used as the variable value, while the latter part will be displayed in the menu.

For example “B__Good|F__Fail|C__OK|B__Good|A__Excellent” would be shown as:

Fail
OK
Good  (selected by default)
Excellent

but would set the variable to A, B, C,or F as appropriate.

• Sometimes you might like to use a Keyboard Maestro Variable to store the list of Popup Choices, and then use this Variable in the Prompt for User Input Action. This can be done simply starting the default value for the Popup with a vertical bar (|).
• If the Popup default value starts with a bar (|), then the Variable (which contains choices separated by |) will be expanded and evaluated before the Prompt is displayed, thus showing the choices from the Variable.

Otherwise, the entry is separated by bar first, and then token expansion is applied to each field, so that fields may contain bars, for example, “This|That|%Variable%One Entry%”.

It is a good idea to have a common prefix in all of the variables used by the same macro. This clearly identifies the macro that uses these variables, and groups them together in the Variables section of the Keyboard Maestro Preferences. But you may not want to expose this prefix to the user running the macro.

So, you can hide the prefix if the variable name starts with a prefix followed by two underscores. Then the label will show only the latter part of the variable name.

For example, if you enter “MyMacro__Text Message” in the variable name field of the Prompt for User Input action:

• It will display a label of “Text Message”:
• But the actual variable name that is set will be just as you entered it: “MyMacro__Text Message”

If the popup menu would contain only “0” and “1”, then a checkbox is used (so for example, “0|1“ or “1|0”, depending on the desired default).

By default, the Prompt for User Input Action comes with two buttons:

1. 
   • Responds to shortcut ⏎ (RETURN)
   • Closes the Prompt
   • Flows proceeds to next Action
2. 
   • Responds to shortcuts of either ⎋ (ESCAPE), or ⌘. (COMMAND-PERIOD)
   • Closes the Prompt
   • Cancels the Macro

You can optionally assign a shortcut key by applying a suffix to the Button Name in the form of /«character», which will cause the Button to respond to a keystroke of ⌘/«character»

The %PromptButton% token (v8+) is set to the name of the button pressed, and can be used in actions later in this instance like any other text token. The deprecated Result Button variable is also set to the name of the button pressed.

• The first button (from the top) has a default key of ⏎ (RETURN), unless you have assigned the RETURN response to another button using “/” at the end of a button name.
• The second button has a default key of either ⎋ (ESCAPE), or ⌘. (COMMAND-PERIOD), unless you have turned off canceling the macro for that button or assigned the ESCAPE response to another button using “/.” at the end of a button name.
• Any button can Cancel the macro if the “Cancel Macro” checkbox is checked for it.
• Other buttons have no default key.
• Whatever button has the RETURN response will be the Default button, and will be highlighted in blue appropriately by the system.
• If you have the system preference “Use keyboard navigation to move focus between controls” enabled, the button shown with a colored outline (usually blue) can be chosen/activated by pressing the SPACE key.

Guidelines for Good Button UI

• The default button should be the “OK” button, the one that performs the normal behaviour.
• The default button should be rightmost.
• The left most button should be “Cancel”.
• Other buttons may vary.
• If the normal behaviour is significantly dangerous, then it may be appropriate for it to not be the default button, or for there to be no default button.

“normal behaviour” here is defined as doing what the user just asked to do.

A consequence of all of this is that if you have a second button in the Prompt For User Input action, and it does not cancel the macro, then you should definitely give it some other key, or disable it with “/-”.

An update is planned so that if the first button has the Cancel Macro flag, then it is not the default (by default), and if the second button does not have the Cancel Macro flag, then it does not get the Escape/Command-, key (by default).

Note that the system will not allow Keyboard Maestro Engine to see keys typed in its own windows so the Typed String triggers will not work within Keyboard Maestro Engine windows.

Note that the system really really wants a “default” button, and if you do not give it one, it will choose one for you.

• Alert action
• Prompt With List action
• Prompt for File action
• Prompt for Screen Rectangle action
• Custom HTML Prompt action
• Show Palette of Macros action
• Get Touch Bar Selection action
• All Actions

• %AlertButton% token
• %PromptButton% token
• %HTMLResult% token
• All Tokens

• Using extra buttons to select next action on Prompt for user input
• Prompt for user input Popup Menu not working with Variables?
• Can a prompt for user input remember user input?
• Spotlight General Purpose Search
• How to Use Dynamic Choices in Prompt for User Input Action?
• Dialog checkbox state remembered between calls?
• Using buttons in Prompt for User Input for things other than OK and Cancel
• Dynamic Default List for Prompt for User Input (Example)
• Default selection in prompt for user input
• Keyboard Maestro Forum topics about Prompt for User Input