User Tools

Site Tools


action:Prompt_for_User_Input

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
action:Prompt_for_User_Input [2019/06/30 22:04]
peternlewis
action:Prompt_for_User_Input [2023/09/13 00:04] (current)
peternlewis [Slider Field]
Line 1: Line 1:
-====== Prompt For User Input ======+====== Prompt For User Input Action ​======
  
 _Prompt For User Input_ allows you to design a form that will ask for user input, storing the results in [[manual:​Variables|Keyboard Maestro Variables]]. _Prompt For User Input_ allows you to design a form that will ask for user input, storing the results in [[manual:​Variables|Keyboard Maestro Variables]].
Line 5: Line 5:
 You can prompt for variables with text, checkbox, popup menu, or password fields. You can prompt for variables with text, checkbox, popup menu, or password fields.
  
-{{ promptaction.png?​nolink&​575x402 ​| Prompt ​Action ​}}+{{ promptaction.png?​nolink&​600 | Prompt ​For User InputAction ​}}
  
-===== Example =====+This action produces this Display:
  
-This action: +{{ promptwindow.png?​nolink&​583 | Prompt For User Input Window }}
- +
-{{ promptfullaction.png?​nolink&​575x612 | Prompt Example Action }} +
- +
-Produces this Display: +
- +
-{{ promptwindow.png?​nolink&​585x505 ​| Prompt For User Input Window }}+
  
 ===== Form Fields ===== ===== Form Fields =====
Line 24: Line 18:
 |Form Title|Display Only|Identify the Main Purpose of the Form| |Form Title|Display Only|Identify the Main Purpose of the Form|
 |Prompt|Display only|Optionally provide instructions and/or display Variables| |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+|Keyboard Maestro Variables|Display/​Edit|Optionally ​allow you to input variable values. ​Variables may be displayed as *Text(Single Line, or Password), *Popup Menu*, or *Checkbox*, *Slider* (v10.0+), *Color* (v10.0+), Date or Time or Date&​Time (v10.0+)
-|Buttons|Standard Mac|Allow ​User to accept, cancel, or provide other responses you may define|+|Buttons|Standard Mac|Allow ​you to accept, cancel, or provide other responses you may define|
  
 ==== Form Title ==== ==== Form Title ====
Line 42: Line 36:
  
 The Form may contain zero or more _Variable_ lines, with each line providing two form fields: The Form may contain zero or more _Variable_ lines, with each line providing two form fields:
-  - [[manual:​Variables|Keyboard Maestro Variable]] Name (for display only) +  - [[manual:​Variables|Keyboard Maestro Variable]] Name 
-  - Value of the _Variable_  +  - default value for the _Variable_, which also implies the type of entry.
-      - May optionally have a default value +
-      - Can be edited by the User+
  
-Each _Variable_ ​value may be displayed as any of the following+Using the menu selection to the right of the default ​value (v10.0+), you can specify the type of the field: 
-  * Text (single-line) +  * Automatic 
-  * Popup Menu +  * Text 
-  * Checkbox ​(value must be either "​0"​ or "​1"​) +  * Password 
-  * Password Field +  * Checkbox 
-      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).+  * Menu 
 +  Slider 
 +  * Color 
 +  * Date 
 +  * Date and Time 
 +  * Time 
 +  * Time with Seconds 
 + 
 +==== Automatic ==== 
 + 
 +Automatic type will guess the type based on the value of the default field - if it contains “|” bar separated fields, then it will be a menu, or a checkbox if all the values are 0 or 1, and if the variable is a Password variable (starts or ends with “Password” or “PW”)then a password field will be used.
  
 ==== Text Field ==== ==== Text Field ====
  
-==== Popup Field ====+The field will be displayed as a single line text input field.
  
 +The default field is a token text field.
  
-Simply enter a default value with the Popup Choices separated by a bar (|), like this: “`Good|Better|Best`”+==== Password Field ====
  
-* Then a popup menu will be used. +The field will be displayed as single line password input fielddisplayed with bullets instead of characters.
-The first value in the list of choices ​will be assigned to the Variable, unless the user chooses ​different Popup Choice. +
-* You can assign a different default value for the Popupby 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`”).+
  
-=== Using Variable for Popup Choices ===+The default field is token text field.
  
 +==== Checkbox ====
  
-To use Variable for the popup choicessee: +The field will be displayed as checkbox. If the default value is “0”or starts with “0|”, then the checkbox will default to offIf the default ​value is “1”, or starts with “1|”, the checkbox will default to on.
-  * [Dynamic Default List for Prompt for User Input (Example)](https://​forum.keyboardmaestro.com/​t/​dynamic-default-list-for-prompt-for-user-input-example/​4441/​1)+
  
-=== Using Dash ("​`-`"​) to Separate Choices ===+The default field is token text field.
  
-If a popup menu item is a dash (-), then a separator is displayed. For example, “%%Good|Better|Best|-|Terrible%%”+==== Menu Field ====
  
-=== How to Store Different Value than Displayed ===+The field will be displayed as popup menu.
  
-Sometimes you may want to display a "​friendly" ​value as the default valuebut store a different value (like a code) in the actual Variable. ​ You can do this by using prefix to the default value.+The default ​value defines ​the choices,  ​separated ​by a bar “|”, like: “Good|Better|Best”.
  
-If a popup menu item starts with a prefix followed ​by two underscoresthen the prefix will be used as the variable ​value, ​while the latter part will be displayed in the menu.+The first value in the list of choices will be selected in the menu by default. For exampleif you would like "​Better"​ to be the default Popup value, ​then use “Better|Good|Better|Best”.
  
-For example “%%B__Good|F__Fail|C__OK|B__Good|A__Excellent%%” would be shown as:+If the menu item is a dash “-”, a menu separator will be used in its place. ​For exampleGood|Better|Best|-|Terrible.
  
-``` +If a menu items is separated in to two parts with two underscores (‗), then the first part is used as the result, while the second part is displayed in the menu. For example, “B‗‗Good|F‗‗Fail|C‗‗OK|B‗‗Good|A‗‗Excellent”.
-Fail +
-OK +
-Good  ​(selected by default) +
-Excellent +
-```+
  
-but would set the variable to ABC,or F as appropriate.+The default field is a token text field, so you can include variable options in your list, for example: “%Variable%First Choice%|%Variable%Second Choice%”. If you want to provide a list in a variable, then you do so by starting ​the field with a bar (“|”), followed by your list (or your default value and then your list) in a variable ​(which contains choices separated by `|`), for example “|%Variable%Current Choice%|%Variable%Choice List%”. Without the leading bar, the entry is separated by bar first, and then token expansion is applied ​to each fieldso that fields may contain barsfor example“This|That|%Variable%One Entry%”.
  
-=== How to Use a Variable for the Popup Choices ​===+==== Slider Field ====
  
-* 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 (`|`). +The field will be displayed ​as a slider.
-* 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 fieldso that fields may contain barsfor example“This|That|%Variable%One Entry%”.+The default value defines ​the initial value and range of the slider. It can contain from zero to four comma-separated ​values, which are either: 
 +0. initial value of 50, range 0-100. 
 +1. initial value as specified, range 0-100. 
 +2. range as specified, initial value half way between. 
 +3. minimum, initial, maximum value as specified. 
 +4. minimum, initial, maximum value as specified, and if the last value is greater than zerothe gap between allowed valuesand if it is less than zerothe number of allowed values.
  
-=== How to Hide Variable Prefix in the Prompt ===+For example, “0,​50,​100,​10” means range from 0 to 100, initial value of 50, and only valid values of 0, 10, 20, 30, … 90, 100.
  
-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.+The result stored ​in the variable will be the value of the slider.
  
-**So, you can hide the prefix if the variable name starts with prefix followed by two underscores**. Then the label will show only the latter part of the variable name.+This default value field is calculation field.
  
-For exampleif you enter "​**`MyMacro__Text Message`**"​ in the variable name field of the Prompt for User Input action: +Up to Keyboard Maestro version 10.2, the result ​of the slider ​will always be an integer, and any initial value above 100 will be clipped to 100 ([[https://​forum.keyboardmaestro.com/​t/​slider-keeps-rounding-my-values-down/​32936|forum]]). Neither of these limitations apply in version 11.0+.
-  * 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`**"​+
  
-==== Checkbox ​Field ====+==== Color Field ====
  
-If the popup menu would contain only "0" ​and "​1",​ then checkbox ​is used (so for example, “0|1" ​or "​1|0"​depending on the desired default).+The field will be displayed as a color well. 
 + 
 +The default ​ value defines ​the color with three or four comma-separated values, being the red, green, blue and optional alpha values. All values have a range of to 255. 
 + 
 +This default value field is a calculation field. 
 + 
 +==== Date and Time Fields ==== 
 + 
 +The field will be displayed as date, date & time, time, or time with seconds field. 
 + 
 +The default value is [[/​unixtime|unixtime]] for the date and time. For time-only values, you can use either a unixtime or a time in seconds in the day (so 28,800 would be 8am) - either way the result will be in the same day as the specified default value. 
 + 
 +This default value field is a calculation field. 
 + 
 +==== Labels ==== 
 + 
 +It can be 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. 
 + 
 +Similarly, you can use Instance or Local variables, and the Instance” ​or “Local” will be removed from the variable name when displayed in the form. 
 + 
 +For examplevariables named “MyMacro‗‗Text Message”, “Instance Text Message” or “Local Text Message” will all display ​the label “Text Message” in the form. The actual variable used will be the full variable name.
  
 ==== Buttons ==== ==== Buttons ====
Line 118: Line 138:
   - {{:​action:​km-7.3-ok-button.png?​nolink|}}   - {{:​action:​km-7.3-ok-button.png?​nolink|}}
     * Responds to shortcut <​kbd>​⏎</​kbd>​ (RETURN)     * Responds to shortcut <​kbd>​⏎</​kbd>​ (RETURN)
-    * Closes the Prompt +    * Closes the Prompt. 
-    * Flows proceeds to next Action+    * Flows proceeds to next Action.
   - {{:​action:​km-7.3-cancel-button.png?​nolink|}}   - {{:​action:​km-7.3-cancel-button.png?​nolink|}}
     * Responds to shortcuts of either <​key>​⎋</​key>​ (ESCAPE), or <​key>​⌘</​key><​key>​.</​key>​ (COMMAND-PERIOD)     * Responds to shortcuts of either <​key>​⎋</​key>​ (ESCAPE), or <​key>​⌘</​key><​key>​.</​key>​ (COMMAND-PERIOD)
-    * Closes the Prompt+    * Closes the Prompt ​**without writing the variables**.
     * **Cancels the Macro**     * **Cancels the Macro**
  
-=== Optional Buttons Can be Assigned Shortcut Keys ===+You can add more buttons to allow for other options. For example, “Save” and “Save and Send”.
  
-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 <​key>​⌘</​key><​key>/​«character»</​key>​+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 <​key>​⌘</​key><​key>​«character»<​/key> (or just <key>«character»</​key> ​if there are no focusable text fields).
  
 ^Suffix^Button Responds to Shortcut Key of:^ ^Suffix^Button Responds to Shortcut Key of:^
 |`/​.`|<​key>​⎋</​key>​ (ESCAPE) key.| |`/​.`|<​key>​⎋</​key>​ (ESCAPE) key.|
 |`/​`|<​kbd>​⏎</​kbd>​ (RETURN) key.| |`/​`|<​kbd>​⏎</​kbd>​ (RETURN) key.|
-|`/​H`|<​key>​⌘</​key><​key>​H</​key>​ keystroke (as an example).\\ (The <key></​key> ​key is not needed IF there are not any text fields in the Prompt User dialog)|+|`/​H`|<​key>​⌘</​key><​key>​H</​key>​ keystroke (as an example) (or just <key>H</​key> ​if there are not any text fields in the form)
 +|`/-`|no shortcut|
  
 === Result Button === === Result Button ===
Line 140: Line 161:
 === How Buttons are Processed === === How Buttons are Processed ===
  
-* The first button (from the top) has a default key of <​kbd>​⏎</​kbd>​ (RETURN). +* The first button (from the top) has a default key of <​kbd>​⏎</​kbd>​ (RETURN), _unless_ you have assigned the _RETURN_ response to another button using “/” at the end of a button name, or marked the button to cancel the macro
-* The second button has a default key of either <​key>​⎋</​key>​ (ESCAPE), or <​key>​⌘</​key><​key>​.</​key>​ (COMMAND-PERIOD),​ _unless_ you have assigned the _escape_ ​response to another button using <key>/</​key><​key>​.</​key> ​at the end of the Button Name.+* The second button has a default key of either <​key>​⎋</​key>​ (ESCAPE), or <​key>​⌘</​key><​key>​.</​key>​ (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. * Any button can _Cancel_ the macro if the "​Cancel Macro" checkbox is _checked_ for it.
 * Other buttons have no default key. * Other buttons have no default key.
-* Whatever button has the key <​kbd>​⏎</​kbd> ​will be the "Default" ​button, and will be highlighted in blue appropriately by the system. +* Whatever button has the _RETURN_ response ​will be the Default button, and will be highlighted in blue appropriately by the system. 
-The button shown with a colored outline (usually blue) can be chosen/​activated by pressing the SPACE_BAR ​key.+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**+=== Guidelines for Good Button ​User Experience ===
  
-* The default button should be the "OK" ​button, the one that performs the *normal behaviour*.+* The default button should be the OK” button, the one that performs the *normal behaviour*.
 * The default button should be rightmost. * The default button should be rightmost.
 * The left most button should be "​Cancel"​. * The left most button should be "​Cancel"​.
Line 155: Line 176:
 * 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. * 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.+“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 “/-”. 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). 
  
 ===== Notes ===== ===== Notes =====
  
 Note that the system will not allow Keyboard Maestro Engine to see keys typed in its own windows so the [[trigger:​Typed String]] triggers will not work within Keyboard Maestro Engine windows. Note that the system will not allow Keyboard Maestro Engine to see keys typed in its own windows so the [[trigger:​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. 
  
 ===== See Also ===== ===== See Also =====
Line 174: Line 191:
 * [[action:​Prompt_With_List|Prompt With List]] action * [[action:​Prompt_With_List|Prompt With List]] action
 * [[action:​Prompt_for_File|Prompt for File]] action * [[action:​Prompt_for_File|Prompt for File]] action
 +* [[action:​Prompt_for_Screen_Rectangle|Prompt for Screen Rectangle]] action
 * [[action:​Custom_HTML_Prompt|Custom HTML Prompt]] action * [[action:​Custom_HTML_Prompt|Custom HTML Prompt]] action
 * [[action:​Show_Palette_of_Macros|Show Palette of Macros]] action * [[action:​Show_Palette_of_Macros|Show Palette of Macros]] action
action/Prompt_for_User_Input.1561946663.txt.gz · Last modified: 2019/06/30 22:04 by peternlewis