The VkCheckBox class, derived from VkComponent, provides a simple method for creating check boxes. Instantiating the component creates an empty, labeled component to which you can add individual toggle buttons. VkCheckBox provides a variety of methods for determining when the user changes the state of a toggle; you can use the method most convenient for your applications. You can also programmatically change the values of the toggles.
Creating a Check Box
The VkCheckBox constructor accepts the standard ObjectPak component name and parent widget arguments:
- VkCheckBox(const char *name, Widget parent)
The constructor creates an empty, labeled component.
Adding Toggles to the Check Box
You add toggles to the check box using the VkCheckBox::addItem() function:
name is the name of the toggle item. You can specify its initial state by providing a state argument; TRUE sets the toggle and FALSE clears it.
You can also provide an Xt-style callback function, proc, that VkCheckBox activates whenever the user changes the value of the toggle; and clientData, which VkCheckBox passes as client data to the callback function. Following ObjectPak conventions as described in "Using Xt Callbacks with Components" , if you provide a callback function, you should pass the this pointer as client data so that the callback functions can retrieve the pointer, cast it to the expected component type, and call a corresponding member function. "Recognizing Changes in Check Box Toggle Values" further discusses how to use the callback function.
Setting Check Box and Toggle Labels
The VkCheckBox component creates a LabelGadget named "label" to display a label. Each toggle in the check box is implemented as a ToggleButtonGadget. The name of the gadget is the name string that you provide to addItem() when you add the toggle.
Setting labels
Set the XmNlabelString resource of the check box label and its toggles to set their labels:
- Use the VkComponent::setDefaultResources() function to provide default resource values as described in "Setting Default Resource Values for a Component" .
- 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 values 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.
For example, Figure 52. illustrates a simple window that contains only a check box with four toggles:
Figure 52. Example Check Box
The following example shows the code used to create this check box.
Example 41. Creating a Check Box
Code
- #include <Vk/VkApp.h>
- #include <Vk/VkSimpleWindow.h>
- #include <Vk/VkCheckBox.h>
- class CheckBoxWindow: public VkSimpleWindow {
- protected:
- virtual Widget setUpInterface ( Widget parent );
- static String _defaultResources[];
- public:
- CheckBoxWindow ( const char *name ) : VkSimpleWindow ( name ) { }
- ~CheckBoxWindow();
- virtual const char* className();
- };
- CheckBoxWindow:: ~CheckBoxWindow()
- { }
- const char* CheckBoxWindow::className() { return "CheckBoxWindow"; }
- String CheckBoxWindow::_defaultResources[] = {
- "*check*label.labelString: Selections:",
- "*check*one*labelString: First choice",
- "*check*two*labelString: Second choice",
- "*check*three*labelString: Third choice",
- "*check*four*labelString: Fourth choice",
- NULL
- };
- Widget CheckBoxWindow::setUpInterface ( Widget parent )
- {
- setDefaultResources(parent, _defaultResources);
- VkCheckBox *cb = new VkCheckBox("check", parent);
- cb->addItem("one");
- cb->addItem("two");
- cb->addItem("three");
- cb->addItem("four");
- cb->show();
- return cb->baseWidget();
- }
- void main ( int argc, char **argv )
- {
- VkApp *cbApp = new VkApp("checkBoxApp", &argc, argv);
- CheckBoxWindow *cbWin = new CheckBoxWindow("checkbox");
- cbWin->show();
- cbApp->run();
- }
Setting and Obtaining Check Box Toggle Values
After creation, you can programmatically set the state of any toggle with the VkCheckBox::setValue() function:
- void setValue(int index, Boolean newValue)
index is the position of the toggle in the check box; the first toggle in the check box has an index of 0. newValue is the new state for the toggle; TRUE sets the toggle and FALSE clears it.
Note: Setting a toggle using setValue() activates the toggle's valueChanged callback. This in turn activates all of the VkCheckBox object's methods for detecting changes in toggle values as described in "Recognizing Changes in Check Box Toggle Values" on page 293.
Setting values of multiple toggles
You can set the values of multiple toggles using the VkCheckBox::setValues() function:
- void setValues(Boolean *values, int numValues)
The Boolean array values specifies the new values for a group of toggles in the check box beginning with the first toggle. numValues specifies the number of values the values array contains.
Note: Setting toggles using setValues() activates each toggle's valueChanged callback, which activates all of the VkCheckBox object's methods for detecting changes in toggle values. Refer to "Recognizing Changes in Check Box Toggle Values" for more information on each toggle.
Retrieving a specific toggle value
You can retrieve the value of a specific toggle with the VkCheckBox::getValue() function:
- int getValue(int index)
index is the position of the toggle in the check box; the first toggle in the check box has an index of 0. The function returns TRUE if the toggle is set and FALSE if the toggle is not set.
Recognizing Changes in Check Box Toggle Values
VkCheckBox provides different methods that you can use to determine when the user changes the value of a toggle: Xt-style callbacks, ObjectPak callbacks, and subclassing. Use whichever method is most convenient.
Using Xt-Style callbacks to change check box toggle values
The first method of determining when the user changes a toggle value is to register an Xt-style callback for each toggle button. When you create a toggle with the addItem() function, you can optionally specify a callback function and client data. When the value of the toggle changes, the callback function is called with the client data you provided, and a pointer to a XmToggleButtonCallbackStruct structure as call data.
For example, the following adds a toggle named "lineNumbers" to the parametersBox check box and registers a callback function:
- MyComponent::MyComponent(const char *name, Widget parent) : VkComponent (name)
- {
- // ...
- parametersBox->addItem("lineNumbers", FALSE,
- &MyComponent::toggleLineNumbersCallback(),
- (XtPointer) this );
- // ...
- }
MyComponent::toggleLineNumbersCallback(), which must be declared as a static member function of the class MyComponent, is registered as a callback function for this toggle, and the this pointer is used as the client data. The definition of toggleLineNumbersCallback() could look like this:
-
void MyComponent::toggleLineNumbersCallback(Widget,
- XtPointer clientData,
- XtPointer callData )
- {
- MyComponent *obj = (MyComponent) clientData;
- XmToggleButtonCallbackStruct *cb =
- (XmToggleButtonCallbackStruct) callData;
- // Call MyComponent::toggleLineNumbers(), a regular
- // member function to either display or hide line numbers
- // based on the value of the toggle.
- obj->toggleLineNumbers(cb->set);
- }
Using ObjectPak callbacks to change check box toggle values
The second method of determining when the user changes a toggle value is to use a ObjectPak callback. The VkCheckBox component provides the VkCheckBox::itemChanged callback. Any ViewKit ObjectPak component can register a member function to be called when the user changes a check box toggle. The VkCheckBox object provides the integer index of the toggle as client data to the callback functions.
Note: The itemChanged callback is activated when the user changes any toggle. You cannot register an ObjectPak callback for an individual toggle.
For example, the following line registers the member function MyComponent::parameterChanged() as an ObjectPak callback function to call when the user changes a toggle in the parametersBox check box:
- MyComponent::MyComponent(const char *name, Widget parent) : VkComponent (name)
- {
- // ...
- parametersBox->addCallback(VkCheckBox::itemChanged, this,
- (VkCallbackMethod) &MyComponent::parameterChanged );
- // ...
- }
Note this example lacks client data.
The definition of parameterChanged() could look like this:
- void MyComponent::parameterChanged(VkComponent *obj, void *,
- void *callData )
- {
- VkCheckBox *checkBox = (VkCheckBox) obj;
- int index = (int) callData;
- switch (index) {
- // ...
- // Assume that the constant LINE_NUMBER_INDEX is set to the index of
- // the "lineNumber" toggle. If the "lineNumber" toggle value changed,
- // Call MyComponent::toggleLineNumbers(), a regular member function to
- // either display or hide line numbers based on the value of the toggle
- case LINE_NUMBER_INDEX:
- toggleLineNumbers( checkBox->getValue(index) );
- // ...
- }
- }
Using subclassing to change check box toggle values
The third method of determining when the user changes a toggle value is to create a subclass of VkCheckBox. Whenever the user changes a toggle, VkCheckBox calls the virtual function VkCheckBox::valueChanged():
- virtual void valueChanged(int index, Boolean newValue)
index is the index of the item that changed and newValue is the current (new) value of that item. By default, valueChanged() is empty. You can override its definition in a subclass and perform processing as needed.
Protected data members
Derived classes have access to the following protected data members of the VkCheckBox class: