XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
NAME
XmLabelGadget-The LabelGadget widget class
SYNOPSIS
#include <Xm/LabelG.h>
DESCRIPTION
LabelGadget is an instantiable widget and is also used as a
superclass for other button gadgets, such as
PushButtonGadget and ToggleButtonGadget.
LabelGadget can contain either text or a pixmap.
LabelGadget text is a compound string. Refer to the
OSF/Motif Programmer's Guide for more information on
compound strings. The text can be multilingual, multiline,
and/or multifont. When a LabelGadget is insensitive, its
text is stippled, or the user-supplied insensitive pixmap is
displayed.
LabelGadget supports both accelerators and mnemonics
primarily for use in LabelGadget subclass widgets that are
contained in menus. Mnemonics are available in a menu
system when the button is visible. Accelerators in a menu
system are accessible even when the button is not visible.
The LabelGadget displays the mnemonic by underlining the
first matching character in the text string. The
accelerator is displayed as a text string adjacent to the
label text or pixmap.
LabelGadget consists of many margin fields surrounding the
text or pixmap. These margin fields are resources that may
be set by the user, but LabelGadget subclasses and Manager
parents also modify some of these fields. They tend to
modify the XmNmarginLeft, XmNmarginRight, XmNmarginTop, and
XmNmarginBottom resources and leave the XmNmarginWidth and
XmNmarginHeight resources as set by the application.
LabelGadget takes into account XmNshadowThickness in
determining its layout but does not draw the shadow. That
is, if XmNshadowThickness is greater than 0, LabelGadget
leaves space for the shadow, but the shadow does not appear.
In a LabelGadget XmNtraversalOn and XmNhighlightOnEnter are
forced to False inside Popup MenuPanes, Pulldown MenuPanes,
and OptionMenus. Otherwise these resources default to
False.
Classes
LabelGadget inherits behavior and resources from Object,
RectObj and XmGadget classes.
1 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
The class pointer is xmLabelGadgetClass.
The class name is XmLabelGadget.
New Resources
The following table defines a set of widget resources used
by the programmer to specify data. The programmer can also
set the resource values for the inherited classes to set
attributes for this widget. To reference a resource by name
or by class in a .Xdefaults file, remove the XmN or XmC
prefix and use the remaining letters. To specify one of the
defined values for a resource in a .Xdefaults file, remove
the Xm prefix and use the remaining letters (in either
lowercase or uppercase, but include any underscores between
words). The codes in the access column indicate if the
given resource can be set at creation time (C), set by using
XtSetValues (S), retrieved by using XtGetValues (G), or is
not applicable (N/A).
XmLabelGadget Resource Set
Name Class Type Default Access
_________________________________________________________________________________________________________
XmNaccelerator XmCAccelerator String NULL CSG
XmNacceleratorText XmCAcceleratorText XmString NULL CSG
XmNalignment XmCAlignment unsigned char dynamic CSG
XmNfontList XmCFontList XmFontList dynamic CSG
XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNlabelPixmap XmCLabelPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNlabelString XmCXmString XmString dynamic CSG
XmNlabelType XmCLabelType unsigned char XmSTRING CSG
XmNmarginBottom XmCMarginBottom Dimension 0 CSG
XmNmarginHeight XmCMarginHeight Dimension 2 CSG
XmNmarginLeft XmCMarginLeft Dimension 0 CSG
XmNmarginRight XmCMarginRight Dimension 0 CSG
XmNmarginTop XmCMarginTop Dimension 0 CSG
XmNmarginWidth XmCMarginWidth Dimension 2 CSG
XmNmnemonic XmCMnemonic KeySym NULL CSG
XmNmnemonicCharSet XmCMnemonicCharSet String dynamic CSG
XmNrecomputeSize XmCRecomputeSize Boolean True CSG
XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG
XmNaccelerator
Sets the accelerator on a button widget in a menu,
which activates a visible or invisible, but
managed, button from the keyboard. This resource
is a string that describes a set of modifiers and
the key that may be used to select the button.
The format of this string is identical to that
used by the translations manager, with the
exception that only a single event may be
specified and only KeyPress events are allowed.
2 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
Accelerators for buttons are supported only for
PushButtonGadgets and ToggleButtonGadgets in
Pulldown and Popup menus.
XmNacceleratorText
Specifies the text displayed for the accelerator.
The text is displayed adjacent to the label string
or pixmap. Accelerator text for buttons is
displayed only for PushButtonGadgets and
ToggleButtonGadgets in Pulldown and Popup Menus.
XmNalignment
Specifies the label alignment for text or pixmap.
⊕ XmALIGNMENT_BEGINNING (left alignment)-causes
the left sides of the lines of text to be
vertically aligned with the left edge of the
gadget. For a pixmap, its left side is
vertically aligned with the left edge of the
gadget.
⊕ XmALIGNMENT_CENTER (center alignment)-causes
the centers of the lines of text to be
vertically aligned in the center of the
gadget. For a pixmap, its center is
vertically aligned with the center of the
gadget.
⊕ XmALIGNMENT_END (right alignment)-causes the
right sides of the lines of text to be
vertically aligned with the right edge of the
gadget. For a pixmap, its right side is
vertically aligned with the right edge of the
gadget.
The above descriptions for text are correct when
XmNstringDirection is XmSTRING_DIRECTION_L_TO_R;
the descriptions for XmALIGNMENT_BEGINNING and
XmALIGNMENT_END are switched when the resource is
XmSTRING_DIRECTION_R_TO_L.
If the parent is a RowColumn whose XmNisAligned
resource is True, XmNalignment is forced to the
same value as the RowColumn's XmNentryAlignment if
the RowColumn's XmNrowColumnType is XmWORK_AREA or
if the gadget is a subclass of XmLabelGadget.
Otherwise, the default is XmALIGNMENT_CENTER.
XmNfontList
Specifies the font of the text used in the gadget.
3 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
If this value is NULL at initialization, the font
list is initialized by looking up the parent
hierarchy of the widget for an ancestor that is a
subclass of the XmBulletinBoard, VendorShell, or
XmMenuShell widget class. If such an ancestor is
found, the font list is initialized to the
XmNbuttonFontList (for button gadget subclasses)
or XmNlabelFontList of the ancestor widget. If no
such ancestor is found, the default is
implementation dependent. Refer to XmFontList(3X)
for more information on the creation and structure
of a font list.
XmNlabelInsensitivePixmap
Specifies a pixmap used as the button face if
XmNlabelType is XmPIXMAP and the button is
insensitive. The default value,
XmUNSPECIFIED_PIXMAP, displays an empty label.
XmNlabelPixmap
Specifies the pixmap when XmNlabelType is
XmPIXMAP. The default value,
XmUNSPECIFIED_PIXMAP, displays an empty label.
XmNlabelString
Specifies the compound string when XmNlabelType is
XmSTRING. If this value is NULL, it is
initialized by converting the name of the gadget
to a compound string. Refer to XmString(3X) for
more information on the creation and the structure
of compound strings.
XmNlabelType
Specifies the label type.
⊕ XmSTRING - text displays XmNlabelString
⊕ XmPIXMAP - icon data in pixmap displays
XmNlabelPixmap or XmNlabelInsensitivePixmap
XmNmarginBottom
Specifies the amount of spacing between the bottom
of the label text and the top of the bottom margin
specified by XmNmarginHeight. This may be
modified by LabelGadget's subclasses. For
example, CascadeButtonGadget may increase this
field to make room for the cascade pixmap.
XmNmarginHeight
Specifies an equal amount of spacing above the
4 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
margin defined by XmNmarginTop and below the
margin defined by XmNmarginBottom. XmNmarginHeight
specifies the amount of spacing between the top
edge of the margin set by XmNmarginTop and the
bottom edge of the top shadow, and the amount of
spacing between the bottom edge of the margin
specified by XmNmarginBottom and the top edge of
the bottom shadow.
XmNmarginLeft
Specifies the amount of spacing between the left
edge of the label text and the right side of the
left margin (specified by XmNmarginWidth). This
may be modified by LabelGadget's subclasses. For
example, ToggleButtonGadget may increase this
field to make room for the toggle indicator and
for spacing between the indicator and label.
Whether this actually applies to the left or right
side of the label may depend on the value of
XmNstringDirection.
XmNmarginRight
Specifies the amount of spacing between the right
edge of the label text and the left side of the
right margin (specified by XmNmarginWidth). This
may be modified by LabelGadget's subclasses. For
example, CascadeButtonGadget may increase this
field to make room for the cascade pixmap.
Whether this actually applies to the left or right
side of the label may depend on the value of
XmNstringDirection.
XmNmarginTop
Specifies the amount of spacing between the top of
the label text and the bottom of the top margin
specified by XmNmarginHeight. This may be
modified by LabelGadget's subclasses. For
example, CascadeButtonGadget may increase this
field to make room for the cascade pixmap.
XmNmarginWidth
Specifies an equal amount of spacing to the left
of the margin defined by XmNmarginLeft and to the
right of the margin defined by XmNmarginRight.
XmNmarginWidth specifies the amount of spacing
between the left edge of the margin set by
XmNmarginLeft and the right edge of the left
shadow, and the amount of spacing between the
right edge of the margin specified by
XmNmarginRight and the left edge of the right
shadow.
5 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
XmNmnemonic
Provides the user with an alternate means of
activating a button. A button in a MenuBar, a
Popup MenuPane, or a Pulldown MenuPane can have a
mnemonic.
This resource contains a keysym as listed in the
X11 keysym table. The first character in the
label string that exactly matches the mnemonic in
the character set specified in XmNmnemonicCharSet
is underlined when the button is displayed.
When a mnemonic has been specified, the user
activates the button by pressing the mnemonic key
while the button is visible. If the button is a
CascadeButtonGadget in a MenuBar and the MenuBar
does not have the focus, the user must use the
MAlt modifier while pressing the mnemonic. The
user can activate the button by pressing either
the shifted or the unshifted mnemonic key.
XmNmnemonicCharSet
Specifies the character set of the mnemonic for
the label. The default is XmFONTLIST_DEFAULT_TAG.
XmNrecomputeSize
Specifies a Boolean value that indicates whether
the gadget shrinks or expands to accommodate its
contents (label string or pixmap) as a result of
an XtSetValues resource value that would change
the size of the gadget. If True, the gadget
shrinks or expands to exactly fit the label string
or pixmap. If False, the gadget never attempts to
change size on its own.
XmNstringDirection
Specifies the direction in which the string is to
be drawn. The following are the values:
⊕ XmSTRING_DIRECTION_L_TO_R - left to right
⊕ XmSTRING_DIRECTION_R_TO_L - right to left
The default for this resource is determined at
creation time. If no value is specified for this
resource and the widget's parent is a manager, the
value is inherited from the parent; otherwise, it
defaults to XmSTRING_DIRECTION_L_TO_R.
6 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
Inherited Resources
LabelGadget inherits behavior and resources from the
following superclasses. For a complete description of each
resource, refer to the man page for that superclass.
XmGadget Resource Set
Name Class Type Default Access
___________________________________________________________________________________
XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCHighlightColor Pixel dynamic G
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightThickness XmCHighlightThickness Dimension 0 CSG
XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG
XmNshadowThickness XmCShadowThickness Dimension 0 CSG
XmNtopShadowColor XmCTopShadowColor Pixel dynamic G
XmNtraversalOn XmCTraversalOn Boolean False CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData XtPointer NULL CSG
RectObj Resource Set
Name Class Type Default Access
____________________________________________________________________
XmNancestorSensitive XmCSensitive Boolean dynamic G
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNheight XmCHeight Dimension dynamic CSG
XmNsensitive XmCSensitive Boolean True CSG
XmNwidth XmCWidth Dimension dynamic CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Object Resource Set
Name Class Type Default Access
____________________________________________________________________
XmNdestroyCallback XmCCallback XtCallbackList NULL C
Behavior
XmLabelGadget includes behavior from XmGadget. Additional
XmLabelGadget behavior is described below:
BDrag Press:
Drags the contents of a LabelGadget, identified by
pressing BDrag. This action creates a DragContext
object whose XmNexportTargets resource is set to
"COMPOUND_TEXT" for a label type of XmSTRING;
otherwise, "PIXMAP" if the label type is XmPIXMAP.
This action is undefined for LabelGadgets used in
a menu system.
KHelp: In a Popup or Pulldown MenuPane, unposts all menus
in the menu hierarchy and, when the shell's
7 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
keyboard focus policy is XmEXPLICIT, restores
keyboard focus to the widget that had the focus
before the menu system was entered. Calls the
callbacks for XmNhelpCallback if any exist. If
there are no help callbacks for this widget, this
action calls the help callbacks for the nearest
ancestor that has them.
MAny KCancel:
In a MenuBar, disarms the CascadeButton and the
menu and, when the shell's keyboard focus policy
is XmEXPLICIT, restores keyboard focus to the
widget that had the focus before the menu was
entered.
In a toplevel Pulldown MenuPane from a MenuBar,
unposts the menu, disarms the MenuBar
CascadeButton and the MenuBar, and, when the
shell's keyboard focus policy is XmEXPLICIT,
restores keyboard focus to the widget that had the
focus before the MenuBar was entered. In other
Pulldown MenuPanes, unposts the menu.
In a Popup MenuPane, unposts the menu and, when
the shell's keyboard focus policy is XmEXPLICIT,
restores keyboard focus to the widget from which
the menu was posted.
KDown: If the current menu item has a submenu and is in a
MenuBar, then this action posts the submenu,
disarms the current menu item, and arms the
submenu's first traversable menu item.
If the current menu item is in a MenuPane, then
this action disarms the current menu item and arms
the item below it. This action wraps within the
MenuPane. When the current menu item is at the
MenuPane's bottom edge, then this action wraps to
the topmost menu item in the column to the right,
if one exists. When the current menu item is at
the bottom, rightmost corner of the MenuPane, then
this action wraps to the tear-off control, if
present, or to the top, leftmost menu item.
KLeft: When the current menu item is in a MenuBar, then
this action disarms the current item and arms the
MenuBar item to the left. This action wraps
within the MenuBar.
In MenuPanes, if the current menu item is not at
the left edge of a MenuPane, this action disarms
the current item and arms the item to its left.
8 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
If the current menu item is at the left edge of a
submenu attached to a MenuBar item, then this
action unposts the submenu and traverses to the
MenuBar item to the left, wrapping if necessary.
If that MenuBar item has a submenu, it posts the
submenu and arms the first traversable item in the
submenu. If the current menu item is at the left
edge of a submenu not directly attached to a
MenuBar item, then this action unposts the current
submenu only.
In Popup or Torn-off MenuPanes, when the current
menu item is at the left edge, this action wraps
within the MenuPane. If the current menu item is
at the left edge of the MenuPane and not in the
top row, this action wraps to the rightmost menu
item in the row above. If the current menu item
is in the upper, leftmost corner, this action
wraps to the tear-off control, if present, or else
it wraps to the bottom, rightmost menu item in the
MenuPane.
KRight: If the current menu item is in a MenuBar, then
this action disarms the current item and arms the
MenuBar item to the right. This action wraps
within the MenuBar.
In MenuPanes, if the current menu item is a
CascadeButton, then this action posts its
associated submenu. If the current menu item is
not a CascadeButton and is not at the right edge
of a MenuPane, this action disarms the current
item and arms the item to its right, wrapping if
necessary. If the current menu item is not a
CascadeButton and is at the right edge of a
submenu that is a descendent of a MenuBar, then
this action unposts all submenus and traverses to
the MenuBar item to the right. If that MenuBar
item has a submenu, it posts the submenu and arms
the submenu's first traversable item.
In Popup or Torn-off menus, if the current menu
item is not a CascadeButton and is at the right
edge of a row (except the bottom row), this action
wraps to the leftmost menu item in the row below.
If the current menu item is not a CascadeButton
and is in the bottom, rightmost corner of a Popup
or Pulldown MenuPane, this action wraps to the
tear-off control, if present, or else it wraps to
the top, leftmost menu item of the MenuPane.
KUp: When the current menu item is in a MenuPane, then
9 (printed 6/8/92)
XmLabelGadget(3X) UNIX System V XmLabelGadget(3X)
this action disarms the current menu item and arms
the item above it. This action wraps within the
MenuPane. When the current menu item is at the
MenuPane's top edge, then this action wraps to the
bottommost menu item in the column to the left, if
one exists. When the current menu item is at the
top, leftmost corner of the MenuPane, then this
action wraps to the tear-off control, if present,
or to the bottom, rightmost menu item.
Virtual Bindings
The bindings for virtual keys are vendor specific. For
information about bindings for virtual buttons and keys, see
VirtualBindings(3X).
RELATED INFORMATION
Object(3X), RectObj(3X), XmCreateLabelGadget(3X),
XmFontListCreate(3X), XmStringCreate(3X),
XmStringCreateLtoR(3X), and XmGadget(3X).
10 (printed 6/8/92)