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 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 but-
tons (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).
Figure  1  shows  several  buttons,  in normal, default, and
current states (two versions).
               Figure 1.  Rectangular Buttons

Use of Rectangular Buttons 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.

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.

RectButton Coloration Figure 2 illustrates the resources that affect the coloration of the RectButton widget.

Figure 2.  Rectangular Button Coloration

RESOURCES

 _____________________________________________________________________________________
|_______________________________RectButton_Resource_Set______________________________|
| Name                |  Class          |  Type          |  Default         |  Access|
|_____________________|_________________|________________|__________________|________|
| XtNancestorSensitive|  XtCSenstitive  |  Boolean       |  TRUE            |  G*    |
|_____________________|_________________|________________|__________________|________|
|_XtNbackground_______|__XtCBackground__|__Pixel_________|__White___________|__SGI-__|
| XtNbackgroundPixmap |  XtCPixmap      |  Pixmap        |  (none)          |  SGI-  |
|_____________________|_________________|________________|__________________|________|
|_XtNdefault__________|__XtCDefault_____|__Boolean_______|__FALSE___________|__SGI___|
| XtNdepth            |  XtCDepth       |  int           |  (parent's)      |  GI    |
|_____________________|_________________|________________|__________________|________|
|_XtNdestroyCallback__|__XtCCallback____|__XtCallbackList|__NULL____________|__SI____|
| XtNdim              |  XtCDim         |  Boolean       |  FALSE           |  SGI   |
|_____________________|_________________|________________|__________________|________|
|_XtNfont_____________|__XtCFont________|__XFontStruct_*_|__(OPEN_LOOK_font)|__SI____|
| XtNfontColor        |  XtCFontColor   |  Pixel         |  Black*          |  SGI   |
|_____________________|_________________|________________|__________________|________|
|_XtNforeground_______|__XtCForeground__|__Pixel_________|__Black___________|__SGI-__|
| XtNheight           |  XtCHeight      |  Dimension     |  (calculated)    |  SGI   |
|_____________________|_________________|________________|__________________|________|
|_XtNlabel____________|__XtCLabel_______|__String________|__(class_name)____|__SGI___|
| XtNlabelImage       |  XtCLabelImage  |  XImage *      |  NULL            |  SGI   |
|_____________________|_________________|________________|__________________|________|
|_XtNlabelJustify_____|__XtCLabelJustify|__OlDefine______|__OL_LEFT_________|__SGI___|
| XtNlabelTile        |  XtCLabelTile   |  Boolean       |  FALSE           |  SGI   |
|_____________________|_________________|________________|__________________|________|
|_XtNlabelType________|__XtCLabelType___|__int___________|__OL_STRING_______|__SGI___|
 ______________________________________________________________________________________
|___________________________RectButton_Resource_Set_(cont.)___________________________|
| Name                |  Class               |  Type          |  Default     |  Access|
|_____________________|______________________|________________|______________|________|
| XtNmappedWhenManaged|  XtCMappedWhenManaged|  Boolean       |  TRUE        |  SGI   |
|_____________________|______________________|________________|______________|________|
|_XtNrecomputeSize____|__XtCRecomputeSize____|__Boolean_______|__TRUE________|__SGI___|
| XtNselect           |  XtCCallback         |  XtCallbackList|  NULL        |  SI    |
|_____________________|______________________|________________|______________|________|
|_XtNsensitive________|__XtCSensitive________|__Boolean_______|__TRUE________|__GI*___|
| XtNset              |  XtCSet              |  Boolean       |  TRUE        |  SGI   |
|_____________________|______________________|________________|______________|________|
|_XtNunselect_________|__XtCCallback_________|__XtCallbackList|__NULL________|__SI____|
| XtNuserData         |  XtCUserData         |  XtPointer     |  NULL        |  SGI   |
|_____________________|______________________|________________|______________|________|
|_XtNwidth____________|__XtCWidth____________|__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 XtNlabel-Justify 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 Figure 3 shows.

Figure 3.  Rectangular Button Appearance when Set/Default/Dim

Label Appearance The XtNwidth, XtNheight,  XtNrecomputeSize,
and  XtNlabelJustify  resources  interact to produce a trun-
cated, clipped, centered, or left-justified label  as  shown
in Figure 4.
                Figure 4.  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  XtNback-
groundPixmap  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 char-
acter 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  XtNla-
belTile  resource  for  how  it  affects the appearance of a
label.