NAME

CheckBox − check box widget

SYNOPSIS

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/CheckBox.h>
 . . .
Widget my_checkbox, my_parent;
String my_name;
ArgList args;
Cardinal num_args;

my_checkbox =  XtCreate( my_name, checkBoxWidgetClass,

my_parent, args, num_args);

DESCRIPTION

Components

The CheckBox widget implements one of the OPEN LOOK button widgets.  It 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. 

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   Expected   Results
=
OL_SELECTKEY
Update       its    visual     to
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

CheckBox             Resource       Set
Name                 Type           Default             Access
 
XtNaccelerator       String         NULL                SGI
XtNacceleratorText   String         Dynamic             SGI
XtNancestorSensitive Boolean        TRUE                GO
XtNconsumeEvent      XtCallbackList NULL                SGI
XtNdepth             int            (parent’s)          GI
XtNdestroyCallback   XtCallbackList NULL                SI
XtNdim               Boolean        FALSE               SGI
XtNfont              XFontStruct∗   (OPEN               LOOK
XtNfontColor         Pixel          XtDefaultForeground SGI
XtNforeground        Pixel          XtDefaultForeground SGI
XtNheight            Dimension      (calculated)        SGI
XtNinputFocusColor   Pixel          Red                 SGI
XtNlabel             String         (class              name)
XtNlabelImage        XImage∗        (class              name)
XtNlabelJustify      OlDefine       OL_LEFT             SGI
XtNlabelTile         Boolean        FALSE               SGI
XtNlabelType         OlDefine       OL_STRING           SGI
XtNmappedWhenManaged Boolean        TRUE                SGI
XtNmnemonic          unsigned       char                NULL
XtNposition          OlDefine       OL_LEFT             SGI
XtNrecomputeSize     Boolean        TRUE                SGI
XtNreferenceName     String         NULL                SGI
XtNreferenceWidget   Widget         NULL                SGI
XtNscale             int            12                  SGI
XtNselect            XtCallbackList NULL                SI
XtNsensitive         Boolean        TRUE                GIO
XtNset               Boolean        TRUE                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 timeO = other access
† see resources(3W)

XtNdim

 class:XtCDimtype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’

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:XtCFonttype:XFontStruct∗default:(OPEN LOOK font)(OPEN LOOK font)’u’access:SISI’u’

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

Values: any valid return from XLoadQueryFont()

The default is chosen to match the scale and screen resolution.  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:XtCFontColortype:Pixeldefault:BlackBlack’u’access:SGISGI’u’

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:XtCForegroundtype:Pixeldefault:BlackBlack’u’access:SGISGI’u’

Action: defines the foreground color for the widget. 

XtNlabel

 class:XtCLabeltype:Stringdefault:(class name)(class name)’u’access:SGISGI’u’

Action: points to the text for the label. 

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

XtNlabelImage

 class:XtCLabelImagetype:XImage∗default:(class name)(class name)’u’access:SGISGI’u’

Action: points to the image for the label of the CheckBox widget. 

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:XtCLabelJustifytype:OlDefinedefault:OL_LEFTOL_LEFT’u’access:SGISGI’u’

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:XtCLabelTiletype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’

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

Values: TRUE – the label area is tiled with the image/pixmap to fill the sub-object’s background, if the image/pixmap 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 and XtNlabelPixmap resources to allow tiling of the sub-object’s background.  The XtNlabelTile resource is ignored for text labels. 

XtNlabelType

 class:XtCLabelTypetype:intdefault:OL_STRINGOL_STRING’u’access:SGISGI’u’

Action: identifies the form that the Label takes. 

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

XtNposition

 class:XtCPositiontype:OlDefinedefault:OL_LEFTOL_LEFT’u’access:SGISGI’u’

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

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

XtNrecomputeSize

 class:XtCRecomputeSizetype:Booleandefault:TRUETRUE’u’access:SGISGI’u’

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:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’

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

XtNset

 class:XtCSettype:Booleandefault:TRUETRUE’u’access:SGISGI’u’

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:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’

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  —  Last change: 19 July 91