EntryForm

Create custom data entry forms in AutoHotkey

Requires AutoHotkey v1.1+ or v2.0-a053+

License: WTFPL

---

Syntax:

output := EntryForm( form, fields* )

Return Value:

out := {
    "event":  [ OK, Cancel, Close, Escape, Timeout ], // [string] either of these
    "output": [ field1, field2, ... ] // array containing the output of each input field
}

Remarks:

• If the EntryForm has only one(1) field, .output will contain a string, the value itself

Parameters:

Parameter	Description
form [in]	string or associative array_(untested)_ specifying the EntryForm window's options
fields* [in, variadic]	string or associative array_(untested)_ specifying each field's options

Form [in]:

form [-cap | -c <caption>] [-fnt | -f <fontspec>] [-ico | -i <iconspec>] [-t <period>]
     [-F <callback>] [-pos | -p <position>] [-opt | -o <options>]

A space-delimited string containing one or more of the following below. Options are passed in command line-like syntax. Note: if an argument contains a space, it must be enclosed in single quotes. Multiple arguments are separated by a comma:

Option <Argument(s)> alternative syntax	Description
-cap OR -c <caption>	window caption / title
-fnt OR -f <options,name>	window font, argument(s) is the same as in Gui, Font. e.g.: -fnt 's10 cBlue,Segoe UI'
-ico OR -i <icon,icon-no>	window icon, icon can be a file, exe or dll e.g.: -ico 'shell32.dll,25'
-t <period> Tperiod	similar to Timeout parameter of InputBox except period is in milliseconds instead of seconds. e.g.: -t 5000 or t5000
-F <callback> Fcallback	callback function. Output is passed as 1st parameter. -F is case sensitive when using dash - syntax. If a timeout period is defined (using -t option), this option is ignored. e.g.: -F Callback_Function or fCallback_Function
-pos OR -p <Xn Yn Wn> [ Xn Yn Wn ]	window position, same as in Gui, Show. Default is xCenter yCenter w375
-opt OR -o <options> [ options ... ]	standard Gui options e.g.: +ToolWindow etc.

Remarks:

• Window height must not be specified, it is calculated automatically based on the total number of input fields
• For -ico, the same icon will be used for the window caption (small) and the Alt+Tab switcher (large)
• If a callback function is defined (via -F option), the function will return immediately instead of waiting for the window to close. Function must require atleast one(1) parameter. However, if a -t (timeout) is defined, callback function is ignored

Example Usage:

/* If window position is not specified, it is shown in the center
 * The '-fnt' option applies to fields(controls) whose '-fnt' option is not specified
 */
form := "-c 'Test Form' -ico 'cmd.exe,0' -fnt 's10 cBlue,Consolas' T5000 w500 +ToolWindow"
/* Optional syntax for timeout, pos and options
 * form := "-t 5000 -pos 'x0 w500' -o '+ToolWindow -Caption'"
 */
output := EntryForm(form, ...)

Fields [in, variadic]:

field (-p <prompt>) [-d <default>] [-fnt <fontspec>] [-in <input_ctrl>] [-cb <cuebanner>]
      [-tt <tooltip>] [-ud <updown>] [-fs <fileselect>] [-ds <dirselect>] [-opt | -o <options>]

A space-delimited string containing one or more of the following below. Options are passed in command line-like syntax. Note: if an argument contains a space, it must be enclosed in single quotes. Multiple arguments are separated by a comma:

-Option <Argument(s)> alternative syntax	Description
-p <prompt>	Required, similar to Prompt parameter of InputBox.
-d <default-text>	similar to Default parameter of InputBox. If input field control type is not an Edit (default) control, usage is similar to Text parameter of Gui, Add.
-fnt <p-fontargs;i-fontargs>	a semicolon separates the arguments for the prompt (p-fontargs) and the arguments for the input field (i-fontargs). e.g.: -fnt 's10 cBlue,Segoe UI;s9,Consolas'
-in <input-ctrl> *INPUT_CTRL	input field control type, defaults to Edit(E) control. input-ctrl must be one of the following strings: E (Edit), CB (ComboBox), DDL (DropDownList), DT (DateTime). e.g.: -in DDL or simply *DDL
-cb <cuebanner>	textual cue, or tip, that is displayed by the Edit control
-tt <tooltip>	tooltip for the input field, shown when mouse cursor is over the control
-ud <updown-ctrl-options>	attaches an UpDown control to the input field. updown-ctrl-options are the same as in Gui, Add, UpDown e.g.: -ud 'Range1-100 Wrap'
-fs <fileselectfile-args>	a button is placed to the right of the input field. When pressed, a FileSelectFile dialog is shown. fileselectfile-args is the same as in FileSelectFile command. e.g.: -fs 'M3,C:\Users,Select file,Text (*.txt)'
-ds <fileselectfolder-args>	same as File above, but works like FileSelectFolder e.g.: -ds 'C:\Users,3,Select folder'
-opt OR -o <options> [ options ... ]	standard options that apply to the specified input field control type should work. e.g.: -o 'R1 -Wrap +HScroll' or R1 -Wrap +HScroll

Remarks:

• For -fs and -ds, order of the arguments is the same as in their counterpart AHK commands
• Input field width must not be specified, it is calculated automatically based on the EntryForm window width as specified in form parameter
• For -fs and -ds, if the button's associated Edit control is NOT empty, a SplitPath will be performed on the text(contents), OutDir will be used as the initial directory and OutFileName will be used as the initial file name (latter applies to -fs) when the dialog is shown.
• If input field control type is not an Edit control, the following options are ignored: -cb, -ud, -fs, -ds

Example Usage:

/* For options which require arguments to be enclosed in single quotes, to specify a literal
 * single quote, escape it with a backslash '\'
 */
field1 := "-p 'Enter your password:' -fnt 'Italic,Segoe UI' -cb 'Password here' R1 Password"

/* For '-fs' option, separate each argument with a comma, order of arguments is the same as
 * FileSelectFile command: [ Options, RootDir\Filename, Prompt, Filter ]
 */
field2 := "-p 'File to upload:' -fs '1,C:\Dir,Select a file,Text Document (*.txt; *.tex)'"

out := EntryForm(form, field1, field2)

Screenshot:

Remarks:

• Behavior is similar to that of the InputBox command, that is the script will be in a waiting state while the EntryForm window is shown. To bypass this, the caller can use a timer or define a callback function using the -F option - see Form options above.