In ViewKit, preference dialogs are implemented as a specialized class of dialog. Specifically, the base preference dialog class, VkPrefDialog, is a subclass of VkGenericDialog, which is in turn a subclass of VkDialogManager. Thus, the VkPrefDialog class inherits all of the functions and data members provided by these base classes.

However, there are some significant differences in the way you use preference dialogs in your programs compared to the other dialog classes. For the other dialog classes, a single, reusable instance of each type of dialog is sufficient. Details such the message, the button labels, or the dialog title change from posting to posting, but the general dialog behavior remains the same.

On the other hand, individual postings of preference dialogs often vary significantly; they usually have greatly different preference items and data structures associated with each preference item. Therefore, unlike the other dialog classes, VkPrefDialog does not create a global instance of a preference dialog. Instead, you must create a separate instance of VkPrefDialog for each preference dialog that you want to display in your program. For very simple preference dialogs (for example, just a few toggle buttons), you might be able to directly instantiate a VkPrefDialog object; however, in most cases you should create a separate subclass of VkPrefDialog for each preference dialog in your application.

For each preference dialog, you create a collection of preference items and associate them with the dialog. Each preference item maintains its own state or value, and your program can query the value of preference items as needed. Users can change the values associated with any number of preference items, then click the Apply button to apply all changes and keep the dialog up, or the OK button to apply all changes and dismiss the dialog. Users can also click the Cancel button to return all preferences to their last applied values and dismiss the dialog.

The VkPrefDialog class also supplies a ViewKit callback named prefCallback. The preference dialog activates this callback whenever the user clicks the dialog's Apply, OK, or Cancel button.

The basis for all ViewKit preference item classes is the abstract class VkPrefItem, which is derived from VkComponent. All preference items are derived from the base class VkPrefItem, which provides a common set of manipulation functions.

Preference items can be divided into three groups: those that implement various controls such as text fields, toggles, and option menus; those that are “ornamental”; and those that arrange other preference items and manage them as a group.

The following preference items implement controls:

The following preference items are ornamental:

The following preference items create groups of items:

Each preference item maintains its own state or value, and your program can query the value of preference items as needed. Preference items automatically handle updating their stored values when the user clicks the preference dialog's Apply or OK button, and reverting to their previous values when the user clicks the dialog's Cancel button.

Figure 8-2 shows an example of a preference dialog created using the ViewKit classes.

Figure 8-2. ViewKit Preference Dialog

Example 8-1 lists the code used to create this preference dialog.

/////////////////////
//  DocPrefDiag.c++
/////////////////////
 
#include <Vk/VkApp.h>
#include <Vk/VkPrefDialog.h>
#include <Vk/VkPrefItem.h>
class DocPrefDialog: public VkPrefDialog {
 
 protected:
 
 VkPrefLabel *dialogName;
 VkPrefSeparator *sep1;
 VkPrefText *firstPageNumber;
 VkPrefOption *firstPageSide;
 VkPrefGroup *numberGroup;
 VkPrefSeparator *sep2;
 VkPrefToggle *paginSingleSide;
 VkPrefToggle *paginDoubleSide;
 VkPrefRadio *paginationGroup;
 VkPrefSeparator *sep3;
 VkPrefToggle *textQuotes;
 VkPrefToggle *textSpaces;
 VkPrefGroup *textGroup;
 VkPrefList *docList;
  
 static String _defaultResources[];
 virtual Widget createDialog(Widget parent);
 
 public:
 
 DocPrefDialog ( const char *name );
 ~DocPrefDialog();
 virtual const char* className();
};
 
String DocPrefDialog::_defaultResources[] = {
 “*dialogNameBase.labelString:	Document Properties”,
 “*numberGroupLabel.labelString:	Numbering:”,
 “*firstPageNumberLabel.labelString:	1st Page #:”,
 “*firstPageSideLabel.labelString:	1st Page:”,
 “*firstPageRight:			Right”,
 “*firstPageLeft:			Left”,
 “*paginationGroupLabel.labelString:	Pagination:”,
 “*paginSingleSideBase.labelString:	Single-sided”,
 “*paginDoubleSideBase.labelString:	Double-sided”,
 “*textGroupLabel.labelString:	Text:”,
 “*textQuotesBase.labelString:	Smart Quotes”,
 “*textSpacesBase.labelString:	Smart Spaces”,
 NULL
};
 
DocPrefDialog::DocPrefDialog ( const char *name ) : VkPrefDialog ( name )
{
 // Empty
}
 
Widget DocPrefDialog::createDialog(Widget parent) {
 
 setDefaultResources(parent, _defaultResources);
  
 VkPrefLabel *dialogName = new VkPrefLabel(“dialogName”);
  
 VkPrefSeparator *sep1 = new VkPrefSeparator(“sep1”);
  
 VkPrefText *firstPageNumber = new VkPrefText(“firstPageNumber”);
  
 VkPrefOption *firstPageSide = new VkPrefOption(“firstPageSide”, 2);
 firstPageSide->setLabel(0, “firstPageRight”);
 firstPageSide->setLabel(1, “firstPageLeft”);
  
 VkPrefGroup *numberGroup = new VkPrefGroup(“numberGroup”);
 numberGroup->addItem(firstPageNumber);
 numberGroup->addItem(firstPageSide);
  
 VkPrefSeparator *sep2 = new VkPrefSeparator(“sep2”);
  
 VkPrefToggle *paginSingleSide = new VkPrefToggle(“paginSingleSide”);
 VkPrefToggle *paginDoubleSide = new VkPrefToggle(“paginDoubleSide”);
  
 VkPrefRadio *paginationGroup = new VkPrefRadio(“paginationGroup”, TRUE);
 paginationGroup->addItem(paginSingleSide);
 paginationGroup->addItem(paginDoubleSide);
  
 VkPrefSeparator *sep3 = new VkPrefSeparator(“sep3”);
  
 VkPrefToggle *textQuotes = new VkPrefToggle(“textQuotes”);
 VkPrefToggle *textSpaces = new VkPrefToggle(“textSpaces”);
  
 VkPrefGroup *textGroup = new VkPrefGroup(“textGroup”, TRUE);
 textGroup->addItem(textQuotes);
 textGroup->addItem(textSpaces);
  
 VkPrefList *docList = new VkPrefList(“docList”);
 docList->addItem(dialogName);
 docList->addItem(sep1);
 docList->addItem(numberGroup);
 docList->addItem(sep2);
 docList->addItem(paginationGroup);
 docList->addItem(sep3);
 docList->addItem(textGroup);
  
 setItem(docList);
 
 Widget base = VkPrefDialog::createDialog(parent);
 
 return(base);
}
 
DocPrefDialog::~DocPrefDialog()
{
 // Empty
}
 
const char* DocPrefDialog::className()
{
 return “DocPrefDialog”;
}
 
 
void main ( int argc, char **argv )
{
 VkApp *app = new VkApp(“PrefDialogDemoApp”, &argc, argv);
 DocPrefDialog *docPrefs = new DocPrefDialog(“docPrefs”);
 
 docPrefs->show();
 app->run();
}

To post this dialog, you simply create an instance of the DocPrefDialog class and use one of the post() functions described in “Posting Dialogs”. For example:

DocPrefDialog *docPref = new DocPrefDialog("docPref");
// ...
docPref->post();

You can retrieve the value of a preference item with the getValue() function as described in “Getting and Setting Preference Item Values”. For example:

Boolean smartSpaces;
// ...
smartSpaces = docPref->textSpaces->getValue();

Most preference items contain two top-level widgets: a base widget and a label widget. The base widget implements the preference items “control” mechanism (for example, a text field, an option menu, or a toggle button). The label widget (actually 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.”

To specify the string that is displayed as the label, you must set the XmNlabelString resource for the label widget. There are various ways to do this:

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

#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. VkPrefSeparator is an example of this type of preference item. 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 sections appearing later in this chapter that describe individual preference items discuss how each item uses its label widget.

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 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 the dialog's Apply or OK button do preference items update their internally stored values to match the values displayed on the screen.

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().

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.

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 as an argument an Xt Dimension value and respectively set the item's label and base widget to the given 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 are: PI_group, PI_list, PI_radio, PI_text, PI_toggle, PI_option, PI_empty, PI_label, PI_separator, PI_custom, and PI_none.

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

virtual Boolean isContainer()

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

The VkPrefText class supports text field preference items, allowing users to enter text strings. Figure 8-3 shows a simple preference dialog containing a text field preference item.

Figure 8-3. Preference Dialog With a Text Field Preference Item

The VkPrefText constructor has the following form:

VkPrefText(const char *name, int columns = 5)

The VkPrefText constructor expects as its first argument the name of the preference item. You can optionally provide as a second argument an integer value specifying the default number of columns for the text field.

For example, creating the text field shown in Figure 8-3 requires only this line:

VkPrefText *name = new VkPrefText("name");

To set the label for the text field you must set the XmNlabelString resource of the preference item's label widget. Therefore, to set the label as shown in Figure 8-3, you must set the resource:

*nameLabel.labelString: Enter your name:

Refer to “Preference Item Labels” for more information on setting the label of a preference item.

Use the getValue() function to retrieve the internally-stored value of the text field:

char *getValue()

getValue() duplicates the internal value and then returns a pointer to the duplicate string. (You should free this string when you no longer need it.) For example, the following line retrieves the value of the name text field shown above:

userName = name->getValue();

Use the setValue() function to programmatically set the value of the text field:

void setValue(const char *str)

setValue() copies the string that you pass as an argument, sets the internally-stored value to that string, and updates the value displayed by the text field. For example, the following line sets the value of the name text field shown above to “John Doe”:

name->setValue("John Doe");

The VkPrefToggle class supports a single toggle button preference item. You can group multiple toggle buttons using a VkPrefGroup or VkPrefList item, and you can enforce radio-style behavior on a group of toggles by grouping them in a VkPrefRadio item. These classes are discussed later in this chapter.

Figure 8-4 shows a simple preference dialog containing a single toggle button preference item.

Figure 8-4. Preference Dialog With Toggle Button Preference Item

The VkPrefToggle constructor has the following form:

VkPrefToggle(const char *name, Boolean forceLabelFormat = FALSE)

The first argument the VkPrefToggle constructor expects is the name of the preference item. For example, creating the toggle button shown in Figure 8-4 requires only the line:

VkPrefToggle *erase = new VkPrefToggle("erase");

You can provide an optional Boolean value as a second argument to the VkPrefToggle constructor. A TRUE value forces the VkPrefToggle object to create and use a label widget as described in “Preference Item Labels”. Otherwise, if the value is FALSE, the behavior of the label is determined as described below in “Setting Toggle Preference Item Labels.” The default value is FALSE.

Setting Toggle Preference Item Labels

Setting the label for a toggle preference item is more complex than with other preference items. Unlike many of the other preference items, the ToggleButton widget that is the base widget of the VkPrefToggle item includes a text label. Therefore, to set that label, you must set the XmNlabelString resource of the preference item's base widget instead of its label widget. For example, to set the label as shown in Figure 8-4, you must set the resource:

*eraseBase.labelString: History Erase

This works for all cases except for when a toggle is an item in a vertical VkPrefGroup or VkPrefRadio item that contains items other than toggles. (A group that contains more than one type of preference item is a non-homogenous group; a group that contains only one type of preference item is a homogenous group.) To understand why this is done, consider first a simple vertical VkPrefGroup containing only two toggle buttons, as shown in Figure 8-5. In this case, the labels appear to the right side of the buttons as they normally do.

Figure 8-5. Toggle Preference Items in a Homogenous Vertical Group

When toggle items appear in a homogenous group like the one shown in Figure 8-5, you should set the XmNlabelString resources for the base widgets of the toggle items. For example:

*firstToggleBase.labelString:  Toggle One *secondToggleBase.labelString: Toggle Two

However, the labels for most other preference items appear to the left of the items. Left uncorrected, if a vertical, non-homogenous VkPrefGroup or VkPrefRadio contained a toggle item, the label for the toggle would not align with the other labels.

Therefore, in the case of a non-homogenous vertical VkPrefGroup or VkPrefRadio, ViewKit sets the XmNlabelString resource of all toggle items' base widgets to NULL and instead displays their label widgets. The result is that all of the preference items' labels correctly align, as shown in Figure 8-6.

Figure 8-6. Toggle Preference Items in a Non-Homogenous Vertical Group

When toggle items appear in a non-homogenous, vertical group like the one shown in Figure 8-6, you should set the XmNlabelString resources for the label widgets of the toggle items rather than the base widgets. For example:

*firstToggleLabel.labelString:  Toggle One *secondToggleLabel.labelString: Toggle Two

Note that if you provide the Boolean value TRUE as a second argument to the VkPrefToggle constructor, the VkPrefToggle object always creates and uses a label widget instead of using the base widget's text label.

Refer to “Preference Item Labels” for more information on setting the label of a preference item.

Boolean getValue()

toggleSet = firstToggle->getValue();

void setValue(Boolean value)

secondToggle->setValue(TRUE);

The VkPrefOption class supports option menu preference items, allowing users to choose an option from a menu. Figure 8-7 shows a simple preference dialog containing an option menu preference item.

Figure 8-7. Preference Dialog With Option Menu Preference Item

The VkPrefOption constructor has the following form:

VkPrefOption(const char *name, int numEntries)

The VkPrefOption constructor expects as its first argument the name of the preference item. The second argument is an integer value specifying the number of entries in the option menu.

For example, you can create the option menu shown in Figure 8-7 with this line:

VkPrefOption *align = new VkPrefOption("align", 3);

Setting Option Menu Preference Item Labels

To set the label for the option menu, you must set the XmNlabelString resource of the preference item's label widget. Therefore, to set the label as shown in Figure 8-7, you must set the resource as follows:

*alignLabel.labelString: Alignment

Refer to “Preference Item Labels” for more information on setting the label of a preference item.

To set the labels for the individual items in the option menu, use the setLabel() function:

void setLabel(int index, const char *label)

setLabel() expects two arguments. The first is an integer value specifying the index of the of the menu item. Menu items are numbered starting with 0.

The second setLabel() argument is a character string. This string is first treated as a resource name which is looked up relative to the menu item's widget. If the resource value exists, it is used as the label. If no resource is found, or if the string contains spaces or newline characters, the string itself is used as the label.

For example, the following lines directly set the labels for the option menu items shown in Figure 8-7:

align->setLabel(0, "Align Left"); align->setLabel(1, "Align Center"); align->setLabel(2, "Align Right");

On the other hand, the following lines set the labels using resource values:

align->setLabel(0, "alignLeft"); align->setLabel(1, "alignCenter"); align->setLabel(2, "alignRight");

In the second case, you would also have to set the appropriate resource values. You could do so using the setDefaultResources() function, or you could include the following lines in a resource file:

*align*alignLeft: Align Left *align*alignCenter: Align Center *align*alignRight:  Align Right

You can retrieve the label for a given item using the getLabel() function:

char *getLabel(int index)

index is the index of the menu item.

---

Note: getLabel() returns the same string that you passed to setLabel() when setting the item's label. Therefore, if you set the item's label by specifying a resource name, getLabel() returns the resource name, not the value of the resource.

---

void setSize(int numEntries)

int size()

Widget getButton(int index)

int getValue()

alignment = align->getValue();

void setValue(int index)

align->setValue(1);

The VkPrefLabel class supports text labels for preference dialogs.

---

Note: VkPrefLabel is useful only in conjunction with VkPrefList. You should not use VkPrefLabel with either VkPrefGroup or VkPrefRadio; VkPrefLabel does not create a label widget and therefore it does not align properly with other items contained in a VkPrefGroup or VkPrefRadio item.

---

Figure 8-8 shows a simple preference dialog containing a label preference item.

Figure 8-8. Preference Dialog With Label Preference Item

The only argument the VkPrefLabel constructor expects is the name of the preference item:

VkPrefLabel(const char *name)

For example, creating the label shown in Figure 8-8 requires only this line:

VkPrefLabel *dialogName = new VkPrefLabel("dialogName");

Many other ViewKit preference items include label widgets in addition to their base widget; however, in the case of the VkPrefLabel item, the label is the base widget. Therefore, in preference item groups, a VkPrefLabel item aligns with other base widgets, not with other label widgets.

Because the label that is displayed for a VkPrefLabel item is the base widget, you set the label's text by setting the XmNlabelString resource of the item's base widget. Therefore, to set the label as shown in Figure 8-8, you must set the resource as follows:

*dialogNameBase.labelString: Document Properties

Refer to “Preference Item Labels” for more information on setting the label of a preference item.

The VkPrefSeparator class supports a simple separator for use in preference dialogs.

---

Note: VkPrefSeparator is useful only in conjunction with VkPrefList. You should not use VkPrefSeparator with either VkPrefGroup or VkPrefRadio; VkPrefSeparator does not create a label widget and therefore it does not align properly with other items contained in a VkPrefGroup or VkPrefRadio item.

---

The only argument the VkPrefSeparator constructor expects is the name of the preference item:

VkPrefSeparator(const char *name)

For example:

VkPrefSeparator *sep = new VkPrefSeparator("sep");     

The VkPrefEmpty class provides a “null” item that you can use to add extra space between other items. This preference item is useful only in conjunction with one of the grouping preference items: VkPrefGroup, VkPrefRadio, or VkPrefList.

The VkPrefEmpty constructor accepts no arguments:

VkPrefEmpty()

For example:

VkPrefEmpty *space = new VkPrefEmpty();

ViewKit provides three classes for creating groups of items: VkPrefGroup, VkPrefRadio, and VkPrefList. Both VkPrefRadio and VkPrefList are implemented as subclasses of VkPrefGroup.

Comparison of Group Preference Items

VkPrefGroup defines a group of related items. You can specify either vertical or horizontal layout; the default is vertical. With a vertical layout, VkPrefGroup pads items so that they take equal space. You have the option of displaying a label for the group.

Figure 8-9 shows an example of a vertical VkPrefGroup item with a label. The label is the group item's label widget, not a VkPrefLabel item. The VkPrefGroup item right-aligns the labels for all of the items it contains. (Because the VkPrefToggle items are part of a non-homogenous VkPrefGroup item, you must set the XmNlabelString resources of their label widgets instead of their base widgets, as described in “Setting Toggle Preference Item Labels”.) Also, all items are allocated the same amount of vertical space. If you were to add a larger item to this group, the group item would allocate for each item the same amount of vertical space.

Figure 8-9. Vertical VkPrefGroup Item With Label

Figure 8-10 shows the same preference items grouped by a horizontal VkPrefGroup item with a label.

Figure 8-10. Horizontal VkPrefGroup Item With Label

VkPrefList is similar to VkPrefGroup; however, it supports only a vertical orientation and it does not support displaying a group label. Unlike VkPrefGroup, VkPrefList does not pad its items so that they take equal space; instead, each item takes only as much space as it needs. Typically, you use a VkPrefList item to group other group items. For example, in Example 8-1, the top-level VkPrefList item contained a VkPrefLabel item and two VkPrefGroup items—one vertical and one horizontal—separated by two VkPrefSeparator items.

VkPrefList is also the only grouping item to which you should add VkPrefLabel or VkPrefSeparator items. You should not use VkPrefLabel or VkPrefSeparator with either VkPrefGroup or VkPrefRadio; they do not create label widgets and therefore do not align properly with other items contained in a VkPrefGroup or VkPrefRadio item.

Figure 8-11 shows an example of a VkPrefList. Note that the VkPrefList item does not contain a group label; if you want to provide a label for a VkPrefList item, you can include a VkPrefLabel item in it. Also note that the VkPrefList item does not align the labels of the items it contains. (Because the VkPrefToggle items are part of a VkPrefList item, you must set the XmNlabelString resources of their base widgets instead of their label widgets, as described in “Setting Toggle Preference Item Labels”.) Each item is allocated only as much vertical space as it needs. If you were to add a larger item to this group, it would not affect the vertical spacing of the other items.

Figure 8-11. VkPrefList Item

VkPrefRadio is almost identical to VkPrefGroup except that you use it only for enforcing radio-style behavior on the VkPrefToggle items that it contains. You should add only VkPrefToggle items to a VkPrefRadio item. Otherwise, VkPrefRadio supports the same functionality as VkPrefGroup.

Figure 8-12 shows an example of a vertical VkPrefRadio item with a label. The label is the group item's label widget, not a VkPrefLabel item. Because the VkPrefToggle items are part of a homogenous VkPrefRadio item, you must set the XmNlabelString resources of their base widgets instead of their label widgets, as described in “Setting Toggle Preference Item Labels”.

Figure 8-12. VkPrefRadio Item With Label

VkPrefGroup(const char *name,		
            Boolean horizOrientation = FALSE,
            Boolean noLabel = FALSE)

VkPrefGroup *numberGroup = new VkPrefGroup("numberGroup");

VkPrefGroup *horizGroup = new VkPrefGroup("horizGroup",
                                          TRUE, TRUE);

VkPrefRadio(const char *name, 
            Boolean horizOrientation = FALSE,
            Boolean noLabel = FALSE)

VkPrefRadio *paginationGroup = new VkPrefRadio("paginationGroup");

VkPrefList(const char *name)

VkPrefList *docList = new VkPrefList("docList");     

void addItem(VkPrefItem *item)

docList->addItem(dialogName);
docList->addItem(sep1);
docList->addItem(numberGroup);
docList->addItem(sep2);
docList->addItem(horizGroup);       

VkPrefItem *item(int item)

item = docList->index(2);     

int size()

virtual void deleteChildren()

*numberGroupLabel.labelString:      Numbering:
*paginationGroupLabel.labelString:  Pagination:
*textGroupLabel.labelString:        Text:

Unlike the other dialog classes, VkPrefDialog does not create a global instance of a preference dialog. Instead, you must create a separate instance of VkPrefDialog for each preference dialog that you want to display in your program. For very simple preference dialogs (for example, just a few toggle buttons), you might be able to directly instantiate a VkPrefDialog object; however, in most cases you should create a separate subclass of VkPrefDialog for each preference dialog in your application. This is described in “Creating Preference Dialog Subclasses”.

The form of the VkPrefDialog constructor is as follows:

VkPrefDialog(const char *name, VkPrefItem *item = NULL)

The VkPrefDialog constructor expects as its first argument the name of the preference dialog. The second argument is an optional pointer to a preference item that the dialog should use as the top-level preference item. See “Setting the Preference Items for a Preference Dialog” for more information on setting the top-level preference item.

For example, the following line creates a preference dialog named “simplePref”:

VkPrefDialog *simplePref = new VkPrefDialog("simplePref");     

A preference dialog can have only one top-level preference item. In most cases, you use a group item such as VkPrefList as the top-level item.

As described in “Creating a Preference Dialog”, you can set the top-level preference item in the VkPrefDialog constructor. You can also set the top-level item with the setItem() function:

void setItem(VkPrefItem *item)

---

Note: If the preference dialog already has a top-level preference item associated with it, setItem() replaces that item with the new item, but does not delete the old item. This allows you to reuse the old preference item later.

---

For example, the following line sets the item docList as the top-level item of the preference dialog simplePref:

simplePref->setItem(docList);

The item() function returns a pointer to the top-level item associated with a preference dialog:

VkPrefItem *item()

You post preference dialogs using any of the various post() variants provided by the base ViewKit dialog classes. You should not pass a message string argument to the post() function when posting a preference dialog.

For example, the following line posts the simplePref dialog as a non-modal, non-blocking dialog:

simplePref->post();   

You should rarely have to unpost a preference dialog programmatically. ViewKit automatically dismisses a preference dialog when the user clicks either the OK or Cancel button. If for some reason you do need to unpost a preference dialog from your program, use the unpost() function.

When the user clicks the OK or Apply button on a preference dialog, the dialog automatically applies any change of values to the preference dialog's items by setting the items's internally-stored values so that they match whatever is currently displayed on the screen. If the user clicks the OK button, the preference dialog calls its hide() function to remove itself from the screen. If the user clicks on the Apply button, the preference dialog remains visible on the screen.

When the user clicks the Cancel button on a preference dialog, the dialog automatically resets all of the dialog's preference items's on-screen values so that they match the items's internally-stored values. Additionally, the preference dialog calls its hide() function to remove itself from the screen.

The VkPrefDialog class also supplies a ViewKit member function callback named prefCallback. The preference dialog activates this callback whenever the user clicks the dialog's Apply, OK, or Cancel button. The callback passes as call data an enumerated value of type VkDialogReason, which is defined in VkDialogManager. The value can be any of VkDialogManager::OK, VkDialogManager::APPLY, or VkDialogManager::CANCEL, corresponding to the button that the user clicked. To notify components in your application when the user changes preferences associated with a preference dialog, register member functions with this ViewKit callback.

---

Note: When the user clicks the OK button, ViewKit first updates the preference items's internally stored values and activates the prefCallback callback with VkDialogManager::APPLY as the call data. Then, ViewKit activates the prefCallback callback with VkDialogManager::OK as the call data. In some ways, this is analogous to an Motif pushbutton performing an activate() action followed by a disarm() action when a user clicks it. You can use this feature to perform certain actions whenever the user updates preference values by clicking either the Apply or OK button, and a separate set of actions when the user dismisses the preference dialog by clicking the OK button.

---

For example, consider a window, myWindow, that is a member of the subclass MyWindow, derived from VkWindow. In this example, assume that there is a preference dialog, displayPrefs, that is a member of the subclass DisplayPrefDialog, derived from VkPrefDialog, that allows the user to specify certain display parameters such as the font. myWindow could register its member function MyWindow::fontChanged() to be called whenever the user clicks a button in the preference dialog displayPrefs, by using the following line of code:

displayPrefs->addCallback(VkPrefDialog::prefCallback,
                  this,
                  (VkCallbackMethod) &MyWindow::fontChanged);

When MyWindow::fontChanged() is called, it checks to see if any of the parameters in which it is interested have changed and, if so, performs whatever processing is needed. For example:

void MyWindow::fontChanged(VkComponent *obj,
                           void *clientData,
                           void *callData)
{
  DisplayPrefDialog *dialog = (DisplayPrefDialog*) obj;
  MyWindow *win = (MyWindow*) clientdata;
  VkDialogManager::VkDialogReason reason =
                  (VkDialogManager::VkDialogReason) callData;
  // If the user clicked Cancel, nothing changed
  if (reason == VkDialogManager::CANCEL)
    return;
  // Now process new preference values as needed ...
}       

To retrieve the value of a preference item, simply call that item's getValue() function.

This implies that preference items must be accessible to all components that need to use the preference values. For example, if you create a subclass for a preference dialog, declare as “public” those preference items that you want to access outside of the dialog.

Example 8-3 shows the header for a NamePref subclass in which two preference items, firstName and lastName, are declared “public.” These two preference items can be accessed by other components in the applications.

class NamePref: public VkPrefDialog {
 
  protected:
    VkPrefGroup *nameGroup;
  
    static String _defaultResources[];
    virtual Widget createDialog(Widget parent);
 
  public:
    VkPrefText *firstName;
    VkPrefText *lastName;
 
    NamePref ( const char *name );
    ~NamePref();
    virtual const char* className();
};

The NamePref subclass also contains a group, nameGroup, which is declared “protected.” In most cases, outside components would not need to access a group item. One case in which it could be useful to make a group item publicly accessible is if you want other components to be able to activate and deactivate a group of preference items by calling the activate() and deactivate() functions on that group item.

The preferred method of handling preference dialogs in ViewKit applications is to create a separate subclass for each preference dialog in the application. Properly designed, a preference dialog can serve as a self-contained component that you can use in multiple applications.

The first step in creating a preference dialog subclass is to decide what preference items to include. List all of the information you want to be able to set with the preference dialog and determine which preference item class is appropriate for each item. For example, an item requiring text input is an obvious candidate for a VkPrefText item. However, an item allowing the user to choose one of several options can be handled by either a single VkPrefOption item or a number of VkPrefToggle items grouped with a VkPrefRadio item. Presumably, you want all of these preference items to be accessible outside of the preference dialog, so you want to declare these items in the “public” section of your class declaration.

Then determine the layout you want for the preference dialog. You should group similar items together so that a user can easily find and set related items. The layout determines what group items you need. Usually, you can define these items in the “private” or “protected” section of your class declaration; however, in some cases, you might want to declare some groups as “public.” For example, you might want to be able to activate and deactivate a group of preference items by calling the activate() and deactivate() functions on that group item.

Then determine how you want to “publicize” changes in preference items to other components in your application. In many cases, those components can simply call the getValue() functions for appropriate items as needed. However, some components need to be notified immediately whenever certain preference items change. In most cases, these components can register ViewKit member function callbacks with the preference dialog that are called whenever the user clicks one of the dialog's buttons. The components can then test for changes in preference item values in their callback functions and react accordingly.

In some cases, you might need to perform special processing when the user clicks one of the preference dialog's buttons. In that case, you can override the default ok(), apply(), or cancel() function for the dialog. These functions are called whenever the user clicks the corresponding button. In your override definition, you should perform whatever processing is needed and then call the base VkPrefDialog::ok(), VkPrefDialog::apply(), of VkPrefDialog::cancel() function as appropriate.

Usually you should also provide a set of default resource values to serve as labels for all the dialog's preference items. To do so, you must override the createDialog() function, which creates and manages all of the widgets in a preference dialog. Your preference dialog's createDialog() function must perform the following tasks, in order:

Example 8-1 shows a complete example of a preference dialog subclass. You could include DocPrefDialog dialogs in any application that needed to set various document parameters.