[Top] [Prev] [Next] [Index]
Page 54 out of 116 total pages , Page 3 out of 5 pages in this chapter

ViewKit Preference Item Base Class

All preference items are derived from an abstract base class, VkPrefItem, which defines the structure of ViewKit ObjectPak preference items and provides a common set of manipulation functions.

Preference Item Labels

Most preference items contain two top-level widgets: a base widget and a label widget. The base widget implements the control mechanism for the preference item (for example, a text field, an option menu, or a toggle button). The label widget (implemented as a gadget) displays a text label for the item.

The name of the base widget is the string "Base" appended to the name of the preference item as given in its constructor. The name of the label widget is the string "Label" appended to the name of the preference item as given in its constructor. So, if you create a VkPrefText object named "firstName," the name of the base widget is "firstNameBase" and the name of the label widget is "firstNameLabel."

Setting XmNlabelString resource

To specify the string that is displayed as the label, you must set the XmNlabelString resource for the label widget. To set the XmNlabelString resource, use one of the following methods:

The code fragment in Example 38. sets the labels for two VkPrefText items using the first method.

Example 38. Setting Default Resource Values for Preference Items

Code

#include <Vk/VkPrefDialog.h>
#include <Vk/VkPrefItem.h>
class NameDialog: public VkPrefDialog {
  public:
    VkPrefText *firstName;
    VkPrefText *lastName;
    // ...
  protected:
    Widget createDialog(Widget)
  private:
    static String _defaultResources[];
    // ...
};
String NameDialog::_defaultResources[] = {
"*firstNameLabel.labelString:  First Name:",
"*lastNameLabel.labelString:   Last Name:",
};
Widget NameDialog::createDialog(Widget parent)
{
  setDefaultResources(mainWindowWidget(), _defaultResources);
  firstName = new VkPrefText("firstName");
  lastName = new VkPrefText("lastName");
  VkPrefList *nameList = new VkPrefList("nameList");
  // ...
}

Not all items display a label, for example VkPrefSeparator. Some preference items, such as VkPrefGroup, allow you to specify in the constructor whether or not you want to display a label for the item. The latter sections of this chapter describe individual preference items and how each item uses its label widget.

Obtaining and Setting Preference Item Values

Preference items that allow the user to input information--VkPrefText, VkPrefToggle, and VkPrefOption--have values associated with them. Each such item stores its own value internally. This value might or might not match the value currently displayed in the preference dialog. Because users can click on the Cancel button to return all preferences to their last applied values, a preference item must not immediately store a new value that a user enters. Only when the user clicks on the dialog's Apply button or OK button do preference items update their internally-stored values to match the values displayed on the screen.

getValue()

Preference items provide a getValue() function that updates the internally-stored value with the currently displayed value and returns the updated value. The getValue() function is not actually declared in the VkPrefItem base class because different types of preference items use different types of values (for example, VkPrefToggle uses a Boolean value whereas VkPrefText uses a character string). Each preference item with an associated value provides its own definition of getValue().

setValue()

The setValue() function allows you to programmatically set the internally-stored value of a preference item. The setValue() function automatically updates the displayed value to reflect the new internal value. As with the getValue() function, setValue() is not actually declared in the VkPrefItem base class; each preference item with an associated value provides its own definition of setValue().

The VkPrefItem::changed() function checks to see whether or not the user has changed the value displayed on the screen so that it no longer matches the item's internally-stored value:

virtual Boolean changed()

If the value has changed, changed() returns the Boolean value TRUE; otherwise, it returns FALSE. You should use changed() as a test to determine whether or not you need to call getValue() for a preference item.

Preference Item Access Functions

The activate() and deactivate() functions control whether or not a preference item is activated:

void activate()
void deactivate()

If the item is deactivated, the item is grayed out on the screen, and the user cannot change the item's value. Call activate() to activate an item and deactivate() to deactivate an item.

Occasionally, you might want to achieve certain effects by manually setting the height of a preference item's label or base widget. The setLabelHeight() and setBaseHeight() functions each accept an Xt Dimension value as and argument and set the item's label and base widget, respectively, to the entered height:

void setLabelHeight(Dimension h)
void setBaseHeight(Dimension h)

The labelHeight() function returns the current height of the item's label widget, and the baseHeight() function returns the current height of the item's base widget, each expressed as an Xt Dimension value:

Dimension labelHeight()
Dimension baseHeight()

The labelWidget() function returns the item's label widget:

Widget labelWidget()

labelWidget() returns NULL if an item does not have a label widget.

The type() function returns an enumerated value of type VkPrefItemType that identifies an item's type:

virtual VkPrefItemType type()

Valid return values include the following:

PI_group
PI_text
PI_empty
PI_custom
PI_list
PI_toggle
PI_label
PI_none
PI_radio
PI_option
PI_separator

The isContainer() function returns TRUE if the preference item is one used to group (or contain) other items:

virtual Boolean isContainer()

isContainer() returns true for VkPrefGroup, VkPrefRadio, and VkPrefList.



[Top] [Prev] [Next] [Index]
Page 54 out of 116 total pages , Page 3 out of 5 pages in this chapter

info@ics.com
Copyright © 1998, Integrated Computer Solutions, Inc. All rights reserved.