xtappaddworkproc(3) [hpux man page]

XtAppAddWorkProc()														XtAppAddWorkProc()

XtAppAddWorkProc - register a procedure to be called when the event loop is idle.

Synopsis
  XtWorkProcId XtAppAddWorkProc(app_context, proc, client_data)
	 XtAppContext app_context;
	 XtWorkProc proc;
	 XtPointer client_data;

Inputs
  app_context
	    Specifies the application context.

  proc	    Specifies the procedure that is to be called when the application is idle.

  client_data
	    Specifies data to be passed to proc when it is called.

Returns
  A handle of type XtWorkProcId that can be passed to XtRemoveWorkProc() to unregister the work procedure.

Description
  XtAddWorkProc()  registers  the  procedure proc and the data client_data to be called by XtAppNextEvent() or XtAppProcessEvent() when there
  are no pending input events and it would otherwise block.  Multiple work procedures can be registered, and the most recently added  one  is
  always  the  one  that  is called.  However, if a work procedure itself adds another work procedure, the newly added one has lower priority
  than the current one.

  A work procedure returns a Boolean.  If it returns True, it will automatically be unregistered and will not be called again.	If it returns
  False it will be called the next time the application is idle.  See XtWorkProc(2) for more information.

Usage
  XtAppAddWorkProc() implements a limited form of background processing.  Most applications spend most of their time waiting for input; to do
  useful work during this idle time, you can register a work procedure that will run when the application is idle.

  A work procedure must return quickly or the application will not be able to promptly respond to user events.	If a large task needs  to  be
  done	in  the background, the work procedure should periodically save its state and return False.  Work procedures should not be used to do
  frivolous work in the background.  In a multi-tasking system, an idle application should generally actually be idle, and not steal CPU time
  from other processes.

  A work procedure can be explicitly removed by calling XtRemoveWorkProc() with the XtWorkProcId returned by this function.

Structures
  The XtWorkProcId type is defined as follows:

     typedef unsigned long XtWorkProcId;

See Also
  XtAppNextEvent(1), XtAppProcessEvent(1), XtRemoveWorkProc(1),
  XtWorkProc(2).

Xt - Event Handling														XtAppAddWorkProc()

XtWorkProc()															      XtWorkProc()

Name
  XtWorkProc - interface definition for procedure called when the event loop is idle.

Synopsis
  typedef Boolean (*XtWorkProc)(XtPointer);
	 XtPointer client_data;

Inputs
  client_data
	    Specifies data registered with this procedure.

Returns
  True if the procedure should not be called again; False otherwise.

Description
  An XtWorkProc is registered with XtAppAddWorkProc() and is called by XtAppMainLoop() and XtAppProcessEvent() if there are no events pending
  and the application would otherwise block.

  The client_data argument is data of any type registered in the call to XtAppAddWorkProc().  It is generally cast to an XtPointer when  reg-
  istered  and cast back to the appropriate type within the XtWorkProc.  An XtWorkProc must get all of its context from this argument or from
  global variables.

  An XtWorkProc should perform a single short task and return.	If it does not return quickly then events that arrive  while  it  is  running
  will not be handled immediately, and the response time seen by the user will suffer.	If a work procedure has a lot of processing to do, it
  should perform a piece of it, save its state in static variables, and return False.  When an XtWorkProc returns False, the Intrinsics  will
  call	it again the next time the event loop is idle, and it can resume its processing where it left off.  When it completes all of its pro-
  cessing, it should return True, and the Intrinsics will automatically un-register it, so that it will not be called again.

Usage
  One possible use of work procedures is to create the widgets in dialog boxes which are not needed immediately when  an  application  starts
  up.	This will save start up time for the main application window, and will probably also mean that the dialog boxes will be fully created
  by the time the user requests that one is popped up.

  You can register multiple work procedures, and they will be performed one at a time.	The most recent work procedure added has the  highest
  priority.  Therefore, for example, if you want to create ten popup widgets during idle time, you might add ten work procedures.  The pop up
  that you expect to need first should be created by the last work procedure registered.  See the example below for  an  alternate  approach,
  however.

  You can explicitly remove a work procedure with XtRemoveWorkProc().

Example
  The  first  procedure below is an XtWorkProc that creates several dialog widgets.  Note that it returns after creating each dialog.  If the
  dialogs are needed before they are created by this procedure, they will have to be created explicitly as  shown  in  the  second  procedure
  below.   The	only  standard client in X11R5 that uses work procedures is xfontsel which performs sophisticated scheduling of all the back-
  ground work of parsing the names of all the fonts available from the server.

     Widget file_dialog = NULL;
     Widget print_dialog = NULL;
     Widget confirm_dialog = NULL;

     Boolean CreateDialogsInBackground(client_data)
     XtPointer client_data;
     {
	 Widget toplevel = (Widget) client_data;
	 static int num = 0;

	 num++;

	 switch(num) {
	 case 1:
	     if (file_dialog == NULL)
		 file_dialog = CreateFileDialog(toplevel);
	     return False;
	 case 2:
	     if (print_dialog == NULL)
		 print_dialog = CreatePrintDialog(toplevel);
	     return False;
	 case 3:
	     if (confirm_dialog == NULL)
		confirm_dialog = CreateConfirmDialog(toplevel);
	     return True;
	 }
	 return True;
     }

     void DoFileDialog(toplevel)
     Widget toplevel;
     {
	 if (file_dialog == NULL)
	     file_dialog = CreateFileDialog(toplevel);
	 XtPopup(file_dialog, XtGrabExclusive);
     }

  This work procedure could be registered with a call like the following:

	 toplevel = XtAppInitialize(...);
	 BuildInterface(toplevel);
	 XtRealizeWidget(toplevel);

	 XtAppAddWorkProcedure(app_context, CreateDialogsInBackground,
			       (XtPointer) toplevel);

	 XtAppMainLoop(app_context);

See Also
  XtAppAddWorkProc(1), XtRemoveWorkProc(1).

Xt - Event Handling														      XtWorkProc()