WIDGET CLASS NAME

RectButton

SYNOPSIS

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

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

DESCRIPTION

RectButton Components

the diagram Rectangular Buttons shows several OPEN LOOK button widgets, in normal, default, and current states (two versions). 

Use of Rectangular Buttons

The RectButton widget implements one of the OPEN LOOK button widgets.  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.  Toggling the 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. 
RectButton Coloration

the diagram Rectangular Button Coloration illustrates the resources that affect the coloration of the RectButton widget. 

Work in Exclusives/Nonexclusives Only

The RectButton widget needs to be a child of a proper composite widget to work correctly.  Only the Exclusives and Nonexclusives composite widgets have the necessary capabilities. 

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.  Rectangular Buttons in a Pop-up Menu

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.  Rectangular Buttons Not in a Pop-up Menu

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. 

RESOURCES

RectButton Resource Set
                Name            Type       Default   Access XtNancestorSensitive         Boolean          TRUE       G∗
       XtNbackground           Pixel         White  SGI†
 XtNbackgroundPixmap          Pixmap        (none)  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        Black∗      SGI
       XtNforeground           Pixel         Black  SGI†
           XtNheight       Dimension  (calculated)      SGI
            XtNlabel          String  (class name)      SGI
       XtNlabelImage        XImage ∗          NULL      SGI
        XtNlabelTile         Boolean         FALSE      SGI XtNmappedWhenManaged         Boolean          TRUE      SGI
    XtNrecomputeSize         Boolean          TRUE      SGI
           XtNselect  XtCallbackList          NULL       SI
        XtNsensitive         Boolean          TRUE      GI∗
              XtNset         Boolean          TRUE      SGI
         XtNunselect  XtCallbackList          NULL       SI
         XtNuserData       XtPointer          NULL      SGI
            XtNwidth       Dimension  (calculated)      SGI XtNdefault

Range of Values:

TRUE
FALSE

If this resource is TRUE, the Border is doubled to two lines, to show that the button is the default choice of one or more buttons.  XtNdim

Range of Values:

TRUE
FALSE

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

Range of Values:

(any valid return from XLoadQueryFont())

Default:

(chosen to match the scale and screen resolution)

This resource identifies the font to be used to display the Label. 

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

Range of Values:

(any Pixel value valid for the current display)/(any name from the rgb.txt file)

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

See the note about the interaction of this resource with other color resources under the description of the XtNbackground resource in CORE RESOURCES(3W).  XtNforeground

This resource defines the foreground color for the widget. 

See the note about the interaction of this resource with other color resources under the description of the XtNbackground resource in CORE RESOURCES(3W).  XtNlabel

This resource is a pointer to the text for the Label.  This resource is ignored if the XtNlabelType resource has the value OL_IMAGE.  XtNlabelImage

This resource is a pointer to the image for the Label.  This resource is ignored unless the XtNlabelType resource has the value OL_IMAGE. 

If the image is of type XYBitmap, the image is highlighted when appropriate by reversing the 0 and 1 values of each pixel (i.e. by "‘xor’ing" the image data).  If the image is of type XYPixmap or ZPixmap, the image is not highlighted, although the space around the image inside the Border is highlighted. 

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

Range of Values:

OL_LEFT/"left"
OL_CENTER/"center"

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

Range of 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.  XtNlabelType

Range of Values:

OL_STRING/"string"
OL_IMAGE/"image"

This resource identifies the form that the Label takes.  It can have the value OL_STRING or OL_IMAGE for text or image, respectively. 

XtNrecomputeSize

Range of Values:

TRUE
FALSE

This resource indicates whether the RectButton widget should calculate its size and automatically set the XtNheight and XtNwidth resources.  If set to TRUE, the RectButton widget will do normal size calculations that may cause its geometry to change.  If set to FALSE, the RectButton widget will leave its size alone; 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.  XtNselect

This is the list of callbacks invoked when the widget is selected.  XtNset

Range of Values:

TRUE
FALSE

This resource reflects the current state of the button.  The button’s border is thickened to show a TRUE state.  XtNunselect

This is the list of callbacks invoked when a RectButton widget is toggled into the “unset” mode by the end user to make XtNset be FALSE.  Note that simply setting XtNset to FALSE with a call to XtSetValues() does not issue the XtNunselect callbacks. 
XtNdim, XtNdefault, XtNset

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, as the state table in the diagram Rectangular Button Appearance shows. 

Label Appearance

The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources interact to produce a truncated, clipped, centered, or left-justified label as shown in the diagram 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. 

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