Volume 6A: Motif Programming Manual

that are specific to these objects.

Frame

The purpose of the Frame widget is to provide a visible, three−dimensional border for objects such as

RowColumns or Labels that do not provide a border for themselves. In Motif 1.2, the Frame widget may have

two children: a work area child and a label child. With Motif 1.1, the Frame widget may have only one child.

In either case, the Frame sizes itself just big enough to contain its children.

PanedWindow

The PanedWindow manages its children in a vertically−tiled format. The widget takes its width from the

widest widget in its list of children. The PanedWindow also provides control sashes or grips that enable the

user to adjust the individual heights of the PanedWindow's children. Constraint resources for the

PanedWindow allow each child to specify its desired maximum and minimum height and whether it may be

resized.

DrawingArea

Although the DrawingArea widget is subclassed from the Manager widget class, it is not generally used in the

way that conventional managers are used. The widget does not do any drawing and it doesn't define any

keyboard or mouse behavior, although it does provide callbacks for user input. It is basically a free−form

widget that can be used for application−specific purposes. The widget provides callback resources to handle

keyboard, mouse, exposure, and resize events. While the DrawingArea widget can have children, it does not

manage them in any defined way. Since the DrawingArea widget is typically used for drawing, rather than for

managing other widgets, it is discussed separately in Chapter 10, The DrawingArea Widget.

ScrolledWindow

The ScrolledWindow widget provides a viewing area into another widget. The user can adjust the viewing

area using ScrollBars that are attached to the ScrolledWindow. The ScrolledWindow can handle scrolling

automatically, so that the application does not have to do any work. The widget also has an

application−defined mode, which allows an application to control all of the aspects of scrolling. Since the

operation of the ScrolledWindow is tied to the operation of ScrollBars, the two widgets are discussed together

in Chapter 9, ScrolledWindows and ScrollBars.

MainWindow

The MainWindow widget is subclassed from the ScrolledWindow widget. The MainWindow is the standard

layout manager for the main application window in a Motif application. The widget is designed to lay out a

MenuBar, a work area, ScrollBars, a command area, and a message area. Since the MainWindow is central to

any real Motif application, it is discussed separately in Chapter 4, The Main Window.

Scale

The Scale widget displays a slider object that has a specific value in a range of values. The user can adjust the

value of the widget by moving the slider. The Scale creates and manages its own widgets; the only children

that you can add to a Scale are Label widgets that represent tickmarks. The widget class is not meant to be a

general−purpose manager, so it is described separately in Chapter 13, The Scale Widget.

The MessageBox, SelectionBox, FileSelectionBox, and Command widgets are also Motif manager widgets.

These widgets are used for predefined Motif dialogs and are discussed in Chapter 5, Introduction to Dialogs;

Chapter 6, Selection Dialogs; and Chapter 7, Custom Dialogs.

9.2 Creating Manager Widgets

A manager widget may be created and destroyed like any other widget. The main difference between using a manager

9 Manager Widgets 9.2 Creating Manager Widgets

200

and other widgets involves when the widget is declared to be managed in the creation process. While we normally

suggest that you create widgets using XtVaCreateManagedWidget(), we recommend that you create a manager

widget using XtVaCreateWidget() instead, and then manage it later using XtManageChild(). To understand

why this technique can be important, you need to understand how a manager widget manages its children.

A manager widget manages its children by controlling the sizes and positions of the children. The process of widget

layout only happens when the child and the parent are both in the managed state. If a child is created as an unmanaged

widget, the parent skips over that widget when it is determining the layout until such time as the child is managed.

However, if a manager widget is not itself managed, it does not perform geometry management on any of its children

regardless of whether those children are managed. To be precise, a manager does not actually manage its children until

it is both managed and realized. If you realize all of your widgets at once, by calling XtRealizeWidget() on the

top−level widget of the application, as described in Chapter 2, The Motif Programming Model, it should not make a

difference whether a manager is managed before or after its children are created. However, if you are adding widgets

to a tree of already−realized widgets, the principles set forth in this section are important. If you are adding children to

an already−realized parent, the child is automatically realized when it is managed. If you are adding a manager widget

as a child of a realized widget, you should explicitly realize the widget before you manage it. Otherwise, the resize

calculations may be performed in the wrong order. In a case such as this, it is essential to use XtManageChild()

rather than XtVaCreateManagedWidget(), since doing so allows you to make the explicit realize call before

managing the widget.

To demonstrate the problems that you are trying to avoid, consider creating a manager as a managed widget before

any of its children are created. The manager is going to have a set of PushButtons as its children. When the first child

is added using XtVaCreateManagedWidget(), the manager widget negotiates the size and position of the

PushButton. Depending on the type of manager widget being used, the parent either changes its size to accommodate

the new child or it changes the size of the child to its own size. In either case, these calculations are not necessary

because the geometry needs to change as more buttons are added. The problem becomes complicated by the fact that

when the manager's size changes, it must also negotiate its new size with its own parent, which causes that parent to

negotiate with its parent all the way up to the highest−level shell. If the new size is accepted, the result goes back

down the widget tree with each manager widget resizing itself on the way down. Repeating this process each time a

child is added almost certainly affects performance.

Because of the different geometry management methods used by the different manager widgets, there is the possibility

that all of this premature negotiation can result in a different layout than you intended. For example, as children are

added to a RowColumn widget, the RowColumn checks to see if there is enough room to place the new child on the

same row or column. If there isn't, then a new row or column is created. This behavior depends heavily on whether the

RowColumn is managed and also on whether its size has been established by being realized. If the manager parent is

not managed when the children are added, the whole process can be avoided, yet you still have the convenience of

using XtVaCreateManagedWidget() for all of the widget children. When the manager is itself managed, it

queries its children for their size and position requests, calculates its own size requirements, and communicates that

size back up the widget tree.

For best results, you should use XtVaCreateWidget() to create manager widgets and

XtVaCreateManagedWidget() to create primitive widgets. Creating a primitive widget as an unmanaged

widget serves no purpose, unless you explicitly want the widget's parent to ignore it for some reason. If you are adding

another manager as a child, the same principle applies; you should also create it as an unmanaged widget until all its

children are added as well. The idea is to descend as deeply into the widget tree and create as many children as

possible before managing the manager parents as you ascend back up. Once all the children have been added,

XtManageChild() can be called for the managers so that they only have to negotiate with their parents once, thus

saving time, improving performance, and probably producing better results.

9 Manager Widgets 9.2 Creating Manager Widgets

201