Textfields

The --textfield option let you specify an area where the user can enter in some text before dismissing the dialog

It takes a parameter as text and uses that parameter as the textfield label both in the dialog UI and in reporting output

The results are sent to stdout when dialog exits in the following format:

<textfield text> : <user input>

or if using the --json option to enable json output:

{
"<textfield text>" : "<user input>"
}

Examples

If using the following dialog:

dialog --textfield "Textfield 1"

Will display the following dialog:

The user enters in a response:

which will result in the following output:

Textfield 1 : This is what the user entered

or when using --json

{
"Textfield 1" : "This is what the user entered"
}

Additional Textfields

Multiple textfields can be specified by adding additional --textfield options when calling dialog

e.g. dialog --textfield "Textfield 1" --textfield "Textfield 2"

You can specify as many textfialds as you need. Each textfield will output as a seperate field in the output.

You may need to adjust the --height of your dialog window if you are adding multiple textfirlds so they fit

Example:

dialog --textfield "First Name" --textfield "Surname" --textfield "Age" --textfield "Favourite Colour"

results in the following output:

First Name : Joe
Surname : Bloggs
Age : 32
Favourite Colour : Red

--json

{
"First Name" : "Joe",
"Surname" : "Bloggs",
"Age" : "32",
"Favourite Colour" : "Red"
}

Textfields Properties

Textfields can have one or more of the following properties:

• name
• secure
• required
• prompt (only available in macOS 12+)
• regex
• regexerror
• editor
• fileselect
• filetype
• confirm

Name

name=<text> will use the name value in output as the key instead of the title.

Secure

secure creates a field that hides the input as it is being typed. A lock icon indicates a field has this property.

as a note of caution, if using a secure field to accept passwords, be aware that the entered string will still appear in cleartext when returned to stdout

Required

required creates a field that must be filled in before swiftDialog will exit. If a field is not filled, a highlight will appear indicating which field(s) require input. The title will be appended with an * character and the text Required fields will appear as a subtext to the list of text fields.

Prompt

prompt="<prompt_text> will inset some prompt text into the textfield. This text is not returned to stdout and disappears once you start typing in the text field area

** Prompt text is macOS 12 only and is not supported on secure fields.

Value

value="<default text>" will pre-populate the textfield with the specified value.

This differs from prompt in that the text can be edited

--textfield "Default Value Test",value="Some default value"

Regex and Regex Error

regex=<regular_expression> will require that the textfeld match the expression.

regexerror=<text> is the error message that will be presented if the text entered does not meet the regular expression requirements

Example:

--textfield "Regex Test",prompt="Enter 5 digit product code",regex="\d{5}",regexerror="Code must be a five digit number"

NOTE: Unless the regex allows it, using regex implies that the field cannot be empty and the error prompt will be displayed if and entry is not made.

Editor

editor will present a text field that is larger and can accept multiple lines of text if detailed responses are required.

--textfield "Editor Demo:,editor"

Fileselect and Filetype

fileselect will add a "Select" button to the textfield to allow selection of a file using the standard file selection sheet. The path of the selected file will be placed into the contents of the textfield. No other action is taken on the file.

Optionally filetype=<file_extension> can limit the selection to only allowable filetypes. e.g. filetype=png would only allow files with the .png extension to be selected in the file selection sheet.

Multiple filetypes can be specified as space separated list, e.g. filetype="jpeg jpg png"

--textfield "Select a file,fileselect"

filetype=folder will allow selection of a folder

Confirm

confirm will add a secondary textfield whose contents need to match the primary one for validation to succeed.

This can be combined with one or more other modifiers like secure, required and regex

Use

The added properties are optional and can be invoked on the command line by separating the properties with a comma (no spaces). For example:

--textfield <field_label>,secure,required,prompt="<promt_text>"

or in json with:

{
  "textfield" : [
    {"title" : "<field_label>", "secure" : true, "required" : true, "prompt" : "<prompt_text>" },
    {"title" : "<field_label>", "editor" : true },
    {"title" : "<field_label>", "fileselect" : true, "filetype" : "<file_extension>" }
  ]
}