|
Unix VPS
Support
FAQ
Network
Miscellaneous
|
| XmtAskForItem(3) | FreeBSD 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
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 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 user's 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.
DESCRIPTION
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 user's 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 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 insensitive.
Customization
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 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().
| Motif Tools | Xmt |
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.