XmIconButton(3X) Miscellaneous Library Functions XmIconButton(3X)
NAME
The Icon Button widget
SYNOPSIS
Documents the XmIconButton widget
DESCRIPTION
The Icon Button widget is a selectable area of the screen that
contains both a label and a string. When the user selects this button
with the OSF/Motif select button its activateCallback is called. This
widget can also be used as a Toggle button, although it will have no
indicator. The placement of the icon relative to the text can be
modified by using the iconPlacement resource.
Note: This widget takes a String as its label, not an XmString, so
there is no need to use XmStringCreate to get a properly formatted
string. Internationalized text is not currently supported.
Normal Resources Name Class Type Initial Value
activateCallback Callback Callback NULL
alignment Alignment Alignment XmALIGNMENT_
BEGINNING
armColor ArmColor Pixel <dynamic>
doubleClickCallback Callback Callback NULL
fontList FontList FontList fixed
horizontalMargin Space HorizontalDimension 2
iconTextPadding Space VerticalDimension 2
iconPlacement IconPlacement IconPlacement XmIconTop
label Label String Widget name
labelString LabelString XmString Widget name
pixmap Pixmap Pixmap None
recomputeSize Boolean Boolean True
set Boolean Boolean False
stringDirection StringDirection StringDirection XmSTRING_
DIRECTION_L_TO_R
verticalMargin Space VerticalDimension 2
All resource names begin with XmN and all resource class names begin
with XmC.
activateCallback This list of callback routines is called whenever the icon button is
clicked on by the user. The format of the callback routines is
specified below.
armColor This is the pixel index that describes the color to fill the widget
with when it is set.
doubleClickCallback This list of callback routines is called whenever the user double
clicks on this widget. The format of the callback routines is
specified below.
fontList The default font in this list is used to render the label string of
the icon button.
horizontalMarginverticalMargin The amount of space to be left between the edge of the shadow and the
text or pixmap displayed. The vertical and horizontal spacing can be
controlled independently.
iconTextPadding The amount of space to be left between the pixmap and the label
string.
iconPlacement The location of the pixmap (icon) with respect to the displayed text.
This resource can take one of the following values: XmIconTop,
XmIconBottom, XmIconLeft, XmIconRight, XmIconNone, and XmIconOnly. A
type converter has been registered that converts the following
strings: "top", "bottom", "left", "right", "none", and "iconOnly".
If only a string is displayed in the Icon Button, this resource can
be used to change the justification of the label. XmIconTop=bottom,
XmIconBottom=top, XmIconRight=Left, XmIconLeft=Right,
XmIconNone=Center. In order to use these options, pixmap must be set
to None.
label The string to display in this button. This string can only have one
font, but can be any number of lines long. Use the NEW_LINE character
( '0 ) to separate lines. This resource has been superceded by
labelString, but is included for backwards compatibility. If
XmNlabelString is set , XmNlabel is ignored
labelString Specifies the compound string to be displayed in the button. If this
value is NULL, the value of XmNlabel is used. If both are NULL,
labelString is initialized by converting the name of the widget to a
compound string. Refer to
XmString(3X) in the OSD/Motif Programmers'
Reference for more information on the creation and structure of
compound strings.
pixmap The pixmap to display. This pixmap may either be of depth one (1), or
the same depth as the screen this widget is being displayed on. If
the pixmap is of depth one then XCopyPlane is used to render the
pixmap in the foreground and background colors. If the pixmap is not
of depth one then XCopyArea is used and all the original colors of
the pixmap are preserved. Unlike the Motif PushButton widget the
pixmap is automatically stippled when the Icon Button becomes
insensitive.
recomputeSize If this Boolean value is True then the icon button will ask its
parent to resize it to be just large enough to contain the pixmap,
label and shadows. If it is False then the icon button will not
attempt a resize.
set This Boolean value represents the current state of the icon button.
If this value is True then the icon button is set and is rendered as
depressed. Otherwise it is unset and is rendered normally.
stringDirection Specifies the direction in which the string is to be drawn.
XmNSTRING_DIRECTION_L_TO_R is drawn left to right, while
XmNSTRING_DIRECTION_R_TO_L is drawn 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
XmNSTRING_DIRECTION_L_TO_R.
Callback Routines Whenever the user selects the icon button the activate callbacks will
be called. When- ever the user double clicks on this widget the first
click will call the activateCallback, and if the second occurs within
MultiClickTime it will call the doubleClickCallback.. These
callbacks have the following parameters:
void (activate_callback)(Widget w, XtPointer client_data, XtPointer
call_data)
w the Icon Button widget
client_data the client data specified by the application
call_data a pointer to an XmIconButtonCallbackInfo structure
void (double_click_callback)(Widget w, XtPointer client_data,
XtPointer call_data)
w the Icon Button widget
client_data the client data specified by the application
call_data a pointer to an XmIconButtonCallbackInfo structure
All procedures on the Icon Button's activateCallback and
doubleClickCallback lists will have a pointer to an
IconButtonCallbackInfo structure passed to them in the call_data
field. This structure is defined in the Icon Button widget's public
header file as follows:
typedef struct _XmIconButtonCallbackInfo {
Boolean state; /* The current state of the icon button.*/
XEvent * event; /* The event that caused this action.*/
} XmIconButtonCallbackInfo;
state the current state of the icon button. When this is
used as a push button (the default) the state variable
will always be True.
event the X Event that caused this action, see Translations
and Actions below for details on the events that can
cause these callbacks to be called.
Convenience RoutineXmCreateIconButton - Widget creation convenience routine Widget XmCreateIconButton(
Widget parent,/* Widget id of parent for IconButton */
String name, /* Name of the created widget */
ArgList args,/* argument list */
Cardinal num_args/* number of items in argument list */
)
Translations and Actions:
The following are the default translation bindings used by the icon button:
<Btn1Down>,<Btn1Up>: XmToggle() XmNotify()
<Btn1Down>(2): XmDoubleNotify()
<Btn1Down>: XmGetFocus() XmToggle()
<Key>osfSelect: XmArmAndActivate()
<Key>osfActivate: XmArmAndActivate()
None<Key>space: XmArmAndActivate()
None<Key>Return: XmArmAndActivate()
<Btn1Down>,<Leave> XmToggle()
The following actions are supported by the icon button:
XmToggle() Toggles the state of the icon button.
XmNotify() Calls all routines on activateCallback list.
XmDoubleNotify()Calls all routines on the doubleClickCallback list.
XmArmAndActivated()This action will arm the button, call the actions on the activateCallback
list, wait a fraction of a second and then disarm the button.
To use this button as a toggle button rather than a push button, replace the default
translation table with the following table.
<Btn1Down>: XmToggle() XmNotify()
<Btn1Up>(2): XmDoubleNotify()
<Key>osfSelect: XmToggle() XmNotify()
<Key>osfActivate: XmToggle() XmNotify()
None<Key>space: XmToggle() XmNotify()
None<Key>Return: XmToggle() XmNotify()
COPYRIGHT
Copyright (c) 1992 by Integrated Computer Solutions, Inc.
15 July 1992 XmIconButton(3X)
