Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
		   resources. NULL may be specified, but will result in	a dia-
		   log that cannot be customized through  the  resource	 data-
		   base.

	    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 wid-
		   get,	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 but-
		   ton,	unless an overriding value is found in resource	 data-
		   base. NULL may be specified.
       OUTPUTS

	    buffer_in_out
		   For	XmtAskForItem()	 only, a character buffer owned	by the
		   caller. When	XmtAskForItem()	returns	True, this buffer con-
		   tains 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 meth-
       ods,  then the functions	store the user's input as a string or an inte-
       ger 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 dis-
       played (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().

Xmt				  Motif	Tools		      XmtAskForItem(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmtAskForItem&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help