Differences

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

--- action:Prompt_for_User_Input [2017/09/26 01:16]
peternlewis
+++ action:Prompt_for_User_Input [2021/10/14 02:57]
peternlewis
@@ Line 1: / Line 1: @@
-{{:action:form-icon.png?nolink |}}
+====== Prompt For User Input Action ======
-====== Prompt For User Input ======
 _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]].
-===== Example =====
+You can prompt for variables with text, checkbox, popup menu, or password fields.
-**This Setup of the Prompt for User Action . . .**
+{{ promptaction.png?nolink&600 | Prompt For User InputAction }}
-{{:action:promptaction.png|}}
+This action produces this Display:
-**Produces this Display***
+{{ promptwindow.png?nolink&583 | Prompt For User Input Window }}
-{{:action:promptwindow.png|}}
 ===== Form Fields =====
@@ Line 21: / Line 18: @@
 |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|
+|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 ====
@@ Line 39: / Line 36: @@
 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_
+  - A 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 ====
-==== Popup Field ====
+The field will be displayed as a single line text input field.
+==== Password Field ====
-Simply enter a default value with the Popup Choices separated by a bar (|), like this: “`Good|Better|Best`”
+The field will be displayed as a single line password input field, displayed with bullets instead of characters.
-* Then a popup menu will be used.
+==== Checkbox ====
-* 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`”).
-=== Using a Variable for Popup Choices ===
+The field will be displayed as a checkbox. If the default value is “0”, or starts with “0|”, then the checkbox will default to off. If the default value is “1”, or starts with “1|”, the checkbox will default to on.
+==== Menu Field ====
+The field will be displayed as a popup menu.
+The default value defines the choices,  separated by a bar “|”, like: “Good|Better|Best”.
+The first value in the list of choices will be selected in the menu by default. For example, if you would like "Better" to be the default Popup value, then use “Better|Good|Better|Best”.
+If the menu item is a dash “-”, a menu separator will be used in its place. For example, “Good|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”.
+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 field, so that fields may contain bars, for example, “This|That|%Variable%One Entry%”.
+==== Slider Field ====
+The field will be displayed as a slider.
+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:
+. initial value of 50, range 0-100.
+. initial value as specified, range 0-100.
+. range as specified, initial value half way between.
+. minimum, initial, maximum value as specified.
+. minimum, initial, maximum value as specified, and if the last value is greater than zero, the gap between allowed values, and if it is less than zero, the number of allowed values.
+For example, “0,50,100,10” means a range from 0 to 100, initial value of 50, and only valid values of 0, 10, 20, 30, … 90, 100.
+The result stored in the variable will be the value of the slider.
+==== Color Field ====
+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 0 to 255.
+==== Date and Time Fields ====
+The field will be displayed as a 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.
-To use a Variable for the popup choices, see:
-  * [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 a Dash ("`-`") to Separate Choices ===
-If a popup menu item is a dash (-), then a separator is displayed. For example, “%%Good|Better|Best|-|Terrible%%”
-=== How to Store a Different Value than Displayed ===
-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.
 === How to Use a Variable for the Popup Choices ===
@@ Line 134: / Line 163: @@
 The [[token:PromptButton|%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.
-Note that the system will not allow Keyboard Maestro Engine to see keys typed in its own windows so the [[trigger:Typed String | Typed String triggers]] will not work within Keyboard Maestro Engine windows.
 === 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.
-* 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.
 * 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**
@@ Line 159: / Line 186: @@
 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 =====
+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.
@@ Line 169: / Line 200: @@
 * [[action:Prompt_With_List|Prompt With List]] 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:Show_Palette_of_Macros|Show Palette of Macros]] action

Keyboard Maestro Wiki

User Tools

Site Tools

Differences

Page Tools