Top-level shell widgets

This section describes how to create and use top-level shell widgets (CwTopLevelShell). Some commonly used shell resources and callbacks are discussed. A list of all resources and callbacks used by top-level shells is in Appendix A, "Widget resources and callbacks".

The root of a widget tree must be a CwTopLevelShell. A top level shell widget has no parent. Top-level shells are created using the createApplicationShell:argBlock: method, which is sent to the CwTopLevelShell class. A top-level shell widget must have a child widget before it can be realized.

Tip:

A common programming error is to attempt to realize a top level shell that has no child widget, or whose child widget computes an initial size with zero width or height. On a Motif platform this normally causes the application to exit with the message: "Error: Shell widget has zero width or height." VA Smalltalk detects most common cases and prevents the application from exiting.

The following example creates a top-level shell with a main window widget as its child. In this example, the main window's width and height are explicitly set. However a main window is not usually given explicit dimensions. It is usually left to calculate its dimensions based on the needs of its children.

| shell mainWindow |

shell := CwTopLevelShell

createApplicationShell: 'shell'

argBlock: [:w | w title: 'Shell Example 1'].

mainWindow := shell

createMainWindow: 'main'

argBlock: [:w | w width: 100; height: 100].

mainWindow manageChild.

shell realizeWidget.

The resources for CwTopLevelShell include title, mwmDecorations, icon, iconPixmap, and iconMask. The mwmDecorations resource indicates which decorations are to be added to the shell. The following table lists the bit masks used to specify decorations. The icon (or iconPixmap) resources indicate the icon (or pixmap) to be used by the window manager for the application's icon, and the iconMask resource indicates the pixmap to clip to if the icon is non-rectangular.

Table 36. TopLevel shell decoration resource flags

Decoration Literal	Definition
MWMDECORALL	If set, changes the meaning of the other flags to indicate that the specified decoration should be removed from the default set.
MWMDECORBORDER	Include a border.
MWMDECORRESIZEH	Include resize frame handles.
MWMDECORTITLE	Include title bar.
MWMDECORMENU	Include window close/system menu.
MWMDECORMINIMIZE	Include minimize window button.
MWMDECORMAXIMIZE	Include maximize window button.

 

Tip:

The top-level shell decorations settings indicate the preferred configuration for the window. The window manager can alter or ignore the settings if particular combinations are not supported by the platform.

In the following example, the shell's mwmDecorations resource is explicitly altered in the create argBlock to specify that the minimize button should not be provided.

| shell main |

shell := CwTopLevelShell

createApplicationShell: 'shell'

argBlock: [:w |

w

title: 'Shell Example 2';

mwmDecorations: MWMDECORALL | MWMDECORMINIMIZE].

main := shell

createMainWindow: 'main'

argBlock: [:w | w width: 100; height: 100].

main manageChild.

shell realizeWidget.