Window Manager Interface

The VkSimpleWindow and VkWindow classes set up various properties on the shell window and provide simple hooks for window manager interactions.

Window and Icon Titles

The VkSimpleWindow and VkWindow classes provide easy-to-use functions to set your application's window and icon titles.

The setTitle() function sets the title of a window:

void setTitle(const char *newTitle)

The string is treated first as a resource name that setTitle() looks up relative to the window. If the resource exists, its value is used as the window title. If the resource does not exist, or if the string contains spaces or newline characters, setTitle() uses the string itself as the window title. This allows applications to dynamically change a window title without hard-coding the exact title names in the application code. Example 21. shows an example of setting a window title using a resource value.

Retrieving the current title

You can retrieve the current window title using getTitle():

const char *getTitle()

Setting a window's icon title

The setIconName() function sets the title of a window's icon:

void setIconName(const char *newTitle)

The string is treated first as a resource name that setIconName() looks up relative to the window. If the resource exists, its value is used as the window's icon title. If the resource does not exist, or if the string contains spaces or newline characters, setIconName() uses the string itself as the icon title. This allows applications to dynamically change a window's icon title without hard-coding the exact title names in the application code. Example 21. shows an example of setting a window's icon title using a resource value.

Example 21. Setting Window and Icon Titles Using Resource Values

Code

class MainWindow : public VkSimpleWindow {
public:
MainWindow (const char *);
// ...
private:
static String _defaultResources[];
// ...
};
String _defaultResources[] = {
"*winTitle: Foobar Main Window",
"*iconTitle: Foobar",
NULL
};
MainWindow::MainWindow(const char *name) : VkSimpleWindow(name)
{
setDefaultResources(mainWindowWidget(), _defaultResources);
setTitle("winTitle");
setIconName("iconTitle");
// ...
}

Window Properties and Shell Resources

The window class constructors automatically set up various window properties and shell resources when you create a window. The window classes also provide some hooks to allow you to set your own properties or change the window manager message handling in a derived class.

Because the first window you create is by default the main window, the window class constructors also set some shell resources on the popup shell widget of that window. The constructors obtain the geometry of the invisible application shell created by VkApp and assign that geometry to the window's popup shell widget. The constructors also set the XmNargc and XmNargv resources on the popup shell to the values of VkApp::argc() and VkApp::argv() respectively. ("Application Data Access Functions" describes VkApp::argc() and VkApp::argv().)

For all windows, the window class constructors register a callback function to handle WM_DELETE_WINDOW messages from the window manager. This callback function calls handleWmDeleteMessage():

virtual void handleWmDeleteMessage()

By default, handleWmDeleteMessage() calls the window's okToQuit() function. If okToQuit() returns TRUE, then handleWmDeleteMessage() deletes the window. You can override handleWmDeleteMessage() to change how your window handles a WM_DELETE_WINDOW message. In most cases, you should simply perform any additional actions that you desire and then call the base class's handleWmDeleteMessage() function.

The window class constructors also register a callback function to handle WM_QUIT_APP messages from the window manager. This callback function calls handleWmQuitMessage():

virtual void handleWmQuitMessage()

By default, handleWmQuitMessage() calls the application's quitYourself() function to quit the application. You can override handleWmQuitMessage() to change how your windows handles a WM_QUIT_APP message. In most cases, you should simply perform any additional actions that you desire and then call the base class's handleWmQuitMessage() function to exit your application.

Setting additional properties on a window

If you want to set any additional properties on a window, you can override setUpWindowProperties():

virtual void setUpWindowProperties()

setUpWindowProperties() is called after realizing a window's popup shell widget but before mapping it. Subclasses that wish to store other properties on windows can override this function and perform additional actions. If you override this function, you should set all desired properties and then call the base class's setUpWindowProperties() function.


Note: Use setUpWindowProperties() to set window properties instead of VkComponent::afterRealizeHook() as described in "Displaying and Hiding Components" on page 19. The difference between the two is that setUpWindowProperties() is guaranteed to be called before the window manager is notified of the window's existence. Because of race conditions, this might not be true of afterRealizeHook().


You can also change the value of the window manager class hint stored on a window using setClassHint():

void setClassHint(const char *className)

setClassHint() sets the class resource element of the XA_WM_CLASS property stored on this window to the string you pass as an argument.

 

Documentation Type: