CheckBox(3W) UNIX System V CheckBox(3W)
NAME
CheckBox - creates a label button with a check box to act as a toggle
switch
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <CheckBox.h>
widget = XtCreateWidget(name, checkBoxWidgetClass, ...);
DESCRIPTION
CheckBox Components
The CheckBox widget implements one of the OPEN LOOK button widgets. It
consists of a Label next to a Check Box; the Check Box will have a Check
Mark, if selected.
Figure 1. CheckBox Widget
10/89 Page 1
CheckBox(3W) UNIX System V CheckBox(3W)
Figure 2 shows several buttons, in unselected and selected, as well as
normal and dim states.
Figure 2. CheckBoxes
Typical Use of Check Boxes
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 layout is not guaranteed.
Operating on Check Boxes
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 "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 CheckBox, 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 CheckBox box and Check Mark respond to SELECT, as shown in
Figure 3.
Figure 3. Active Region for a CheckBox
CheckBox 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.
Page 2 10/89
CheckBox(3W) UNIX System V CheckBox(3W)
Figure 4 illustrates the resources that affect the coloration of the
CheckBox widget.
Figure 4. CheckBox 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 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
10/89 Page 3
CheckBox(3W) UNIX System V CheckBox(3W)
right of the label in parenthesis and highlighted according to the value
returned by OlQueryMnemonicDisplay().
If truncation is necessary, the mnemonic displayed in parenthesis 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
__________________________________________________________________________________________
| CheckBox Resource Set |
|_____________________|______________________|________________|__________________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|________________|__________________|________|
__________________________________________________________________________________________
XtNaccelerator XtCAccelerator String NULL SGI
__________________________________________________________________________________________
XtNacceleratorText XtCAcceleratorText String Dynamic SGI
__________________________________________________________________________________________
XtNancestorSensitive XtCSenstitive Boolean TRUE G*
__________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SGI
__________________________________________________________________________________________
XtNdepth XtCDepth int (parent's) GI
__________________________________________________________________________________________
XtNdestroyCallback XtCCallback XtCallbackList NULL SI
__________________________________________________________________________________________
XtNdim XtCDim Boolean FALSE SGI
__________________________________________________________________________________________
XtNfont XtCFont XFontStruct * (OPEN LOOK font) SI
__________________________________________________________________________________________
XtNfontColor XtCFontColor Pixel Black* SGI
__________________________________________________________________________________________
XtNforeground XtCForeground Pixel Black SGI†
__________________________________________________________________________________________
XtNheight XtCHeight Dimension (calculated) SGI
__________________________________________________________________________________________
XtNinputFocusColor XtCInputFocusColor Pixel Black SGI
__________________________________________________________________________________________
XtNlabel XtCLabel String (class name) SGI
__________________________________________________________________________________________
XtNlabelImage XtCLabelImage XImage * (class name) SGI
__________________________________________________________________________________________
XtNlabelJustify XtCLabelJustify OlDefine OL_LEFT SGI
__________________________________________________________________________________________
Page 4 10/89
CheckBox(3W) UNIX System V CheckBox(3W)
__________________________________________________________________________________________
| CheckBox Resource Set |
|_____________________|______________________|________________|__________________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|________________|__________________|________|
| XtNlabelTile | XtCLabelTile | Boolean | FALSE | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNlabelType | XtCLabelType | int | OL_STRING | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNmappedWhenManaged| XtCMappedWhenManaged| Boolean | TRUE | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNmnemonic | XtCMnemonic | unsigned char | NULL | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNposition | XtCPosition | OlDefine | OL_LEFT | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNrecomputeSize | XtCRecomputeSize | Boolean | TRUE | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNreferenceName | XtCReferenceName | String | NULL | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNreferenceWidget | XtCReferenceWidget | Widget | NULL | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNselect | XtCCallback | XtCallbackList| NULL | SI |
|_____________________|______________________|________________|__________________|________|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_____________________|______________________|________________|__________________|________|
| XtNset | XtCSet | Boolean | TRUE | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNtraversalOn | XtCTraversalOn | Boolean | TRUE | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNunselect | XtCCallback | XtCallbackList| NULL | SI |
|_____________________|______________________|________________|__________________|________|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNx | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNy | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|________________|__________________|________|
XtNdim
Range of 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.
10/89 Page 5
CheckBox(3W) UNIX System V CheckBox(3W)
XtNfont
Range of Values:
(any valid return from XLoadQueryFont())
Default:
(chosen to match the scale and screen resolution)
This resource identifies the font to be used to display the Label.
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
Range of Values:
(any Pixel value valid for the current display)/(any name from the
rgb.txt file)
This resource specifies the color for the font. If not set, the color
from the XtNforeground resource, if available, is used for the font.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources, Section 2.
XtNforeground
This resource defines the foreground color for the widget.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources, Section 2.
XtNlabel
This resource is a pointer to the text for the Label. This resource is
ignored if the XtNlabelType resource has the value OLIMAGE.
XtNlabelImage
This resource is a pointer to the image for the Label of the CheckBox
widget. This resource is ignored unless the XtNlabelType resource has
the value OLIMAGE.
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
Range of Values:
OLLEFT/"left"
OLRIGHT/"right"
Page 6 10/89
CheckBox(3W) UNIX System V CheckBox(3W)
This resource dictates whether the Label should be left- or right-
justified within the space left before or after the Check Box, if the
XtNwidth resource gives more space than needed.
XtNlabelTile
Range of Values:
TRUE
FALSE
This resource augments the XtNlabelImage/XtNlabelPixmap resource to allow
tiling of the sub-object's background. For an image/pixmap that is
smaller than the sub-object's background, the label area is tiled with
the image/pixmap to fill the sub-object's background if this resource is
TRUE; otherwise, the label is placed as described by the XtNlabelImage
resource.
The XtNlabelTile resource is ignored for text labels.
XtNlabelType
Range of Values:
OLSTRING/"string"
OLIMAGE/"image"
This resource identifies the form that the Label takes. It can have the
value OLSTRING or OLIMAGE for text or image, respectively.
XtNposition
Range of Values:
OLLEFT/"left"
OLRIGHT/"right"
This resource determines on which side of the Check Box the Label is to
be placed. The value may be one of OLLEFT or OLRIGHT to indicate that
the Label is to be placed to the left or to the right of the Check Box,
respectively.
XtNrecomputeSize
Range of Values:
TRUE
FALSE
This resource indicates whether the CheckBox widget should calculate its
size and automatically set the XtNheight and XtNwidth resources. If set
to TRUE, the CheckBox widget will do normal size calculations that may
cause its geometry to change. If set to FALSE, the CheckBox widget will
leave its size alone; 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.
10/89 Page 7
CheckBox(3W) UNIX System V CheckBox(3W)
XtNselect
This is the list of callbacks invoked when the widget is selected.
XtNset
Range of Values:
TRUE
FALSE
This resource reflects the current state of the check box. The Check
Mark is present if XtNset is TRUE and is absent otherwise.
XtNunselect
This is the list of callbacks invoked when a CheckBox widget is toggled
into the ``unset'' mode by the end user to make XtNset be FALSE. Note
that simply setting XtNset to FALSE with a call to XtSetValues() does not
issue the XtNunselect callbacks.
XtNdim and XtNset Interaction
The XtNdim and XtNset resources can be set independently, as the state
table in Figure 5 shows.
Figure 5. Check Box Appearance with Set/Default/Dim
Label and Check Box Appearance
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 Figure 6.
Figure 6. 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.
Page 8 10/89