1XmIconButton(3X)                                              XmIconButton(3X)
2
3
4

NAME

6       The Icon Button widget
7

SYNOPSIS

9       Documents the XmIconButton widget
10

DESCRIPTION

12       The Icon Button widget is a selectable area of the screen that contains
13       both a label and a string. When the user selects this button  with  the
14       OSF/Motif select button its activateCallback is called. This widget can
15       also be used as a Toggle button, although it will  have  no  indicator.
16       The placement of the icon relative to the text can be modified by using
17       the iconPlacement resource.
18
19       Note: This widget takes a String as its  label,  not  an  XmString,  so
20       there  is  no  need  to  use XmStringCreate to get a properly formatted
21       string. Internationalized text is not currently supported.
22

Normal Resources

24       Name                  Class             Type                  Initial Value
25       activateCallback      Callback          Callback              NULL
26       alignment             Alignment         Alignment             XmALIGNMENT_
27                                                                      BEGINNING
28       armColor              ArmColor          Pixel                 <dynamic>
29       doubleClickCallback   Callback          Callback              NULL
30       fontList              FontList          FontList              fixed
31       horizontalMargin      Space             HorizontalDimension   2
32       iconTextPadding       Space             VerticalDimension     2
33       iconPlacement         IconPlacement     IconPlacement         XmIconTop
34       label                 Label             String                Widget name
35       labelString           LabelString       XmString              Widget name
36       pixmap                Pixmap            Pixmap                None
37       recomputeSize         Boolean           Boolean               True
38       set                   Boolean           Boolean               False
39       stringDirection       StringDirection   StringDirection       XmSTRING_
40                                                                     DIRECTION_L_TO_R
41       verticalMargin        Space             VerticalDimension     2
42
43       All resource names begin with XmN and all resource  class  names  begin
44       with XmC.
45

activateCallback

47       This  list  of  callback routines is called whenever the icon button is
48       clicked on by the user. The format of the callback routines  is  speci‐
49       fied below.
50

armColor

52       This  is  the  pixel  index that describes the color to fill the widget
53       with when it is set.
54

doubleClickCallback

56       This list of callback routines  is  called  whenever  the  user  double
57       clicks on this widget. The format of the callback routines is specified
58       below.
59

fontList

61       The default font in this list is used to render the label string of the
62       icon button.
63

horizontalMargin

verticalMargin

66       The  amount  of space to be left between the edge of the shadow and the
67       text or pixmap displayed. The vertical and horizontal  spacing  can  be
68       controlled independently.
69

iconTextPadding

71       The amount of space to be left between the pixmap and the label string.
72

iconPlacement

74       The  location  of the pixmap (icon) with respect to the displayed text.
75       This resource can take one of the following values: XmIconTop,  XmIcon‐
76       Bottom,  XmIconLeft,  XmIconRight,  XmIconNone,  and XmIconOnly. A type
77       converter has been registered  that  converts  the  following  strings:
78       "top", "bottom", "left", "right", "none", and "iconOnly".
79
80       If  only a string is displayed in the Icon Button, this resource can be
81       used to change the justification of the label.  XmIconTop=bottom,  XmI‐
82       conBottom=top,  XmIconRight=Left,  XmIconLeft=Right, XmIconNone=Center.
83       In order to use these options, pixmap must be set to None.
84

label

86       The string to display in this button. This string  can  only  have  one
87       font, but can be any number of lines long. Use the NEW_LINE character (
88       '0 ) to separate lines. This resource has  been  superceded  by  label‐
89       String,  but is included for backwards compatibility. If XmNlabelString
90       is set , XmNlabel is ignored
91

labelString

93       Specifies the compound string to be displayed in the  button.  If  this
94       value  is NULL, the value of XmNlabel is used. If both are NULL, label‐
95       String is initialized by converting the name of the widget  to  a  com‐
96       pound  string. Refer to XmString(3X) in the OSD/Motif Programmers' Ref‐
97       erence for more information on the creation and structure  of  compound
98       strings.
99

pixmap

101       The  pixmap  to display. This pixmap may either be of depth one (1), or
102       the same depth as the screen this widget is being displayed on. If  the
103       pixmap  is of depth one then XCopyPlane is used to render the pixmap in
104       the foreground and background colors. If the pixmap is not of depth one
105       then  XCopyArea  is  used and all the original colors of the pixmap are
106       preserved. Unlike the Motif PushButton widget the pixmap  is  automati‐
107       cally stippled when the Icon Button becomes insensitive.
108

recomputeSize

110       If  this Boolean value is True then the icon button will ask its parent
111       to resize it to be just large enough to contain the pixmap,  label  and
112       shadows. If it is False then the icon button will not attempt a resize.
113

set

115       This  Boolean value represents the current state of the icon button. If
116       this value is True then the icon button  is  set  and  is  rendered  as
117       depressed. Otherwise it is unset and is rendered normally.
118

stringDirection

120       Specifies  the  direction  in  which  the  string  is to be drawn. XmN‐
121       STRING_DIRECTION_L_TO_R is drawn left to right, while  XmNSTRING_DIREC‐
122       TION_R_TO_L  is  drawn  right to left. The default for this resource is
123       determined at creation time. If no value is specified for this resource
124       and  the  widget's parent is a manager, the value is inherited from the
125       parent; otherwise, it defaults to XmNSTRING_DIRECTION_L_TO_R.
126

Callback Routines

128       Whenever the user selects the icon button the activate  callbacks  will
129       be  called.  When- ever the user double clicks on this widget the first
130       click will call the activateCallback, and if the second  occurs  within
131       MultiClickTime  it will call the doubleClickCallback..  These callbacks
132       have the following parameters:
133
134
135       void (activate_callback)(Widget  w,  XtPointer  client_data,  XtPointer
136                           call_data)
137
138
139       w              the Icon Button widget
140
141       client_data    the client data specified by the application
142
143       call_data      a pointer to an XmIconButtonCallbackInfo structure
144
145
146       void (double_click_callback)(Widget w, XtPointer client_data, XtPointer
147                           call_data)
148
149
150       w              the Icon Button widget
151
152       client_data    the client data specified by the application
153
154       call_data      a pointer to an XmIconButtonCallbackInfo structure
155
156       All procedures on the Icon Button's activateCallback  and  doubleClick‐
157       Callback  lists will have a pointer to an IconButtonCallbackInfo struc‐
158       ture passed to them in the call_data field. This structure  is  defined
159       in the Icon Button widget's public header file as follows:
160
161       typedef struct _XmIconButtonCallbackInfo {
162
163            Boolean state;   /* The current state of the icon button.*/
164
165            XEvent * event;  /* The event that caused this action.*/
166
167       } XmIconButtonCallbackInfo;
168
169
170       state          the  current state of the icon button. When this is used
171                      as a push button (the default) the state  variable  will
172                      always be True.
173
174       event          the  X  Event  that caused this action, see Translations
175                      and Actions below for details on  the  events  that  can
176                      cause these callbacks to be called.
177

Convenience Routine

179
180
181
182

XmCreateIconButton - Widget creation convenience routine

184       Widget XmCreateIconButton(
185                      Widget parent,/* Widget id of parent for IconButton */
186                      String name, /* Name of the created widget */
187                      ArgList args,/* argument list */
188                      Cardinal num_args/* number of items in argument list */
189                      )
190
191
192       Translations and Actions:
193
194       The following are the default translation bindings used by the icon button:
195
196       <Btn1Down>,<Btn1Up>:   XmToggle() XmNotify()
197       <Btn1Down>(2):         XmDoubleNotify()
198       <Btn1Down>:            XmGetFocus() XmToggle()
199       <Key>osfSelect:        XmArmAndActivate()
200       <Key>osfActivate:      XmArmAndActivate()
201
202       None<Key>space:        XmArmAndActivate()
203       None<Key>Return:       XmArmAndActivate()
204       <Btn1Down>,<Leave>     XmToggle()
205
206       The following actions are supported by the icon button:
207
208
209       XmToggle()     Toggles the state of the icon button.
210
211       XmNotify()     Calls all routines on activateCallback list.
212
213       XmDoubleNotify()Calls all routines on the doubleClickCallback list.
214
215       XmArmAndActivated()This action will arm the button, call the actions on the activateCallback
216                      list, wait a fraction of a second and then disarm the button.
217
218       To use this button as a toggle button rather than a push button, replace the default
219       translation table with the following table.
220
221       <Btn1Down>:         XmToggle() XmNotify()
222       <Btn1Up>(2):        XmDoubleNotify()
223       <Key>osfSelect:     XmToggle() XmNotify()
224       <Key>osfActivate:   XmToggle() XmNotify()
225       None<Key>space:     XmToggle() XmNotify()
226       None<Key>Return:    XmToggle() XmNotify()
227
229       Copyright (c) 1992 by Integrated Computer Solutions, Inc.
230
231
232
233                                 15 July 1992                 XmIconButton(3X)
Impressum