*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> Vk/VkApp (3)              
Title
Content
Arch
Section
 

Contents


VkApp(3x)							     VkApp(3x)


NAME    [Toc]    [Back]

     VkApp - Class used	by all ViewKit applications to handle initialization

INHERITS FROM    [Toc]    [Back]

     VkComponent : VkCallbackObject

HEADER FILE    [Toc]    [Back]

     #include <Vk/VkApp.h>

PUBLIC PROTOCOL	SUMMARY
   Constructors
	  VkApp(char	   *appClassName,
		int		 *arg_c,
		char		**arg_v,
		XrmOptionDescRec *optionList	   = NULL,
		int		  sizeOfOptionList = 0 )

	  VkApp(char	   *appClassName,
		int		 *arg_c,
		char		**arg_v,
		ArgList		  argList,
		Cardinal	  argCount,
		void		(*preRealizeFunction)(Widget w),
		XrmOptionDescRec *optionList,
		int		  sizeOfOptionList)


   Version Information    [Toc]    [Back]
	       static const int	ViewKitMajorRelease
	       static const int	ViewKitMinorRelease
	       static const char ViewKitReleaseString[]
	       void   setVersionString(const char *str)
	       const char  *versionString()
	       void setAboutDialog(VkDialogManager *aboutDialog)
	       void setStartupDialog(VkDialogManager *startupDialog)


   Runtime Interaction    [Toc]    [Back]
	      virtual void run()
	      void run(Boolean(*appEventHandler)(XEvent	&))
	      void runOneEvent(Boolean(*appEventHandler)(XEvent	&) = NULL)
	      void run_first()
	      virtual void handlePendingEvents()
	      void handlePendingEvents(Boolean(*appEventHandler)(XEvent	&))
	      XtInputMask handleOnePendingEvent(Boolean(*appEventHandler)(XEvent &) = NULL)
	      virtual void handleRawEvent(XEvent *event)
	      virtual void quitYourself()
	      virtual void terminate(int status	= 0)







									Page 1






VkApp(3x)							     VkApp(3x)



   Operations on Application Windows    [Toc]    [Back]
	      void setMainWindow(VkSimpleWindow	*win)
	      virtual void raise()
	      virtual void lower()
	      virtual void iconify()
	      virtual void open()
	      virtual void show()
	      virtual void hide()
	      void   startupIconified(Boolean flag)


   Application Cursor Control    [Toc]    [Back]
	      virtual Cursor  busyCursor()
	      virtual Cursor  normalCursor()
	      void    setNormalCursor(Cursor c)
	      void    setBusyCursor(Cursor c)
	      void    setBusyCursor(VkCursorList *cl)
	      void    showCursor(Cursor	c)


   Support for Busy States    [Toc]    [Back]
	     virtual void  busy(const char *msg	= NULL,
				VkSimpleWindow *parent = NULL)
	     virtual void  veryBusy(const char *msg = NULL,
				    VkSimpleWindow *parent = NULL)
	     virtual void  notBusy()
	     void  setBusyDialog(VkBusyDialog *d)
	     virtual void progressing(const char *msg =	NULL);


   Convenient Access Functions    [Toc]    [Back]
	      XtAppContext	  appContext() const
	      char		  *name() const
	      Display		 *display() const
	      char		**argv() const
	      char		 *argv(int index) const
	      int		  argc() const
	      char		 *applicationClassName() const
	      VkSimpleWindow	 *mainWindow() const
	      void		  setFallbacks(char **fallbacks)
	      char		 *shellGeometry() const
	      Boolean		  startupIconified() const
	      virtual const char *className() const
	      VkApp		 *theApplication


   Visual Control    [Toc]    [Back]
	       static void useOverlayApps(const	Boolean	flag)







									Page 2






VkApp(3x)							     VkApp(3x)



   Help	system
	      int helpInit(char	*client, char *sep);
	      int helpMsg(char *key, char *book, char *userData);
	      int helpIndexMsg(char *key, char *book);
	      static const char	*const helpInitCallback;
	      static const char	*const helpMsgCallback;
	      static const char	*const helpIndexMsgCallback;
	      void useSGIHelp();
	      static void sgiHelpInit(VkCallbackObject*	caller,
				      void* clientData,
				      void* callData);
	      static void sgiHelpMsg(VkCallbackObject* caller,
				     void* clientData,
				     void* callData);
	      static void sgiHelpIndexMsg(VkCallbackObject* caller,
					  void*	clientData,
					  void*	callData);


PROTECTED PROTOCOL SUMMARY    [Toc]    [Back]

	      int parseCommandLine(XrmOptionDescRec *opt,
				   Cardinal numOptions)
	      VkComponentList _winList
	      virtual void afterRealizeHook()




COMMAND	LINE OPTIONS ASSOCIATED	WITH THIS CLASS
     -scheme
	  Sets the scheme for the application's	resources.

     -useOverlayApps
	  If true, this	resource causes	the entire application to use the
	  deepest available overlay planes.

     -useOverlayDialogs
	  If true, this	resource causes	all dialogs to use the deepest
	  available overlay planes.

     -useOverlayMenus
	  If true, this	resource causes	all menus to use the deepest available
	  overlay planes.


X RESOURCES ASSOCIATED WITH THIS CLASS    [Toc]    [Back]

     busyCursorForeground
	  The foreground color used by the busy	cursor.





									Page 3






VkApp(3x)							     VkApp(3x)



     busyCursorBackground
	  The background color used by the busy	cursor.

     iconic
	  If true, this	resource causes	the entire application to startup
	  iconified.

     normalCursorForeground
	  The foreground color used by the normal cursor.

     normalCursorBackground
	  The background color used by the normal cursor.

     silenceWarnings
	  If True, an application will install error and warning handlers that
	  effectively hide all Xt warnings.  Some of these messages are
	  unavoidable, and this	resource can be	set before a product is
	  shipped.

     useOverlayApps
	  This is equivalent to	the command-line switch	-useOverlayApps.

     useOverlayDialogs
	  This is equivalent to	the command-line switch	-useOverlayDialogs.

     useOverlayMenus
	  This is equivalent to	the command-line switch	-useOverlayMenus.


X DEBUGGING RESOURCES ASSOCIATED WITH THIS CLASS    [Toc]    [Back]

     There are some resources that are only available in the debugging
     versions of the library.  Non-debugging versions of the library simply
     ignore them.

     debugResources
	  If this resource is set to true, the application will	save the
	  contents of its resource database to /usr/tmp/resources.db.

     debugXtMode
	  If true, the application will	core dump when any X or	Xt warning or
	  error	occurs.

     printEvent
	  if non-zero, ViewKit will print information about each event to
	  stderr.  Currently (6/96) the	name of	each event, the	name of	the
	  widget that got the event, and the widget's classname	are printed.

CLASS DESCRIPTION    [Toc]    [Back]

     VkApp provides various central facilities required	by all ViewKit
     applications. All applications must create	a single instance of VkApp or
     a derived class.



									Page 4






VkApp(3x)							     VkApp(3x)



     The following constructor is the normal one.  Most	applications will have
     no	reason to use any other.

	      VkApp(char	     *appClassName,
		    int		     *arg_c,
		    char	    **arg_v,
		    XrmOptionDescRec *optionList       = NULL,
		    int		      sizeOfOptionList = 0);


     The following constructor is rarely needed.  It is	used when an
     application must set creation-time	resources on the invisible top-level
     shell widget that VkApp creates.

     One use of	it is for an application that runs entirely in a non-default
     visual, and also has Motif	drag and drop enabled.	Such an	application
     should use	this constructor to set	the visual attributes for the shell
     that the VkApp constructor	creates, so that they match those used for the
     rest of the application.  Setting the visual attributes this way allows
     the application to	have all of its	shells in a single non-default visual.

     (As of 6/96, if an	application does not ensure that its visuals match,
     Motif drag	and drop will core dump.  There	are non-obvious	work-arounds,
     and a genuine multi-visual	application must still use them.)

	      VkApp(char	     *appClassName,
		    int		     *arg_c,
		    char	    **arg_v,
		    ArgList	      argList,
		    Cardinal	      argCount,
		    void	    (*preRealizeFunction)(Widget w),
		    XrmOptionDescRec *optionList,
		    int		      sizeOfOptionList);


     Upon instantiation, VkApp calls various Xt	functions to connect to	the X
     server and	initialize the Xt Intrinsics.  ViewKit applications should not
     call XtAppInitialize() or other similar Xt	initialization functions
     directly.	VkApp uses the application-context style Xt functions
     throughout, and wherever applicable, ViewKit applications must use	the
     app-context versions of all Xt functions.

     The simplest use of the VkApp class is to create an instance, create
     other windows as needed (see VkSimpleWindow), and call VkApp::run(), as
     seen in the following example program.


	   #include <Vk/VkApp.h>
	   #include <Vk/VkSimpleWindow.h>

	   void	main ( int argc, char **argv )
	   {



									Page 5






VkApp(3x)							     VkApp(3x)



	      VkApp    *app = new VkApp("Application",
					 &argc,	argv);
	      VkSimpleWindow  *win = new VkSimpleWindow("window");

	      win->show();
	      app->run();
	   }


     An	application's instance of VkApp	can be referenced as theApplication
     throughout	an application,	in any file that includes VkApp.h. This	allows
     easy use of various VkApp facilities, such	as the busy() facility,	and
     easy access to the	X Display pointer, the Xt application context, and so
     on.

   Deriving Subclasses    [Toc]    [Back]
     It	is often useful	to create subclasses of	VkApp to support additional
     application-wide services.	One typical use	of a derived class is to parse
     additional	command-line arguments.	For example, the following simple
     example specifies a -verbose command-line argument, using an
     XrmOptionDescRec. This array is passed to the protected member function
     parseCommandLine()	to extract the flag, if	it exists. The value of	all
     recovered options are placed in the application's resource	database,
     where they	can be retrieved as needed.  Notice that parseCommandLine()
     returns an	updated	value of argc which must be used to update the value
     of	argc as	passed in by the calling application.  Failure to do so	will
     cause problems for	applications that reference this value after
     instantiating a VkApp object. (Applications can avoid any difficulties by
     not referencing args directly, and	using theApplication->argc() instead.)


	   #include <Vk/VkApp.h>

	   class App : public VkApp {

	    private:

	      // Declare a description of the command line options

	      static XrmOptionDescRec _cmdLineOptions[];

	    public:

	      App(char		   *appClassName,
		  int		   *arg_c,
		  char		  **arg_v,
		  XrmOptionDescRec *optionList	     = NULL,
		  int		    sizeOfOptionList = 0);
	   };

	   // Describe the command line	options




									Page 6






VkApp(3x)							     VkApp(3x)



	   XrmOptionDescRec App::_cmdLineOptions[] =
	   {
	      {
	      "-verbose", "*verbose", XrmoptionNoArg, "TRUE",
	      },
	   };

	   // Constructor

	   App::MyApp(char	       *appClassName,
		     int	      *arg_c,
		     char	     **arg_v,
		     XrmOptionDescRec *optionList,
		     int	       sizeOfOptionList) :
	      VkApp(appClassName,
		    arg_c,
		    arg_v,
		    optionList,
		    sizeOfOptionList)
	   {
	      // Parse the command line

	      *arg_c = parseCommandLine(_cmdLineOptions,
					XtNumber(_cmdLineOptions));
	   }


     Derived classes may also need access to the windows currently used	in an
     application. The _winList member provides access to a list	of windows, in
     the form of a VkComponentList object (see VkComponentList(3x)).


VIEWKIT	VERSIONS
     The ViewKit supports several constants that can be	used to	identify the
     current ViewKit release. These are:

   ViewKitMajorRelease;
	       static const int	ViewKitMajorRelease;


	  This integer value identifies	the major release of the ViewKit. For
	  example, in a	1.2 release, this value	would be "1". Should it	prove
	  necessary to use conditional statements in your code to handle
	  different versions of	the library, this value	can be useful.

   ViewKitMinorRelease;
	       static const int	ViewKitMinorRelease;


	  This integer value identifies	the current minor release of the
	  ViewKit. For example,	in a 1.2 release, this value would be "2".
	  Should it prove necessary to use conditional statements in your code



									Page 7






VkApp(3x)							     VkApp(3x)



	  to handle different versions of the library, this value can be
	  useful.

   ViewKitReleaseString    [Toc]    [Back]
	       static const char ViewKitReleaseString[];


	  This string contains the complete major and minor release
	  information on the ViewKit. You can identify the version of the
	  ViewKit an application is compiled with by running:

	  strings program | grep "ViewKit Release"

FUNCTION DESCRIPTIONS    [Toc]    [Back]

   VkApp()
	  VkApp(char		 *appClassName,
	       int		*arg_c,
	       char	       **arg_v,
	       XrmOptionDescRec	*optionList	  = NULL,
	       int		 sizeOfOptionList = 0)


	  The VkApp constructor	initializes the	Xt Intrinsics by calling
	  XtToolkitInitialize(), XtCreateApplicationContext() and
	  XtOpenDisplay().  The	constructor also creates a shell to serve as a
	  parent for all other main windows. The ViewKit supports the multishell
	architecture described in the book "X Window System Toolkit",
	  Asente and Swick, 1990. All other windows are	created	as popup
	  children of the shell	created	by VkApp, which	is never visible. The
	  VkApp	constructor also installs various error	handlers and retrieves
	  the application resources recognized by VkApp.

	  The first argument indicates the class name of the application,
	  which	is used	to load	application resources. The second and third
	  arguments must be a pointer to argc and the application's argv
	  array. These arguments are passed to XtOpenDisplay() and the
	  recognized arguments are removed.

     The following constructor is rarely needed.  It is	only used when an
     application must set creation-time	resources on the invisible top-level
     shell widget that VkApp creates.  This constructor	operates just like the
     (shorter) more common one (above),	except that it provides	control	over
     the resources used	when the application's top level shell is created.
     The motivation for	this is	that without it	you cannot have	a singlevisual
 application	that was not in	the default visual.

	  VkApp(char		 *appClassName,
		int		 *arg_c,
		char		**arg_v,
		ArgList		  argList,
		Cardinal	  argCount,



									Page 8






VkApp(3x)							     VkApp(3x)



		void		(*preRealizeFunction)(Widget w),
		XrmOptionDescRec *optionList,
		int		  sizeOfOptionList);


	  One use of this constructor is for an	application that runs entirely
	  in a non-default visual, and also has	Motif drag and drop enabled.
	  Such an application should use this constructor to set the visual
	  attributes for the shell that	the VkApp constructor creates, so that
	  they match those used	for the	rest of	the application.  Setting the
	  visual attributes this way allows the	application to have all	of its
	  shells in a single non-default visual.  (As of 6/96, if an
	  application does not ensure that its visuals match, Motif drag and
	  drop will core dump.	There are non-obvious work-arounds, and	a
	  genuine multi-visual application must	still use them.)

     o	  Any resource that can	be passed on the argList, such as default font
	  list,	should be passed in that way.

     o	  Visual information cannot be known until after the display is
	  opened, and so cannot	be passed in on	the argList.

     o	  preRealizeFunction(w)	will be	called with the	baseWidget (i.e	the
	  shell).  It will be called after widget creation, but	before the
	  widget is realized.  At that time, the application can find the
	  visual information it	needs, and do an XtSetValues() call.  The
	  manual not withstanding, since the widget has	not yet	been realized,
	  this is OK - provided	that the call sets all visual resources
	  consistently.

   setAboutDialog
	       void setAboutDialog(VkDialogManager *dialog);


	  This function	allows applications to replace the dialog displayed
	  when the user	asks for help on "Product Info". The default behavior
	  of this help item is to display a VkInformationDialog	that reports
	  the name and version information for this application	(See
	  setVersionInfo, and VkInformationDialog). Applications that wish to
	  customize the	dialog that appears in this case can install any
	  subclass of VkDialogManager using this function. The new dialog will
	  be posted with a string that identifies the name of the application
	  and the version, but otherwise the content of	the dialog is up to
	  the application. (See	VkDialogManager	and VkGenericDialog for	more
	  information on dialogs.)

     o	  The string "Application Name:" in the	default	popup dialog can be
	  localized by adding a	resource, vkAppNameL10NString, with a
	  translated string to the application's app-defaults file.  For
	  example;





									Page 9






VkApp(3x)							     VkApp(3x)



	       *vkAppNameL10NString: Application Name:


   setVersionString
	       void setVersionString(const char	*str);


	  This function	specifies a string to be used as the version of	an
	  application based on the ViewKit. This string	appears	by default in
	  the "Product Info" dialog.

   versionString
	      const char *versionString();


	  This function	retrieves the currently	installed version string.

   run
	      virtual void run();


	  This function	should be called instead of XtAppMainLoop() in ViewKit
	  programs.  run() calls run_first() to	do some	internal
	  initialization, and then enters a custom main	loop that dispatches
	  application events, raw X events, and	normal Xt events.  (see
	  handleRawEvent().)

	      void run(Boolean(*appEventHandler)(XEvent	&))


	  This is the easiest way to customize ViewKit's X event loop.	This
	  entry	allows an application to customize the event loop without
	  taking responsibility	for the	entire event loop.  For	each event,
	  the application can either supplement	or replace the main event loop
	  handling.

	  Each time through the	event loop, before doing any event processing
	  of its own, run() calls appEventHandler() with the event.  If
	  appEventHandler() has	completely handled the event, it returns TRUE
	  and no further handling of that event	occurs.	 If ViewKit handling
	  of that event	is still needed, then appEventHandler()	must return
	  FALSE.

	      void run_first()


	  run_first() is called	by run().  Any application that	overrides
	  run()	must ensure that run_first() gets called.  See Overriding
	  VkApp::run(),	below, for more	information.






								       Page 10






VkApp(3x)							     VkApp(3x)



	      void runOneEvent(Boolean(*appEventHandler)(XEvent	&) = NULL)


	  runOneEvent()	is the event handling function called by run().	 It
	  does whatever	things ViewKit needs beyond the	standard Xt event
	  handling.  Any application that overrides run() must ensure that
	  some ViewKit event handling function gets called.  See Overriding
	  VkApp::run(),	below, for more	information.


   handlePendingEvents
	      virtual void handlePendingEvents();


	  handlePendingEvents()	retrieves and dispatches all X11 events,
	  timers, and alternate	input.	It does	not block -- it	returns	when
	  there	is nothing pending.  It	does not call any workproc's.

	      void VkApp::handlePendingEvents(Boolean(*appEventHandler)(XEvent &))


	  This version is exactly the same as handlePendingEvents(), above,
	  except that it allows	an application's event handler to also see
	  each event.  See runOneEvent(Boolean(*appEventHandler)(XEvent	&) =
	  NULL), above,	for more information.

	      XtInputMask VkApp::handleOnePendingEvent(
			 Boolean(*appEventHandler)(XEvent &) = NULL)


	  handleOnePendingEvent() returns after	handling a single event, or
	  immediately if there are no events.  The return value	is the mask
	  returned by XtAppPending(), which will be zero if there are no
	  pending events.  The purpose of this routine is to permit
	  construction of non-blocking event loops that	do something before
	  (and/or after) each event.


   Overriding VkApp::run()
	  run()	consists of:

	       void VkApp::run()
	       {
		    run_first();
		    while (True)
		    {
			 runOneEvent((Boolean(*)(XEvent	&)) NULL);
		    }
	       }






								       Page 11






VkApp(3x)							     VkApp(3x)



	  In most cases, an application	does not need to override VkApp::run()
	  to control events.  Instead, the application can do such things as:
	  use standard X mechanisms to add event handlers; use one or more
	  workproc's; maintain its own queue of	all that it needs to do, and
	  then dispatch	that work in a single workproc;

	  If the above are not sufficient, the next thing to look into is
	  calling run(Boolean(*appEventHandler)(XEvent &)).

	  If an	application really does	need to	override run(),	though,	then
	  the application must call run_first()	before the first event
	  processing is	done, and it must call one of the ViewKit event
	  processing routines from the application's event loop.  If it	does
	  not do those two things, it may not be compatible with a future
	  release of ViewKit.

	  An application can override VkApp::run() to add application code
	  that will be executed	each time through the event loop.
	  runOneEvent()	will only return if there was an X11 event.  Otherwise
	  it will service any workproc's, and then block waiting for the next
	  X11 event.  Such an overridden event loop might look like the
	  following:

	       MyApp::run()
	       {
		    run_first();
		    for	(;;) {
			 <application code here>
			 runOneEvent();
			 <application code here>
		    }
	       }


	  If the application does not want to block in ViewKit when there are
	  no X11 events, it can	use the	following event	loop.  Note that since
	  handlePendingEvents()	neither	blocks nor calls any workproc's, the
	  application must take	care of	both of	those things.

	       MyApp::run()
	       {
		    XEvent event;
		    run_first();
		    for	(;;) {
			 <application code, if any here>
			 handlePendingEvents();
			 <application code to handle any workproc's here>
			 // Block until	there are more events
			 XtAppPeekEvent( appContext(), &event);
		    }
	       }




								       Page 12






VkApp(3x)							     VkApp(3x)



	  Alternatively, the loop could	call handleOnePendingEvent() if	it
	  needs	to take	control	each time through the event loop.

	      Demonstration program


	  For a	demonstration program illustrating the several ways to
	  customize the	event loop, see	/usr/share/src/ViewKit/Basic/run.c++.


   quitYourself;
	      virtual void quitYourself();


     Applications that wish to exit, but that wish to allow other parts	of the
     applications to abort the shutdown	should call quitYourself().
     QuitYourself() loops through each top level VkSimpleWindow	(or subclass)
     calling each window's okToQuit() method.  The windows are queried in the
     reverse order in which they are created, except that the window
     designated	as the main window is checked last.  (See VkSimpleWindow for
     more information.)	 If any	object's okToQuit() method returns FALSE, the
     shutdown is terminated.

     If	the resource quitMode is set to	all, then no action is taken unless
     all windows return	TRUE.  If they do, then	all windows are	deleted	and
     the application is	terminated.

     If	the resource quitMode is not set to all, then any window that returns
     TRUE is deleted and any window that returns FALSE is not deleted.


   terminate
	      virtual void terminate(int status	= 0);


	  terminate() is called	within the ViewKit when	any fatal error
	  occurs.  Because terminate() is a virtual function, it can be
	  overloaded by	derived	class that need	to perform some	cleanup	before
	  exiting. Classes that	override terminate() should perform their
	  clean	up and call their base class's terminate() method. This
	  function is not meant	for clean shutdowns, but is normally reserved
	  for situations in which the termination cannot be stopped.  You may
	  also want to consider	using the UNIX atexit()	facility (See
	  atexit(3C)).	Terminate() is called automatically when all windows
	  have been deleted.  Also see quitYourself().


   handleRawEvent
	      virtual void handleRawEvent(XEvent *event);






								       Page 13






VkApp(3x)							     VkApp(3x)



	  Some events do not have a type and are not dispatched	by the Xt
	  dispatch mechanism. These events include client messages and events
	  registered for non-widgets (for example, a PropertyNotify on the
	  root window).	When such an event is received,	VkApp calls the
	  virtual function handleRawEvent() for	event loops the	VkApp instance
	  as well as for all VkSimpleWindow instances.

   setMainWindow
	      void setMainWindow(VkSimpleWindow	*win);


	  Specify a subclass of	VkSimpleWindow to be treated as	the main
	  window of the	application. This window is used by default for
	  centering dialogs that have not specified otherwise, and is also
	  treated differently when the application is being shut down. See
	  quitYourself().

    raise
	      virtual void raise();


	  Raises all visible windows in	the application.

   lower
	      virtual void lower();


	  Lowers all visible windows in	the application.


   iconify
	      virtual void iconify();


	  Iconifies all	visible	windows	in the application.

   open
	      virtual void open();


	  Opens	all iconified windows in the application.

   show
	      virtual void show();


	  Make all hidden, non-iconified windows visible.

   hide
	      virtual void hide();





								       Page 14






VkApp(3x)							     VkApp(3x)



	  Remove all visible, non-iconified windows from the screen.

   startupIconified
	      void   startupIconified(Boolean flag);


	  If called before an application enters the event loop	(run()), this
	  will cause the application to	start in an iconified state.

   busyCursor
	     virtual Cursor  busyCursor();


	  Returns the current busy cursor used by the application.

   normalCursor
	      virtual Cursor  normalCursor();


	  Returns the current normal cursor used by the	application.

   setNormalCursor
	      void    setNormalCursor(Cursor c);


	  Sets the normal cursor used by the application. If the application
	  is not busy, this cursor will	be displayed in	all windows. If	the
	  application is busy, this cursor will	become visible when the
	  application returns from its busy state.

   setBusyCursor
	      void setBusyCursor(Cursor	c);
	      void setBusyCursor(VkCursorList *cl);


	  Sets the busy	cursor used by the application.	If the application is
	  busy,	this cursor will be displayed in all windows immediately. If
	  the application is not busy, this cursor will	become visible when
	  the application becomes busy.	If a VkCursorList object is specified
	  as the busy cursor, the application can support an animated cursor.
	  The application will cycle through one cursor	each time the
	  application calls progressing().

	  By default, a	initial	VkCursorList is	installed in all ViewKit
	  applications.

   showCursor
	      void    showCursor(Cursor	c);







								       Page 15






VkApp(3x)							     VkApp(3x)



	  This function	temporarily displays a cursor in all windows. The
	  cursor can be	reset by calling this function with a NULL cursor
	  argument. The	cursor will also be reset if the program becomes busy
	  or returns from a busy state.	This function is intended for use only
	  for briefly displaying a cursor. For more permanent cursors, use
	  setNormalCursor(), or	setBusyCursor().

   busy
   veryBusy
   notBusy
	     virtual void  busy(const char *msg	= NULL,
				VkSimpleWindow *parent = NULL);
	     virtual void  veryBusy(const char *msg = NULL,
				     VkSimpleWindow *parent = NULL);
	     virtual void notBusy();


	  Applications that expect to be unable	to process events for some
	  length of time should	call busy() when they enter the	busy state and
	  call notBusy() when the program is no	longer busy. Calls can be
	  nested, but there must be matching pairs of busy() and notBusy()
	  calls.  If no	arguments are given to busy(), the application simply
	  displays a busy cursor. The application also blocks out all input,
	  to prevent any type-ahead problems that might	occur.	If an string
	  is given as the first	argument, a dialog is posted to	display	the
	  string. The string is	treated	first as the name of a resource	that
	  indicates a message to be displayed. If no resource is found the
	  string is used as the	message	itself.	If a VkSimpleWindow (or
	  subclass) is specified, the dialog will be posted over this window.
	  (See VkBusyDialog and	VkDialogManager	for more details on dialog
	  behavior).

	  The veryBusy() function is intended for use when the application
	  expects to be	busy for an extended period of time. In	this release,
	  veryBusy() simply calls busy(). In future releases, veryBusy() may
	  take some more interesting or	appropriate action.

	  Calling notBusy() undoes the affect of the most recent call to
	  busy(). If the number	of notBusy() calls matches the number of
	  busy() calls,	the application	restores the normal cursor, enables
	  device input,	and unposts any	busy dialog currently being displayed.

   progressing
	     void  progressing(char *msg = NULL);


	  If an	application is busy, and has a VkCursorList object installed,
	  this member function causes the next cursor in the list to be
	  displayed. This function should be called periodically while an
	  application is busy. If an option string is provided,	the string is
	  displayed in a busy dialog.




								       Page 16






VkApp(3x)							     VkApp(3x)



   setBusyDialog
	     void  setBusyDialog(VkBusyDialog *d);


	  By default, busy() displays a	dialog using the VkBusyDialog class.
	  (See VkBusyDialog(3X)). Applications that wish to alter this
	  behavior can call setBusyDialog() to display an alternate dialog.
	  This dialog must be implemented using	a subclass of VkDialogManager.
	  Calling setBusyDialog() with a NULL argument restores	the default
	  VkBusyDialog.	(See also, VkInterruptDialog(3X)).  Applications
	  should call setBusyDialog() only when	the application	is not busy.

   appContext
	      XtAppContext	  appContext() const;


	  This access function returns the application context used by the
	  application.

   name
	      char		 *name() const;


	  This access function returns the base	name by	which the application
	  was invoked.

   display
	      Display		 *display() const;


	  Returns a pointer to the X Display structure associated with this
	  application's	connection to the X server.

   argv()
	      char		**argv() const;


	  Returns a pointer to the argv	array supplied to this application,
	  but with all recognized command line arguments removed.

   argv
	      char		 *argv(int index) const;


	  Returns a specific entry in the argv array.

   argc
	      int		  argc() const;







								       Page 17






VkApp(3x)							     VkApp(3x)



	  Returns the number of	command	line arguments remaining after all
	  recognized arguments have been removed.

   applicationClassName
	      char		 *applicationClassName() const;


	  Returns the application class	name.

   mainWindow
	      VkSimpleWindow	 *mainWindow() const;


	  Returns a pointer to the VkSimpleWindow (or subclass)	object
	  installed as the application's main window.

   setFallbacks
	      static void	  setFallbacks(char **fallbacks)


	  Sets fallbacks as the	specification_list needed to call
	  XtAppSetFallbackResources(3X).  setFallbacks() must be called	before
	  the application constructs its VkApp object, because the VkApp
	  constructor does call	XtAppSetFallbackResources(3X), passing it the
	  specification_list.

   shellGeometry
	      char		 *shellGeometry() const;


	  Returns the geometry of the base shell of the	application. Some
	  windows may wish to use this size as their own.

   startupIconified
	      Boolean		  startupIconified() const;


	  Calling this function	before run() is	entered	will cause all
	  application windows to start up as icons.

   className
	      virtual const char *className() const;


	  Returns the class name of the	VkApp (or subclass) instance being
	  used.

   *theApplication
	      VkApp		 *theApplication;






								       Page 18






VkApp(3x)							     VkApp(3x)



	  This pointer can be used to reference	the single instance of VkApp
	  (or subclass)	that must exist	in any ViewKit application.


   useOverlayApps()
	   static void useOverlayApps(const Boolean flag)


	  Effectively, useOverlayApps(TRUE) defaults the entire	application
	  into the deepest available overlay planes.

	  The normal default for the (unrealized) VkApp	shell is the normal
	  planes.  That	sets the default for all of its	descendants to be the
	  normal planes	also.  useOverlayApps(TRUE) sets the VkApp shell in
	  the deepest available	overlay	planes,	thus resetting the default
	  planes for the entire	application.

   helpInit()
   helpMsg()
   helpIndexMsg()
   helpInitCallback
   helpMsgCallback
   helpIndexMsgCallback
   useSGIHelp()
   sgiHelpInit()
   sgiHelpMsg()
   sgiHelpIndexMsg()
	      int helpInit(char	*client, char *sep);
	      int helpMsg(char *key, char *book, char *userData);
	      int helpIndexMsg(char *key, char *book);
	      static const char	*const helpInitCallback;
	      static const char	*const helpMsgCallback;
	      static const char	*const helpIndexMsgCallback;
	      void useSGIHelp();
	      static void sgiHelpInit(VkCallbackObject*	caller,
				      void* clientData,
				      void* callData);
	      static void sgiHelpMsg(VkCallbackObject* caller,
				     void* clientData,
				     void* callData);
	      static void sgiHelpIndexMsg(VkCallbackObject* caller,
					  void*	clientData,
					  void*	callData);

     Historically, the way to provide help from	a ViewKit application has been
     to	link the application with a library that implemented the C functions
     SGIHelpInit(), SGIHelpMsg(), and SGIHelpIndexMsg().  ViewKit and the
     application would call these functions in response	to users' requests for
     help.






								       Page 19






VkApp(3x)							     VkApp(3x)



     Help can also be provided by adding callbacks to the helpInitCallback,
     helpMsgCallback, and helpIndexMsgCallback lists.  Instead of calling the
     SGIHelp*()	functions, ViewKit and the application call the	VkApp methods
     helpInit(), helpMsg(), and	helpIndexMsg().

     If	there are no callbacks installed on the	corresponding callback lists,
     the VkApp help methods call the corresponding SGIHelp*() methods so that
     old applications continue to work.	 If callbacks are installed, the
     callbacks are called instead.

     An	application that provides help using the sgihelp program can call the
     VkApp method useSGIHelp(),	which will install sgiHelpInit() on the
     helpInitCallback list, sgiHelpMsg() on the	helpMsgCallback	list, and
     sgiHelpIndexMsg() on the helpIndexMsgCallback list.

     sgiHelpInit(), sgiHelpMsg(), and sgiHelpIndexMsgx() interact with the
     sgihelp program to	provide	the same help that applications	used to	get by
     linking with -lhelpmsg.

     An	application wishing to provide its own help mechanism can add its own
     callbacks to the callback lists.  The callData arguments for the
     helpInitCallback, helpMsgCallback,	and helpIndexMsgCallback lists are of
     type VkApp::HelpInitArgs*,	VkApp::HelpMsgArgs*, and
     VkApp::HelpIndexMsgArgs* respectively.  After installing these callbacks,
     helpInit()	will need to be	called.

PROTECTED PROTOCOL SUMMARY    [Toc]    [Back]

   parseCommandLine()
	      int parseCommandLine(XrmOptionDescRec *opt,
				   Cardinal num);


	  This function	can be called by subclasses to extract arguments from
	  the command line.

   _winList
	      VkComponentList _winList;


	  This member can be accessed by derived classes that need to
	  manipulate the application's top-level windows. See
	  VkComponentList(3X).

   afterRealizeHook()
	      virtual void afterRealizeHook();


	  Some applications need to perform certain actions only after the
	  application's	windows	have been realized. Examples might include
	  installing a colormap, or setting up properties on the application's
	  windows.



								       Page 20






VkApp(3x)							     VkApp(3x)


INHERITED MEMBER FUNCTIONS    [Toc]    [Back]

   Inherited from VkComponent
	  installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
	  setDefaultResources(), getResources(), manage(), unmanage(),
	  baseWidget(),	okToQuit(), _name, _baseWidget,	_w, deleteCallback


   Inherited from VkCallbackObject    [Toc]    [Back]
	  callCallbacks(), addCallback(), removeCallback(),
	  removeAllCallbacks()

KNOWN DERIVED CLASSES    [Toc]    [Back]

     VkMsgApp

CLASSES	USED BY	THIS CLASS
     VkComponent, VkComponentList, VkDialogManager, VkSimpleWindow

KNOWN CLASSES THAT USE THIS CLASS    [Toc]    [Back]

     VkApp, VkBackground, VkDialogManager, VkDoubleBuffer, VkFatalErrorDialog,
     VkGraph, VkHelpPane, VkInterruptDialog, VkMenuBar,	VkMsgFacility, VkNode,
     VkPeriodic, VkPipe, VkResizer, VkSimpleWindow

SEE ALSO    [Toc]    [Back]

      
      
     VkComponent, VkDialogManager, VkMsgApp, VkSimpleWindow, VkWindow,
     VkCursorList
     ViewKit Programmer's Guide
     The X Window System, DEC Press, Bob Sheifler and Jim Gettys
     The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
     The OSF/Motif Programmers Reference, Prentice Hall, OSF


								       PPPPaaaaggggeeee 22221111
[ Back ]
 Similar pages
Name OS Title
VkSoApp IRIX Class used by all Inventor ViewKit applications to handle initialization
VkSoMsgApp IRIX Class used by all Inventor ViewKit messaging applications to handle initialization
VkMsgApp IRIX Class used by messaging applications to handle initialization
VkTrace IRIX Utility routines for tracing ViewKit applications
VkComponent IRIX Abstract base class for all ViewKit components
VkMenuItem IRIX Abstract base class for all ViewKit menu classes
VkMsgComponent IRIX Abstract base class for all ViewKit message components
MediaViewer IRIX a ViewKit class for viewing media files and data
VkMenu IRIX Abstract base class for all ViewKit menu container objects
VkMsgClient IRIX ViewKit application interface to the ViewKit Message Facility
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service