NAME

Exclusives − exclusive choice widget

SYNOPSIS

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

my_exclusive =  XtCreate( my_name, exclusivesWidgetClass,

my_parent, args, num_args);

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

,LP 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

Exclusives           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 timeO = 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/fixedcolumns – 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
 class:XtCNoneSettype:Booleandefault: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  —  19 July 91