Management Classes for Controlling Component and Widget Operation

ViewKit ObjectPak provides management classes that control the operation of components and widgets. These classes function as attachments, that is, you attach them to one or more existing widgets or components. You can then use the management class to control an aspect of operation of the widgets and components to which the class is attached.

Supporting "Ganged" Scrollbar Operation

The VkGangedGroup class provides support for "ganging" together OSF/Motif ScrollBar or Scale widgets so that all of them move together; when the value of one of the ScrollBar or Scale widgets changes. All other widgets in the group are updated with that value. VkGangedGroup is derived from the convenience class VkWidgetList. Consult the VkWidgetList(3) reference page for more information on that class.

To use the VkGangedGroup class, you create a VkGangedGroup object and add widgets or components to the group. Thereafter, the VkGangedGroup object automatically updates all of the scales and scrollbars in the group whenever the value of one of them changes.

Ganged scrollbar group constructor and destructor

The VkGangedGroup constructor does not take any arguments:

VkGangedGroup()

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

The VkGangedGroup destructor destroys only the VkGangedGroup object. If you have widgets or components managed by the object, they are unaffected by the VkGangedGroup destructor.

Adding scales and scrollbars to a ganged group

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

virtual void add(Widget w)
virtual void add(VkComponent *obj)

If you provide a widget, add() adds that widget to the alignment group. If you provide a pointer to a component, add() adds the component's base widget to the alignment group.


Note: If you add a component to a VkGangedGroup object, the base widget of that component must be an OSF/Motif ScrollBar or Scale widget.


Removing scales and scrollbars from a ganged group

You can remove widgets or components from a VkGangedGroup 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 ganged group.

You can also use the removeFirst() and removeLast() functions inherited from VkWidgetList to remove the first or last item respectively in the ganged group:

virtual void removeFirst()
virtual void removeLast()

Enforcing Radio-Style Behavior on Toggle Buttons

OSF/Motif supports collections of toggle buttons that exhibit one-of-many or "radio-style" behavior by placing all related buttons in a RadioBox widget. This is adequate in many cases, but in some cases it is useful to enforce radio-style behavior on a collection of buttons dispersed throughout an application.

The VkRadioGroup class provides support for enforcing radio-style behavior on an arbitrary group of toggle buttons, no matter where they appear in your application's widget hierarchy. The VkRadioGroup class supports both OSF/Motif ToggleButton and ToggleButtonGadget widgets. Furthermore, you can add OSF/Motif PushButton and PushButtonGadget widgets to a VkRadioGroup object; the VkRadioGroup object simulates radio-style behavior on these buttons by displaying them as armed when the user selects them (using the XmNarmColor color resource as the button's background color and displaying the XmNarmPixmap if the button contains a pixmap).

VkRadioGroup is derived from the convenience class VkWidgetList. Refer to the VkWidgetList(3) reference page for more information.

To use the VkRadioGroup class, create a VkRadioGroup object and add widgets or components to the group. Thereafter, the VkRadioGroup object automatically updates all buttons contained in the group whenever the user selects one of the buttons.


Note: Membership in a VkRadioGroup object is not exclusive; a widget can potentially belong to multiple groups at once.


Radio group constructor and destructor

The VkRadioGroup constructor does not take any arguments:

VkGangedGroup()

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

The VkRadioGroup destructor destroys only the VkRadioGroup object. If you have widgets or components managed by the object, they are unaffected by the VkRadioGroup destructor.

Adding Toggles and buttons to a radio group

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

virtual void add(Widget w)
virtual void add(VkComponent *obj)

If you provide a widget, add() adds that widget to the radio group. If you provide a pointer to a component, add() adds the component's base widget to the alignment group.


Note: If you add a component to a VkRadioGroup object, the base widget of that component must be an OSF/Motif ToggleButton, ToggleButtonGadget, PushButton, or PushButtonGadget widget.


Removing toggles and buttons from a radio group

You can remove widgets or components from a VkRadioGroup 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 radio group.

You can also use the removeFirst() and removeLast() functions inherited from VkWidgetList to remove the first or last item, respectively, in the radio group:

virtual void removeFirst()
virtual void removeLast()

Deriving radio group subclasses

If you use a direct instantiation of VkRadioGroup, you must rely on Xt callback functions registered directly with the toggle buttons to detect and handle state changes in the group. Another approach is to derive a subclass of VkRadioGroup and override the protected VkRadioGroup::valueChanged() function:

virtual void valueChanged (Widget w, XtPointer callData)

valueChanged() is called whenever any member of the radio group changes state. The first argument is the selected widget. The second argument is the call data from the XmNvalueChangedCallback (in the case of a ToggleButton or ToggleButtonGadget widget) or the XmNactivateCallback (in the case of a PushButton or PushButtonGadget widget).

You can override valueChanged() to receive notification of state changes and perform any actions you want. If you override valueChanged(), you should call VkRadioGroup::valueChanged() to update the states of all members of the radio group before performing any other actions.

Modified Text Attachment

The VkModifiedAttachment class provides support for tracking the previous and current values in an OSF/Motif Text or TextField widget. The VkModifiedAttachment class automatically displays a dogear (a "folded corner") in the upper-right corner of the text widget when the user changes the text value. Figure 58. shows an example of a text widget with a VkModifiedAttachment dogear.

Figure 58. VkModifiedAttachment Dogear

The user can "flip" between the previous and current text values by clicking on the dogear. Figure 59. demonstrates the results of flipping to a previous text value by clicking on the dogear.

Figure 59. Flipping to a Previous Text Widget Value using a
VkModifiedAttachment Dogear

When the user presses the <Return> key in the text field, the text displayed becomes the current value of the text field and the previously-displayed text becomes the previous value. If the current and previous values are the same, the VkModifiedAttachment object does not display the dogear; the VkModifiedAttachment object redisplays the dogear when the current and previous values are different.


Note: If the user clicks on the dogear before pressing the <Return> key, any changes the user made are discarded.


To use the VkModifiedAttachment class, you must: 1) create an OSF/Motif Text or TextField widget; 2) create a VkModifiedAttachment object; 3) attach the VkModifiedAttachment object to the widget; and 4) display the VkModifiedAttachment object (to display its dogear).

The VkModifiedAttachment class also provides several functions for retrieving the previous and current values of the text field, setting the value of the text field, and managing the display of the object.


Note: Because the VkModifiedAttachment class adds callback functions to handle the changes in value of the text widget, you should not register your own XmNactivateCallback or XmNvalueChangedCallback functions with the text widget. Instead, use the VkModifiedAttachment::modifiedCallback ObjectPak callback to determine when the text widget changes its value, and use the VkModifiedAttachment access functions to obtain the current or previous value of the text widget.


VkModifiedAttachment is derived from the VkModified base class, which tracks previous and current text values not necessarily associated with a text widget. In most cases, you will use the VkModifiedAttachment class; therefore, this section describes the functions inherited from VkModified along with the functions implemented by VkModifiedAttachment. For more information on the VkModified class, consult the VkModified(3) reference page.


Note: The VkModified and VkModifiedAttachment classes are both declared in the <Vk/VkModified.h> header file.


Modified text attachment constructor and destructor

The VkModifiedAttachment constructor accepts three Boolean values:

VkModifiedAttachment(Boolean blankIsValue = FALSE,
Boolean autoAdjust = TRUE,
Boolean incrementalChange = FALSE)

blankIsValue determines whether the VkModifiedAttachment object accepts a null string (a blank) as a valid previous value when displaying the dogear. If blankIsValue is FALSE, the VkModifiedAttachment object does not display the dogear if the previous value is blank.

autoAdjust determines whether the VkModifiedAttachment object automatically watches its attached text widget for geometry changes and adjusts its own area accordingly. If you set this value to FALSE, you must explicitly call VkModifiedAttachment::adjustGeometry() after changing the geometry of the text widget.

If incrementalChange is TRUE, each incremental change to the text value updates the current and previous values. In this mode, activation of the text widget's XmNvalueChangedCallback callback is considered an incremental change. Examples of incremental changes are: each character added or deleted, each deletion of selected characters, and each text insertion by pasting selected text. If incrementalChange is FALSE, the VkModifiedAttachment object updates the current and previous values only when the user presses the <Return> key in the text field.

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

Attaching and detaching modified text attachment to and from a widget

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

void attach(Widget w)

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

void detach()

Displaying and hiding modified text attachment

Once you have attached a VkModifiedAttachment object to a text widget, you must call VkModifiedAttachment::show() to display the attachment:

void show()

You can hide a VkModifiedAttachment object by calling VkModifiedAttachment::hide():

void hide()

When a VkModifiedAttachment object is hidden, it still tracks the current and previous values of the text widget to which it is attached; the user simply cannot toggle between the values. You can still use the VkModifiedAttachment class's access functions to retrieve the previous and current values of the text field.

VkModifiedAttachment::expose() forces a redraw of the attachment's dogear:

void expose()

expose() is called whenever the dogear widget receives an Expose event. Normally, you should not need to call this function.

Retrieving current and previous values of text widget

You can retrieve the current and previous values of the text widget with value() and previousValue() respectively:

char *value()
char *previousValue()

Note: Do not change or delete the character strings returned by value() and previousValue().


Detecting changes in text widget

The VkModifiedAttachment class provides an ObjectPak member function callback named VkModifiedAttachment::modifiedCallback:

static const char *const modifiedCallback

The VkModifiedAttachment object activates this callback whenever the text widget triggers its XmNactivateCallback or XmNvalueChangedCallback callback. The modifiedCallback provides a pointer to a VkModifiedCallback structure as call data. VkModifiedCallback has the following structure:

typedef struct {
VkModifiedReason reason;
class VkModified *obj;
XEvent *event;
} VkModifiedCallback

The VkModifiedCallback fields are:

reason Reason for callback. Can take one of two values: VM_activate, if text widget triggered its XmNactivateCallback callback, or VM_valueChanged if text widget triggered its XmNvalueChangedCallback callback.

obj Pointer to the VkModifiedAttachment object

event Pointer to the event that triggered the callback

Typically, your callback function should test the reason for the callback and perform an action if appropriate. For example, you can use one of the access functions to obtain the current or previous value of the text widget.


Note: Because the VkModifiedAttachment class adds callback functions to handle the changes in value of the text widget, you should not register your own XmNactivateCallback or XmNvalueChangedCallback callback functions with the text widget. Instead, always use the modifiedCallback ObjectPak callback to determine when the text widget changes its value.


Controlling the contents of the text widget

You can programmatically set the new current value of a VkModifiedAttachment object with VkModifiedAttachment::setValue():

virtual void setValue(const char *value)

setValue() sets the object's new current value; the old current value becomes the previous value. VkModifiedAttachment forces the text widget to display the new current value.

VkModifiedAttachment::toggleDisplay() programmatically toggles the text widget display between the current value and the previous value:

virtual void toggleDisplay()

To determine which value the text widget is displaying, call VkModifiedAttachment::latestDisplay():

Boolean latestDisplay()

latestDisplay() returns TRUE if the text widget is displaying the current value or FALSE if the text widget is displaying the previous value.

Finally, you can reset the contents of the text widget with VkModifiedAttachment::displayValue()

void displayValue()

displayValue() discards any changes the user may have made and updates the text widget with the current value (if the user has the current view selected) or the previous value (if the user has the previous view selected).

Adjusting the modified text attachment's geometry

By default, the VkModifiedAttachment object automatically watches its attached text widget for geometry changes and adjusts its own area accordingly. If you set the autoAdjust argument in the VkModifiedAttachment constructor to FALSE, you must explicitly call VkModifiedAttachment::adjustGeometry() after changing the geometry of the text widget to adjust the attachment's geometry:

void adjustGeometry()

You can also control the size of the VkModifiedAttachment dogear. By default, the dogear is 10 pixels wide by 10 pixels tall. You can set the width and height to different values with the VkModifiedAttachment::setParameters() function:

virtual void setParameters(Dimension width, Dimension height)

To retrieve the current width and height of the dogear, call VkModifiedAttachment::getParameters():

void getParameters(Dimension *width, Dimension *height)

Other modified text attachment utility and access functions

The VkModifiedAttachment class provides several additional utility and access functions:

  • VkModifiedAttachment::fixPreviousValue() allows you to specify a fixed value to use as the attachment's previous value. After setting a fixed previous value, the attachment does not update the previous value; this provides a "default" value that the user can always toggle to and use.

    If setValueAlso is TRUE, fixPreviousValue() also updates the attachment's current value to fixedValue; however, this does not permanently fix the current value.

    virtual void fixPreviousValue(char *fixedValue,

    Boolean setValueAlso = TRUE)

  • VkModifiedAttachment::widget() returns the text widget to which the VkModifiedAttachment object is currently attached.
    Widget widget()

  • VkModifiedAttachment::modified() returns TRUE if the current value and the previous value are equal and FALSE if they are not equal.
    Boolean modified()

  • VkModifiedAttachment::setModified() forces the value of the object's modified flag. If you set the value to TRUE, the VkModifiedAttachment object displays its dogear; otherwise, it hides its dogear.
    virtual void setModified(Boolean value)

X Resources associated with modified text attachment

You can set the value of an XmNdisplayModified resource for a text widget to determine whether or not the attached VkModifiedAttachment object should display its dogear. If you set the text widget's XmNdisplayModified resource to TRUE or if you do not provide a value for the text widget's XmNdisplayModified resource, the attached VkModifiedAttachment object displays its dogear. This is the default behavior.

If you set the text widget's XmNdisplayModified resource to FALSE, the attached VkModifiedAttachment object does not display its dogear, but it does continue to track the text widget's current and previous values. You can still use the functions and callbacks provided by VkModifiedAttachment to manipulate the values and manage the text widget.