The DLGLISTPROMPT function displays a customizable dialog that prompts the user to select an item from a list of items. Most aspects of the dialog are customizable. You should call dlgListPromptReset and dlgListPromptAddItem before calling this function. Although not essential, these statements reset the contents of the list and add new items to it respectively, so without using these functions the DLGLISTPROMPT function is somewhat pointless.

The syntax of this function is almost identical to dlgTextPrompt, however this function does not have a default value parameter.

 

Parameters

Title

The title of the dialog.

Frame

The text to use as the frame title inside the dialog. Providing a zero length string for this parameter hides the frame.

Prompt

The text string to display above the list box. This should be used for an explanatory prompt of what the user should select.

XPos

The X pixel position on-screen to show the dialog at. Specify -1 to show the dialog in its default position.

YPos

The Y pixel position on-screen to show the dialog at. Specify -1 to show the dialog in its default position.

ShowCancel

True if the "Cancel" button should be shown, False to only show the "OK" button.

 

Return Value

True if the user closes the dialog using the OK button, otherwise False.

Example Code

// Reset the list before use
dlgListPromptReset();

// Add some items for selection
dlgListPromptAddItem("list item 1");
dlgListPromptAddItem("list item 2");

// Open the prompt dialog with the specified options
if(dlgTextPrompt("The Title", "The Frame", Select an item ",
                 -1, -1, True) == True)
{
    // Retrieve the text of the selected item
    string SelText = dlgListPromptGetSelString();
}