WIDGET CLASS NAME

FlatExclusives

SYNOPSIS

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

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

DESCRIPTION

Figure 1.  Flat Exclusives Widget

Selection Control - One Set In one mode operation (i.e., XtNnoneSet is FALSE), exactly one sub-object in a FlatExclusives widget must be "set," i.e., the XtNset resource is TRUE for one of the sub-objects. A warning is generated if two or more sub-objects are set. If no items are set, the FlatExclusives makes the first sub-object that is both managed and mapped when managed be the set item. No warning is produced in this case. The FlatExclusives maintains this condition by ensuring that when a sub-object is set by the user clicking SELECT over it, the sub-object that was set is cleared and its XtNunselectProc procedure is called and the sub-object under the pointer is made to be set and its XtNselectProc procedure is called. However, clicking SELECT over a sub-object that is already set does nothing.

Selection Control - None Set In the other mode of operation (i.e., XtNnoneSet is TRUE), at most one sub-object in a FlatExclusives widget can be "set." A warning is generated if two or more sub-objects are set. The FlatExclusives maintains this condition by ensuring that when a sub-object is set by the user clicking SELECT over it, the sub-object that was set is cleared and its XtNunselectProc procedure is called and the sub-object under the pointer is made to be set and its XtNselectProc procedure is called. Clicking SELECT over a sub-object that is already set clears it and its XtNselectProc procedure is called.

Use in a Menu The FlatExclusives widget can be added as child in a menu pane to implement a one-of-many menu choice.

FlatExclusives Coloration The FlatExclusives container inherits its background color from the container's parent widget. Setting the background color affects only the sub-objects' background.

RESOURCES

The following table lists the resources for the FlatExclusives. Resources that have a bullet (•) in the Access column 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 OlFlat-GetValues().

 ___________________________________________________________________________________________
|_______________________________Flat_Exclusives_Resource_Set_______________________________|
| Name                |  Class              |  Type         |  Default            |  Access|
|_____________________|_____________________|_______________|_____________________|________|
|_XtNancestorSensitive|__XtCSensitive_______|__Boolean______|__TRUE_______________|__G•____|
| XtNbackground       |  XtCBackground      |  Pixel        |  XtDefaultBackground|  SGI•  |
|_____________________|_____________________|_______________|_____________________|________|
|_XtNbackgroundPixmap_|__XtCBackgroundPixmap|__Pixmap_______|__None_______________|__SGI•__|
| XtNborderWidth      |  XtCBorderWidth     |  Dimension    |  0                  |  SGI•  |
|_____________________|_____________________|_______________|_____________________|________|
|_XtNclientData_______|__XtCClientData______|__XtPointer____|__NULL_______________|__SGI•__|
| XtNdefault          |  XtCDefault         |  Boolean      |  FALSE              |  SGI-• |
|_____________________|_____________________|_______________|_____________________|________|
|_XtNdepth____________|__XtCDepth___________|__Cardinal_____|__(parent's)_________|__GI____|
| XtNdim              |  XtCDim             |  Boolean      |  FALSE              |  SGI•  |
|_____________________|_____________________|_______________|_____________________|________|
|_XtNfont_____________|__XtCFont____________|__XFontStruct_*|__(OPEN_LOOK_font)___|__SI•___|
| XtNfontColor        |  XtCFontColor       |  Pixel        |  XtDefaultForeground|  SGI•  |
|_____________________|_____________________|_______________|_____________________|________|
|_XtNforeground_______|__XtCForeground______|__Pixel________|__XtDefaultForeground|__SGI___|

 _______________________________________________________________________________________
 _________________________Flat_Exclusives_Resource_Set_(cont.)__________________________
  Name                   Class                  Type             Default         Access
 _______________________________________________________________________________________
 _XtNgravity_____________XtCGravity_____________int______________CenterGravity___SGI____
  XtNhPad                XtCHPad                Dimension        0               SGI
 _______________________________________________________________________________________
 _XtNheight______________XtCHeight______________Dimension________(calculated)____SGI____
  XtNitemFields          XtCItemFields          String *         NULL            GI
 _______________________________________________________________________________________
 _XtNitemMaxHeight_______XtCItemMaxHeight_______Dimension________OL_IGNORE_______SGI____
  XtNitemMaxWidth        XtCItemMaxWidth        Dimension        OL_IGNORE       SGI
 _______________________________________________________________________________________
 _XtNitemMinHeight_______XtCItemMinHeight_______Dimension________OL_IGNORE_______SGI____
  XtNitemMinWidth        XtCItemMinWidth        Dimension        OL_IGNORE       SGI
 _______________________________________________________________________________________
 _XtNitems_______________XtCItems_______________XtPointer________NULL____________SGI____
  XtNitemsTouched        XtCItemsTouched        Boolean          FALSE           SG
 _______________________________________________________________________________________
 _XtNlabel_______________XtCLabel_______________String___________NULL____________SGI•___
  XtNlabelImage          XtCLabelImage          XImage *         NULL            SGI•
 _______________________________________________________________________________________
 _XtNlabelJustify________XtCLabelJustify________OlDefine_________OL_LEFT_________SGI•___
  XtNlabelTile           XtCLabelTile           Boolean          FALSE           SGI•
 _______________________________________________________________________________________
 _XtNlayoutHeight________XtCLayoutHeight________OlDefine_________OL_MINIMIZE_____SGI____
  XtNlayoutType          XtCLayoutType          OlDefine         OL_FIXEDROWS    SGI
 _______________________________________________________________________________________
 _XtNlayoutWidth_________XtCLayoutWidth_________OlDefine_________OL_MINIMIZE_____SGI____
  XtNmanaged             XtCManaged             Boolean          TRUE            SGI
 _______________________________________________________________________________________
 _XtNmappedWhenManaged___XtCMappedWhenManaged___Boolean__________TRUE____________SGI•___
  XtNmeasure             XtCMeasure             int              1               SGI
 _______________________________________________________________________________________
 _XtNnoneSet_____________XtCNoneSet_____________Boolean__________FALSE___________SGI____
  XtNnumItemFields       XtCNumItemFields       Cardinal         0               SGI
 _______________________________________________________________________________________
 _XtNnumItems____________XtCNumItems____________Cardinal_________0_______________SGI____
  XtNsameHeight          XtCSameHeight          OlDefine         OL_ALL          SGI
 _______________________________________________________________________________________
 _XtNsameWidth___________XtCSameWidth___________OlDefine_________OL_COLUMNS______SGI____
  XtNselectProc          XtCCallbackProc        XtCallbackProc   NULL            SGI•
 _______________________________________________________________________________________
 _XtNsensitive___________XtCSensitive___________Boolean__________TRUE____________SGI•___
  XtNset                 XtCSet                 Boolean          FALSE           SGI-•
 _______________________________________________________________________________________
 _XtNunselectProc________XtCCallbackProc________XtCallbackProc___NULL____________SGI•___
  XtNuserData            XtCUserData            XtPointer        NULL            SGI•
  XtNvPad                XtCVPad                Dimension        0               SGI
 _______________________________________________________________________________________
 _XtNwidth_______________XtCWidth_______________Dimension________(calculated)____SGI____
  XtNx                   XtCPosition            Position         0               SGI

 _______________________________________________________________________________________
|_XtNy___________________XtCPosition____________Position_________0_______________SGI___|
 XtNancestorSensitive Range of Values:
                      TRUE/"true"
                      FALSE/"false"

This resource indicates the sensitivity of the sub-object's ancestors. If TRUE, all the sub-object's ancestors are sensitive and the sub-object is sensitive to user input. If 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 This is the pixel color used to fill in the background of the sub-object.

XtNbackgroundPixmap This resource 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 This is the client data supplied to all callback procedures.

XtNdefault Range of Values:

TRUE/"true"
FALSE/"false"

When used on the sub-object, this resource specifies whether or not the sub-object is a default item. If more than one item is a set as a default item, a warning is generated and all but the first default item is unselected. When used on the container, this resource indicates whether or not one of the sub-objects is a default item. If a sub-object is a default item, XtNdefault has a value of TRUE; else it has a value of FALSE. Setting this resource on the container widget indicates whether or not one of the sub-objects should be a default item. If the application sets this value to TRUE on the container, the container will set the first managed and mapped sub-object as the default item if a default item does not exist. If the application sets this value to FALSE, the container will unset its default item if one exists. Even if the application does not use XtNdefault in its item fields list, the container will correctly maintain the default item and the application can change the default item via OlFlatSetValues.

XtNdim Range of Values:

TRUE/"true"
FALSE/"false"

If TRUE, the sub-object shows a dimmed visual indicating that the item represents the state of one or more objects, that as a group, are in different states.

XtNfont This resource displays the string specified by the XtNlabel resource.

XtNfontColor This resource specifies the foreground color of the sub-object's label, even if the label is an XImage.

XtNforeground This is the pixel color used when drawing the sub-object's outline.

XtNitems This is 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 This is 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 OlFlat-CallData structure during callbacks. Therefore, if the application plans on querying this resource, it's recommended that the application make this resource point to static information.

XtNitemsTouched
Range of Values:
                     TRUE
                     FALSE
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.

XtNlabel This is the text string that appears in the sub-object.

XtNlabelImage This is an XImage pointer that can appear in a sub-object. This resource is ignored if XtNlabel is non-NULL.

XtNlabelJustify Range of Values:

OL_LEFT/"left"
OL_CENTER/"center"
OL_RIGHT/"right"

This resource specifies the justification of the label or XImage that appears within a sub-object.

XtNlabelTile Range of Values:

TRUE/"true"
FALSE/"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 XtNlabel-Justify resource.

The XtNlabelTile resource is ignored for text labels.

XtNmappedWhenManaged Range of Values:

                     TRUE/"true"
                     FALSE/"false"

This resource specifies whether or not a managed  sub-object
is  displayed.   Regardless  of  this  resource's value, all
managed sub-objects will be including when  determining  the
layout.  Note:
This resource is never inherited from the container, so  its
default value is always TRUE.

XtNnoneSet Range of Values:

TRUE/"true"
FALSE/"false"

This resource controls whether the settings can be toggled into an unset mode directly. If set to FALSE, exactly one sub-object must be in the set state always. Attempting to select the currently set sub-object does nothing. If set to TRUE, no more than one sub-object can be set at any time. However, the user can select the currently set sub-object and toggle it back to an unset state.

XtNnumItems This resource specifies the number of sub-object items.

XtNnumItemFields This resource indicates the number of resource names contained in XtNitemFields.

XtNsameHeight Range of Values:

OL_ALL/"all"
OL_ROWS/"rows"

This resource specifies the rows that are forced to the same height.

XtNsameWidth Range of Values:

OL_ALL/"all"
OL_COLUMNS/"columns"

This resource specifies the columns that are forced to the same width.

XtNselectProc This callback procedure is called whenever the sub-object becomes selected by user input.

XtNsensitive Range of Values:

TRUE/"true"
FALSE/"false"

If TRUE, the sub-object is sensitive to user input. If 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 Range of Values:

                     TRUE/"true"
                     FALSE/"false"

This resource reflects the current state of the  sub-object.
Note:
This resource is never inherited from the container, so  its
default value is always FALSE.  Even if the application does
not use XtNset in its item fields list, the  container  will
correctly  maintain  the  set  item  and the application can
change the set item via OlFlatSetValues.

XtNunselectProc This callback procedure is called whenever the sub-object becomes unselected by user input.