WIDGET CLASS NAME

OblongButton

GADGET CLASS NAME

OblongButton

SYNOPSIS

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

widget = XtCreateWidget(name, oblongButtonWidgetClass, ...);
OR widget = XtCreateWidget(name, oblongButtonGadgetClass, ...);

DESCRIPTION

OblongButton Components

The OblongButton consists of a Label surrounded by a rounded, or oblong, Border. 

  Figure 1 Oblong Buttons

Busy Button while Action Takes Place

Each OblongButton is associated with an application-defined action implemented as a list of callbacks.  To let the end user know that an action is still taking place, the OblongButton stipples the area inside the border before issuing the callbacks.  When the last callback returns, the OblongButton restores its original appearance.  If the application’s action continues to be "busy" after the callbacks return, the application should set the XtNbusy resource to TRUE before returning from the callbacks, then reset it to FALSE when the action is no longer taking place. 

The "busy" stipple pattern is designed to show enough dots to gray the button noticeably, while still leaving a text label legible.  Oblong Buttons in a Pop-up Menu

Entering an oblong button while MENU is depressed highlights the button’s interior.  Releasing MENU then restores the original appearance and invokes the action for the button as described above.  Leaving the button before releasing MENU restores the appearance but does not invoke the action. 

  Figure 2 Oblong Button Coloration Oblong Buttons not in a Pop-up Menu

Clicking SELECT on an oblong button starts the action associated with the button.  Pressing SELECT, or moving the pointer into the button while SELECT is pressed, highlights the button’s interior.  Releasing SELECT restores the appearance and invokes the action for the button as described above.  Moving the pointer off the button before releasing SELECT also restores the appearance, but does not invoke the action. 

If the oblong button is in a stay-up menu, clicking or pressing MENU works the same as SELECT.  If the oblong 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.  OblongButton Gadgets

OblongButton gadgets cannot be parents (i.e., be used as the parent parameter when creating a widget or other gadget). 

Correct button behavior is not guaranteed if gadgets are positioned so that they overlap. 

Gadgets share some core fields but, since they are not subclasses of Core, do not have all Core fields.  In particular, they don’t have a name field or a translation field (so translations cannot be specified/overriden). 

Event Handlers cannot be added to gadgets using XtAddEventHandler.  XtAddEventHandler.  OblongButton Coloration

The diagram Oblong Button Coloration illustrates the resources that affect the coloration of the OblongButton widget. 

Note:
Events that occur outside the Border (but within the OblongButton widget) are still in the domain of the button. 

RESOURCES

  Table 1 Oblong Buttons Resource Set OblongButton Resource Set\\*(cO
                Name                  Type       Default      Access XtNancestorSensitive               Boolean          TRUE          G∗
       XtNbackground                 Pixel         White     SGI† ‡ XtNbackgroundPixmap                Pixmap        (none)     SGI†
             XtNbusy               Boolean         FALSE         SGI
          XtNdefault               Boolean         FALSE         SGI
       ‡ XtNdepth                   int    (parent’s)          GI
  XtNdestroyCallback        XtCallbackList          NULL          SI
             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∗
         XtNuserData             XtPointer          NULL         SGI
            XtNwidth             Dimension  (calculated)         SGI
                XtNx              Position             0         SGI
                XtNy              Position             0         SGI ‡ These resources are not available to OblongButton gadgets. XtNbusy

Range of Values:

TRUE
FALSE

This resource controls whether the button interior should be stippled to show that the action associated with the button is “busy.” While XtNbusy is TRUE, the system will beep if the end user attempts to select the button; the attempt is refused and no callbacks are invoked.  XtNdefault

Range of Values:

TRUE
FALSE

If this resource is TRUE, and the button is in a menu, an oval ring is drawn around the button to show that the button is the default choice of one or more buttons.  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 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"
OL-POPUP/"string..."

This resource identifies the form that the Label takes.  It can have the value OL_STRING for text, OL_IMAGE for an image, or OL_POPUP for text followed by an ellipsis (such as .  XtNrecomputeSize

Range of Values:

TRUE
FALSE

This resource indicates whether the OblongButton widget should calculate its size and automatically set the XtNheight and XtNwidth resources.  If set to TRUE, the OblongButton widget will do normal size calculations that may cause its geometry to change.  If set to FALSE, the OblongButton widget will leave its size alone; this may cause truncation of the visible image being shown by the OblongButton 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.  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. 

  Figure 3 Label Appearance

When the label is centered or left-justified, the extra space is filled with the background color of the OblongButton widget, as determined by the XtNbackground and XtNbackgroundPixmap resources. 

When a text label is truncated, the truncation occurs at a character boundary and a solid 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. 

An image label is simply truncated; no triangle is shown. 

See also the XtNlabelTile resource for how it affects the appearance of a label image. 

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