CheckBox Class

Check boxes are similar in many ways to radio buttons. A check box consists of a square box and a programmer defined label, icon, or bitmap that indicates to the user a choice. Check boxes are typically grouped together as a set of independent options. Checking or unchecking one option usually has no effect on the other check box options.

There are four styles of check boxes: standard, automatic, three-state, and automatic three-state, The system manages the check state of automatic and automatic three-state check boxes. All check boxes have at least two states, either checked or cleared (unchecked.) In addition three-state check boxes have a third state called indeterminate, which the system draws as a grayed box inside the check box.

Repeatedly clicking standard and automatic check boxes toggles them back and forth from cleared to checked, and back again. Doing the same with a three-state check box toggles it from cleared, to checked, to indeterminate, and back again.

The CheckBox class provides methods to query and modify check box controls.

Requires:

The CheckBox class requires the class definition file oodWin32.cls :

::requires "oodWin32.cls"

Subclass of:

The check box class is a direct subclass of the RadioButton class, and therefore an indirect subclass of the ButtonControl class and the DialogControl class class. It inherits all the methods of all three classes.

Mixin Class Inherits:

The check box class inherits from the following mixin classes, (indirectly through the DialogControl class.)

The WindowBase

The WindowExtensions

Instantiation:

Use the getCheckControl() method to retrieve an object of the check box class.

Dynamic Definition:

To dynamically define a check box in a UserDialog class, use one of the add button methods described in the Add Button Control section. That section also describes methods for adding push buttons, radio buttons, etc.. All the methods to add check boxes begin with: addCheck.

Event Notification

A check box, is a button, and the programmer uses the same methods to recieve notifications of events as with the ButtonControl: the connectButton() method, or the connectButtonNotify() method.

Methods:

The CheckBox class implements the instance methods listed in the following table:

Table 14-4. CheckBox Instance Methods

Method......Description
isIndeterminateisIndeterminate
getCheckStategetCheckState
setIndeterminatesetIndeterminate

isIndeterminate

>>--isIndeterminate------------------------------><

Determines if the check box is in indeterminate state, or not.

Arguments:

There are no arguments.

Return value:

Returns true if the check box is in the indeterminate state, otherwise false.

Example:

This example is from a program that sets the background color to black, white, or gray.

  chkBox = self~getCheckControl(IDC_CHK_BACKGROUND)
  if chkBox~isIndeterminate then return self~grayBackground

getCheckState

>>--getCheckState----------------------------------------------------><

This method over-rides the RadioButton getCheckState() method to return a keyword indicating the check state of the check box, checked, unchecked, or indeterminate.

Arguments:

There are no arguments to this method.

Return value:

The return value is a keyword indicating the checked state of the check box and will exactly one of the following:

UNCHECKED The check box is not checked.
CHECKED The check box is checked.
INDETERMINATEThe check box is in the indeterminate state.
UNKNOWN The object is not a check box.

Example:

This example is a variation of the example for the isIndeterminate() method.

  state = self~getCheckControl(IDC_CHK_BACKGROUND)~getCheckState

  select
    when state == "CHECKED" then return self~blackBackground
    when state == "UNCHECKED" then return self~whiteBackground
    when state == "INDETERMINATE" then return self~grayBackground
    otherwise nop  -- Drop through and do error handling
  end
  -- End select

setIndeterminate

>>--setIndterminate------------------------------><

The setIndeterminate method puts the check box in the indeterminate state. The system will redraw the check box to indicate the indeterminate state.