|w||The shell widget over which the dialog will be displayed, or any descendant of that shell.|
|query_name||The name of this invocation of the dialog; used to look up resources. NULL may be specified, but will result in a dialog that cannot be customized through the resource database.|
|prompt_default||The prompt message to be displayed over the XmText widget of the dialog, unless an overriding value is found in the resource database.|
|list_title_default||The message to be displayed over the XmList widget of the dialog, unless an overriding value is found in the resource database.|
|items_default||An array strings to be displayed in the dialog XmList widget, unless an overriding value is found in the resource database.|
|num_items||The number of elements in the items_default array.|
|must_match||For XmtAskForItem() only, a Boolean that indicates whether the users may type any string, or may only type a string that appears in the list.|
|buffer_in_out||For XmtAskForItem() only, a character buffer owned by the caller. On entry to XmtAskForItem() it contains the default item to be selected in the XmList widget and/or displayed in the XmText widget of the dialog.|
|buffer_len||The length in characters of buffer_in_out.|
|value_in_out||For XmtAskForItemNumber() only, the address of an integer owned by the caller. On entry to XmtAskForItemNumber(), this variable contains the index in the list of the default item to be displayed to the user.|
|help_text_default||The help text to display when the user clicks the Help button, unless an overriding value is found in resource database. NULL may be specified.|
buffer_in_out For XmtAskForItem() only, a character buffer owned by the caller. When XmtAskForItem() returns True, this buffer contains the item selected or the string typed by the user. It is guaranteed to be null-terminated, and to contain no more than buffer_len-1 characters. value_in_out For XmtAskForItemNumber() only, the address of an integer owned by the caller. When XmtAskForItem Number() returns True, this integer contains the index of the item selected by the user.
True if the user clicked the Ok button to dismiss the dialog; False if the user clicked the Cancel button.
XmtAskForItem() and XmtAskForItemNumber() display an application modal dialog similar to that created by XmCreateSelectionDialog(). They process events in a local event loop until the user double clicks on an item, types the Return key, or selects the Ok or Cancel buttons of the dialog, then they return to the calling procedure.
If the user clicks the Cancel button, then these functions immediately return False. If the user selects an item by any of the supported methods, then the functions store the users input as a string or an integer and return True.
XmtAskForItem() returns the item as a string stored in buffer_in_out. If must_match is True and the user types a string that does not appear in the List widget, then XmtAskForItem() will display an error message (with XmtDisplayError()) and will not return.
XmtAskForItemNumber() returns the users input differently. It stores the index of the users selected item at the address specified by value_in_out. If the user types the name of an item that does not appear in the list, the XmtAskForItemNumber() will display an error dialog.
If help text is found in the resource database for this dialog, or if the help_text_default argument is non-NULL, then this text will be displayed (using XmtDisplayInformation()) when the user clicks on the Help button. If there is no help available for the dialog, then the Help button will be insensitive.
To allow customization, XmtAskForItem() and XmtAskForItemNumber() look up the following subpart resources of the toplevel shell. The name of the subpart is given by the query_name argument, and the class of the subpart is XmtItemDialog. These subpart resources are looked up every time the functions are called, not simply when the widgets are created.
Resource Default Description message prompt_default The prompt for the dialog. title Select an Item The string in the dialogs titlebar. listTitle list_title_default The title of the List in the dialog. items items_default The list of items to display. visibleItems 8 How many items should be visible at once. helpText help_text_default Online help for the dialog.
These functions create an XmDialogShell named xmtItemDialogShell and an XmSelectionBox widget named xmtItemDialog as a child of that shell. Once this dialog has been created, it is cached for reuse by subsequent calls.
Chapter 26, Simple Input Dialogs,
XmtAskForBoolean(), XmtAskForDouble(), XmtAskForFile(), XmtAskForFilename(), XmtAskForInteger(), XmtAskForItemNumber(), XmtAskForString().
|Xmt||XMTASKFORITEM (3)||Motif Tools|