GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  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.

CONTENTS

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 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.
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 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.
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 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.

ResourceDefaultDescription
messageprompt_defaultThe prompt for the dialog.
title”Select an Item“The string in the dialog’s titlebar.
listTitlelist_title_defaultThe title of the List in the dialog.
itemsitems_defaultThe list of items to display.
visibleItems8How many items should be visible at once.
helpTexthelp_text_defaultOnline 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().
Search for    or go to Top of page |  Section 3 |  Main Index


Xmt XMTASKFORITEM (3) Motif Tools

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.