NAME

RectButton − rectangular button widget

SYNOPSIS

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

ANCESTRY

Core-Primitive-Button-RectButton

DESCRIPTION

The RectButton is a toggle button that can be either set or not set.  When the user pushes the button its 3D look inverts, making it look like the button has been pressed.  The button remains in this set state until the user presses it again or it is unset programmatically. 

Components

The figure below shows several OPEN LOOK button widgets, in normal, default, and current states (two versions). 

  Figure 1 Rectangular Buttons

The RectButton widget implements one of the OPEN LOOK buttons.  It consists of a Label surrounded by a rectangular border.  The border can change to reflect that the button may be a default of several buttons (double border), or represents a current state of an object (thick border), or represents a current state of one of several objects with different states (dimmed border). 

Rectangular buttons are not used alone but in one of the Exclusives or Nonexclusives composite widgets for implementing a one-of-many or several-of-many selection.  Making this widget a child of a different composite widget will not produce an error message, but proper behavior is not guaranteed. 

RectButton State

A RectButton widget has two states: set and not set. (When set, its border is thickened.) Toggling this state alternates a resource (XtNset) between TRUE and FALSE and starts an action associated with the button.  The RectButton widget is typically toggled by the user using SELECT or MENU, except that it is possible to disable user toggling of a button that is already set. 

Restrictions

To work correctly, the RectButton widget needs to be a child of a proper composite widget: either an:

Exclusives, or a

Nonexclusives composite widget. 

The descriptions below of using the RectButton widget in a menu should be read to imply that the RectButton widget is enclosed in an Exclusives or Nonexclusives widget, which, in turn, is enclosed in a menu. 

Popup Menu RectButtons

Entering a rectangular button while MENU is depressed changes the appearance of the button from unset to set state or vice versa, to reflect the state the button would be in if MENU were released.  Releasing MENU toggles the state associated with the button.  Leaving the button before releasing MENU restore the original state appearance and does not toggle the button. 

Non-Popup Menu RectButtons

Clicking SELECT on a rectangular button toggles the state associated with it.  Pressing SELECT, or moving the pointer into the button while SELECT is pressed, changes the border from unset to set state or vice versa, to reflect the state the button would be in if SELECT were released.  Releasing SELECT toggles the state.  Moving the pointer off the button before releasing SELECT restores the state appearance and does not toggle the button.  but does not toggle the state. 

If the button is in a stay-up menu, clicking or pressing MENU works the same as SELECT.  If the button is not in a stay-up (or pop-up) menu, clicking or pressing MENU does not do anything; the event is passed up to an ancestor widget. 

Coloration

On a monochrome display, the RectButton widget indicates that it has input focus by inverting the foreground and background colors of the control. 

On color displays, when the RectButton widget receives the input focus, the background color is changed to the input focus color set in the XtNinputFocusColor resource. 

EXCEPTIONS:

—If the input focus color is the same as the font color for the control labels, then the coloration of the active control is inverted. 

—If the input focus color is the same as the Input Window Header Color and the active control is in the window header, then invert the colors. 

—If the input focus color is the same as the window background color, then the RectButton widget inverts the foreground and background colors when it has input focus.  of the RectButton widget. 

  Figure 2 Rectangular Button Coloration

Keyboard Traversal

The default value of the XtNtraversalOn resource is TRUE. 

The RectButton widget responds to the following keyboard navigation keys:

—NEXT_FIELD moves to the next traversable widget in the window

—PREV_FIELD moves to the previous traversable widget in the window

—MOVEUP moves to the RectButton above the current widget in the Nonexclusives or Exclusives composite

—MOVEDOWN moves to the RectButton below the current widget in the Nonexclusives or Exclusives composite

—LEFT moves to the RectButton to the left of the current widget in the Nonexclusives or Exclusives composite

—MOVERIGHT moves to the RectButton to the right of the current widget in the Nonexclusives or Exclusives composite

—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 RectButton will respond to the SELECTKEY by acting as if the SELECT buttons had been clicked. 

RectButton Activation Types

Activation Typeand Expected Results
 OL_MENUDEFAULTKEY: Set the sub-object as the shell’s default object (if on a menu)
 OL_SELECTKEY: Call its callbacks

Keyboard Mnemonic Display

The RectButton widget displays the mnemonic accelerator for its child as part of its label.  If the mnemonic character is in the label, then that character is highlighted according to the value returned by OlQueryMnemonicDisplay().  If the mnemonic character is not in the label, it is displayed to the right of the label in parentheses and highlighted according to the value returned by OlQueryMnemonicDisplay(). 

If truncation is necessary, the mnemonic displayed in parentheses is truncated as a unit. 

Display of Keyboard Accelerators

The RectButton widget displays the keyboard accelerator as part of its label.  The string in the XtNacceleratorText resource is displayed to the right of the label (or mnemonic) separated by at least one space.  The acceleratorText is right justified. 

If truncation is necessary, the accelerator is truncated as a unit.  The accelerator is truncated before the mnemonic or the label. 

RESOURCES

  Table 1 Rectangular Buttons Resource Set

Name                    Type             Default             Access
XtNaccelerator-         String           NULL                   SGI
XtNacceleratorText-     String           Dynamic                SGI
XtNancestorSensitive-   Boolean          TRUE                   GO
XtNbackground-          Pixel            XtDefaultBackground    SGI
XtNbackgroundPixmap-    Pixmap           (none)                 SGI
XtNconsumeEvent-        XtCallbackList   NULL                   SGI
XtNdefault              Boolean          FALSE                  SGI
XtNdepth-               int              (parent’s)             GI
XtNdestroyCallback-     XtCallbackList   NULL                   SI
XtNdim                  Boolean          FALSE                  SGI
XtNfont                 XFontStruct∗     (OPEN LOOK font)       SI
XtNfontColor            Pixel            XtDefaultForeground∗   SGI
XtNforeground-          Pixel            XtDefaultForeground    SGI
XtNheight-              Dimension        (calculated)           SGI
XtNinputFocusColor-     Pixel            Red                    SGI
XtNlabel                String           (class name)           SGI
XtNlabelImage           XImage∗          NULL                   SGI
XtNlabelJustify         OlDefine         OL_LEFT                SGI
XtNlabelTile            Boolean          FALSE                  SGI
XtNlabelType            OlDefine         OL_STRING              SGI
XtNmappedWhenManaged-   Boolean          TRUE                   SGI
XtNmnemonic-            unsigned char    NULL                   SGI
XtNreferenceName-       String           NULL                   SGI
XtNreferenceWidget-     Widget           NULL                   SGI
XtNrecomputeSize        Boolean          TRUE                   SGI
XtNscale                int              12                     SGI
XtNselect               XtCallbackList   NULL                   SI
XtNsensitive-           Boolean          TRUE                   GIO
XtNset                  Boolean          TRUE                   SGI
XtNtraversalOn-         Boolean          TRUE                   SGI
XtNunselect             XtCallbackList   NULL                   SI
XtNuserData-            XtPointer        NULL                   SGI
XtNwidth-               Dimension        (calculated)           SGI

Access:   S = XtSetValues   G = XtGetValues
            I = init time   O = other access
† see resources(3W)

XtNdefault

 class:XtCDefaulttype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’

Action: indicates default choice. 

Values: TRUE – the button is the default choice of one or more buttons, as indicated by the border being doubled to two lines, FALSE – the button is not a default choice and the border is not doubled,

XtNdim

 class:XtCDimtype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’

Action: determines whether the border of the CheckBox visually reflects the state of underlying objects

Values: TRUE, FALSE.

If this resource is TRUE, the check box border is dimmed to show that the check box represents the state of one or more of several objects that, as a group, are in different states. 

XtNfont

 class:XtCFonttype:XFontStruct∗default:(OPEN LOOK font)(OPEN LOOK font)’u’access:SISI’u’

Action: identifies the font to be used to display the label Values: any valid return from XLoadQueryFont()

Default: chosen to match the scale and screen resolution

Note: The default value points to a cached font structure.  An application should not expect to get this value with a call to XtGetValues() and use it reliably thereafter. 

XtNfontColor

 class:XtCFontColortype:Pixeldefault:XtDefaultForegroundXtDefaultForeground’u’access:SGISGI’u’

Action: specifies the font color. 

Values: any pixel value valid for the current display, or
any name from the rgb.txt file

If not set, the color from the XtNforeground resource, if available, is used for the font. 

XtNforeground

 class:XtCForegroundtype:Pixeldefault:XtDefaultForegroundXtDefaultForeground’u’access:SGISGI’u’

Action: defines the foreground color for the widget. 

XtNlabel

 class:XtCLabeltype:Stringdefault:(class name)(class name)’u’access:SGISGI’u’

Action: points to the text for the label. 

This resource is ignored if the XtNlabelType resource has the value OL_IMAGE. 

XtNlabelImage

 class:XtCLabelImagetype:XImagedefault:NULLNULL’u’access:SGISGI’u’

Action: points to the image for the Label. 

This resource is ignored unless the XtNlabelType resource has the value OL_IMAGE. 

When the RectButton is highlighted, the image is unchanged, but the border thickens. 

If the image is smaller than the space available for it inside the Border and XtNlabelTile is FALSE, the image is centered vertically and either centered or left-justified horizontally, depending on the value of the XtNlabelJustify resource. 

If the image is larger than the space available for it, it is clipped so that it does not stray outside the border. 

If the XtNdefault resource is TRUE so that the border is doubled, the space available is that inside the inner line of the border. 

XtNlabelJustify

 class:XtCLabelJustifytype:OlDefinedefault:OL_LEFTOL_LEFT’u’access:SGISGI’u’

Action: This resource dictates whether the Label should be left-justified or centered within the widget width. 

Values: OL_LEFT, OL_CENTER

XtNlabelTile

 class:XtCLabelTiletype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’

Action: augments the XtNlabelImage/XtNlabelPixmap resource to allow tiling of the sub-object’s background. 

Values: TRUE – the label area of an image/pixmap that is smaller than the sub-object’s background is tiled with the image/pixmap to fill the sub-object’s background FALSE – the label is placed as described by the XtNlabelJustify resource. 

The XtNlabelTile resource is ignored for text labels. 

XtNlabelType

 class:XtCLabelTypetype:OlDefinedefault:OL_STRINGOL_STRING’u’access:SGISGI’u’

Action: identifies the form that the Label takes. 

Values: OL_STRING – for text, OL_IMAGE – for image. 

XtNrecomputeSize

 class:XtCRecomputeSizetype:Booleandefault:TRUETRUE’u’access:SGISGI’u’

Action: indicates whether the widget should calculate its size

Values: TRUE – the RectButton widget will do normal size calculations that may cause its geometry to change and automatically set the XtNheight and XtNwidth resources.  FALSE – the RectButton widget will not change its size.  This may cause truncation of the visible image being shown by the RectButton widget if the fixed size is too small, or may cause padding if the fixed size is too large.  The location of the padding is determined by the XtNlabelJustify resource. 

XtNscale

 class:XtCScaletype:Intdefault:1212’u’access:SGISGI’u’

Action: determines size of graphical elements, in points (1/72 inch), not pixels

Values: 0 < XtNscale

This resource sets the size of graphical elements (widgets) in a manner similar to other scale resources. Only sizes 10, 12, 14, and 19 are presently supported.  If this resource is set to any other value, one of these is substituted instead. 
 

XtNselect

 class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’

Action: the list of callbacks invoked when the widget is selected. 

XtNset

 class:XtCSettype:Booleandefault:TRUETRUE’u’access:SGISGI’u’

Action: reflects the current state of the button. 

Values: TRUE, FALSE

The button’s border is thickened to show a TRUE state. 

XtNunselect

 class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’

Action: the list of callbacks invoked when widget is toggled into “unset” mode. 

When the RectButton is toggled into “unset” mode by the end user to make XtNset become FALSE, the callbacks specified in this resource are activated. 

Note that simply setting XtNset to FALSE with a call to XtSetValues() does not issue the XtNunselect callbacks. 

Border Resource Interactions

The XtNdim, XtNdefault, and XtNset resources can be set independently; however, all these states cannot be reflected in the visual appearance of the rectangular button,

  Table 2 Rectangular Button Appearance

Label Resource Interactions

Label Appearance The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources interact to produce a truncated, clipped, centered, or

  Table 3 Label Appearance

When the label is centered or left-justified, the extra space is filled with the background color of the RectButton widget, as determined by the XtNbackground and XtNbackgroundPixmap resources.  When the label is truncated, a solid-black triangle is inserted to show that part of the label is missing.  The triangle requires that more of the label be truncated than would otherwise be necessary.  If the width of the button is too small to show even one character with the triangle, only the triangle is shown.  If the width is so small that the entire triangle cannot be shown, the triangle is clipped on the right.  See also the XtNlabelTile resource for how it affects the appearance of a label. 
 
 

Version 3.0.1  —  Last change: June 92