VkApp(3x)VkApp(3x)NAMEVkApp - Class used by all ViewKit applications to handle initialization
INHERITS FROM
VkComponent : VkCallbackObject
HEADER FILE
#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
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
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
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
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
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
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
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
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
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
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 DESCRIPTIONVkApp 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
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
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 DESCRIPTIONSVkApp()
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 multi-
shell 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 single-
visual 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 SUMMARYparseCommandLine()
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
Inherited from VkComponent
installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
setDefaultResources(), getResources(), manage(), unmanage(),
baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback
Inherited from VkCallbackObject
callCallbacks(), addCallback(), removeCallback(),
removeAllCallbacks()KNOWN DERIVED CLASSES
VkMsgApp
CLASSES USED BY THIS CLASS
VkComponent, VkComponentList, VkDialogManager, VkSimpleWindow
KNOWN CLASSES THAT USE THIS CLASS
VkApp, VkBackground, VkDialogManager, VkDoubleBuffer, VkFatalErrorDialog,
VkGraph, VkHelpPane, VkInterruptDialog, VkMenuBar, VkMsgFacility, VkNode,
VkPeriodic, VkPipe, VkResizer, VkSimpleWindow
SEE ALSO
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
Page 21
