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:
Field | Type | Purpose/Use |
---|---|---|
Form Title | Display Only | Identify the Main Purpose of the Form |
Prompt | Display only | Optionally provide instructions and/or display Variables |
Keyboard Maestro Variables | Display/Edit | Optionally Allow User Input to Enter, Change, or Accept default value • Variables may be displayed as “Text (Single Line)”, “Popup Menu”, or Checkbox • “Text Area” and “Radio Buttons” are not supported |
Buttons | Standard Mac | Allow User to accept, cancel, or provide other responses you may define |
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:
Each Variable value may be displayed as any of the following:
Simply enter a default value with the Popup Choices separated by a bar (|), like this: “Good|Better|Best
”
Better|Good|Better|Best
”).To use a Variable for the popup choices, see:
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.
|
).|
) 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:
Text Message
”: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:
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»
Suffix | Button Responds to Shortcut Key of: |
---|---|
/. | ⎋ (ESCAPE) key. |
/ | ⏎ (RETURN) key. |
/H | ⌘H keystroke (as an example). (The ⌘ key is not needed IF there are not any text fields in the Prompt User dialog) |
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.
Guidelines for Good Button UI
“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.