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:

• Use the VkComponent::setDefaultResources() function to provide default resource values. See "Creating Preference Dialog Subclasses" for information on using the setDefaultResources() function when you create a subclass of VkPrefDialog.
• Set resource values in an external app-defaults resource file. Any values you provide in an external file will override values that you set using the VkComponent::setDefaultResources() function. This is useful when your application must support multiple languages; you can provide a separate resource file for each language supported.
• Set the resource value directly using the XtSetValues() function. Values you set using this method override any values set using either of the above two methods. You should avoid using this method as it "hard codes" the resource values into the code, making them more difficult to change.

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:

 

 

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.