NAME

CheckBox − check box widget

SYNOPSIS

#include <Xol/OpenLook.h>
#include <Xol/CheckBox.h>
 . . .

ANCESTRY

Core-Composite-Constraint-Manager-CheckBox

DESCRIPTION

The CheckBox widget is similar in function to the RectButton widget. Several CheckBoxes are typically used together to provide the user with a set of options that can be toggled on or off. 

Components

The CheckBox widget consists of a label next to a CheckBox; the CheckBox will have a Check Mark, if selected. 

  Figure 1 CheckBox Widget

in unselected and selected, as well as normal and dim states. 

  Figure 2 Check Boxes

Typical Use

Check Boxes may be used alone, but are usually used in the Nonexclusives composite widget, where they are used to implement a several-of-many selection.  Making the CheckBox widget a child of a different composite widget will not produce an error, but proper behavior is not guaranteed. 

Operations

A CheckBox widget has two states: "set" and "not set".  When set, the Check Mark is visible.  Toggling this state alternates a resource (XtNset) between logical true and false and starts an action associated with the check box. Clicking SELECT on a check box toggles the state associated with it. Pressing SELECT, or moving the pointer into the check box while SELECT is pressed, adds or removes the Check Mark to reflect the state the check box would be in if SELECT was released. Releasing SELECT toggles the state. Moving the pointer off the check box before releasing SELECT restores the original Check Box, but does not toggle the state. Clicking or pressing MENU does not do anything in the CheckBox widget; the event is passed up to an ancestor widget. 

Bounds on SELECT

Only the Check Box and Check Mark respond to SELECT,

  Figure 3 Active Region for a Check Box

Coloration

On a monochrome display, the CheckBox widget indicates that it has input focus by inverting the foreground color and parent’s background colors within the bounding box of the widget. 

On color displays, when the CheckBox widget receives the input focus, the background color within the bounding box of the widget is changed to the input focus color set in the XtNinputFocusColor resource.  When the CheckBox widget loses the input focus, the background color reverts to its parent’s XtNbackground color or XtNbackgroundPixmap. 

EXCEPTIONS:

—If the input focus color is the same as the parent’s background color, then the CheckBox widget inverts the foreground and background colors when it has input focus. 

—If the input focus color is the same as the font color or foreground color, then the CheckBox widget inverts the foreground and background colors when it has input focus. 

The diagram illustrates the resources that affect the coloration of the CheckBox widget. 

  Figure 4 Check Box Coloration

Keyboard Traversal

The default value of the XtNtraversalOn resource is TRUE. 

The CheckBox widget responds to the following keyboard navigation keys:

—NEXT_FIELD moves to the next traversable widget in the window

—PREV_FIELD moves to the previous traversable widget in the window

—MOVEUP moves to the CheckBox above the current widget in the Nonexclusives composite

—MOVEDOWN moves to the CheckBox below the current widget in the Nonexclusives composite

—MOVELEFT moves to the CheckBox to the left of the current widget in the Nonexclusives composite

—MOVERIGHT moves to the CheckBox to the right of the current widget in the Nonexclusives composite

—NEXTWINDOW moves to the next window in the application

—PREVWINDOW moves to the previous window in the application

—NEXTAPP moves to the first window in the next application

—PREVAPP moves to the first window in the previous application

CheckBox Widget Activation Types Activation Type: OL_SELECTKEY Expected Results: Update its visual to reflect the new state and call the appropriate callback list. 

Display of Keyboard Mnemonic

The CheckBox widget displays the mnemonic accelerator as part of its label.  If the mnemonic character is in the label, then that character is highlighted according to the value returned by OlQueryMnemonicDisplay().  If the mnemonic character is not in the label, it is displayed to the right of the label in parentheses and highlighted according to the value returned by OlQueryMnemonicDisplay(). 

If truncation is necessary, the mnemonic displayed in parentheses is truncated as a unit. 

Display of Keyboard Accelerators

The CheckBox widget displays the keyboard accelerator as part of its label.  The string in the XtNacceleratorText resource is displayed to the right of the label (or mnemonic) separated by at least one space.  The acceleratorText is right justified. 

If truncation is necessary, the accelerator is truncated as a unit.  The accelerator is truncated before the mnemonic or the label. 

RESOURCES

  Table 1 CheckBox Resource Set

Name                     Type              Default           Access
XtNaccelerator-         String           NULL                    SGI
XtNacceleratorText-     String           Dynamic                 SGI
XtNancestorSensitive-   Boolean          TRUE                    GO
XtNconsumeEvent-        XtCallbackList   NULL                    SGIO
XtNdepth-               int              (parent’s)              GI
XtNdestroyCallback-     XtCallbackList   NULL                    SI
XtNdim                  Boolean          FALSE                   SGI
XtNfont                 XFontStruct∗     (OPEN LOOK bold font)   SI
XtNfontColor            Pixel            XtDefaultForeground     SGI
XtNforeground-          Pixel            XtDefaultForeground     SGI
XtNheight-              Dimension        (calculated)            SGI
XtNinputFocusColor-     Pixel            Red                     SGI
XtNlabel                String           (widget name)           SGI
XtNlabelImage           XImage∗          NULL                    SGI
XtNlabelJustify         OlDefine         OL_LEFT                 SGI
XtNlabelTile            Boolean          FALSE                   SGI
XtNlabelType            OlDefine         OL_STRING               SGI
XtNmappedWhenManaged-   Boolean          TRUE                    SGI
XtNmnemonic-            unsigned char    NULL                    SGI
XtNposition             OlDefine         OL_LEFT                 SGI
XtNrecomputeSize        Boolean          TRUE                    SGI
XtNreferenceName-       String           NULL                    SGI
XtNreferenceWidget-     Widget           NULL                    SGI
XtNscale                int              OL_DEFAULT_POINT_SIZE   SGI
XtNselect               XtCallbackList   NULL                    SI
XtNsensitive-           Boolean          TRUE                    GIO
XtNset                  Boolean          FALSE                   SGI
XtNtraversalOn-         Boolean          TRUE                    SGI
XtNunselect             XtCallbackList   NULL                    SI
XtNuserData-            XtPointer        NULL                    SGI
XtNwidth-               Dimension        (calculated)            SGI
XtNx-                   Position         0                       SGI
XtNy-                   Position         0                       SGI

Access:   S = XtSetValues   G = XtGetValues
            I = init time   O = other access
† see resources(3W)

XtNdim

class:XtCDim type:Boolean default:FALSEaccess:SGI

Action: determines whether border of CheckBox shows state of underlying objects

Values: TRUE, FALSE. 

If this resource is TRUE, the check box border is dimmed to show that the check box represents the state of one or more of several objects that, as a group, are in different states. 

XtNfont

class:XtCFont type:XFontStruct∗ default:(OPEN LOOK font)access:SI

Action: identifies the font to be used to display the label. 

Values: any valid return from XLoadQueryFont()

The default is the bold version of the font specified by the XtNolDefaultFont application resource.  The default value points to a cached font structure; an application should not expect to get this value with a call to XtGetValues() and use it reliably thereafter. 

XtNfontColor

class:XtCFontColor type:Pixel default:XtDefaultForegroundaccess:SGI

Action: specifies the font color. 

Values: any pixel value valid for the current display, or
any name from the rgb.txt file

If not set, the color from the XtNforeground resource, if available, is used for the font. 

XtNforeground

class:XtCForeground type:Pixel default:XtDefaultForegroundaccess:SGI

Action: defines the foreground color for the widget. 

XtNlabel

class:XtCLabel type:String default:(class name)access:SGI

Action: points to the text for the label. 

This resource is ignored if the XtNlabelType resource has the value OL_IMAGE. 

XtNlabelImage

class:XtCLabelImage type:XImage∗ default:(widget name)access:SGI

Action: points to the image for the label of the CheckBox widget.  The default value is the name of the widget as specified in the XtCreateWidget routine. 

This resource is ignored unless the XtNlabelType resource has the value OL_IMAGE.  If the image is smaller than the space available for it next to the Check Box, it is centered vertically and either centered or left-justified horizontally depending on the value of the XtNlabelJustify resource.  If the image is larger than the space available for it, it is clipped so that it does not stray outside the space. 

XtNlabelJustify

class:XtCLabelJustify type:OlDefine default:OL_LEFTaccess:SGI

Action: controls justification of label if space available

Values: OL_LEFT/"left" , OL_RIGHT/"right"

This resource indicates whether the label should be left-justified or right-justified, if the XtNwidth resource gives more space than needed. 

The label is justified within the space left before or after the CheckBox. 

XtNlabelTile

class:XtCLabelTile type:Boolean default:FALSEaccess:SGI

Action: partially controls tiling of the sub-object’s background. 

Values: TRUE – the label area is tiled with the image to fill the sub-object’s background, if the image is smaller than the sub-object’s background FALSE – otherwise, the label is placed as described by the XtNlabelImage resource. 

This resource augments the XtNlabelImage resource to allow tiling of the sub-object’s background.  The XtNlabelTile resource is ignored for text labels. 

XtNlabelType

class:XtCLabelType type:OlDefine default:OL_STRINGaccess:SGI

Action: identifies the form that the Label takes. 

Values: OL_STRING/"string" , OL_IMAGE/"image"

XtNposition

class:XtCPosition type:OlDefine default:OL_LEFTaccess:SGI

Action: determines on which side of the CheckBox the label is placed. 

Values: OL_LEFT/"left" , OL_RIGHT/"right"

XtNrecomputeSize

class:XtCRecomputeSize type:Boolean default:TRUEaccess:SGI

Action: indicates whether the CheckBox widget should calculate its size. 

TRUE – the CheckBox widget will do normal size calculations that may cause its geometry to change, and automatically set the XtNheight and XtNwidth resources. 

FALSE – the CheckBox widget will leave its size unchanged; this may cause truncation of the visible image being shown by the CheckBox widget if the fixed size is too small, or may cause padding if the fixed size is too large.  The location of the padding is determined by the XtNlabelJustify resource. 

XtNselect

class:XtCCallback type:XtCallbackList default:NULLaccess:SI

Action: the list of callbacks invoked when the widget is selected. 

XtNset

class:XtCSet type:Boolean default:FALSEaccess:SGI

Action: reflects the current state of the check box. 

Values: TRUE – the check mark is present.  FALSE – the check mark is not present.

XtNunselect

class:XtCCallback type:XtCallbackList default:NULLaccess:SI

Action: points to the list of callbacks invoked when toggled into the “unset” mode. 

This resource indicates the callbacks to invoke when the end user toggles the CheckBox into the unset mode, making XtNset be FALSE.  Note that simply setting XtNset to FALSE with a call to XtSetValues does not issue the XtNunselect callbacks. 

CheckBox Appearance

The XtNdim and XtNset resources can be set independently,

  Table 2 Check Box Appearance with Set/Default/Dim

Label Resource Interactions

The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources interact to produce a truncated, clipped, centered, left-justified, or right-justified Label and Check Box as shown in

  Table 3 Label and Check Box Appearance When the label is left-justified, right-justified, or centered the extra space is filled with the background color of the CheckBox widget’s parent, as determined by the XtNbackground and XtNbackgroundPixmap resources of the parent.  See also the XtNlabelTile resource for how it affects the appearance of a label. 
 

Version 3.0.1  —  Last change: June 92