VkSimpleWindow(3x)VkSimpleWindow(3x)NAMEVkSimpleWindow - Base class for all top-level windows
INHERITS FROM
VkComponent : VkCallbackObject
HEADER FILE
#include <Vk/VkSimpleWindow.h>
PUBLIC PROTOCOL SUMMARY
Constructor/Destructor
VkSimpleWindow(const char *name,
ArgList args = NULL,
Cardinal argCount = 0);
virtual ~VkSimpleWindow();
Constructor - ViewKit 2.1 only
VkSimpleWindow(const char *name,
VkScreen *screen,
ArgList args = NULL,
Cardinal argCount = 0);
Adding and Removing Views
void addView(Widget w);
void addView(VkComponent *comp);
void removeView();
Manipulating Windows
virtual void open();
virtual void raise();
virtual void lower();
virtual void iconify();
virtual void show();
virtual void hide();
Window Manager Interfaces
const char *getTitle();
void setTitle(const char *newTitle);
void setIconName(const char *newName);
void setClassHint(const char *className);
Access Functions
virtual const char* className();
int getVisualState()
Boolean iconic()
Boolean visible()
static VkSimpleWindow *getWindow(VkComponent *component);
Page 1
VkSimpleWindow(3x)VkSimpleWindow(3x)
Access Functions - ViewKit 2.1 only
VkScreen *getScreen();
SUBCLASS PROTOCOL SUMMARY
Window State
enum IconState { OPEN, CLOSED, ICON_UNKNOWN };
enum VisibleState { HIDDEN, VISIBLE, VISIBLE_UNKNOWN };
enum StackingState{ RAISED, LOWERED, STACKING_UNKNOWN};
IconState _iconState;
VisibleState _visibleState;
StackingState _stackingState;
Widget Access
Widget _mainWindowWidget;
virtual Widget mainWindowWidget() const;
virtual Widget viewWidget() const;
virtual operator Widget () const;
Adding Views
virtual Widget setUpInterface(Widget parent);
Subclass Hooks
virtual void setUpWindowProperties();
virtual void stateChanged(IconState);
virtual void handleWmDeleteMessage();
virtual void handleWmQuitMessage();
virtual void handleRawEvent(XEvent *event);
virtual void afterRealizeHook();
CLASS DESCRIPTION
The VkSimpleWindow class implements a simple top-level window to be used
by ViewKit applications. The VkSimpleWindow is intended for use when a
menu bar is not desired. Instantiating a VkSimpleWindow object creates a
popup shell widget as a child of the shell supported by an instance of
VkApp, which must already exist. VkSimpleWindow also creates a Motif
XmMainWindow widget as a child of the shell. Applications must create a
widget to be used as the work area, or "view" contained by the
XmMainWindow. By default, the XmMainWindow is configured to not display
scrollbars, and no other areas of the XmMainWindow widget, besides the
work area, are used. Applications, or subclasses, can access the main
window to configure it however they would like. Menus are supported by
the VkWindow class.
In addition to creating a shell and an XmMainWindow, the VkSimpleWindow
class registers itself with the application's VkApp instance, sets up
various properties on the shell window, and provides simple hooks for
applications that need to handle window manager interactions. For
Page 2
VkSimpleWindow(3x)VkSimpleWindow(3x)
example, all windows support operations to raise, lower, iconify, and
open windows by calling a single member function. Each window also
maintains its current state, so it is straightforward to find out whether
or a not a given window is iconified, or whether is it is currently
visible. The class also supports the user's ability to close a window
using the window manager. (See the handleWmDeleteMessage() and
handleWmQuitMessage() methods.)
The VkSimpleWindow class works together with VkApp to provide
application-wide services such as displaying cursors in all windows,
entering busy states, and manipulating all windows in an application.
Adding a View
By itself, the VkSimpleWindow class simply provides a framework for a
window. The contents of the window must be defined by the application.
This can be done in one of several ways. In most cases, it is best to
define a subclass of VkSimpleWindow in which to add the view, along with
handling other supporting operations and data. In some cases, it may be
useful to add a view directly to a VkSimpleWindow instance, without
deriving a new class.
QuickHelp
QuickHelp is a facility that displays a (presumably helpful) string when
the pointer enters a widget. Help can be displayed in a message line at
the bottom of the application, in a small window that pops up next to the
pointer (i.e., "balloon help" or "popup help"), or both ways. Each way
can have its own help text -- perhaps a brief phrase for popup help, and
a more detailed message for the message line.
QuickHelp availability is controlled by the resources showHelp,
showPopupHelp, and showMsgLineHelp. These resources must be set when the
VkSimpleWindow is created. QuickHelp cannot be created later, though the
programmatic interface allows it to be activated and de-activated.
If showHelp is FALSE, then no QuickHelp will be shown. This
provides an easy way to enable or disable the entire QuickHelp
system.
If showPopupHelp is FALSE, there will be no popup help. If it is
TRUE, there will be popup help if, and only if, showHelp is also
TRUE. Popup help is a good way to solve the problem of ensuring
that a user understands what a button displaying a pixmap is really
for.
If showMsgLineHelp is FALSE, there will be no message line help. If
it is TRUE, there will be message line help if, and only if,
showHelp is also TRUE. Space will be allocated for message line
help at the bottom of the window only if message line help is
enabled.
Page 3
VkSimpleWindow(3x)VkSimpleWindow(3x)
QuickHelp usability includes getting balloons promptly when you want
them, but not getting them when you do not want them. This is a DWIM (Do
What I Mean) problem, and so has no perfect solution. In an attempt to
come as close as we can, QuickHelp has a several timers. These timings
greatly affect the usability of QuickHelp, so you should not generally
alter them. However, if you do not like the default timings, you can
adjust them to suit yourself.
A full discussion of these timers is beyond the scope of this man page,
but here are the ones that are available:
helpTextBrowseCancelTime -- the length of time after leaving a
widget before browse mode is canceled.
helpTextBrowseWaitTime -- the delay after entering a widget, when in
browse mode, before the QuickHelp balloon will be posted.
helpTextBrowseVelocity -- the velocity below which a QuickHelp
balloon should be posted as you browse, and above which you are just
in transit. If you are just in transit, then no balloon will be
posted.
helpTextWaitTime -- the delay after entering a widget, when not in
browse mode, before the QuickHelp balloon will be posted.
helpTextTimeUp -- the length of time a QuickHelp balloon will remain
posted.
There are some miscellaneous resources:
helpTextInsensitive -- controls whether or not QuickHelp is given
when entering insensitive widgets.
smallWidget -- this is the size of the minor dimension of a "wide"
of a "tall" widget. This is used to determine whether a QuickHelp
balloon goes below a widget, or whether it should be posted beside
the widget. For example, if you have a vertical scrollbar that has
QuickHelp, you would probably want QuickHelp to the right of the
scrollbar, not below it.
There are two resources intended for developers and for debugging, but
which may also be useful to some end-users.
dumpTree prints the name and class for each of the widgets in the
widget tree when the VkSimpleWindow is created. This can be useful
as a starting point for creating the QuickHelp text for each widget.
NOTE: A common error is to forget that this cannot dump any widget
that is not yet created. For example, unless you have disabled it,
ViewKit created menus later (in a workProc). That means they will
not get included in the widget tree that is dumped.
Page 4
VkSimpleWindow(3x)VkSimpleWindow(3x)
showWidgetInfo causes QuickHelp to display the widget name, rather
than any QuickHelp text. The information displayed this way may be
expanded in a future release. This can be useful when trying to
figure out just what a widget is called so you can set a resource
for it.
And, finally, there are two per-widget resources that provide the actual
help strings, msgLineHelpText and popupHelpText. Both of these are of
resource class QuickHelpText. If any widget does not have one of these
resources set, it will not get that kind of help, regardless of any
global settings.
There is also a programmatic interface to QuickHelp. This interface is
still experimental, so it may change in incompatible ways in a future
release. When it becomes a supported permanent ABI, it will be
documented here. If you need to use it in the meantime, see the header
files and the QuickHelp ViewKit demo program for information.
Deriving Subclasses
It is best to add a view (or work area) in which to display an
application-specific interface in a subclass. The view can be added in
one of two ways. The first way is to create a widget, or a component in
the subclass constructor, and to call addView(). A VkSimpleWindow
supports only a single child widget.
The following example derived class adds a Motif XmLabel widget as a
view. The XmLabel widget is created as a child of the XmMainWindow
(accessed through the mainWindowWidget() member function inherited from
VkSimpleWindow). More complex examples might create entire widget
hierarchies. Real examples also seldom declare the constructor inline, as
shown here.
#include <Vk/VkApp.h>
#include <Vk/VkSimpleWindow.h>
#include <Xm/Label.h>
class SampleWindow: public VkSimpleWindow {
public:
SampleWindow ( const char *name ) :
VkSimpleWindow ( name )
{
Widget label = XmCreateLabel ( mainWindowWidget(),
"sample", NULL, 0 );
addView(label);
}
};
Page 5
VkSimpleWindow(3x)VkSimpleWindow(3x)
It is recommended that applications be designed so that the view added to
a VkSimple window is a component. (See VkComponent(3X).) This approach
works the same as that demonstrated above. For example, the following
example creates a VkRadioBox component and installs several items. (See
VkRadioBox(3X).)
#include <Vk/VkApp.h>
#include <Vk/VkSimpleWindow.h>
#include <Vk/VkRadioBox.h>
class SampleWindow: public VkSimpleWindow {
public:
SampleWindow ( const char *name ) :
VkSimpleWindow ( name )
{
VkRadioBox *rb = new VkRadioBox("check",
mainWindowWidget());
rb->addItem("one");
rb->addItem("two");
rb->addItem("three");
rb->addItem("four");
addView(rb);
}
};
Some applications may wish to delay the creation of an interface until
the window is ready to be displayed. In this case, a subclass of
VkSimpleWindow can be created without adding a view in the constructor.
Instead, a virtual method, setUpInterface() can be defined. This method
is called when the component is displayed (as a result of a call to
show()) if no view has been added. This method supplies the main window
widget to be used as the parent of the window's widget hierarchy as an
argument. The setUpInterface() method is expected to return a widget to
be added as a view. Using this approach,the above example can be written
as follows:
#include <Vk/VkApp.h>
#include <Vk/VkSimpleWindow.h>
#include <Vk/VkRadioBox.h>
class SampleWindow: public VkSimpleWindow {
protected:
Widget setUpInterface(Widget parent)
{
Page 6
VkSimpleWindow(3x)VkSimpleWindow(3x)
VkRadioBox *rb = new VkRadioBox("check", parent);
rb->addItem("one");
rb->addItem("two");
rb->addItem("three");
rb->addItem("four");
return (rb->baseWidget());
// Could also be: return ((Widget) *rb);
}
public:
SampleWindow ( const char *name ) :
VkSimpleWindow ( name ) {};
};
FUNCTION DESCRIPTIONSVkSimpleWindow()
VkSimpleWindow(const char *name,
ArgList argList = NULL,
Cardinal argCount = 0);
Create a VkSimpleWindow object. This function creates a popup shell
and a Motif XmMainWindow widget, and sets up various properties and
callbacks needed for window manager interaction. The window is also
registered with the current application object.
VkSimpleWindow() - ViewKit 2.1 only
VkSimpleWindow(const char *name,
VkScreen *screen,
ArgList argList = NULL,
Cardinal argCount = 0);
Create a VkSimpleWindow object on the specified VkScreen. This
function creates a popup shell and a Motif XmMainWindow widget, and
sets up various properties and callbacks needed for window manager
interaction. The window is also registered with the specified
VkScreen object.
~VkSimpleWindow()
virtual ~VkSimpleWindow();
The destructor deletes any privately allocated data and removes the
window from the current application's list of windows. The
VkComponent destructor destroys the widgets used in this class.
Page 7
VkSimpleWindow(3x)VkSimpleWindow(3x)getScreen() - ViewKit 2.1 only
VkScreen *getScreen();
Returns the VkScreen object associated with this window.
addView()
void addView(Widget w);
void addView(VkComponent *comp);
Add a widget or a component as the window's work area, or view.
There can be only one view at any given time. However, views can be
changed by removing a view and then adding a new view. (See also
VkDeck(3X), which supports stacks of widgets or components.)
removeView()
void removeView();
Remove the current view from the screen. This function should not be
called unless a view has been previously added. The view (Widget or
component) is not destroyed.
open()
virtual void open();
If the VkSimpleWindow object is in an iconified state, the window is
changed to an un-iconified state. This does not affect whether or
not the window is actually visible. It may still be hidden, or not
hidden but another window may be on top of it. See WINDOW STATES,
below.
raise()
virtual void raise();
Raise the window to the top of the screen.
lower()
virtual void lower();
Lower the window to the bottom of the screen.
iconify()
virtual void iconify();
Page 8
VkSimpleWindow(3x)VkSimpleWindow(3x)
If the VkSimpleWindow object is in a normal state, the window is
changed to an iconified state. This does not affect whether or not
the icon is actually visible. It may still be hidden, or not hidden
but another window may be on top of it. See WINDOW STATES, below.
show()
virtual void show();
If a window is currently in a hidden state, display the window.
This does not affect whether or not the window is iconic. It also
does not affect whether or not the window is actually visible -
another window may be on top of it. See WINDOW STATES, below.
hide()
virtual void hide();
If the window or icon is currently visible, it is removed from the
screen. This does not affect whether or not the window is
considered iconic. See WINDOW STATES, below.
getTitle
const char *getTitle();
Return the current title of the window as a string.
setTitle
void setTitle(const char *newTitle);
Set the current title of the window. This string is treated first as
the name of a resource that indicates a title. If no such resource
is found, the string is used as the title itself. This allows
applications to dynamically change a window title, without
necessarily hard-coding the exact title names in the application
code.
setIconName
void setIconName(const char *newName);
Set the current title of the window's icon. This string is treated
first as the name of a resource that indicates a title. If no such
resource is found, the string is used as the icon title itself. This
allows applications to dynamically change an icon's title, without
necessarily hard-coding the exact icon names in the application
code.
Page 9
VkSimpleWindow(3x)VkSimpleWindow(3x)setClassHints()
void setClassHint(const char *className);
Changes the value of the window manager class hint stored on this
window.
className
virtual const char* className();
The class name of VkSimpleWindow is "VkSimpleWindow".
getVisualState
int getVisualState();
This returns the X11 window state, as specified by the ICCCM
(sections 4.1.2.4, 4.1.4), with one extension. The ICCCM specifies
states WithdrawnState, NormalState, and IconicState. In actual
fact, when an unmapped window is mapped, it may come back as either
Normal or Iconic. In recognition of this ViewKit adds the
corresponding states:
WithdrawnNormalState
is the same as WithdrawnState. Both mean that the window will be in
NormalState when it gets mapped.
WithdrawnIconicState
is new. It means that the window will be in IconicState when it
gets mapped.
iconic
Boolean iconic()
Returns TRUE if the window is currently in an iconic state. Returns
FALSE if the window is currently in a normalized state. This is
unrelated to whether or not the window or icon is actually visible.
It may still be hidden, or not hidden but another window may be on
top of it. See WINDOW STATES, below.
visible()
Boolean visible()
Returns TRUE if the window is not hidden (i.e., the window or icon
is mapped). This is unrelated to whether or not the window or icon
is actually visible on the screen. It may still be hidden, or not
Page 10
VkSimpleWindow(3x)VkSimpleWindow(3x)
hidden but another window may be on top of it. See WINDOW STATES,
below.
getWindow()
static VkSimpleWindow *getWindow(VkComponent *component);
Returns the VkSimpleWindow object (or subclass) that contains the
given VkComponent. This allows components to operate on the window
in which they are contained without a hard coded connection between
the window and the component.
Window State Values
enum IconState { OPEN, CLOSED, ICON_UNKNOWN };
enum VisibleState { HIDDEN, VISIBLE, VISIBLE_UNKNOWN };
enum StackingState { RAISED, LOWERED, STACKING_UNKNOWN };
These values are used to track the window's state. These values are
available to subclasses only.
_iconState
IconState _iconState;
This member is kept up-to-date with the current state of the window,
which will be one of OPEN, CLOSED, or ICON_UNKNOWN. This state is
independent of the value of other states.
_visibleState
VisibleState _visibleState;
This member will be set to HIDDEN if the window is not visible and
VISIBLE if it is. This state is independent of the value of other
states.
_stackingState
StackingState _stackingState;
This member will be set to RAISED if the window has been raised to
the top of other windows, and LOWERED if it has been lowered below
its siblings.
mainWindowWidget
virtual Widget mainWindowWidget() const;
This function returns the XmMainWindow widget created by the
VkSimpleWindow.
Page 11
VkSimpleWindow(3x)VkSimpleWindow(3x)
viewWidget
virtual Widget viewWidget() const;
Returns the widget currently installed as a view.
setUpInterface
virtual Widget setUpInterface(Widget parent);
If no view has been added by the time a VkSimpleWindow needs to
display itself (because show() has been called), setUpInterface() is
called. This function is expected to create and return a widget as a
child of the specified parent. Using this function has the same
effect as calling addView, but the widgets are not created until the
window is about to be displayed.
setUpWindowProperties
virtual void setUpWindowProperties();
This function is called after a VkSimpleWindow object's shell widget
is realized. It initializes the properties involved in the window
manager's WM_DELETE protocol. Derived classes that wish to store
other properties on the window can override this function and
perform additional actions. If this function is overridden, the
function belonging to the base class should be called from the
derived class function.
stateChanged
virtual void stateChanged(IconState);
This function is called when the window's iconic state changes.
Derived classes that need to know when these transitions occur can
override this function. Because this function is responsible for
maintaining the objects state information, functions defined by a
derived class should always call the base class function before
performing any desired additional operations.
handleWmDeleteMessage()
virtual void handleWmDeleteMessage();
This function is called when the user closes a window using the
window manager. (For example, the Motif Window manager, mwm,
supports a Close menu entry for each window.) The default action of
this function is to delete the object. Derived class that wish to
change this behavior can override this function. Derived classes
that simply wish to perform additional actions before the object is
deleted can override the function, perform the required actions, and
then call the base class function.
Page 12
VkSimpleWindow(3x)VkSimpleWindow(3x)handleWmQuitMessage()
virtual void handleWmQuitMessage();
This function is called when the user quits an application using the
4Dwm window manager extension to the ICCCM protocol. The default
action of this function is to call VkApp::quitYourself(). Derived
class that wish to change this behavior can override this function.
Derived classes that simply wish to perform additional actions
before the object is deleted can override the function, perform the
required actions, and then call the base class function.
handleRawEvent
virtual void handleRawEvent(XEvent *event);
Some events that may be received by an application are not
dispatched by the Xt dispatch mechanism. For example, propertyNotify
on windows other than Motif widgets cannot be dispatched. When such
an event is received by the VkApp event loop, the event is
dispatched to all top-level windows by calling each window's
handleRawEvent() member function. The default function is empty.
Derived classes that wish to handle the event should override this
function.
afterRealizeHook
virtual void afterRealizeHook();
This function is called immediately after a VkSimpleWindow object's
shell widget is realized. Derived classes that need to perform
certain actions only after a window exists can override this
function.
WINDOW STATES
In X11, there are three possible window states:
NormalState
Only the application's VkSimpleWindow is mapped.
IconicState
Only the application's icon is mapped.
WithdrawnState
Neither the application's window nor its icon is mapped.
To clarify two possible meanings of WithdrawnState, VkSimpleWindow adds
the following states:
Page 13
VkSimpleWindow(3x)VkSimpleWindow(3x)
WithdrawnNormalState
Is the same as WithdrawnState. Both mean that when the window is
mapped, it will be in NormalState.
WithdrawnIconicState
Means that when the window is mapped, it will be in IconicState.
A window's state is unrelated to whether or not the actual window is in
fact visible on the screen. A window can be in either NormalState or
IconicState, and still not be visible if it is obscured by another window
on top of it.
A window starts out in WithdrawnState (ICCCM 4.1.1, 4.1.2.4). The window
manager, possibly cooperating with a session manager, then transitions
the window to either NormalState or IconicState. This means that there
is no way for an application to know in advance what the initial state of
a window will be. The application must either:
o wait until the window is no longer in WithdrawnState and then see
what the actual state is.
o force the initial state. Because it defeats session management,
this is generally a Bad Thing to do.
VkSimpleWindow allows independent control over the iconic state of a
window and whether or not it is actually mapped. These aspects are
independent of each other.
Mapping a window
A window must be mapped to be visible. If mapped, the application's
window or icon will actually be visible only if it is within the
screen area and not obscured by another window. show() maps the
window or icon, hide() unmaps it, and visual() tells whether or not
it is mapped.
Iconifying a window
An application is visually represented by either its window or its
icon. If it is represented by its icon, the application's actual
window will be unmapped, and therefore invisible. Whether or not
the icon is visible is determined by whether it is mapped. This
means that iconic() does not tell anything about whether or not the
actual window or icon is visible. Iconify() iconifies a window,
open() un-iconifies it, and iconic() tells whether or not the window
is iconified.
getVisualState()
allows an application to tell, with a single call, which state the
application is in: WithdrawnNormalState, WithdrawnIconicState,
NormalState, or IconicState.
If the window is in NormalState, its window is visible. If the
window is in IconicState, its icon is visible.
Page 14
VkSimpleWindow(3x)VkSimpleWindow(3x)
Optimal Order of Operations
The application should eliminate unnecessary window mapping and
unmapping, because they cause wasteful X server traffic, and because
they may cause visible flashing on the screen. To do so:
1) If the end result of a series of operations is to be hidden, and if
the window is currently visible, give the hide() call first.
2) If the end result of a series of operations is to be visible, and if
the window is currently hidden, give the show() call last.
X11 states map into the ViewKit states as follows:
IconicState visible() && iconic()
NormalState visible() && !iconic()
WithdrawnIconicState !visible() && iconic()
WithdrawnNormalState !visible() && !iconic()
To explore window states, see the demo program
/usr/share/src/ViewKit/Basic/windowState.
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
VkWindow, VkForkDoc, VkMsgWindow
CLASSES USED BY THIS CLASS
VkApp, VkComponent
KNOWN CLASSES THAT USE THIS CLASS
VkApp, VkDialogManager, VkMsgApp
SEE ALSO
VkComponent, VkApp, VkComponent, VkDialogManager, VkMsgApp
ViewKit Programmer's Guide
The X Window System, DEC Press, Bob Scheifler and Jim Gettys
The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
The OSF/Motif Programmers Reference, Prentice Hall, OSF
Page 15
VkSimpleWindow(3x)VkSimpleWindow(3x)
Page 16
