NAME

Exclusives − exclusive choice widget

SYNOPSIS

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

ANCESTRY

Core-Composite-Constraint-Manager-Exclusives

DESCRIPTION

The Exclusives widget provides a simple way to build a one-of-many button selection object.  It manages a set of rectangular buttons, providing layout management. 

Grid Layout and Button Labels

  Figure 1 Example of Exclusive Buttons

The Exclusives widget lays out the rectangular buttons in a grid in the order they were added as child widgets by the application.  The number of rows or columns in this grid can be controlled by the application. 

If the grid has more than one row, the Exclusives widget forces the buttons in each column to be the same size as the widest in the column, and forces their labels to be left-justified. 

Note:  If the grid has a single row, each button will be only as wide as necessary to display the label. 

Selection Control

One Set - When XtNnoneSet is FALSE, exactly one button in an Exclusives widget must be set (its XtNset resource is set to TRUE).  An error is generated if an Exclusives is configured with two or more rectangular buttons set or with no button set.  The Exclusives widget maintains this condition by ensuring that when a button is set by the user clicking SELECT over it, the button that was set is cleared and its XtNunselect callbacks are invoked.  However, clicking SELECT over a button that was already set does nothing. 

None Set - When XtNnoneSet is TRUE, at most one button in an Exclusives widget can be set.  An error is generated if an Exclusives is configured with two or more rectangular buttons set, but not if configured with no button set. 

The Exclusives widget maintains this condition by ensuring that when a button is set by the user clicking SELECT over it, any button that was previously set is cleared.  Also, clicking SELECT over a button that was already set will unset it.  Clearing a button in either case invokes its XtNunselect callbacks. 

Menu Use

The Exclusives widget can be added as a single child to a menu pane to implement a one-of-many menu choice. 

Child Constraint

The Exclusives widget constrains its child widgets to be of the class rectButtonWidgetClass

Coloration

There is no explicit foreground or background in the Exclusives composite widget; each rectangular button has its own coloration. 

Keyboard Traversal

The Exclusives widget manages the traversal between a set of RectButtons.  When the user traverses to an Exclusives widget, the first RectButton in the set will receive input focus. 

The MOVEUP, MOVEDOWN, MOVERIGHT, and MOVELEFT keys move the input focus between the RectButtons.  To traverse out of the Exclusives 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. 

The SELECTKEY acts as if the SELECT button had been clicked on the RectButton with input focus.  The MENUKEY acts as if the MENU button had been clicked on the RectButton with input focus. 

RESOURCES

  Table 1 Exclusive Buttons Resource Set

Name                    Type           Default            Access
XtNancestorSensitive-   Boolean          TRUE           GO
XtNconsumeEvent-        XtCallbackList   NULL           SG
XtNdepth-               int              (parent’s)     GI
XtNdestroyCallback-     XtCallbackList   NULL           SI
XtNheight-              Dimension        (calculated)   SGI
XtNlayoutType           OlDefine         OL_FIXEDROWS   SGI
XtNmappedWhenManaged-   Boolean          TRUE           SGI
XtNmeasure              int              1              SGI
XtNnoneSet              Boolean          FALSE          SGI
XtNreferenceName-       String           NULL           GI
XtNreferenceWidget-     Widget           NULL           GI
XtNsensitive-           Boolean          TRUE           GIO
XtNtraversalOn-         Boolean          TRUE           SGI
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)

XtNlayoutType

class:XtCLayoutType type:OlDefine default:OL_FIXEDROWSaccess:SGI

Action: controls the type of layout of child widgets

Values: OL_FIXEDROWS/fixedrows – if the layout should have a fixed number of rows; OL_FIXEDCOLS/fixedcols – if the layout should have a fixed number of columns.

The choices are to specify the number of rows or the number of columns.  Only one of these dimensions can be specified directly; the other is determined by the number of child widgets added, and will always be enough to show all the child widgets. 

XtNmeasure

class:XtCMeasure type:int default:1access:SGI

Action: gives number of rows or columns in layout of child widgets. 

Values: 0 < XtNmeasure

If there are not enough child widgets to fill a row or column, the remaining space is left blank.  If there is only one row (column), and it is not filled with child widgets, the remaining “space” is of zero width (height). 

XtNnoneSet

class:XtCNoneSet type:Boolean default:FALSEaccess:SGI

Action: determines whether the buttons controlled by the Exclusives composite can be toggled into an unset mode directly. 

Values: FALSE – at all times exactly one button must be set.  Attempting to select the currently set button does nothing.  TRUE – at all times no more than one button can be set. However, the user can select the currently set button again to toggle it back into an unset mode.
 
 
 

Version 3.0.1  —  Last change: June 92