VkSimpleWindow(3x)
VkSimpleWindow - Base class for all top-level windows
As shipped in IRIX 6.5.15. Last changed in IRIX 6.5.5.
NAME VkSimpleWindow - 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); 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 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. 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. 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); } }; 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) { 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 DESCRIPTIONS VkSimpleWindow() 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. 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(); 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. 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 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. 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. 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: 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. 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