WIDGET CLASS NAME

Exclusives

SYNOPSIS

#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Exclusives.h>

widget = XtCreateWidget(name, exclusivesWidgetClass, ...);

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

Sample exclusive button widgets are shown in the diagram Example of Exclusive Buttons. 

  Figure 1 Example of Exclusive Buttons

The Exclusives widget lays out the rectangular buttons in a grid in the order they are 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 In one mode of operation (i.e, XtNnoneSet is FALSE), exactly one button in an Exclusives widget must be "set" (i.e. the XtNset resource 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.  Selection Control—None Set In the other mode of operation (i.e, 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. 

Use in a Menu

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.  Exclusives Coloration

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

RESOURCES

  Table 1 Exclusive Buttons Resource Set Exclusives Resource Set
                Name            Type       Default  Access XtNancestorSensitive         Boolean          TRUE      G∗
            XtNdepth             int    (parent’s)      GI
  XtNdestroyCallback  XtCallbackList          NULL      SI
           XtNheight       Dimension  (calculated)     SGI XtNmappedWhenManaged         Boolean          TRUE     SGI
          XtNmeasure             int             1     SGI
          XtNnoneSet         Boolean         FALSE     SGI
        XtNsensitive         Boolean          TRUE     GI∗
         XtNuserData       XtPointer          NULL     SGI
            XtNwidth       Dimension  (calculated)     SGI
                XtNx        Position             0     SGI
                XtNy        Position             0     SGI XtNlayoutType

Range of Values:

OL_FIXEDROWS/"fixedrows"
OL_FIXEDCOLS/"fixedcols"

This resource controls the type of layout of the child widgets by the Exclusives composite.  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. 

The values of the XtNlayoutType resource can be

OL_FIXEDROWS
if the layout should have a fixed number of rows;

OL_FIXEDCOLS
if the layout should have a fixed number of columns.

XtNmeasure

Range of Values:

0 < XtNmeasure

This resource gives the number of rows or columns in the layout of the child widgets.  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

Range of Values:

TRUE
FALSE

This resource controls whether the buttons controlled by the Exclusives composite can be toggled into an unset mode directly.  If set to FALSE, at all times exactly one button must be set.  Attempting to select the currently set button does nothing.  If set to 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. 

Sun Release 4.1  —  Last change: 1/8/90