Dial_ListDialog (function reference)

By November 1, 2020November 10th, 2020Online Help, Troi Dialog Plug-in
Troi Dialog Plug-in for FileMaker Pro

Dial_ListDialog

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

SyntaxFunction badge

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:

-Button1NeedsText if you add this switch button 1 is disabled until the user selects an item
-Button2NeedsText if you add this switch button 2 is disabled until the user selects an item
-Button3NeedsText if you add this switch button 3 is disabled until the user selects an item
-Button4NeedsText 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 15 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.

Related functionsFunction badge

Dial_GetButton
Dial_GetInput
Dial_IconControl
Dial_SetDialogTitle
Dial_SetListInput

Related script stepScript step badge

Show List Dialog

Related topics

Troi Dialog Plug-in online help (overview)


Online Help Page for Troi Dialog Plug-in for 15 to 19 –> Dial_ListDialog (dialp4309) 2020-1110 10:35:37