VkDialogManager(3x) VkDialogManager(3x)
NAME
VkDialogManager - An abstract manager class that caches and supports
Motif dialogs
INHERITS FROM
VkComponent : VkCallbackObject
HEADER FILE
#include <Vk/VkDialogManager.h>
PUBLIC PROTOCOL SUMMARY
Destructor
virtual void ~VkDialogManager(void);
Setting Labels and Titles
void setTitle(const char* nextTitle);
void setButtonLabels(const char* okLabel,
const char* cancelLabel,
const char* applyLable);
Unposting Dialogs
void unpost(void);
void unpost(Widget dialogWidget);
void unpostAll(void);
Changing Dialog behavior
void centerOnScreen(Boolean center);
void enableCancelButton (Boolean b);
Access functions
Widget lastPosted(void);
Access functions - ViewKit 2.1 only
VkScreen getScreen();
Posting Non-Modal Dialogs
virtual Widget post (
const char *message = NULL,
XtCallbackProc okCB = NULL,
XtCallbackProc cancelCB = NULL,
XtCallbackProc applyCB = NULL,
XtPointer clientData = NULL,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL,
Widget widgetParent = NULL);
Page 1
VkDialogManager(3x) VkDialogManager(3x)
Widget post ( const char *msg,
VkSimpleWindow *parent)
Widget post ( const char *msg,
const char *helpString,
VkSimpleWindow *parent)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
const char *helpString,
VkSimpleWindow *parent = NULL)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
char *helpString,
VkSimpleWindow *parent = NULL)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtCallbackProc applyCB,
XtPointer clientData,
VkSimpleWindow *parent)
Widget post ( const char *msg,
Widget parent)
Widget post ( const char *msg,
const char *helpString,
Widget parent)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
Widget parent)
Widget post ( const char *msg,
XtCallbackProc okCB,
Page 2
VkDialogManager(3x) VkDialogManager(3x)
XtPointer clientData,
const char *helpString,
Widget parent)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
Widget parent)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
char *helpString,
Widget parent)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtCallbackProc applyCB,
XtPointer clientData,
Widget parent)
Posting Modal Dialogs
virtual Widget postModal (
const char *message = NULL,
XtCallbackProc okCB = NULL,
XtCallbackProc cancelCB = NULL,
XtCallbackProc applyCB = NULL,
XtPointer clientData = NULL,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL,
Widget widgetParent = NULL);
Widget postModal ( const char *msg,
VkSimpleWindow *parent)
Widget postModal ( const char *msg,
const char *helpString,
VkSimpleWindow *parent)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
Page 3
VkDialogManager(3x) VkDialogManager(3x)
const char *helpString,
VkSimpleWindow *parent = NULL)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
char *helpString,
VkSimpleWindow *parent = NULL)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtCallbackProc applyCB,
XtPointer clientData,
VkSimpleWindow *parent)
Widget postModal ( const char *msg,
Widget parent)
Widget postModal ( const char *msg,
const char *helpString,
Widget parent)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
Widget parent)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
const char *helpString,
Widget parent)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
Widget parent)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
char *helpString,
Page 4
VkDialogManager(3x) VkDialogManager(3x)
Widget parent)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtCallbackProc applyCB,
XtPointer clientData,
Widget parent)
Posting Blocking Dialogs
virtual Widget postBlocked (
const char *message = NULL,
XtCallbackProc okCB = NULL,
XtCallbackProc cancelCB = NULL,
XtCallbackProc applyCB = NULL,
XtPointer clientData = NULL,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL,
Widget widgetParent = NULL);
Widget postBlocked ( const char *msg,
VkSimpleWindow *parent)
Widget postBlocked ( const char *msg,
const char *helpString,
VkSimpleWindow *parent)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
const char *helpString,
VkSimpleWindow *parent = NULL)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
char *helpString,
VkSimpleWindow *parent = NULL)
Page 5
VkDialogManager(3x) VkDialogManager(3x)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtCallbackProc applyCB,
XtPointer clientData,
VkSimpleWindow *parent)
Simplified Blocking Dialogs
virtual VkDialogReason postAndWait (
const char *message = NULL,
Boolean ok = TRUE,
Boolean cancel = TRUE,
Boolean apply = FALSE,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL);
VkDialogReason postAndWait (
const char *message,
const char *helpString,
VkSimpleWindow *parent = NULL);
VkDialogReason postAndWait ( const char *message,
VkSimpleWindow *parent)
Visual Control
static void useOverlayDialogs(const Boolean flag)
void setArgs (ArgList list, Cardinal argCnt)
void setVisual (VkVisual *v)
PROTECTED PROTOCOL SUMMARY
Manipulating dialogs prior to posting
virtual Widget prepost (
const char *message,
XtCallbackProc okCB = NULL,
XtCallbackProc cancelCB = NULL,
XtCallbackProc applyCB = NULL,
XtPointer clientData = NULL,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL);
Widget prepost ( const char *message,
const char *helpString,
VkSimpleWindow *parent);
Page 6
VkDialogManager(3x) VkDialogManager(3x)
Responding to User Actions
virtual void ok(Widget widget, XtPointer callData);
virtual void cancel(Widget widget, XtPointer callData);
virtual void apply(Widget widget, XtPointer callData);
Creating New Dialogs
virtual Widget createDialog(Widget parent);
Constructor
VkDialogManager(const char *name);
Protected Data Members
int _action;
Boolean _showOK;
Boolean _showCancel;
Boolean _showApply;
Boolean _allowMultipleDialogs;
Boolean _minimizeMultipleDialogs;
CLASS DESCRIPTION
The VkDialogManager class is an abstract class that supports
cacheable, easy-to-use Motif dialogs for ViewKit applications. The
VkDialogManager class provides the public protocol though which all
derived classes are manipulated. This protocol is intended to
simplify the procedure of posting a dialog, and make it possible to
post dialogs without interacting directly with widgets. This is
useful because the need to report errors often occurs outside the UI
layers of an application. The VkDialogManager class uses caching to
achieve an optimal balance between the time required to create a
dialog dynamically and the time and memory needed to pre-create
dialogs.
Dialogs may be posted using a variation of four basic member
functions: post(), postModal(), postBlocked() and postAndWait().
These member functions allow the calling application to easily
control the style of the dialog. The VkDialogManager attempts to
Page 7
VkDialogManager(3x) VkDialogManager(3x)
cache and reuse existing dialog widgets wherever possible, and also
allows the calling application to determine which buttons and labels
appear on any dialog, as well as to specify functions to be called
when various dialog buttons are selected.
All classes derived from VkDialogManager catch the window manager
close function and redirect it to the "cancel" action normally
associated with the dialog.
SETTING CREATION-TIME RESOURCES FOR DIALOGS
There is no way in the ViewKit dialogs' API, theXyzDialog->post(), for an
application to specify an arglist. There are ways around this:
⊕ Setting dialogs in the deepest available overlay can most easily be
done by using useOverlayDialogs.
⊕ Setting dialogs to a specific visual is most easily done by using
setVisual(). This VkVisual will be used for any subsequent dialog
creation.
⊕ setArgs() allows passing an arbitrary argList. This list will be
used for any subsequent dialog creation.
Dialog arguments should be set once, before any dialog is created.
Resetting the dialog creation arguments after the first dialog is created
results in an undefined action. The reason is that, due to ViewKit's
dialog caching, later setting of creation arguments is not always
predictable.
DIALOGS IN THE OVERLAY PLANES
By default, dialogs appear in the normal planes. A ViewKit application's
dialogs may be explicitly placed in the deepest available overlay planes.
Doing so prevents dialogs from causing expose events and disturbing such
things as complex GL rendering. Whether or not the dialogs look as nice
as they do in the normal planes depends on how deep the deepest available
overlay visual is. The current implementation is global. For a single
application, either all dialogs go in the overlay planes or none of them
do. That may be relaxed in a future release.
There are three ways to enable dialogs in the overlay planes:
⊕ Call VkDialogManager::useOverlayDialogs(TRUE) in your application.
This will force all dialogs to be in the overlay planes, with no way
to put them back in the normal planes without recompiling.
⊕ Put the resource string "*useOverlayDialogs: True" in your
application's app-defaults file. This will put dialogs in the
overlay planes by default, but allow users to use the normal planes
by changing their .Xdefaults file.
Page 8
VkDialogManager(3x) VkDialogManager(3x)
⊕ Ask the user to add the "-useOverlayDialogs" command line switch
when they run your application. This will put dialogs in the normal
planes by default, but allow the user to explicitly ask that the
overlay planes be used.
There are several disadvantages to using the overlay planes, so dialogs
should be put there only when the advantages outweigh the disadvantages:
⊕ The colormap in the overlay planes may have fewer pixels. On some
hardware, the deepest overlay only has three color entries. (The
fourth entry is a transparent pixel.) When there are fewer colors
available, dialogs in the overlay planes have a different appearance
- especially with some of the less-common color schemes.
⊕ Other applications that are using the overlay planes at the same
time will display in the wrong colors when an overlay dialog appears
(i.e. colors will flash). This happens because the dialog's
colormap will get installed and replace any previous overlay
colormap.
⊕ When a dialog is in the overlay planes, 4Dwm puts the window manager
border in the popup visual. The title bar of the window appears
with the wrong colors and, as with (2), the window appears with the
wrong colors when another application uses the overlay planes (e.g.
4Dwm's root-window popup dialog).
For more information see /usr/share/src/ViewKit/Basic/Visual/*.
POSTING DIALOGS
DERIVING SUBCLASSES
Derived classes generally only need to override the function
createDialog() to return a dialog widget of the desired type. The
dialog widget returned by this function must be a subclass of
XmMessageBox or XmSelectionBox. Classes corresponding to the
standard Motif dialog widgets have already been defined. Custom
dialog classes should normally be derived from VkGenericDialog.
FUNCTION DESCRIPTIONS
getScreen() - ViewKit 2.1 only
VkScreen *getScreen();
Return the VkScreen object associated with this dialogManager.
Page 9
VkDialogManager(3x) VkDialogManager(3x)
prepost()
Widget prepost(const char *message,
const char *helpString,
VkSimpleWindow* parent);
virtual Widget prepost(
const char *message,
XtCallbackProc okCB = NULL,
XtCallbackProc cancelCB = NULL,
XtCallbackProc applyCB = NULL,
XtPointer clientData = NULL,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL);
This protected function is called from the VkDialogManager post()
function. The prepost() function is responsible for finding or
creating a dialog to be displayed by one of the post() functions.
Derived classes that wish to perform some operations on a dialog
widget before displaying it on the screen should override this
function, call the VkDialogManager function directly to obtain a
widget, do whatever additional operations are desired and then
return the Widget returned by VkDialogManager::prepost().
ok()
virtual void ok(Widget w, XtPointer clientData);
This function provides a hook for derived classes that need to know
when the user has selected the OK button. Applications that use
dialogs should register Xt callbacks with the post() method to be
notified.
cancel()
virtual void cancel(Widget w, XtPointer clientData);
This function provides a hook for derived classes that need to know
when the user has selected the Cancel button. Applications that use
dialogs should register an Xt-style callback with the post() method
to be notified.
apply()
virtual void apply(Widget w, XtPointer clientData);
This function provides a hook for derived classes that need to know
when the user has selected the Apply button. Applications that use
dialogs should register an Xt-style callback with the post() method
to be notified.
Page 10
VkDialogManager(3x) VkDialogManager(3x)
createDialog()
virtual Widget createDialog(Widget parent) = 0;
Derived classes must override this function, which is called when
the VkDialogManager class requires a new dialog widget. The function
is expected to create and return a dialog of desired type. The
dialog must be a child of the given parent.
VkDialogManager()
VkDialogManager(const char* name);
The constructor initializes the VkDialogManager. It can only be
called by derived classes.
~VkDialogManager()
virtual void ~VkDialogManager(void);
The destructor frees all memory associated with the VkDialogManager
class and destroys all cached dialog widgets.
setTitle()
void setTitle(const char* nextTitle);
This function can be used to specify the title of the next dialog
widget to be posted by this dialog manager. The title is reset after
each call to one of the post() member functions. The string provided
is first treated as the name of a resource, and only used directly
if no resource is found. For example, a dialog's title might be
specified as follows:
theErrorDialog->setTitle("error37Title");
The application's application defaults might then specify the real title
as:
*error37Title: "Internal Malfunction Error Dialog"
The most common use of this feature is for internationalization.
Applications that do not care about the ability to change titles without
recompiling can simply specify the desired string by setting a resource.
If setTitle() is not called prior to posting a dialog, the dialog
title defaults to the value of the XmNdialogTitle resource for the
given widget. If no such resource is set, the title defaults to the
name of the application.
Page 11
VkDialogManager(3x) VkDialogManager(3x)
setButtonLabels()
void setButtonLabels(const char *nextOK,
const char *nextCancel,
const char *nextApply);
This function can be used to specify the labels on the buttons of
the next dialog to be posted. The values affect only the next dialog
to be posted and are reset afterwards to their default values. Like
setTitle() this function first treats each given string as the name
of a resource to be loaded, then as the label itself. If no labels
are specified, the defaults are normally as follows:
Button First Choice Fallback
OK Value of XmNokLabelString "OK"
Cancel Value of XmNcancelLableString "Cancel"
Apply Value of XmNapplyLableString "Apply"
unpost()
void unpost(void);
This function removes the most recently posted dialog.
unpost()
void unpost(Widget w);
This function removes the given dialog widget.
unpostAll()
void unpostAll(void);
This function removes all dialogs of a given type from the screen.
centerOnScreen()
void centerOnScreen(Boolean center);
By default, dialogs are centered over a parent window, as specified
in the call to post(), or over the application's main window, if no
window is given. If this function is called with a value of TRUE
prior to posting a dialog, the dialog will be force to the center of
the screen, regardless of the position of the specified parent.
Page 12
VkDialogManager(3x) VkDialogManager(3x)
enableCancelButton()
void enableCancelButton (Boolean b);
Sets whether or not the default will be to provide a CANCEL button
in future dialogs.
lastPosted()
Widget lastPosted(void);
This function returns the Widget ID of the last posted dialog. In
some cases, it might be useful to be able to manipulate this widget
directly, while it is posted.
post()
virtual Widget post ( const char *message = NULL,
XtCallbackProc okCB = NULL,
XtCallbackProc cancelCB = NULL,
XtCallbackProc applyCB = NULL,
XtPointer clientData = NULL,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL);
This member function displays a new dialog widget, attempting to use
cached dialogs if possible. Like all Motif dialogs, the application
is expected to return to the event loop to allow the user to
interact with the posted dialog. With no arguments, post() simply
displays the dialog. This may be appropriate for some derived
classes that may not support a message. If an initial argument is
given, the dialog displays the indicated message. The message is
first treated as the name of a resource to be loaded and uses as the
string. If no resource is found, the string itself is assumed to be
the dialog message.
The three optional callback arguments must be Xt-style callbacks to
be called if the corresponding button is selected by the user. The
presence or absence of these callbacks provide some control over
what buttons appear in the posted dialog. Some dialogs, however, may
override this behavior to force certain buttons to appear. For
example, a VkWarningDialog will normally have only an OK button. By
calling the post() function with callbacks for the cancel and apply
operations, a warning dialog will appear with three buttons, ok,
cancel, and apply. The clientData argument allows the caller to
specify data to be passed to these callbacks when they are called.
To support context-sensitive help, each individual dialog can supply
a help string to be passed to the help system when the user requests
help for this dialog.
Page 13
VkDialogManager(3x) VkDialogManager(3x)
The final optional argument allows the caller to specify a ViewKit
VkSimpleWindow over which this dialog should be centered. If this
argument is not supplied, the dialog will be centered over the
application's main window.
post()
Widget post ( const char *msg,
VkSimpleWindow *parent)
Widget post ( const char *msg,
const char *helpString,
VkSimpleWindow *parent)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
const char *helpString,
VkSimpleWindow *parent = NULL)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
char *helpString,
VkSimpleWindow *parent = NULL)
Widget post ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtCallbackProc applyCB,
XtPointer clientData,
VkSimpleWindow *parent)
These member functions provide a large number of variations on the
basic post() member function. The arguments are designed to support
typical arrangements of arguments without requiring the complete
list of parameters supported by the basic function.
Page 14
VkDialogManager(3x) VkDialogManager(3x)
postModal()
virtual Widget postModal (
const char *message = NULL,
XtCallbackProc okCB = NULL,
XtCallbackProc cancelCB = NULL,
XtCallbackProc applyCB = NULL,
XtPointer clientData = NULL,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL);
This function is similar to the post() member function, except that
the dialog will be a modal dialog, which must be dismissed before
the application can accept other input.
postModal()
Widget postModal ( const char *msg,
VkSimpleWindow *parent)
Widget postModal ( const char *msg,
const char *helpString,
VkSimpleWindow *parent)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
const char *helpString,
VkSimpleWindow *parent = NULL)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
char *helpString,
VkSimpleWindow *parent = NULL)
Widget postModal ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtCallbackProc applyCB,
XtPointer clientData,
Page 15
VkDialogManager(3x) VkDialogManager(3x)
VkSimpleWindow *parent)
These member functions provide a large number of variations on the
basic postModal() member function. The arguments are designed to
support typical arrangements of arguments without requiring the
complete list of parameters supported by the basic function.
postBlocked()
virtual Widget postBlocked (
const char *message = NULL,
XtCallbackProc okCB = NULL,
XtCallbackProc cancelCB = NULL,
XtCallbackProc applyCB = NULL,
XtPointer clientData = NULL,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL);
This function is similar to post() except that after posting the
dialog, the function enters a secondary event loop which does not
return until the user has dismissed the dialog. The dialog is posted
as a full application modal dialog to minimize potential problems
that could be caused by the secondary event loop, but applications
should be aware that the second event loop is being used, and be
sure that no non-re-entrant code can be called.
postBlocked()
Widget postBlocked ( const char *msg,
VkSimpleWindow *parent)
Widget postBlocked ( const char *msg,
const char *helpString,
VkSimpleWindow *parent)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtPointer clientData,
const char *helpString,
VkSimpleWindow *parent = NULL)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
VkSimpleWindow *parent = NULL)
Page 16
VkDialogManager(3x) VkDialogManager(3x)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtPointer clientData,
char *helpString,
VkSimpleWindow *parent = NULL)
Widget postBlocked ( const char *msg,
XtCallbackProc okCB,
XtCallbackProc cancelCB,
XtCallbackProc applyCB,
XtPointer clientData,
VkSimpleWindow *parent)
These member functions provide a large number of variations on the
basic postBlocked() member function. The arguments are designed to
support typical arrangements of arguments without requiring the
complete list of parameters supported by the basic function.
postAndWait()
virtual VkDialogReason postAndWait (
const char *message = NULL,
Boolean ok = TRUE,
Boolean cancel = TRUE,
Boolean apply = FALSE,
const char *helpString = NULL,
VkSimpleWindow *parent = NULL);
This function is similar to post() except that the application
enters a secondary event loop after posting the dialog and does not
return until the user has dismissed the dialog. Unlike
postBlocked(), postAndWait() handles all callbacks internally and
returns a value that reports what button was selected. The possible
return values are VkDialogManager::OK, VkDialogManager::CANCEL, or
VkDialogManager::APPLY. This function is useful for applications in
which it is necessary or more convenient to not go on to the next
line of code until the user has dismissed the dialog. For example,
an application opening a file might use the VkFileSelectionDialog (a
class derived from VkDialogManager) as follows:
if(theFileSelectionDialog->postAndWait( )
== VkDialogManager::OK)
fd = open(theFileSelectionDialog->fileName(),
O_RDONLY);
Page 17
VkDialogManager(3x) VkDialogManager(3x)
When postAndWait() is used, the dialog is posted as a full
application modal dialog to minimize potential problems that could
be caused by the secondary event loop, but applications should be
aware that the second event loop is being used, and be sure that no
non-re-entrant code can be called.
Because no callbacks are involved when using this interface, the
second, third, and forth arguments are Boolean values that indicate
which buttons should appear in the dialog. Note that these flags are
considered along with the default behavior of each type of dialog.
For example, a VkQuestionDialog will always have OK and Cancel
buttons, but the caller can add an "apply" button if needed.
postAndWait()
VkDialogReason postAndWait ( const char *message,
const char *helpString,
VkSimpleWindow *parent = NULL);
VkDialogReason postAndWait ( const char *message,
VkSimpleWindow *parent)
These member functions provide a large number of variations on the
basic postAndWait() member function. The arguments are designed to
support typical arrangements of arguments without requiring the
complete list of parameters supported by the basic function.
useOverlayDialogs()
static void useOverlayDialogs(const Boolean flag);
Controls whether dialogs that are created subsequently will be in
the normal planes (flag = False) or in the deepest available overlay
(flag = True).
setVisual()
void setVisual (VkVisual *v)
Used to set visual resources before creating the first dialog. In
the event that both this and the arglist are set (see setArgs(),
below), this overrides any visual arguments in the arglist.
setArgs()
void setArgs (ArgList list, Cardinal argCnt)
Page 18
VkDialogManager(3x) VkDialogManager(3x)
Pass in resources to be used when creating the first dialog. These
may or may not include visuals arguments.
DATA MEMBER DESCRIPTIONS
action
int _action;
This protected member always contains a value that indicates the
user's action in choosing dialog buttons. The possible values are
VkDialogManager::OK, VkDialogManager::CANCEL,
VkDialogManager::APPLY, or VkDialogManager::NONE.
showOK
Boolean _showOK;
This member can be set to TRUE by derived classes to force the OK button
to always be shown for all dialogs of a particular type. If set to FALSE,
the appearance of the OK button depends on what callbacks have been
specified when posting the dialog.
showCancel
Boolean _showCancel;
This member can be set to TRUE by derived classes to force the
Cancel button to always be shown for all dialogs of a particular
type. If set to FALSE, the appearance of the Cancel button depends
on what callbacks have been specified when posting the dialog.
showApply
Boolean _showApply;
This member can be set to TRUE by derived classes to force the Apply
button to always be shown for all dialogs of a particular type. If
set to FALSE, the appearance of the Apply button depends on what
callbacks have been specified when posting the dialog.
allowMultipleDialogs
Boolean _allowMultipleDialogs;
The default behavior of the VkDialogManager class is to allow
multiple dialogs of any given type to be posted at once. The
VkDialogManager class calls derived class member function
createDialog() as needed to create additional widgets. For some
types of dialogs, it makes more sense to allow only one instance of
Page 19
VkDialogManager(3x) VkDialogManager(3x)
a particular dialog type to exist at any one time. For example,
multiple nested calls to busy() (see VkApp(3X)) should not normally
produce multiple dialogs. If a derived class sets
_allowMultipleDialogs to FALSE, the VkDialogManager class will not
create additional dialogs, but will reuse an existing dialog in all
cases.
minimizeMultipleDialogs
Boolean _minimizeMultipleDialogs;
Normally, VkDialogManager caches dialogs on a per-toplevel window
basis. If there are many toplevel windows, this could result in
having many dialogs of the same type, which may be undesirable for
some types of dialogs, particularly if they are expensive to create.
If the flag _minimizeMultipleDialogs is set to TRUE, VkDialogManager
will reuse any existing dialog that is not currently displayed. A
new dialog will be created only if all existing instances of the
dialog type are currently being displayed.
prepostCallback
static const char* const prepostCallback;
This callback is invoked just before a dialog is displayed. The
callData parameter indicates the dialog widget about to be
displayed.
INHERITED MEMBER FUNCTIONS
Inherited from VkCallbackObject
callCallbacks(), addCallback(), removeCallback(),
removeAllCallbacks()
Inherited from VkComponent
installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
afterRealizeHook(), setDefaultResources(), getResources(),
name(), baseWidget() okToQuit(), _name, _baseWidget, _w,
deleteCallback
KNOWN DERIVED CLASSES
VkBusyDialog, VkInterruptDialog, VkErrorDialog, VkFatalErrorDialog,
VkFileSelectionDialog, VkWarningDialog, VkGenericDialog, VkPrefDialog,
VkInfoDialog, VkQuestionDialog
CLASSES USED BY THIS CLASS
VkApp, VkSimpleWindow, VkWidgetList
KNOWN CLASSES THAT USE THIS CLASS
VkApp, VkDialogManager, VkHelpPane, VkMenuBar, VkMenuConfirmFirstAction,
VkPipe
Page 20
VkDialogManager(3x) VkDialogManager(3x)
BUGS
SEE ALSO
VkComponent, VkApp, VkSimpleWindow, VkBusyDialog, VkInterruptDialog,
VkErrorDialog, VkFatalErrorDialog, VkFileSelectionDialog,
VkWarningDialog, VkGenericDialog, VkPrefDialog, VkInfoDialog,
VkQuestionDialog
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