FreeBSD Manual Pages
XmtAskForItem(3) Library Functions Manual XmtAskForItem(3) NAME XmtAskForItem(), XmtAskForItemNumber() - use a dialog box to prompt the user to select an item from a list and return the selected item. SYNOPSIS #include <Xmt/Dialogs.h> Boolean XmtAskForItem(Widget w, String query_name, String prompt_default, String list_title_default, String *items_default, int num_items, Boolean must_match, String buffer_in_out, int buffer_len, String help_text_default) Boolean XmtAskForItemNumber(Widget w, String query_name, String prompt_default, String list_title_default, String *items_default, int num_items, int *value_in_out, String help_text_default) ARGUMENTS INPUTS 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 re- sources. 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 dia- log, unless an overriding value is found in the resource data- base. 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 user's may type any string, or may only type a string that ap- pears 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 dis- played 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. OUTPUTS 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 guar- anteed 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. RETURNS True if the user clicked the Ok button to dismiss the dialog; False if the user clicked the Cancel button. DESCRIPTION XmtAskForItem() and XmtAskForItemNumber() display an application modal dia- log 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 re- turn False. If the user selects an item by any of the supported methods, then the functions store the user's input as a string or an integer and re- turn 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 Xmt- DisplayError()) and will not return. XmtAskForItemNumber() returns the user's input differently. It stores the index of the user's 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 in- sensitive. Customization To allow customization, XmtAskForItem() and XmtAskForItemNumber() look up the following subpart resources of the toplevel shell. The name of the sub- part 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 | | | | dialog's 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. | +--------------+--------------------+----------------------+ WIDGETS 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. SEE ALSO Chapter 26, Simple Input Dialogs, XmtAskForBoolean(), XmtAskForDouble(), XmtAskForFile(), XmtAskForFilename(), XmtAskForInteger(), XmtAskForItemNumber(), XmtAskForString(). Xmt Motif Tools XmtAskForItem(3)
NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtAskForItem&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>