CheckField

  (subclass of 9.1.3.12 Group)

A checkfield is the combination of several checkboxes, together with a variable dependence structure. There are some predefined easy dependencies like a radio-button dependence, where only one button at the same time can be pressed. It is also possible to define complex own dependencies. The single checkboxes alternative can switch single bits of one variable of the type CHECKFIELD_VAR (at least 32 bits) or each checkbox has got its own variable, which is switched on and off. Combinations of this variable strategies for one checkfield are possible. Each checkbox in a checkfield is referenced by a unique bit in a CHECKFIELD_VAR. This field will be called the mask of this checkbox in the following context. If the checkfield has one variable whose bits are switched, each checkbox will switch its reference bit. For the dependencies each checkbox of a checkfield has got four dependency bit-masks. Two of them are used, if the checkbox is switched on, we will call them check-masks, the other ones are used if it is switched off and we will call them unset-masks. If you switch the checkbox, it will first switch off all checkboxes of the checkfield, whose bits are not set in the (un-)check-AND-mask. After that all checkboxes, whose bits in the (un-)check-XOR-mask are set, are switched. You can use predefined masks if you want simple a checkfield like one with a radio-button behavior. Otherwise you can set the mask using the method "set-dependency-mask" or "set-checkfield-bits". Pay attention that some methods needed for using checkfields are methods of the class checkbox. Look there to get all information.

   (CHECKFIELD_VAR * ) GRAPE(checkfield, "get-bitfield")()

CHECKFIELD *checkfield

Returns the sum bit mask containing all pressed Checkboxes' mask bits.

   (CHECKFIELD_VAR * ) GRAPE(checkfield, "get-free-mask")()

CHECKFIELD *checkfield

Returns a bit mask containing a single bit not already used by other Checkboxes of this Checkfield.

   (CHECKBOX * ) GRAPE(checkfield, "insert-checkbox")(checkbox, this_mask)

CHECKFIELD * checkfield
CHECKFIELD_VAR this_mask

Adds checkbox to a Checkfield, using this_mask as its unique identifying bitmask. See also "new-checkbox".

   (CHECKBOX * ) GRAPE(checkfield, "new-checkbox")(name, this_mask, var)

CHECKFIELD *checkfield
char *name
CHECKFIELD_VAR this_mask
CHECKFIELD_VAR *var

Creates a new Checkbox named name inside the Checkfield. This checkbox will be referenced by the checkfield only with the bit-mask this_mask. So it is necessary to set one unique bit in this bitmask. If have have chosen an automatic mask-mode for the checkfield, the dependency bit-masks of the other checkboxes will be set correctly. If var != NULL the checkbox will control its own value (which will be set to 0 or to 1), instead of the bit in the variable of the checkfield. Most times the checkfield looks better if you set a size for the single checkboxes after creating them. Because the Checkbox is already inserted into the Checkfield when you can call "set-pref-size" you have to call the method "calc-inter" on the checkfield after all checkboxes are added and correctly resized.

   GRAPE(CheckField, "new-instance")(name, var)

CLASS *CheckField
char *name
CHECKFIELD_VAR *var

var is the pointer to the variable where the state of the single checkboxes is referenced by their bits. This pointer can be a NULL pointer if you want to use a single state variable for each checkbox. If you use this variable, it should have a state which is compatible with the dependency-masks, to have a correct setting at startup.

   GRAPE(checkfield, "set-dependency-masks")(check_and, check_xor, uncheck_and, uncheck_xor)

CHECKFIELD *checkfield
CHECKFIELD_VAR check_and, check_xor
CHECKFIELD_VAR uncheck_and, uncheck_xor

This method sets the default connection bitmasks which will used for each new checkbox created using "new-checkbox", if the active mask-mode is G_CHECKFIELD_CUSTOM. This provides an easy interface to create multiple Checkboxes with the same behaviour.

To be used for more than one special Checkbox the values are rotated until the least significant bits of the set masks are at the actual bit position.

   GRAPE(checkfield, "set-variable")(variable)

CHECKFIELD *checkfield
CHECKFIELD_VAR * variable

Set the variable controlled by the CheckField, i.e. the bitmask whose bits are switched by Checkboxes not having an own variable. This allows to change the setting coming from the "new-instance" argument.

   GRAPE(checkfield, "set-mask-mode")(mask_mode)

CHECKFIELD *checkfield
int mask_mode

Set a global connection mode for the Checkboxes. This must be done before the first "new-checkbox".
G_CHECKFIELD_RADIO: Radio-buttons, one and only one can be ON.
G_CHECKFIELD_CBOXES: Checkboxes, arbitrary combinations allowed.
G_CHECKFIELD_CUSTOM: Use special user defined masks ("set-dependency-masks") for each Checkbox.