NAME

FlatExclusives − flat, exclusive choice widget

SYNOPSIS

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

my_flatexclusive =  XtCreate( my_name, flatExclusivesWidgetClass,

my_parent, args, num_args);

DESCRIPTION

  Figure 1 Flat Exclusives Widget

Selection Control

There are two modes of operation, determined by XtNnoneSet.  In one mode, when XtNnoneSet is FALSE, exactly one sub-object in a FlatExclusives widget must be set. That is, 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. 

In the other mode of operation, when 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. 

Menu Use

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

Coloration

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

Keyboard Traversal

The FlatExclusives widget is a Primitive widget that manages the traversal between a set of sub-objects.  When the user traverses to a FlatExclusives widget, the first sub-object in the set will display itself as having input focus (see the RectButton 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 FlatExclusives 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              Exclusives Activation     Types
_
Activation        Type       Expected       Results
=
 
OL_MENUDEFAULTKEY
If                the        FlatExclusives is
to                be         menu’s         default;
 
_
OL_SELECTKEY
This              command    acts           as
RectButton        with       focus.         See
above.
 

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 Exclusives 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
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
XtNnoneSet           Boolean        FALSE        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 timeO = other access
• sub-object resources; see below
∗ not inherited from container
† see Resources(3W)

Flat                 Exclusives     Resource     Set
Name                 Type           Default      Access
=
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
_
XtNnoneSet           Boolean        FALSE        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 timeO = other access
• sub-object resources; see below
∗ not inherited from container
† see Resources(3W)

XtNancestorSensitive

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

Values: TRUE – all the sub-object’s ancestors are sensitive and the sub-object is sensitive to user input.  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: indicates the pixel color used to fill in the background of the sub-object. 

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: indicates the client data supplied to all callback procedures. 

XtNdefault

class:XtCDefault type:Boolean default:FALSEaccess:SGI

Action: When used on the container, this resource indicates whether or not one of the sub-objects is a default item. 

Values: TRUE – If a sub-object is a default item FALSE – otherwise

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. 

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 .

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. 

XtNdim

class:XtCDim type:Boolean default:FALSEaccess:SGI

Action: indicates substate changes visually

Values: 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.  FALSE – otherwise

XtNfont

class:XtCFont type:XFontStruct∗ default:(OPEN LOOK font)access:SI

Action:  displays the string specified by the XtNlabel resource. 

XtNfontColor

class:XtCFontColor type:Pixel default:XtDefaultForegroundaccess:SGI

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

XtNforeground

class:XtCForeground type:Pixel default:XtDefaultForegroundaccess:SGI

Action: specifies the pixel color used when drawing the sub-object’s outline. 

XtNitems

class:XtCItems type:XtPointer default:NULLaccess:SGI

Action: specifies 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: 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 OlFlatCallData 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

class:XtCItemsTouched type:Boolean default:FALSEaccess:SG

Action: 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. 

Values: TRUE, FALSE

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

class:XtCLabel type:String default:NULLaccess:SGI

Action: specifies the text string that appears in the sub-object. 

XtNlabelImage

class:XtCLabelImage type:XImage default:NULLaccess:SGI

Action: specifies 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 of sub-object. 

Values: OL_LEFT, OL_CENTER, OL_RIGHT. 

XtNlabelTile

class:XtCLabelTile type:Boolean default:FALSEaccess:SGI

Action: specifies tiling of subobject’s background. 

Values: TRUE, 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 XtNlabelJustify resource.  The XtNlabelTile resource is ignored for text labels. 

XtNmappedWhenManaged

class:XtCMappedWhenManaged type:Boolean default:TRUEaccess:SGI

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

Values: TRUE, FALSE

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

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

XtNnoneSet

class:XtCNoneSet type:Boolean default:FALSEaccess:SGI

Action: controls whether the settings can be toggled into an unset mode directly. 

Values: TRUE – zero or more than one sub-object can be set at any time.  The user can select the currently set sub-object and toggle it back to an unset state.  FALSE – exactly one sub-object must be in the set state always. Attempting to select the currently set sub-object does nothing.

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

XtNsameHeight

class:XtCSameHeight type:OlDefine default:OL_ALLaccess:SGI

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

Values: OL_ALL, OL_ROWS

XtNsameWidth

class:XtCSameWidth type:OlDefine default:OL_COLUMNSaccess:SGI

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

Values: OL_ALL, OL_COLUMNS

XtNselectProc

class:XtCCallbackProc type:XtCallbackProc default:NULLaccess:SGI

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

XtNsensitive

class:XtCSensitive type:Boolean default:TRUEaccess:SGI

Action: specifies sensitivity to user input

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

Values: TRUE, FALSE

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

class:XtCCallbackProc type:XtCallbackProc default:NULLaccess:SGI

Action: specifies the callback procedure for the sub-object becoming unselected by user input. 
 

Version 3.0  —  Last change: 19 July 91  —  Last change: 19 July 91