1XmDrawingArea(library call) XmDrawingArea(library call)
2
6 XmDrawingArea — The DrawingArea widget class
7
9 #include <Xm/DrawingA.h>
10
12 DrawingArea is an empty widget that is easily adaptable to a variety of
13 purposes. It does no drawing and defines no behavior except for invok‐
14 ing callbacks. Callbacks notify the application when graphics need to
15 be drawn (exposure events or widget resize) and when the widget
16 receives input from the keyboard or mouse.
17 Applications are responsible for defining appearance and behavior as
19 needed in response to DrawingArea callbacks.
20 DrawingArea is also a composite widget and subclass of XmManager that
22 supports minimal geometry management for multiple widget or gadget
23 children.
24 DrawingArea uses the XmNinitialFocus resource of XmManager to define
26 whether or not DrawingArea will receive focus when it is traversed to,
27 even if it has traversable children. If XmNinitialFocus is NULL,
28 DrawingArea receives focus only if it does not have any traversable
29 children. If XmNinitialFocus is not NULL, then DrawingArea receives
30 focus when traversed to. In the latter case, the application first
31 needs to be able to realize that the DrawingArea will receive focus,
32 then, as appropriate, needs to either call the XmProcessTraversal func‐
33 tion for the desired child, or to navigate across the private
34 DrawingArea graphics objects.
35 The following resources are not currently used by the DrawingArea wid‐
37 get: XmNshadowThickness, XmNtopShadowPixmap, XmNbottomShadowPixmap,
38 XmNtopShadowColor, and XmNbottomShadowColor
39 Data Transfer Behavior
41 DrawingArea has no widget class conversion or destination procedure.
42 Subclasses and the XmNconvertCallback procedures are responsible for
43 any conversion of selections. Subclasses and the XmNdestinationCall‐
44 back procedures are responsible for any data transfers to the widget.
45 Classes
47 DrawingArea inherits behavior and resources from the Core, Composite,
48 Constraint, and XmManager classes.
49 The class pointer is xmDrawingAreaWidgetClass.
51 The class name is XmDrawingArea.
53 New Resources
55 The following table defines a set of widget resources used by the pro‐
56 grammer to specify data. The programmer can also set the resource val‐
57 ues for the inherited classes to set attributes for this widget. To
58 reference a resource by name or by class in a .Xdefaults file, remove
59 the XmN or XmC prefix and use the remaining letters. To specify one of
60 the defined values for a resource in a .Xdefaults file, remove the Xm
61 prefix and use the remaining letters (in either lowercase or uppercase,
62 but include any underscores between words). The codes in the access
63 column indicate if the given resource can be set at creation time (C),
64 set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
65 not applicable (N/A).
66 ┌──────────────────────────────────────────────────────────────────────────────────┐
68 │ │ XmDrawingArea │Resource Set │ │ │
69 │Name │ Class │ Type │ Default │ Access │
70 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
71 │XmNconvertCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
72 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
73 │XmNdestinationCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
74 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
75 │XmNexposeCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
76 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
77 │XmNinputCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
78 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
79 │XmNmarginHeight │ XmCMarginHeight │ Dimension │ 10 │ CSG │
80 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
81 │XmNmarginWidth │ XmCMarginWidth │ Dimension │ 10 │ CSG │
82 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
83 │XmNresizeCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
84 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
85 │XmNresizePolicy │ XmCResizePolicy │ unsigned char │ XmRESIZE_ANY │ CSG │
86 ├───────────────────────┼─────────────────┼────────────────┼──────────────┼────────┤
87 └───────────────────────┴─────────────────┴────────────────┴──────────────┴────────┘
88 XmNconvertCallback
89 Specifies a list of callbacks called when the DrawingArea is
90 asked to convert a selection. The type of the structure
91 whose address is passed to these callbacks is XmConvertCall‐
92 backStruct. The reason is XmCR_OK.
93 XmNdestinationCallback
95 Specifies a list of callbacks called when the DrawingArea is
96 the destination of a transfer operation. The type of the
97 structure whose address is passed to these callbacks is
98 XmDestinationCallbackStruct. The reason is XmCR_OK.
99 XmNexposeCallback
101 Specifies the list of callbacks that is called when
102 DrawingArea receives an exposure event. The callback reason
103 is XmCR_EXPOSE. The callback structure also includes the
104 exposure event.
105 The default bit gravity for Manager windows is NorthWestGrav‐
107 ity. This may cause the XmNexposeCallback procedures not to
108 be invoked when the DrawingArea window is made smaller.
109 XmNinputCallback
111 Specifies the list of callbacks that is called when the
112 DrawingArea receives a keyboard or mouse event (key or but‐
113 ton, up or down). The callback reason is XmCR_INPUT. The
114 callback structure also includes the input event.
115 XmNmarginHeight
117 Specifies the minimum spacing in pixels between the top or
118 bottom edge of DrawingArea and any child widget.
119 XmNmarginWidth
121 Specifies the minimum spacing in pixels between the left or
122 right edge of DrawingArea and any child widget.
123 XmNresizeCallback
125 Specifies the list of callbacks that is called when the
126 DrawingArea is resized. The callback reason is XmCR_RESIZE.
127 XmNresizePolicy
129 Controls the policy for resizing DrawingArea widgets. Possi‐
130 ble values include XmRESIZE_NONE (fixed size), XmRESIZE_ANY
131 (shrink or grow as needed), and XmRESIZE_GROW (grow only).
132 Inherited Resources
134 DrawingArea inherits behavior and resources from the following super‐
135 classes. For a complete description of each resource, refer to the ref‐
136 erence page for that superclass.
137 ┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
139 │ │ XmManager │Resource Set │ │ │
140 │Name │ Class │ Type │ Default │ Access │
141 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
142 │XmNbottomShadowColor │ XmCBottomShadowColor │ Pixel │ dynamic │ CSG │
143 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
144 │XmNbottomShadowPixmap │ XmCBottomShadowPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
145 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
146 │XmNforeground │ XmCForeground │ Pixel │ dynamic │ CSG │
147 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
148 │XmNhelpCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
149 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
150 │XmNhighlightColor │ XmCHighlightColor │ Pixel │ dynamic │ CSG │
151 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
152 │XmNhighlightPixmap │ XmCHighlightPixmap │ Pixmap │ dynamic │ CSG │
153 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
154 │XmNinitialFocus │ XmCInitialFocus │ Widget │ NULL │ CSG │
155 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
156 │XmNlayoutDirection │ XmCLayoutDirection │ XmDirection │ dynamic │ CG │
157 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
158 │XmNnavigationType │ XmCNavigationType │ XmNavigationType │ XmTAB_GROUP │ CSG │
159 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
160 │XmNpopupHandlerCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
161 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
162 │XmNshadowThickness │ XmCShadowThickness │ Dimension │ 0 │ CSG │
163 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
164 │XmNstringDirection │ XmCStringDirection │ XmStringDirection │ dynamic │ CG │
165 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
166 │XmNtopShadowColor │ XmCTopShadowColor │ Pixel │ dynamic │ CSG │
167 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
168 │XmNtopShadowPixmap │ XmCTopShadowPixmap │ Pixmap │ dynamic │ CSG │
169 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
170 │XmNtraversalOn │ XmCTraversalOn │ Boolean │ True │ CSG │
171 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
172 │XmNunitType │ XmCUnitType │ unsigned char │ dynamic │ CSG │
173 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
174 │XmNuserData │ XmCUserData │ XtPointer │ NULL │ CSG │
175 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
176 └────────────────────────┴───────────────────────┴───────────────────┴──────────────────────┴────────┘
177 ┌───────────────────────────────────────────────────────────────────────┐
178 │ │ Composite Reso│urce Set │ │ │
179 │Name │ Class │ Type │ Default │ Access │
180 ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
181 │XmNchildren │ XmCReadOnly │ WidgetList │ NULL │ G │
182 ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
183 │XmNinsertPosition │ XmCInsertPosition │ XtOrderProc │ NULL │ CSG │
184 ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
185 │XmNnumChildren │ XmCReadOnly │ Cardinal │ 0 │ G │
186 ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
187 └──────────────────┴───────────────────┴─────────────┴─────────┴────────┘
188 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
189 │ │ Core Resource Se│t │ │ │
190 │Name │ Class │ Type │ Default │ Access │
191 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
192 │XmNaccelerators │ XmCAccelerators │ XtAccelerators │ dynamic │ CSG │
193 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
194 │XmNancestorSensitive │ XmCSensitive │ Boolean │ dynamic │ G │
195 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
196 │XmNbackground │ XmCBackground │ Pixel │ dynamic │ CSG │
197 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
198 │XmNbackgroundPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
199 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
200 │XmNborderColor │ XmCBorderColor │ Pixel │ XtDefaultForeground │ CSG │
201 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
202 │XmNborderPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
203 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
204 │XmNborderWidth │ XmCBorderWidth │ Dimension │ 0 │ CSG │
205 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
206 │XmNcolormap │ XmCColormap │ Colormap │ dynamic │ CG │
207 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
208 │XmNdepth │ XmCDepth │ int │ dynamic │ CG │
209 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
210 │XmNdestroyCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
211 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
212 │XmNheight │ XmCHeight │ Dimension │ dynamic │ CSG │
213 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
214 │XmNinitialResourcesPersistent │ XmCInitialResourcesPersistent │ Boolean │ True │ C │
215 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
216 │XmNmappedWhenManaged │ XmCMappedWhenManaged │ Boolean │ True │ CSG │
217 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
218 │XmNscreen │ XmCScreen │ Screen * │ dynamic │ CG │
219 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
220 │XmNsensitive │ XmCSensitive │ Boolean │ True │ CSG │
221 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
222 │XmNtranslations │ XmCTranslations │ XtTranslations │ dynamic │ CSG │
223 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
224 │XmNwidth │ XmCWidth │ Dimension │ dynamic │ CSG │
225 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
226 │XmNx │ XmCPosition │ Position │ 0 │ CSG │
227 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
228 │XmNy │ XmCPosition │ Position │ 0 │ CSG │
229 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
230 └──────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘
231 Callback Information
232 A pointer to the following structure is passed to the XmNexposeCall‐
233 back, XmNinputCallback, and XmNresizeCallback procedures:
234 typedef struct
236 {
237 int reason;
238 XEvent * event;
239 Window window;
240 } XmDrawingAreaCallbackStruct;
241 reason Indicates why the callback was invoked.
243 event Points to the XEvent that triggered the callback. This is
245 NULL for the XmNresizeCallback.
246 window Is set to the widget window.
248 A pointer to the following structure is passed to the XmNconvertCall‐
250 back procedures:
251 typedef struct
253 {
254 int reason;
255 XEvent *event;
256 Atom selection;
257 Atom target;
258 XtPointer source_data;
259 XtPointer location_data;
260 int flags;
261 XtPointer parm;
262 int parm_format;
263 unsigned long parm_length;
264 int status;
265 XtPointer value;
266 Atom type;
267 int format;
268 unsigned long length;
269 } XmConvertCallbackStruct;
270 reason Indicates why the callback was invoked.
272 event Points to the XEvent that triggered the callback. It can be
274 NULL.
275 selection Indicates the selection for which conversion is being
277 requested. Possible values are CLIPBOARD, PRIMARY, SEC‐
278 ONDARY, and _MOTIF_DROP.
279 target Indicates the conversion target.
281 source_data
283 Contains information about the selection source. When the
284 selection is _MOTIF_DROP, source_data is the DragContext.
285 Otherwise, it is NULL.
286 location_data
288 Contains information about the location of data to be con‐
289 verted. If the value is NULL, the data to be transferred
290 consists of the widget's current selection.
291 flags Indicates the status of the conversion. Following are the
293 possible values:
294 XmCONVERTING_NONE
296 This flag is currently unused.
297 XmCONVERTING_PARTIAL
299 The target widget was able to be converted, but
300 some data was lost.
301 XmCONVERTING_SAME
303 The conversion target is the source of the data to
304 be transferred.
305 XmCONVERTING_TRANSACT
307 This flag is currently unused.
308 parm Contains parameter data for this target. If no parameter
310 data exists, the value is NULL.
311 When selection is CLIPBOARD and target is _MOTIF_CLIP‐
313 BOARD_TARGETS or _MOTIF_DEFERRED_CLIPBOARD_TARGETS, the value
314 is the requested operation (XmCOPY, XmMOVE, or XmLINK).
315 parm_format
317 Specifies whether the data in parm should be viewed as a list
318 of char, short, or long quantities. Possible values are 0
319 (when parm is NULL), 8 (when the data in parm should be
320 viewed as a list of chars), 16 (when the data in parm should
321 be viewed as a list of shorts), or 32 (when the data in parm
322 should be viewed as a list of longs). Note that parm_format
323 symbolizes a data type, not the number of bits in each list
324 element. For example, on some machines, a parm_format of 32
325 means that the data in parm should be viewed as a list of
326 64-bit quantities, not 32-bit quantities.
327 parm_length
329 Specifies the number of elements of data in parm, where each
330 element has the size specified by parm_format. When parm is
331 NULL, the value is 0.
332 status An IN/OUT member that specifies the status of the conversion.
334 The initial value is XmCONVERT_DEFAULT. The callback proce‐
335 dure can set this member to one of the following values:
336 XmCONVERT_DEFAULT
338 This value means that the widget class conversion
339 procedure, if any, is called after the callback
340 procedures return. If the widget class conversion
341 procedure produces any data, it overwrites the data
342 provided by the callback procedures in the value
343 member.
344 XmCONVERT_MERGE
346 This value means that the widget class conversion
347 procedure, if any, is called after the callback
348 procedures return. If the widget class conversion
349 procedure produces any data, it appends its data to
350 the data provided by the callback procedures in the
351 value member. This value is intended for use with
352 targets that result in lists of data, such as TAR‐
353 GETS.
354 XmCONVERT_DONE
356 This value means that the callback procedure has
357 successfully finished the conversion. The widget
358 class conversion procedure, if any, is not called
359 after the callback procedures return.
360 XmCONVERT_REFUSE
362 This value means that the callback procedure has
363 terminated the conversion process without complet‐
364 ing the requested conversion. The widget class
365 conversion procedure, if any, is not called after
366 the callback procedures return.
367 value An IN/OUT parameter that contains any data that the callback
369 procedure produces as a result of the conversion. The ini‐
370 tial value is NULL. If the callback procedure sets this mem‐
371 ber, it must ensure that the type, format, and length members
372 correspond to the data in value. The callback procedure is
373 responsible for allocating, but not for freeing, memory when
374 it sets this member.
375 type An IN/OUT parameter that indicates the type of the data in
377 the value member. The initial value is INTEGER.
378 format An IN/OUT parameter that specifies whether the data in value
380 should be viewed as a list of char, short, or long quanti‐
381 ties. The initial value is 8. The callback procedure can
382 set this member to 8 (for a list of char), 16 (for a list of
383 short), or 32 (for a list of long).
384 length An IN/OUT member that specifies the number of elements of
386 data in value, where each element has the size symbolized by
387 format. The initial value is 0.
388 A pointer to the following callback structure is passed to the XmNdes‐
390 tinationCallback procedures:
391 typedef struct
393 {
394 int reason;
395 XEvent *event;
396 Atom selection;
397 XtEnum operation;
398 int flags;
399 XtPointer transfer_id;
400 XtPointer destination_data;
401 XtPointer location_data;
402 Time time;
403 } XmDestinationCallbackStruct;
404 reason Indicates why the callback was invoked.
406 event Points to the XEvent that triggered the callback. It can be
408 NULL.
409 selection Indicates the selection for which data transfer is being
411 requested. Possible values are CLIPBOARD, PRIMARY, SEC‐
412 ONDARY, and _MOTIF_DROP.
413 operation Indicates the type of transfer operation requested.
415 · When the selection is PRIMARY, possible values are
417 XmMOVE, XmCOPY, and XmLINK.
418 · When the selection is SECONDARY or CLIPBOARD, possible
420 values are XmCOPY and XmLINK.
421 · When the selection is _MOTIF_DROP, possible values are
423 XmMOVE, XmCOPY, XmLINK, and XmOTHER. A value of
424 XmOTHER means that the callback procedure must get fur‐
425 ther information from the XmDropProcCallbackStruct in
426 the destination_data member.
427 flags Indicates whether or not the destination widget is also the
429 source of the data to be transferred. Following are the pos‐
430 sible values:
431 XmCONVERTING_NONE
433 The destination widget is not the source of the
434 data to be transferred.
435 XmCONVERTING_SAME
437 The destination widget is the source of the data to
438 be transferred.
439 transfer_id
441 Serves as a unique ID to identify the transfer transaction.
442 destination_data
444 Contains information about the destination. When the selec‐
445 tion is _MOTIF_DROP, the callback procedures are called by
446 the drop site's XmNdropProc, and destination_data is a
447 pointer to the XmDropProcCallbackStruct passed to the XmN‐
448 dropProc procedure. When the selection is SECONDARY, desti‐
449 nation_data is an Atom representing a target recommmended by
450 the selection owner for use in converting the selection.
451 Otherwise, destination_data is NULL.
452 location_data
454 Contains information about the location where data is to be
455 transferred. The value is always NULL when the selection is
456 SECONDARY or CLIPBOARD. If the value is NULL, the data is to
457 be inserted at the widget's cursor position. location_data is
458 only valid for the duration of a transfer. Once XmTransfer‐
459 Done procedures start to be called, location_data will no
460 longer be stable.
461 time Indicates the time when the transfer operation began.
463 Translations
465 XmDrawingArea inherits translations from XmManager. Before calling the
466 XmManager actions, all events in the inherited translations except
467 <BtnMotion>, <EnterWindow>, <LeaveWindow>, <FocusIn>, and <FocusOut>
468 also call the DrawingAreaInput() action.
469 XmDrawingArea has the following additional translations. The following
471 key names are listed in the X standard key event translation table syn‐
472 tax. This format is the one used by Motif to specify the widget
473 actions corresponding to a given key. A brief overview of the format
474 is provided under VirtualBindings(3). For a complete description of
475 the format, please refer to the X Toolkit Instrinsics Documentation.
476 <BtnDown>:
478 DrawingAreaInput()
479 <BtnUp>: DrawingAreaInput()
481 <KeyDown>:
483 DrawingAreaInput() ManagerGadgetKeyInput()
484 <KeyUp>: DrawingAreaInput()
486 Action Routines
488 The XmDrawingArea action routines are
489 DrawingAreaInput():
491 Unless the event takes place in a gadget, calls the callbacks
492 for XmNinputCallback
493 ManagerGadgetKeyInput():
495 Causes the current gadget to process a keyboard event
496 Additional Behavior
498 The XmDrawingArea widget has the following additional behavior:
499 <Expose>: Calls the callbacks for XmNexposeCallback
501 <Widget Resize>:
503 Calls the callbacks for XmNresizeCallback
504 Virtual Bindings
506 The bindings for virtual keys are vendor specific. For information
507 about bindings for virtual buttons and keys, see VirtualBindings(3).
508
510 Composite(3), Constraint(3), Core(3), XmCreateDrawingArea(3), XmMan‐
511 ager(3), XmVaCreateDrawingArea(3), and XmVaCreateManagedDrawingArea(3).
512 XmDrawingArea(library call)