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

FreeBSD Manual Pages

  
 
  

home | help
XmtDisplayWorkingDialog(3) Library Functions Manual XmtDisplayWorkingDialog(3)

NAME
       XmtDisplayWorkingDialog(),  XmtHideWorkingDialog()  - display or	hide a
       ``please	wait'' dialog box.

SYNOPSIS
       #include	<Xmt/Dialogs.h>

       Widget XmtDisplayWorkingDialog(Widget w,	String dialog_name, String
		      message_default, String scale_label_default, String but-
		      ton_label_default, int scale_min,	int scale_max, Boolean
		      show_scale, Boolean show_button)

       void XmtHideWorkingDialog(Widget	w)

ARGUMENTS
       INPUTS

	    w	   The shell widget over which the dialog will be popped up or
		   popped down,	or any descendant of that shell.

	    dialog_name
		   The name for	this instantiation of the dialog.   This  name
		   is  used to look up the message and title resources for the
		   dialog. NULL	may be specified, but will result in a	dialog
		   that	cannot be customized through the resource manager.

	    message_default
		   The	default	 message  to be	used if	no dialog_name is pro-
		   vided, or if	no message is found under  that	 name  in  the
		   resource database.

	    scale_label_default
		   The	string to display to the left of the XmScale widget if
		   no overriding value is  found  in  the  resource  database.
		   Specify NULL	for the	default	label.

	    button_label_default
		   The	string to display in the single	XmPushButton widget of
		   the dialog if no overriding value is	found in the  resource
		   database. Specify NULL for the default label.

	    scale_min
		   The minimum value to	be displayed by	the XmScale widget.

	    scale_max
		   The maximum value to	be displayed by	the XmScale widget.

	    show_scale
		   Whether  the	XmScale	widget (and its	associated text	label)
		   should be displayed in the dialog.

	    show_button
		   Whether the XmPushButton widget should be displayed in  the
		   dialog.

       RETURNS

	    A  pointer	to the XmtWorkingBox widget which was popped up	by the
	    function.

DESCRIPTION
       The XmtWorkingBox widget	is designed to display ``Busy;	please	wait''
       dialog	 boxes	  to	the    user.   XmtDisplayWorkingDialog()   and
       XmtHideWorkingDialog() provide  a  simplified  interface	 for  handling
       these  dialogs-they automatically create	the required dialog widget and
       cache it	for subsequent reuse.

       XmtDisplayWorkingDialog() displays a modal  XmtWorkingBox  dialog  con-
       taining	a message and a	``working'' icon. The dialog is	intended to be
       posted while the	application is performing  some	 time  consuming  task
       during which it will not	be responding to user input events. It option-
       ally (depending on show_scale) contains an XmScale widget which can  be
       used  to	 provide  feedback  to the user	about the progress of whatever
       task is underway. A label, ``% Complete:'' by default, appears  to  the
       left  of	 the  XmScale  widget.	The minimum and	maximum	bounds for the
       XmScale slider are specified by scale_min and  scale_max.  The  working
       dialog  also contains an	optional (depending on show_button) XmPushBut-
       ton widget which	can be periodically polled to see if the user wants to
       abort the task. The default label for the button	is Stop.

       XmtDisplayWorkingDialog()  returns the XmtWorkingBox widget of the dia-
       log. This  value	 can  be  used	in  subsequent	calls  to  XmtWorking-
       BoxSetScaleValue()   and	  XmtWorkingBoxHandleEvents()  to  update  the
       XmScale slider value and	to poll	the XmPush Button widget of  the  dia-
       log.

       XmtDisplayWorkingDialog()  calls	 XmtWaitUntilMapped() before returning
       to ensure that the dialog box is	visible	to the user  before  returning
       to  the calling function	which will generally perform some time consum-
       ing task	without	handling events.

       XmtHideWorkingDialog() pops down	 any  XmtWorkingBox  dialog  that  was
       posted over the shell of	w by XmtDisplayWorkingDialog().	Note that w is
       the same	widget	passed	to  XmtDisplayWorkingDialog()  (or  any	 other
       descendant of the shell); not the widget	returned by XmtDisplayWorking-
       Dialog().

       WIDGETS

       XmtDisplayWorkingDialog() creates a  single  XmtWorkingBox  dialog  for
       each screen it is called	on, and	caches that dialog for reuse by	subse-
       quent calls to the function. The	name of	the  XmtWorkingBox  is	``xmt-
       WorkingDialog'',	and the	name of	its XmDialogShell parent is ``xmtWork-
       ingDialogShell''. If you	set resources  on  these  widgets  note	 that,
       because	of  the	dialog caching,	they will affect all instantiations of
       the working dialog.

       Customization

       You can also customize individual instantiations	of working dialogs  by
       specifying  the	dialog_name argument to	XmtDisplayWorkingDialog(). The
       resources are looked up as a subpart of the shell widget	of w. The name
       of the subpart is given by dialog_name, and the class of	the subpart is
       ``XmtWorkingDialog''. The table lists the resources that	are looked up,
       their default values, and how they are used.

       +------------+--------------------------------------+---------------------+
       |Name	    | Default				   | Purpose		 |
       +------------+--------------------------------------+---------------------+
       |message	    | message_default			   | the  message  to be |
       |	    |					   | displayed.		 |
       +------------+--------------------------------------+---------------------+
       |scaleLabel  | scale_label_default or "%	Complete:" | the label	for  the |
       |	    |					   | scale widget.	 |
       +------------+--------------------------------------+---------------------+
       |buttonLabel | button_label_default or "Stop"	   | the button	label.	 |
       +------------+--------------------------------------+---------------------+
       |title	    | "Working"				   | text for the dialog |
       |	    |					   | titlebar.		 |
       +------------+--------------------------------------+---------------------+
SEE ALSO
       Chapter 31, Busy	States and Background Work, XmtWorkingBox,
       XmtWaitUntilMapped(), XmtWorkingBoxHandleEvents(),
       XmtWorkingBoxSetScaleValue().

Xmt				  Motif	Tools	    XmtDisplayWorkingDialog(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=XmtDisplayWorkingDialog&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help