Boolean Gadget Type

Description

A boolean gadget gets yes/no or on/off responses from the user. To make a boolean gadget set the GadgetType field to GTYP_BOOLGADGET in the Gadget structure.

Boolean gadgets come in two types: hit-select and toggle-select. Hit-select gadgets are only active while the user holds down the mouse select button. When the button is released, the gadget is unhighlighted. Action buttons, such as "OK" and "Cancel", are hit-select.

Toggle-select gadgets become selected when the user clicks them. To "unselect" the gadget, the user has to click the gadget again. Switches, such as a checkbox, are toggle-select.

Set the GACT_TOGGLESELECT flag in the Activation field of the Gadget structure to create a toggle-select gadget.

The GFLG_SELECTED flag in Gadget structure Flags field determines the initial and current on/off selected state of a toggle-select gadget. If GFLG_SELECTED is set, the gadget will be highlighted. The application can set the GFLG_SELECTED flag before submitting the gadget to Intuition. The program may examine this flag at any time to determine the current state of this gadget.

Try to make the imagery for toggle-select gadgets visually distinct from hit-select gadgets so that their operation can be determined by the user through visual inspection.

Masked Boolean Gadgets

Imagery for boolean gadgets is rectangular by default, but non-rectangular boolean gadgets are possible, with some restrictions. An auxiliary bit plane, called a mask, may be associated with a boolean gadget. When the user clicks within the select box of the gadget, a further test is made to see if the chosen point is contained within the mask. Only if it is, does the interaction count as a gadget hit.

With masked boolean gadgets, if the gadget has highlight type GFLG_GADGHCOMP then the complement rendering is restricted to the mask. This allows for non-rectangular shapes, such as an oval gadget which highlights only within the oval.

There are some shortcomings to non-rectangular boolean gadgets. For instance, the gadget image is not rendered through the mask. Images are rectangular blocks, with all bits rendered. In the case of an oval mask, the image will be rendered in the corner areas even though they are outside of the oval. Also, it is not possible to mask out the select box, thus non-rectangular masked gadgets cannot overlap in the masked area. Therefore, such gadgets can’t be crowded together without care. Likewise, the ghosting of a disabled gadget does not respect the mask, so ghosting of the corners around an oval may be visible, depending on the colors involved.

To use a masked boolean gadget, fill out an instance of the BoolInfo structure. This structure contains a pointer to the mask plane data. The application must also set the GACT_BOOLEXTEND flag in the gadget's Activation field.

BoolInfo Structure

This is the special data structure required for a masked boolean gadget. A pointer to this structure must be placed in the gadget's SpecialInfo field for a masked boolean gadget.

struct BoolInfo
    {
    UWORD  Flags;
    UWORD  *Mask;
    ULONG  Reserved;
    };

Flags must be given the value BOOLMASK.

This is a bit mask for highlighting and picking the gadget. Construct the mask as a single plane of image data. The image's width and height are determined by the width and height of the gadget's select box. The mask data must be in Chip memory.

Set this field to NULL.

Mutual Exclude

Mutual exclusion of boolean gadgets (sometimes referred to as "radio buttons") is not directly supported by Intuition. This section describes the method an application should use to implement this feature. It is up to the application to handle the manipulation of excluded gadgets in an Intuition compatible way. The program must proceed with caution so as to maintain the synchronization of the gadget and its imagery. The rules provided in this section for the implementation of mutual exclude gadgets minimize the risk and complexity of the application. Other techniques may seem to work with simple input, but may fail in subtle ways when stressed.

Gadget Type for Mutual Exclusion

To implement mutual exclusion, gadgets must be hit-select (not GACT_TOGGLESELECT) boolean gadgets, with the GACT_IMMEDIATE activation type (never GACT_RELVERIFY). All state changes must be executed upon receiving the IDCMP_GADGETDOWN message for the gadgets. Failure to do this could introduce subtle out-of-phase imagery problems.

Gadget Highlighting for Mutual Exclusion

When using complement mode highlighting, the image supplied must be at least the size of the complemented area (the gadget select box). An extended boolean gadget with a mask may be used to constrain the area that is highlighted.

Alternate image highlighting may be used provided the two images have exactly the same size and position. Likewise, a border and alternate border may be used provided the two borders are identical in shape and position, differing only in color.

Do not use other combinations for mutual exclude gadgets such as a gadget with a border that uses complement mode highlighting or a gadget which uses highlighting by drawing a box. See the section on "Updating a Gadget's Imagery" for more information.

Handling of Mutually Exclusive Gadgets

Use RemoveGList() to remove the boolean gadget from the window or requester. Set or clear the GFLG_SELECTED flag to reflect the displayed state of the gadget. Replace the gadget using AddGList() and refresh its imagery with RefreshGList(). Of course, several gadgets may be processed with a single call to each of these functions.