FlatCheckBox(3W)

NAME

FlatCheckBox − flat check box widget, from class FlatNonExclusives

SYNOPSIS

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

ANCESTRY

Core-Primitive-Flat-FlatExclusives-FlatCheckBox

DESCRIPTION

The FlatCheckBox enables you to create a number of check boxes with a single widget. It creates checkbox sub-objects that have the same behavior as checkboxes. In short, it provides the same functionality as a NonExclusives widget populated with CheckBox widgets, however it offers improved performance since you don’t have to create as many widgets.

Keyboard Traversal

The FlatCheckBox widget is a Primitive widget that manages traversal between the check box sub-objects. When the user traverses to a FlatCheckBox widget, the first sub-object in the set will display itself as having input focus (see the CheckBox widget for a description of this appearance.)

The MOVEUP, MOVEDOWN, MOVERIGHT, and MOVELEFT keys move the input focus between the sub-objects. To traverse out of the FlatCheckBox widget, the following keys can be used:

—NEXT_FIELD moves to the next traversable widget in the window

—PREV_FIELD moves to the previous traversable widget in the window

—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.

Keyboard Operation

Flat CheckBox Activation Types OL_SELECTKEY:

These controls have two states: "set" and "not set". (When set, its border is thickened.) Pressing the SELECTKEY while a flat checkbox item has focus will toggle the checkbox’s current state. If the control is "set", then toggling the control will call the XtNunselectProc callback list. If the control is "not set", then toggling the control will call the XtNselectProc callback list.

Display of Keyboard Mnemonic

The FlatCheckBox widget displays the mnemonic accelerator of a sub-object as part of the sub-object’s label. If the mnemonic character is in the label, then that character is highlighted according to the value returned by XtNshowMnemonics(). 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 XtNshowMnemonics().

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

Display of Keyboard Accelerators

The FlatCheckBox widget displays the keyboard accelerator as part of the sub-object’s 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.

Figure 1 FlatCheckBox Item

Coloration

The FlatCheckBox container inherits its background color from the container’s parent widget. Setting the background color affects only the sub-objects’ background.

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

On color displays, when the FlatCheckBox widget receives the input focus, the background color within the bounding box of the first sub-object is changed to the input focus color set in the XtNinputFocusColor resource. When the FlatCheckBox sub-object 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 FlatCheckBox widget inverts the foreground and background colors of the sub-object when it has input focus.

—If the input focus color is the same as the font color or foreground color, then the FlatCheckBox widget inverts the foreground and background colors of the sub-object when it has input focus.

RESOURCES

Sub-object Resources

The following tables list the resources for the FlatExclusives. Resources marked by a bullet (•) denote sub-object resources. If these resources are not included in the XtNitemFields list, they are inherited from the container widget. An application can change the default values for sub-object resources by setting them on the container directly. Even though a sub-object resource is not included in the XtNitemFields list, the application can query the value of any sub-object resource with OlFlatGetValues().

Table 1 Flat CheckBox Resource Summary

Name                      Type           Default             Access
XtNaccelerator-+         String           NULL                  SGI
XtNacceleratorText-+     String           Dynamic               SGI
XtNancestorSensitive-+   Boolean          TRUE                  G
XtNbackground-+          Pixel            XtDefaultBackground   SGI
XtNbackgroundPixmap-+    Pixmap           None                  SGI
XtNborderWidth-+         Dimension        0                     SGI
XtNclientData+           XtPointer        NULL                  SGI
XtNconsumeEvent-         XtCallbackList   NULL                  SGI
XtNdepth-                Cardinal         (parent’s)            GI
XtNdim                   Boolean          FALSE                 SGI
XtNfont+                 XFontStruct∗     (OPEN LOOK font)      SI
XtNfontColor-+           Pixel            XtDefaultForeground   SGI
XtNforeground-           Pixel            XtDefaultForeground   SGI
XtNgravity-              int              CenterGravity         SGI
XtNhPad-                 Dimension        0                     SGI
XtNhSpace-               Dimension        (calculated)          SGI
XtNheight-               Dimension        (calculated)          SGI
XtNinputFocusColor-+     Pixel            Red                   SGI
XtNitemFields            String∗          NULL                  GI
XtNitemGravity-          int              NorthWestGravity      SGI
XtNitemMaxHeight-        Dimension        OL_IGNORE             SGI
XtNitemMaxWidth-         Dimension        OL_IGNORE             SGI
XtNitemMinHeight-        Dimension        OL_IGNORE             SGI
XtNitemMinWidth-         Dimension        OL_IGNORE             SGI
XtNitems                 XtPointer        NULL                  SGI
XtNitemsTouched          Boolean          FALSE                 SG
XtNlabel+                String           NULL                  SGI
XtNlabelImage+           XImage∗          NULL                  SGI
XtNlabelJustify+         OlDefine         OL_LEFT               SGI
XtNlabelTile+            Boolean          FALSE                 SGI
XtNlayoutHeight-         OlDefine         OL_MINIMIZE           SGI
XtNlayoutType-           OlDefine         OL_FIXEDROWS          SGI
XtNlayoutWidth-          OlDefine         OL_MINIMIZE           SGI
XtNmanaged               Boolean          TRUE                  SGI
XtNmappedWhenManaged-+   Boolean          TRUE                  SGI
XtNmeasure-              int              1                     SGI
XtNmnemonic-+            unsigned char    NULL                  SGI
XtNnumItemFields         Cardinal         0                     SGI
XtNnumItems              Cardinal         0                     SGI
XtNposition+             OlDefine         OL_LEFT               SGI
XtNreferenceName-        String           NULL                  SGI
XtNreferenceWidget-      Widget           NULL                  SGI
XtNsameHeight-           OlDefine         OL_ALL                SGI
XtNsameWidth-            OlDefine         OL_COLUMNS            SGI
XtNselectProc+           XtCallbackProc   NULL                  SGI
XtNsensitive-+           Boolean          TRUE                  SGI
XtNset+                  Boolean          FALSE                 SGI∗
XtNtraversalOn-+         Boolean          TRUE                  SGI
XtNunselectProc+         XtCallbackProc   NULL                  SGI
XtNuserData-+            XtPointer        NULL                  SGI
XtNvPad-                 Dimension        0                     SGI
XtNvSpace-               Dimension        (calculated)          SGI
XtNwidth-                Dimension        (calculated)          SGI
XtNx-                    Position         0                     SGI
XtNy-                    Position         0                     SGI

Access: S = XtSetValues G = XtGetValues
I = init time O = other access
• sub-object resources; see below
∗ not inherited from container
† see resources(3W)

XtNancestorSensitive

class:XtCSensitive type:Boolean default:TRUEaccess:G

Action: indicates the sensitivity of the sub-object’s ancestors.

Values: TRUE/true – all the sub-object’s ancestors are sensitive and the sub-object is sensitive to user input. FALSE/false – one or more of the sub-object’s ancestors are insensitive, so the sub-object displays an inactive visual and is not sensitive to user input.

XtNbackground

class:XtCBackground type:Pixel default:XtDefaultBackgroundaccess:SGI

Action: sets the pixel color used to fill in the background of the check box.

XtNbackgroundPixmap

class:XtCBackgroundPixmap type:Pixmap default:Noneaccess:SGI

Action: specifies the pixmap that is displayed as the sub-object’s label.

Any supplied pixmap must have the same depth as the flat widget’s depth. Pixmaps of None and ParentRelative are not considered valid values.

If either XtNlabel or XtNlabelImage has a non -NULL value, this resource is ignored.

XtNclientData

class:XtCClientData type:XtPointer default:NULLaccess:SGI

Action: sets the client data supplied to all callback procedures.

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 borders are dimmed to show that each check box represents inactive or indeterminate states.

XtNfont

class:XtCFont type:XFontStruct∗ default:OPEN LOOK fontaccess:SI

Action: specifies the font for the string specified by the XtNlabel resource.

XtNfontColor

class:XtCFontColor type:Pixel default:XtDefaultForegroundaccess:SGI

Action: specifies the font color of the sub-object’s label, even if the label is an XImage.

XtNforeground

class:XtCForeground type:Pixel default:XtDefaultForegroundaccess:SGI

Action: sets the pixel color used to draw check box and check.

XtNitems

class:XtCItems type:XtPointer default:NULLaccess:SGI

Action: provides the list of sub-object items. This value must point to a static list since flat containers reference this list after initialization but do not cache its information.

XtNitemFields

class:XtCItemFields type:String∗ default:NULLaccess:GI

Action: provides the list of resource names used to parse the records in the XtNitems list.

This resource does not have to point to static information since the flat container does not use this information after initialization. Though the flat container does not reference this resource’s value after initialization, it holds onto it for responding to an XtGetValues() request and supplying it in the OlFlatCallData structure during callbacks. Therefore, if the application plans on querying this resource, it is recommended that the application make this resource point to static information.

XtNitemsTouched

class:XtCItemsTouched type:Boolean default:FALSEaccess:SG

Action: indicates whether visual needs updating.

Whenever the application modifies an item list directly, it must supply this resource with a value of TRUE to the flat widget container so that the container can update the visual. If the resource value is supplied, the flat widget container treats its current item list as a new list and hence, updates its entire visual. Since the list is treated as a new list, the flat container may request a change in geometry from its parent.

Note: It is not necessary to use this resource if the application modifies the list with the OlFlatSetValues procedure; nor is it necessary to use this resource whenever the application supplies a new list to the flat container.

Values: TRUE, FALSE

XtNlabel

class:XtCLabel type:String default:NULLaccess:SGI• Action: sets the text string that appears in the sub-object.class:XtCLabelImage type:XImage∗ default:NULLaccess:SGI

Action: an XImage pointer that can appear in a sub-object.

This resource is ignored if XtNlabel is non-NULL.

XtNlabelJustify

class:XtCLabelJustify type:OlDefine default:OL_LEFTaccess:SGI

Action: specifies the justification of the label or XImage that appears within a sub-object.

Values: OL_LEFT/left, OL_CENTER/center, OL_RIGHT/right

XtNlabelTile

class:XtCLabelTile type:Boolean default:FALSEaccess:SGI

Action: augments the XtNlabelImage/XtNlabelPixmap resource to allow tiling of the sub-object’s background.

Values: TRUE, FALSE

For an image or 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 XtNlabelJustify resource.

The XtNlabelTile resource is ignored for text labels.

XtNmanaged

class:XtCManaged type:Boolean default:TRUEaccess:SGI

Action: Determines whether the FlatCheckbox widget manages its sub-objects.

Values: TRUE – the widget manages its sub-objects. FALSE – the widget doesn’t manage its sub-objects.

XtNmappedWhenManaged

class:XtCMappedWhenManaged type:Boolean default:TRUEaccess:SGI

Action: specifies whether or not a managed sub-object is displayed

Note: This resource is never inherited from the container, so its default value is always TRUE

Values: TRUE/true, FALSE/false

Regardless of this resource’s value, all managed sub-objects will be included when determining the layout.

XtNnumItems

class:XtCNumItems type:Cardinal default:0access:SGI

Action: specifies the number of sub-object items.

XtNnumItemFields

class:XtCNumItemFields type:Cardinal default:0access:SGI

Action: indicates the number of resource names contained in XtNitemFields

XtNposition

class:XtCPosition type:OlDefine default:OL_LEFTaccess:SGI

Action: determines on which side of the check box to place the label.

Values: OL_LEFT/left, OL_RIGHT/right

The value of OL_LEFT or OL_RIGHT indicates the label is placed to the left or to the right of the check box, respectively.

XtNsameHeight

class:XtCSameHeight type:OlDefine default:OL_ALLaccess:SGI

Action: specifies that rows are forced to the same width.

Values: OL_ALL/all, OL_COLUMNS/columns, OL_NONE/none

XtNsameWidth

class:XtCSameWidth type:OlDefine default:OL_ALLaccess:SGI

Action: specifies that columns are forced to the same height.

Values: OL_ALL/all, OL_ROWS/rows, OL_NONE/none

XtNselectProc

class:XtCCallbackProc type:XtCallbackProc default:NULLaccess:SGI

Action: points to the callback procedure for the sub-object becoming selected by user input.

XtNsensitive

class:XtCSensitive type:Boolean default:TRUEaccess:SGI

Action: indicates sensitivity to user input.

Values: TRUE/true – the sub-object is sensitive to user input. FALSE/false – the sub-object is insensitive to user input and an inactive visual is displayed to indicate this state.

Note: This resource is never inherited from the container, so its default value is always TRUE.

XtNset

class:XtCSet type:Boolean default:FALSEaccess:SGI

Action: reflects the current state of the sub-object.