NAME

RectButton − rectangulat button widget

SYNOPSIS

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

my_rectbutton =  XtCreate( my_name, rectButtonWidgetClass,

my_parent, args, num_args);

DESCRIPTION

Components

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        Type       Expected Results
_
 
OL_MENUDEFAULTKEY
 
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

RectButton           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
XtNfontColor         Pixel          XtDefaultForeground∗ SGI
XtNforeground        Pixel          XtDefaultForeground  SGI
XtNheight            Dimension      (calculated)         SGI
XtNinputFocusColor   Pixel          Red                  SGI
XtNlabel             String         (class               name)
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
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 timeO = other access
† see resources(3W)

XtNdefault

class:XtCDefault type:Boolean default:FALSEaccess:SGI

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:XtCDim type:Boolean default:FALSEaccess:SGI

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:XtCFont type:XFontStruct∗ default:(OPEN LOOK font)access:SI

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:XtCFontColor type:Pixel default:Blackaccess:SGI

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:XtCForeground type:Pixel default:Blackaccess:SGI

Action: defines the foreground color for the widget. 

XtNlabel

class:XtCLabel type:String default:(class name)access:SGI

Action: points to the text for the label. 

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

XtNlabelImage

class:XtCLabelImage type:XImage default:NULLaccess:SGI

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:XtCLabelJustify type:OlDefine default:OL_LEFTaccess:SGI

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

Values: OL_LEFT, OL_CENTER

XtNlabelTile

class:XtCLabelTile type:Boolean default:FALSEaccess:SGI

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:XtCLabelType type:int default:OL_STRINGaccess:SGI

Action: identifies the form that the Label takes. 

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

XtNrecomputeSize

class:XtCRecomputeSize type:Boolean default:TRUEaccess:SGI

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:XtCScale type:Int default:12access:SGI

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:XtCCallback type:XtCallbackList default:NULLaccess:SI

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

XtNset

class:XtCSet type:Boolean default:TRUEaccess:SGI

Action: reflects the current state of the button. 

Values: TRUE, FALSE

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

XtNunselect

class:XtCCallback type:XtCallbackList default:NULLaccess:SI

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  —  Last change: 19 July 91  —  Last change: 19 July 91