Debian Codegraph @

doc/man/man3/XmIconButton.3

raw ◀ ▶
Source reconstructed at patch state 0 of 2 — not the installed (fully patched) source.
2 Debian patches touch this file
1 .DT
2 .TH XmIconButton 3X "15 July 1992"
3 .SH NAME
4 The Icon Button widget
5 .SH SYNOPSIS
6 Documents the XmIconButton widget
7 .SH DESCRIPTION
8 .PP
9 .TS
10 tab (%);
11 l l.
12 .TE
13 .PP
14 The Icon Button widget is a selectable area of the screen that contains both a label and
15 a string. When the user selects this button with the OSF/Motif select button its activateCallback
16 is called. This widget can also be used as a Toggle button, although it
17 will have no indicator. The placement of the icon relative to the text can be modified
18 by using the iconPlacement resource.
19 .PP
20 Note: This widget takes a String as its label, not an XmString, so there is no need to
21 use XmStringCreate to get a properly formatted string. Internationalized text is not
22 currently supported.
23 .PP
24 .SH Normal Resources
25 .PP
26 .TS
27 tab (%);
28 l l l l.
29 Name%Class%Type%Initial Value
30 activateCallback%Callback%Callback%NULL
31 alignment%Alignment%Alignment%XmALIGNMENT_
32 %%% BEGINNING
33 armColor%ArmColor%Pixel%<dynamic>
34 doubleClickCallback%Callback%Callback%NULL
35 fontList%FontList%FontList%fixed
36 horizontalMargin%Space%HorizontalDimension%2
37 iconTextPadding%Space%VerticalDimension%2
38 iconPlacement%IconPlacement%IconPlacement%XmIconTop
39 label%Label%String%Widget name
40 labelString%LabelString%XmString%Widget name
41 pixmap%Pixmap%Pixmap%None
42 recomputeSize%Boolean%Boolean%True
43 set%Boolean%Boolean%False
44 stringDirection%StringDirection%StringDirection%XmSTRING_
45 %%%DIRECTION_L_TO_R
46 verticalMargin%Space%VerticalDimension%2
47 .TE
48 .PP
49 All resource names begin with XmN and all resource class names begin with XmC.
50 .PP
51 .SH activateCallback
52 .PP
53 This list of callback routines is called whenever the icon button is clicked on by
54 the user. The format of the callback routines is specified below.
55 .PP
56 .SH armColor
57 .PP
58 This is the pixel index that describes the color to fill the widget with when it is set.
59 .PP
60 .SH doubleClickCallback
61 .PP
62 This list of callback routines is called whenever the user double clicks on this
63 widget. The format of the callback routines is specified below.
64 .PP
65 .SH fontList
66 .PP
67 The default font in this list is used to render the label string of the icon button.
68 .PP
69 .SH horizontalMargin
70 .PP
71 .SH verticalMargin
72 .PP
73 The amount of space to be left between the edge of the shadow and the text or
74 pixmap displayed. The vertical and horizontal spacing can be controlled
75 independently.
76 .PP
77 .SH iconTextPadding
78 .PP
79 The amount of space to be left between the pixmap and the label string.
80 .PP
81 .SH iconPlacement
82 .PP
83 The location of the pixmap (icon) with respect to the displayed text. This resource
84 can take one of the following values: XmIconTop, XmIconBottom, XmIconLeft,
85 XmIconRight, XmIconNone, and XmIconOnly. A type converter has been
86 registered that converts the following strings: "top", "bottom", "left", "right",
87 "none", and "iconOnly".
88 .PP
89 If only a string is displayed in the Icon Button, this resource can be used to change
90 the justification of the label. XmIconTop=bottom, XmIconBottom=top,
91 XmIconRight=Left, XmIconLeft=Right, XmIconNone=Center. In order to use
92 these options, pixmap must be set to None.
93 .PP
94 .SH label
95 .PP
96 The string to display in this button. This string can only have one font, but can be
97 any number of lines long. Use the NEW_LINE character ( '\n' ) to separate lines. This resource has been superceded by labelString, but is included for backwards compatibility. If XmNlabelString is set , XmNlabel is ignored
98 .PP
99 .SH labelString
100 .PP
101 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.
102 .SH pixmap
103 .PP
104 The pixmap to display. This pixmap may either be of depth one (1), or the same
105 depth as the screen this widget is being displayed on. If the pixmap is of depth one
106 then XCopyPlane is used to render the pixmap in the foreground and background
107 colors. If the pixmap is not of depth one then XCopyArea is used and all the
108 original colors of the pixmap are preserved. Unlike the Motif PushButton widget
109 the pixmap is automatically stippled when the Icon Button becomes insensitive.
110 .PP
111 .SH recomputeSize
112 .PP
113 If this Boolean value is True then the icon button will ask its parent to resize it to
114 be just large enough to contain the pixmap, label and shadows. If it is False then
115 the icon button will not attempt a resize.
116 .PP
117 .SH set
118 .PP
119 This Boolean value represents the current state of the icon button. If this value is
120 True then the icon button is set and is rendered as depressed. Otherwise it is unset
121 and is rendered normally.
122 .PP
123 .SH stringDirection
124 .PP
125 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.
126 .PP
127 .SH Callback Routines
128 .PP
129 Whenever the user selects the icon button the activate callbacks will be called. When-
130 ever the user double clicks on this widget the first click will call the activateCallback,
131 and if the second occurs within MultiClickTime it will call the doubleClickCallback..
132 These callbacks have the following parameters:
133
134 .HP 20
135 void (activate_callback)(Widget w, XtPointer client_data, XtPointer call_data)
136
137 .ta 15
138 .HP 15
139 w the Icon Button widget
140 .HP 15
141 client_data the client data specified by the application
142 .HP 15
143 call_data a pointer to an XmIconButtonCallbackInfo structure
144
145 .HP 20
146 void (double_click_callback)(Widget w, XtPointer client_data, XtPointer call_data)
147
148 .ta 15
149 .HP 15
150 w the Icon Button widget
151 .HP 15
152 client_data the client data specified by the application
153 .HP 15
154 call_data a pointer to an XmIconButtonCallbackInfo structure
155 .PP
156 All procedures on the Icon Button's activateCallback and doubleClickCallback lists
157 will have a pointer to an IconButtonCallbackInfo structure passed to them in the
158 call_data field. This structure is defined in the Icon Button widget's public header file
159 as follows:
160
161 .ta 5,10,15,20,25,30,35
162 .df
163 typedef struct _XmIconButtonCallbackInfo {
164
165 Boolean state; /* The current state of the icon button.*/
166
167 XEvent * event; /* The event that caused this action.*/
168
169 } XmIconButtonCallbackInfo;
170
171 .ta 15
172 .HP 15
173 state the current state of the icon button. When this is used as a push
174 button (the default) the state variable will always be True.
175 .HP 15
176 event the X Event that caused this action, see Translations and Actions
177 below for details on the events that can cause these callbacks to
178 be called.
179 .PP
180 .SH Convenience Routine
181 .PP
182 .SH
183 .HP 5
184 .SH XmCreateIconButton - Widget creation convenience routine
185 .nf
186
187 Widget XmCreateIconButton(
188 Widget parent, /* Widget id of parent for IconButton */
189 String name, /* Name of the created widget */
190 ArgList args, /* argument list */
191 Cardinal num_args /* number of items in argument list */
192 )
193
194 .nf
195 .PP
196 Translations and Actions:
197 .PP
198 The following are the default translation bindings used by the icon button:
199 .PP
200 .TS
201 tab (%);
202 l l.
203 <Btn1Down>,<Btn1Up>:%XmToggle() XmNotify()
204 <Btn1Down>(2):%XmDoubleNotify()
205 <Btn1Down>:%XmGetFocus() XmToggle()
206 <Key>osfSelect:%XmArmAndActivate()
207 <Key>osfActivate:%XmArmAndActivate()
208 None<Key>space:%XmArmAndActivate()
209 None<Key>Return:%XmArmAndActivate()
210 <Btn1Down>,<Leave>%XmToggle()
211 .TE
212 .PP
213 The following actions are supported by the icon button:
214
215 .ta 15
216 .HP 15
217 XmToggle() Toggles the state of the icon button.
218 .HP 15
219 XmNotify() Calls all routines on activateCallback list.
220 .HP 15
221 XmDoubleNotify() Calls all routines on the doubleClickCallback list.
222 .HP 15
223 XmArmAndActivated() This action will arm the button, call the actions on the activateCallback
224 list, wait a fraction of a second and then disarm the button.
225 .PP
226 To use this button as a toggle button rather than a push button, replace the default
227 translation table with the following table.
228 .PP
229 .TS
230 tab (%);
231 l l.
232 <Btn1Down>:%XmToggle() XmNotify()
233 <Btn1Up>(2):%XmDoubleNotify()
234 <Key>osfSelect:%XmToggle() XmNotify()
235 <Key>osfActivate:%XmToggle() XmNotify()
236 None<Key>space:%XmToggle() XmNotify()
237 None<Key>Return:%XmToggle() XmNotify()
238 .TE
239 .PP
240 .SH COPYRIGHT
241 .PP
242 Copyright (c) 1992 by Integrated Computer Solutions, Inc.