Controlling display of components and widgets

ViewKit ObjectPak provides some management classes that control the display of components and widgets. These classes function as attachments: you attach them to one or more existing widgets or components. Then you can use the management class to control some aspect of displaying the widgets and components to which the class is attached.

ViewKit Support for Aligning Widgets

The VkAlignmentGroup class provides support for aligning collections of widgets with each other in various ways. VkAlignmentGroup is derived from the convenience class VkWidgetList. Consult the VkWidgetList(3) reference page for more information on that class.

To use the VkAlignmentGroup class, you create a VkAlignmentGroup object, add widgets or components to the group, and then call one of the alignment functions provided by VkAlignmentGroup.

Alignment group constructor and destructor

The VkAlignmentGroup constructor does not take any arguments:

VkAlignmentGroup()

VkAlignmentGroup objects are not components and do not require names. ObjectPak uses names to uniquely identify widget trees of components, and VkAlignmentGroup class does not create any widgets.

The VkAlignmentGroup destructor destroys only the VkAlignmentGroup object, widgets managed by the object remain unaffected by the VkAlignmentGroup destructor.

Adding widgets and components to a group

Use the add() function to add widgets or components to a VkAlignmentGroup object:

virtual void add(Widget w)

virtual void add(VkComponent *obj)

virtual void add(VkOptionMenu *menu)

Add() behavior

Providing a widget causes add() to add the widget to the alignment group. Providing a pointer to a component adds the base widget of the component to the alignment group. Providing a pointer to a VkOptionMenu object adds each individual menu item to the VkAlignmentGroup object rather than adding the VkOptionMenu object as an entity.

Removing widgets and components

Remove widgets or components from a VkAlignmentGroup object with the remove() function inherited from VkWidgetList:

virtual void remove(Widget w)

virtual void remove(VkComponent *obj)

Provide the widget ID or component pointer that you used to add the widget or component to the alignment group.

Aligning and distributing

To align or distribute elements in a VkAlignmentGroup object, call one of the following functions (all take no arguments and have a void return type):

 

 

Alignment group access functions

VkAlignmentGroup provides the following access functions:

• VkAlignmentGroup::width() returns maximum width of all widgets in group. Value set after you call alignWidth().

  Dimension width()

• VkAlignmentGroup::height() returns maximum height of all widgets in group. Value set after you call alignHeight().

  Dimension height()

• VkAlignmentGroup::x() returns minimum x position of all widgets in group. Value set after you call either alignLeft() or alignRight().

  Position x()

• VkAlignmentGroup::y() returns minimum y position of all widgets in group. Value set after you call either alignTop() or alignBottom().

  Position y()

VkAlignmentGroup also inherits all access and utility functions provided by VkWidgetList. Refer to the VkWidgetList(3) reference page for more information on that class.

ViewKit Support for Resizing and Moving Widgets

VkResizer class provides controls for moving and resizing existing widgets. Figure 48. shows a simple example of a push button with a VkResizer attachment.

Figure 48. A Widget With a VkResizer Attachment

Use the left mouse button to click on either of the square handles provided by the VkResizer object to drag the handle to a new location. When you release the handle, the VkResizer object resizes the widget so that the widget matches the new size of the VkResizer object. Figure 49. shows an example of resizing the push button shown in Figure 48.

Figure 49. Effect of Resizing a Widget With a VkResizer Attachment

Use the middle mouse button to click on either of the square handles provided by the VkResizer object to drag the entire widget to a new location. When you release the handle, the VkResizer object moves the widget to the new location of the VkResizer object. Figure 50. shows an example of moving the push button shown in Figure 49.

Figure 50. Effect of Moving a Widget With a VkResizer Attachment

To use the VkResizer class, create a VkResizer object, associate an existing widget with the object, and then display the resizer's geometry controls.

Resizer constructor and destructor

The VkResizer constructor accepts two Boolean arguments:

VkResizer(Boolean autoAdjust = FALSE, Boolean liveResize = FALSE)

autoAdjust controls whether the VkResizer object automatically tracks outside geometry changes of its attached widget. If you set this value to TRUE, the VkResizer object automatically adjusts its geometry controls whenever its attached widget changes geometry. If you set this value to FALSE, you must call the VkResizer::adjustGeometry() function whenever you want the VkResizer object to adjust its geometry controls to the geometry of its attached widget. The default value of this argument is FALSE.

liveResize controls whether the widget itself or a rectangle representing the widget area is displayed during geometry changes. Setting the second parameter to TRUE causes intermediate geometry changes in the attached widget, which may affect performance. The default value is FALSE.

VkResizer objects do not require names because they are not components; ObjectPak uses names to uniquely identify the widget trees of components, and the VkResizer class does not create any widgets.

The VkResizer destructor destroys only the VkResizer object. If you have a widget attached to the object, it is unaffected by the VkResizer destructor.

Attaching and detaching a resizer object to and from a widget

Once you have created a VkResizer object, use the VkResizer::attach() function to attach it to an existing widget:

void attach(Widget w)

You can also attach a VkResizer object to a component by attaching it to the component's base widget. For example, if resizer is a VkResizer object and obj is a component, you can attach the resizer to the component as follows:

resizer->attach( obj->baseWidget() );

If the VkResizer object is already attached to a widget, it detaches from the old widget before attaching to the new one. You can use the VkResizer::detach() function to detach a VkResizer object from a widget without immediately attaching it to another:

void detach()

Displaying the resizer object's geometry controls

After attaching a VkResizer object to a widget, you must call the VkResizer object's VkResizer::show() function to display its geometry controls:

void show()

You can hide the geometry controls by calling the VkResizer object's VkResizer::hide() function:

void hide()

The VkResizer::shown() function returns a Boolean value indicating whether the VkResizer object is visible and displaying its geometry controls:

Boolean shown()

Resizer utility functions

You can configure the VkResizer object's geometry manipulations with the VkResizer::setIncrements() function:

void setIncrements(int resizeWidth, int resizeHeight,

int moveX, int moveY)

setIncrements() accepts four integer arguments. The first two arguments specify the resize increments in the horizontal and vertical dimension, respectively. The last two arguments specify the move increments in the horizontal and vertical dimension, respectively. Setting an increment to zero prohibits resizing or moving in that dimension.

ObjectPak callbacks associated with the resizer

The VkResizer class also provides a ObjectPak member function callback named VkResizer::stateChangedCallback:

static const char *const stateChangedCallback

This callback informs the application when VkResizer has modified the geometry of its attached widget. The callback supplies as call data a value of the enumerated type VkResizerReason (defined in <Vk/VkResizer.h>). The value can be any of VR_resizing, VR_moving, VR_resized, or VR_moved. VR_resizing and VR_moving indicate that resizing or moving are in progress, and are sent repeatedly as the user adjusts the geometry. VR_resized and VR_moved indicate that the resizing or moving is complete, and are sent when the user releases the VkResizer geometry controls.