troi.com – Dial_ListDialog (function reference)

Troi Dialog Plug-in > Functions reference > Dial_ListDialog

Dial_ListDialog

Displays a list dialog box, from which the user can choose an item.

Syntax

Dial_ListDialog ( switches ; prompt ; button1 ; button2; button3 ; button4 ;
                  listitems )

Parameters

switches	this determines the behavior of the dialog and which information is returned
prompt	the text of the dialog
button1..4	the text of the 1st to the 4th button (from right to left)
listitems	the list of items (separated by a "\|" char) which the user can choose from

Switches

If you specify an empty button text, no button will be displayed.

Switches can be empty or you can add one or more of these switches:

-ReturnButtonText	return the text of the button, instead of the number
-ReturnListText	return the text of the listitem selected, instead of the index in the list
-AllowMultipleSelection	allows the user to select multiple items from the list. Selected items are returned separated by the pipe character
-ExtraLineHeight=x	specify extra height (in pixels) for each item in the list

You can also add one of these switches:

-DefaultButton1	this indicates button 1 will be selected when the user presses the ENTER key on the Numeric Keypad
-DefaultButton2	this indicates button 2 will be selected when the user presses the ENTER key on the Numeric Keypad
-DefaultButton3	this indicates button 3 will be selected when the user presses the ENTER key on the Numeric Keypad
-DefaultButton4	this indicates button 4 will be selected when the user presses the ENTER key on the Numeric Keypad

You can also add one or more of these switches:

-Button1NeedsSelection	if you add this switch button 1 is disabled until the user selects an item
-Button2NeedsSelection	if you add this switch button 2 is disabled until the user selects an item
-Button3NeedsSelection	if you add this switch button 3 is disabled until the user selects an item
-Button4NeedsSelection	if you add this switch button 4 is disabled until the user selects an item

You can also add one of these switches:

-StopIcon	shows a stop icon (indicating this is something severe which the user needs to address )
-CautionIcon	shows a caution icon (indicating this dialog warns the user)
-NoteIcon	shows a note icon (indicating this dialog gives the user information)
-CustomIcon	shows a custom icon. This icon needs to be set before with the Dial_IconControl function

You can also add this switch:

-IconSize=48

display the icon at 48×48 pixels

-Width=x	makes the size of the dialog x pixels wide
-Height=y	makes the size of the dialog y pixels high

You can also add this switch:

-StopOnESC

if you add this switch the user can press the ESC key to leave the dialog. The dialog returns as button number 0

Returned Result

Data type returned

Text

Result

The number of the button that was clicked followed by the index in the list of the item that was selected. By adding switches this function can also return the text of the button and/or the item selected.

Originated in

Troi Dialog Plug-in 2.0

Compatibility

FileMaker Pro 16 to 19

Considerations

See Dial_SetDialogTitle if you want to change the title of the dialog.
See Dial_SetListInput if you want to preselect an item from the list.

You can type the first letter of the item you want to select.

New in v6.0: you can add the switch: -AllowMultipleSelection which allows the user to select multiple items from the list. Use the Command key on macOS or the Control + Alt key on Windows to select or deselect extra items. Or use Command-A (on macOS) or Control-A (on Windows) to select all items.

You can also preselect multiple items with Dial_SetListInput. Separate them with a pipe character, for example “fire|water”.

Example

Set Field [ result ; Dial_ListDialog ( "-NoteIcon" ; "Please select a fruit:" ; "OK" ; 
				"Cancel" ; "Help" ; "Stop" ;  "Apple|Pear|Lemon" ) ]

This will show a list of 3 items to choose from, with a note icon. If the user chooses the first item and presses the OK button “1|1” will be returned.

Example 2

We assume that in your FileMaker file the following fields are defined:

gFlavors		Global, text
result     		Global, text

gFlavors should contain a list of items to choose from with each item separated by a “|”. Add the following script steps:

Set Field [ result ; Dial_ListDialog ( "-CustomIcon -returnListText 
				-Button1NeedsSelection" ; "Please select a fruit:" ; 
				"OK" ; "Cancel" ; "" ; "" ; gFlavors ) ]

This will show the list of items to choose from. The dialog uses a custom icon. This icon needs to be set before with the Dial_IconControl function. The OK button can only be pressed after the user selected an item.