1XmDragContext(library call) XmDragContext(library call)
2
6 XmDragContext — The DragContext widget class
7
9 #include <Xm/DragDrop.h>
10
12 DragContexts are special widgets used in drag and drop transactions. A
13 DragContext is implemented as a widget, but a client does not explic‐
14 itly create a DragContext widget. Instead, a client initiates a drag
15 and drop transaction by calling XmDragStart, and this routine initial‐
16 izes and returns a DragContext widget. There is a unique DragContext
17 for each drag operation. The toolkit frees a DragContext when a trans‐
18 action is complete; therefore, an application programmer should not
19 explicitly destroy a DragContext.
20 Initiator and receiver clients both use DragContexts to track the state
22 of a transaction. When the initiator and receiver of a transaction are
23 in the same client, they share the same DragContext instance. If they
24 are in different clients, there are two separate DragContexts. In this
25 case, the initiator calls XmDragStart and the toolkit provides a Drag‐
26 Context for the receiver client. The only resources pertinent to the
27 receiver are XmNexportTargets and XmNnumExportTargets. These can both
28 be passed as arguments to the XmDropSiteRetrieve function to obtain
29 information about the current drop site.
30 In general, in order to receive data, a drop site must share at least
32 one target type and operation in common with a drag source. The Drag‐
33 Context resource, XmNexportTargets, identifies the selection targets
34 for the drag source. These export targets are compared with the XmNim‐
35 portTargets resource list specified by a drop site. The DragContext
36 resource, XmNdragOperations, identifies the valid operations that can
37 be applied to the source data by the initiator. The drop site counter‐
38 part resource is XmNdropSiteOperations, which indicates a drop site's
39 supported operations.
40 A client uses DragIcon widgets to define the drag-over animation
42 effects associated with a given drag and drop transaction. An initia‐
43 tor specifies a set of drag icons, selects a blending model, and sets
44 foreground and background cursor colors with DragContext resources.
45 The type of drag-over visual used to represent a drag operation depends
47 on the drag protocol style. In preregister mode, the server is grabbed,
48 and either a cursor or a pixmap may be used as a drag-over visual. In
49 dynamic mode, drag-over visuals must be implemented with the X cursor.
50 If the resulting drag protocol style is Drop Only or None and the XmN‐
51 dragInitiatorProtocolStyle is XmDRAG_DYNAMIC or XmDRAG_PREFER_DYNAMIC,
52 then a dynamic visual style (cursor) is used. Otherwise, a preregister
53 visual style is used.
54 Classes
56 DragContext inherits behavior and resources from Core.
57 The class pointer is xmDragContextClass.
59 The class name is XmDragContext.
61 New Resources
63 The following table defines a set of widget resources used by the pro‐
64 grammer to specify data. The programmer can also set the resource val‐
65 ues for the inherited classes to set attributes for this widget. To
66 reference a resource by name or by class in a .Xdefaults file, remove
67 the XmN or XmC prefix and use the remaining letters. To specify one of
68 the defined values for a resource in a .Xdefaults file, remove the Xm
69 prefix and use the remaining letters (in either lowercase or uppercase,
70 but include any underscores between words). The codes in the access
71 column indicate if the given resource can be set at creation time (C),
72 set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
73 not applicable (N/A).
74 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
76 │ │ XmDragC│ontext Resource Set │ │ │
77 │Name │ Class │ Type │ Default │ Access │
78 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
79 │XmNblendModel │ XmCBlendModel │ unsigned char │ XmBLEND_ALL │ CG │
80 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
81 │XmNclientData │ XmCClientData │ XtPointer │ NULL │ CSG │
82 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
83 │XmNconvertProc │ XmCConvertProc │ XtConvertSelectionIncrProc │ NULL │ CSG │
84 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
85 │XmNcursorBackground │ XmCCursorBackground │ Pixel │ dynamic │ CSG │
86 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
87 │XmNcursorForeground │ XmCCursorForeground │ Pixel │ dynamic │ CSG │
88 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
89 │XmNdragDropFinishCallback │ XmCCallback │ XtCallbackList │ NULL │ CSG │
90 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
91 │XmNdragMotionCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
92 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
93 │XmNdragOperations │ XmCDragOperations │ unsigned char │ XmDROP_COPY | XmDROP_MOVE │ C │
94 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
95 │XmNdropFinishCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
96 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
97 │XmNdropSiteEnterCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
98 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
99 │XmNdropSiteLeaveCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
100 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
101 │XmNdropStartCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
102 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
103 │XmNexportTargets │ XmCExportTargets │ Atom * │ NULL │ CSG │
104 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
105 │XmNincremental │ XmCIncremental │ Boolean │ False │ CSG │
106 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
107 │XmNinvalidCursorForeground │ XmCCursorForeground │ Pixel │ dynamic │ CSG │
108 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
109 │XmNnoneCursorForeground │ XmCCursorForeground │ Pixel │ dynamic │ CSG │
110 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
111 │XmNnumExportTargets │ XmCNumExportTargets │ Cardinal │ 0 │ CSG │
112 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
113 │XmNoperationChangedCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
114 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
115 │XmNoperationCursorIcon │ XmCOperationCursorIcon │ Widget │ dynamic │ CSG │
116 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
117 │XmNsourceCursorIcon │ XmCSourceCursorIcon │ Widget │ dynamic │ CSG │
118 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
119 │XmNsourcePixmapIcon │ XmCSourcePixmapIcon │ Widget │ dynamic │ CSG │
120 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
121 │XmNstateCursorIcon │ XmCStateCursorIcon │ Widget │ dynamic │ CSG │
122 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
123 │XmNtopLevelEnterCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
124 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
125 │XmNtopLevelLeaveCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
126 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
127 │XmNvalidCursorForeground │ XmCCursorForeground │ Pixel │ dynamic │ CSG │
128 ├────────────────────────────┼────────────────────────┼────────────────────────────┼───────────────────────────┼────────┤
129 └────────────────────────────┴────────────────────────┴────────────────────────────┴───────────────────────────┴────────┘
130 XmNblendModel
131 Specifies which combination of DragIcons are blended to pro‐
132 duce a drag-over visual.
133 XmBLEND_ALL
135 Blends all three DragIcons: the source, state and
136 operation icons. The icons are layered from top to
137 bottom with the operation icon on top and the
138 source icon on the bottom. The hotspot is derived
139 from the state icon.
140 XmBLEND_STATE_SOURCE
142 Blends the state and source icons only. The hotspot
143 is derived from the state icon.
144 XmBLEND_JUST_SOURCE
146 Specifies that only the source icon is used, which
147 the initiator updates as required.
148 XmBLEND_NONE
150 Specifies that no drag-over visual is generated.
151 The client tracks the drop site status through
152 callback routines and updates the drag-over visuals
153 as necessary.
154 XmNclientData
156 Specifies the client data to be passed to XmNconvertProc when
157 it is invoked.
158 XmNconvertProc
160 If XmNincremental is True, specifies a procedure of type
161 XtConvertSelectionIncrProc that converts the source data to
162 the format(s) requested by the receiver client. The widget
163 argument passed to this procedure is the DragContext widget.
164 The selection atom passed is _MOTIF_DROP. If XmNincremental
165 is False, the procedure is an XtConvertSelectionProc, and
166 should ignore the max_length, client_data, and request_id
167 arguments and should handle the conversion atomically. Data
168 returned by XmNconvertProc must be allocated using XtMalloc,
169 and will be freed automatically by the toolkit after the
170 transfer. For additional information on selection conversion
171 procedures, see X Toolkit Intrinsics—C Language Interface.
172 XmNcursorBackground
174 Specifies the background pixel value of the cursor.
175 XmNcursorForeground
177 Specifies the foreground pixel value of the cursor when the
178 state icon is not blended. This resource defaults to the
179 foreground color of the widget passed to the XmDragStart
180 function.
181 XmNdragDropFinishCallback
183 Specifies the list of callbacks that are called when the
184 transaction is completed. The type of the structure whose
185 address is passed to this callback is XmDragDropFinishCall‐
186 backStruct. The reason sent by the callback is
187 XmCR_DRAG_DROP_FINISH.
188 XmNdragMotionCallback
190 Specifies the list of callbacks that are invoked when the
191 pointer moves. The type of structure whose address is passed
192 to this callback is XmDragMotionCallbackStruct. The reason
193 sent by the callback is XmCR_DRAG_MOTION.
194 XmNdragOperations
196 Specifies the set of valid operations associated with an ini‐
197 tiator client for a drag transaction. This resource is a bit
198 mask that is formed by combining one or more of the following
199 values using a bitwise operation such as inclusive OR (|):
200 XmDROP_COPY, XmDROP_LINK, XmDROP_MOVE. The value XmDROP_NOOP
201 for this resource indicates that no operations are valid.
202 For Text and TextField widgets, this resource is set to
203 XmDROP_COPY | XmDROP_MOVE; for List widgets, it is set to
204 XmDROP_COPY.
205 XmNdropFinishCallback
207 Specifies the list of callbacks that are invoked when the
208 drop is completed. The type of the structure whose address is
209 passed to this callback is XmDropFinishCallbackStruct. The
210 reason sent by the callback is XmCR_DROP_FINISH.
211 XmNdropSiteEnterCallback
213 Specifies the list of callbacks that are invoked when the
214 pointer enters a drop site. The type of the structure whose
215 address is passed to this callback is XmDropSiteEnterCall‐
216 backStruct. The reason sent by the callback is
217 XmCR_DROP_SITE_ENTER.
218 XmNdropSiteLeaveCallback
220 Specifies the list of callbacks that are invoked when the
221 pointer leaves a drop site. The type of the structure whose
222 address is passed to this callback is XmDropSiteLeaveCall‐
223 backStruct. The reason sent by the callback is
224 XmCR_DROP_SITE_LEAVE.
225 XmNdropStartCallback
227 Specifies the list of callbacks that are invoked when a drop
228 is initiated. The type of the structure whose address is
229 passed to this callback is XmDropStartCallbackStruct. The
230 reason sent by the callback is XmCR_DROP_START.
231 XmNexportTargets
233 Specifies the list of target atoms associated with this
234 source. This resource identifies the selection targets this
235 source can be converted to.
236 XmNincremental
238 Specifies a Boolean value that indicates whether the transfer
239 on the initiator side uses the Xt incremental selection
240 transfer mechanism described in X Toolkit Intrinsics—C Lan‐
241 guage Interface. If the value is True, the initiator uses
242 incremental transfer; if the value is False, the initiator
243 uses atomic transfer.
244 XmNinvalidCursorForeground
246 Specifies the foreground pixel value of the cursor when the
247 state is invalid. This resource defaults to the value of the
248 XmNcursorForeground resource.
249 XmNnoneCursorForeground
251 Specifies the foreground pixel value of the cursor when the
252 state is none. This resource defaults to the value of the
253 XmNcursorForeground resource.
254 XmNnumExportTargets
256 Specifies the number of entries in the list of export tar‐
257 gets.
258 XmNoperationChangedCallback
260 Specifies the list of callbacks that are invoked when the
261 drag is started and when the user requests that a different
262 operation be applied to the drop. The type of the structure
263 whose address is passed to this callback is XmOpera‐
264 tionChangedCallbackStruct. The reason sent by the callback is
265 XmCR_OPERATION_CHANGED.
266 XmNoperationCursorIcon
268 Specifies the cursor icon used to designate the type of oper‐
269 ation performed by the drag transaction. If NULL, XmScreen
270 resources provide default icons for copy, link, and move
271 operations.
272 XmNsourceCursorIcon
274 Specifies the cursor icon used to represent the source when a
275 dynamic visual style is used. If NULL, the XmNdefaultSource‐
276 CursorIcon resource of XmScreen provides a default cursor
277 icon.
278 XmNsourcePixmapIcon
280 Specifies the pixmap icon used to represent the source when a
281 preregister visual style is used. The icon is used in con‐
282 junction with the colormap of the widget passed to
283 XmDragStart. If NULL, XmNsourceCursorIcon is used.
284 XmNstateCursorIcon
286 Specifies the cursor icon used to designate the state of a
287 drop site. If NULL, XmScreen resources provide default icons
288 for a valid, invalid, and no drop site condition.
289 XmNtopLevelEnterCallback
291 Specifies the list of callbacks that are called when the
292 pointer enters a top-level window or root window (due to
293 changing screens). The type of the structure whose address is
294 passed to this callback is XmTopLevelEnterCallbackStruct. The
295 reason sent by the callback is XmCR_TOP_LEVEL_ENTER.
296 XmNtopLevelLeaveCallback
298 Specifies the list of callbacks that are called when the
299 pointer leaves a top level window or the root window (due to
300 changing screens). The type of the structure whose address is
301 passed to this callback is XmTopLevelLeaveCallbackStruct. The
302 reason sent by the callback is XmCR_TOP_LEVEL_LEAVE.
303 XmNvalidCursorForeground
305 Specifies the foreground pixel value of the cursor designated
306 as a valid cursor icon.
307 Inherited Resources
309 DragContext inherits behavior and resources from the superclass
310 described in the following table. For a complete description of each
311 resource, refer to the Core reference page.
312 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
314 │ │ Core Resource Se│t │ │ │
315 │Name │ Class │ Type │ Default │ Access │
316 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
317 │XmNaccelerators │ XmCAccelerators │ XtAccelerators │ dynamic │ CSG │
318 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
319 │XmNancestorSensitive │ XmCSensitive │ Boolean │ dynamic │ G │
320 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
321 │XmNbackground │ XmCBackground │ Pixel │ dynamic │ CSG │
322 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
323 │XmNbackgroundPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
324 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
325 │XmNborderColor │ XmCBorderColor │ Pixel │ XtDefaultForeground │ CSG │
326 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
327 │XmNborderPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
328 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
329 │XmNborderWidth │ XmCBorderWidth │ Dimension │ 0 │ CSG │
330 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
331 │XmNcolormap │ XmCColormap │ Colormap │ dynamic │ CG │
332 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
333 │XmNdepth │ XmCDepth │ int │ dynamic │ CG │
334 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
335 │XmNdestroyCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
336 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
337 │XmNheight │ XmCHeight │ Dimension │ dynamic │ CSG │
338 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
339 │XmNinitialResourcesPersistent │ XmCInitialResourcesPersistent │ Boolean │ True │ C │
340 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
341 │XmNmappedWhenManaged │ XmCMappedWhenManaged │ Boolean │ True │ CSG │
342 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
343 │XmNscreen │ XmCScreen │ Screen * │ dynamic │ CG │
344 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
345 │XmNsensitive │ XmCSensitive │ Boolean │ True │ CSG │
346 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
347 │XmNtranslations │ XmCTranslations │ XtTranslations │ dynamic │ CSG │
348 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
349 │XmNwidth │ XmCWidth │ Dimension │ dynamic │ CSG │
350 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
351 │XmNx │ XmCPosition │ Position │ 0 │ CSG │
352 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
353 │XmNy │ XmCPosition │ Position │ 0 │ CSG │
354 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
355 └──────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘
356 Callback Information
357 Each of the DragContext callbacks has an associated callback structure.
358 A pointer to the following structure is passed to the XmNdragDropFin‐
360 ishCallback callback:
361 typedef struct
363 {
364 int reason;
365 XEvent *event;
366 Time timeStamp;
367 }XmDragDropFinishCallbackStruct, *XmDragDropFinishCallback;
368 reason Indicates why the callback was invoked
370 event Points to the XEvent that triggered the callback
372 timeStamp Specifies the time at which either the drag or the drop was
374 completed
375 A pointer to the following structure is passed to callbacks for XmN‐
377 dragMotionCallback:
378 typedef struct
380 {
381 int reason;
382 XEvent *event;
383 Time timeStamp;
384 unsigned char operation;
385 unsigned char operations;
386 unsigned char dropSiteStatus;
387 Position x;
388 Position y;
389 }XmDragMotionCallbackStruct, *XmDragMotionCallback;
390 reason Indicates why the callback was invoked.
392 event Points to the XEvent that triggered the callback.
394 timeStamp Specifies the timestamp of the logical event.
396 operation Identifies an operation.
398 If the toolkit has just called a DropSite's XmNdragProc, the
400 toolkit initializes operation to the value of the operation
401 member of the XmDragProcCallbackStruct at the time the Drop‐
402 Site's XmNdragProc returns.
403 If the toolkit has not called an XmNdragProc and the pointer
405 is within an active drop site, the toolkit initializes opera‐
406 tion by selecting an operation from the bitwise AND of the
407 initial value of the operations member and the value of the
408 DropSite's XmNdropSiteOperations resource. The toolkit
409 searches this set first for XmDROP_MOVE, then for
410 XmDROP_COPY, then for XmDROP_LINK, and initializes operation
411 to the first operation it finds in the set. If the toolkit
412 finds none of these operations in the set, it initializes
413 operation to XmDROP_NOOP.
414 If the toolkit has not called an XmNdragProc and the pointer
416 is not within an active drop site, the toolkit initializes
417 operation by selecting an operation from the initial value of
418 the operations member. The toolkit searches this set first
419 for XmDROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK,
420 and initializes operation to the first operation it finds in
421 the set. If the toolkit finds none of these operations in
422 the set, it initializes operation to XmDROP_NOOP.
423 operations
425 Indicates the set of operations supported for the source
426 data.
427 If the toolkit has just called a DropSite's XmNdragProc, the
429 toolkit initializes operations to the bitwise AND of the
430 DropSite's XmNdropOperations and the value of the operations
431 member of the XmDragProcCallbackStruct at the time the Drop‐
432 Site's XmNdragProc returns. If the resulting set of opera‐
433 tions is empty, the toolkit initializes operations to
434 XmDROP_NOOP.
435 If the toolkit has not called an XmNdragProc and the user
437 does not select an operation (by pressing a modifier key),
438 the toolkit initializes operations to the value of the Drag‐
439 Context's XmNdragOperations resource.
440 If the toolkit has not called an XmNdragProc and the user
442 does select an operation, the toolkit initializes operations
443 to the bitwise AND of the corresponding operation and the
444 value of the DragContext's XmNdragOperations resource. If
445 the resulting set of operations is empty, the toolkit ini‐
446 tializes operations to XmDROP_NOOP.
447 dropSiteStatus
449 Indicates whether or not a drop site is valid.
450 If the toolkit has just called a DropSite's XmNdragProc, the
452 toolkit initializes dropSiteStatus to the value of the drop‐
453 SiteStatus member of the XmDragProcCallbackStruct at the time
454 the DropSite's XmNdragProc returns.
455 If the toolkit has not called an XmNdragProc, it initializes
457 dropSiteStatus as follows: the toolkit initializes dropSiteS‐
458 tatus to XmNO_DROP_SITE if the pointer is over an inactive
459 drop site or is not over a drop site. The toolkit initial‐
460 izes dropSiteStatus to XmDROP_SITE_VALID if all the following
461 conditions are met:
462 · The pointer is over an active drop site.
464 · The DragContext's XmNexportTargets and the DropSite's
466 XmNimportTargets are compatible.
467 · The initial value of the operation member is not
469 XmDROP_NOOP.
470 Otherwise, the toolkit initializes dropSiteStatus to
472 XmDROP_SITE_INVALID.
473 A pointer to the following structure is passed for the XmNdropFinish‐
475 Callback callback:
476 typedef struct
478 {
479 int reason;
480 XEvent *event;
481 Time timeStamp;
482 unsigned char operation;
483 unsigned char operations;
484 unsigned char dropSiteStatus;
485 unsigned char dropAction;
486 unsigned char completionStatus;
487 }XmDropFinishCallbackStruct, *XmDropFinishCallback;
488 reason Indicates why the callback was invoked.
490 event Points to the XEvent that triggered the callback.
492 timeStamp Specifies the time at which the drop was completed.
494 operation Identifies an operation.
496 If the pointer is over an active drop site when the drop
498 begins, the toolkit initializes operation to the value of the
499 operation member of the XmDropProcCallbackStruct at the time
500 the DropSite's XmNdropProc returns.
501 If the pointer is not over an active drop site when the drop
503 begins, the toolkit initializes operation by selecting an
504 operation from the initial value of the operations member.
505 The toolkit searches this set first for XmDROP_MOVE, then for
506 XmDROP_COPY, then for XmDROP_LINK, and initializes operation
507 to the first operation it finds in the set. If it finds none
508 of these operations in the set, it initializes operation to
509 XmDROP_NOOP.
510 operations
512 Indicates the set of operations supported for the source
513 data.
514 If the pointer is over an active drop site when the drop
516 begins, the toolkit initializes operations to the bitwise AND
517 of the DropSite's XmNdropOperations and the value of the
518 operations member of the XmDropProcCallbackStruct at the time
519 the DropSite's XmNdropProc returns. If the resulting set of
520 operations is empty, the toolkit initializes operations to
521 XmDROP_NOOP.
522 If the pointer is not over an active drop site when the drop
524 begins and if the user does not select an operation (by
525 pressing a modifier key), the toolkit initializes operations
526 to the value of the DragContext's XmNdragOperations resource.
527 If the pointer is not over an active drop site when the drop
529 begins and if the user does select an operation, the toolkit
530 initializes operations to the bitwise AND of the correspond‐
531 ing operation and the value of the DragContext's XmNdragOper‐
532 ations resource. If the resulting set of operations is
533 empty, the toolkit initializes operations to XmDROP_NOOP.
534 dropSiteStatus
536 Indicates whether or not a drop site is valid.
537 If the pointer is over an active drop site when the drop
539 begins, the toolkit initializes dropSiteStatus to the value
540 of the dropSiteStatus member of the XmDropProcCallbackStruct
541 at the time the DropSite's XmNdropProc returns.
542 If the pointer is not over an active drop site when the drop
544 begins, the toolkit initializes dropSiteStatus to
545 XmNO_DROP_SITE.
546 dropAction
548 Identifies the drop action. The values are XmDROP,
549 XmDROP_CANCEL, XmDROP_HELP, and XmDROP_INTERRUPT. The
550 XmDROP_INTERRUPT value is currently unsupported; if speci‐
551 fied, it will be interpreted as an XmDROP_CANCEL.
552 completionStatus
554 An IN/OUT member that indicates the status of the drop
555 action. After the last callback procedure has returned, the
556 final value of this member determines what visual transition
557 effects will be applied. There are two values:
558 XmDROP_SUCCESS
560 The drop was successful.
561 XmDROP_FAILURE
563 The drop was unsuccessful.
564 A pointer to the following structure is passed to callbacks for XmN‐
566 dropSiteEnterCallback:
567 typedef struct
569 {
570 int reason;
571 XEvent *event;
572 Time timeStamp;
573 unsigned char operation;
574 unsigned char operations;
575 unsigned char dropSiteStatus;
576 Position x;
577 Position y;
578 }XmDropSiteEnterCallbackStruct, *XmDropSiteEnterCallback;
579 reason Indicates why the callback was invoked.
581 event Points to the XEvent that triggered the callback.
583 timeStamp Specifies the time the crossing event occurred.
585 operation Identifies an operation.
587 If the toolkit has just called a DropSite's XmNdragProc, the
589 toolkit initializes operation to the value of the operation
590 member of the XmDragProcCallbackStruct at the time the Drop‐
591 Site's XmNdragProc returns.
592 If the toolkit has not called an XmNdragProc, it initializes
594 operation by selecting an operation from the bitwise AND of
595 the initial value of the operations member and the value of
596 the DropSite's XmNdropSiteOperations resource. The toolkit
597 searches this set first for XmDROP_MOVE, then for
598 XmDROP_COPY, then for XmDROP_LINK, and initializes operation
599 to the first operation it finds in the set. If the toolkit
600 finds none of these operations in the set, it initializes
601 operation to XmDROP_NOOP.
602 operations
604 Indicates the set of operations supported for the source
605 data.
606 If the toolkit has just called a DropSite's XmNdragProc, the
608 toolkit initializes operations to the bitwise AND of the
609 DropSite's XmNdropOperations and the value of the operations
610 member of the XmDragProcCallbackStruct at the time the Drop‐
611 Site's XmNdragProc returns. If the resulting set of opera‐
612 tions is empty, the toolkit initializes operations to
613 XmDROP_NOOP.
614 If the toolkit has not called an XmNdragProc and the user
616 does not select an operation (by pressing a modifier key),
617 the toolkit initializes operations to the value of the Drag‐
618 Context's XmNdragOperations resource.
619 If the toolkit has not called an XmNdragProc and the user
621 does select an operation, the toolkit initializes operations
622 to the bitwise AND of the corresponding operation and the
623 value of the DragContext's XmNdragOperations resource. If
624 the resulting set of operations is empty, the toolkit ini‐
625 tializes operations to XmDROP_NOOP.
626 dropSiteStatus
628 Indicates whether or not a drop site is valid.
629 If the toolkit has just called a DropSite's XmNdragProc, the
631 toolkit initializes dropSiteStatus to the value of the drop‐
632 SiteStatus member of the XmDragProcCallbackStruct at the time
633 the DropSite's XmNdragProc returns.
634 If the toolkit has not called XmNdragProc, it initializes
636 dropSiteStatus to XmDROP_SITE_VALID if the DragContext's XmN‐
637 exportTargets and the DropSite's XmNimportTargets are compat‐
638 ible and if the initial value of the operation member is not
639 XmDROP_NOOP. Otherwise, the toolkit initializes dropSiteSta‐
640 tus to XmDROP_SITE_INVALID.
641 x Indicates the x-coordinate of the pointer in root window
643 coordinates.
644 y Indicates the y-coordinate of the pointer in root window
646 coordinates.
647 A pointer to the following structure is passed to callbacks for XmN‐
649 dropSiteLeaveCallback:
650 typedef struct
652 {
653 int reason;
654 XEvent *event;
655 Time timeStamp;
656 }XmDropSiteLeaveCallbackStruct, *XmDropSiteLeaveCallback;
657 reason Indicates why the callback was invoked
659 event Points to the XEvent that triggered the callback
661 timeStamp Specifies the timestamp of the logical event
663 A pointer to the following structure is passed for the XmNdropStart‐
665 Callback callback:
666 typedef struct
668 {
669 int reason;
670 XEvent *event;
671 Time timeStamp;
672 unsigned char operation;
673 unsigned char operations;
674 unsigned char dropSiteStatus;
675 unsigned char dropAction;
676 Position x;
677 Position y;
678 }XmDropStartCallbackStruct, *XmDropStartCallback;
679 reason Indicates why the callback was invoked.
681 event Points to the XEvent that triggered the callback.
683 timeStamp Specifies the time at which the drag was completed.
685 operation Identifies an operation.
687 If the pointer is over an active drop site when the drop
689 begins, the toolkit initializes operation to the value of the
690 operation member of the XmDropProcCallbackStruct at the time
691 the DropSite's XmNdropProc returns.
692 If the pointer is not over an active drop site when the drop
694 begins, the toolkit initializes operation by selecting an
695 operation from the initial value of the operations member.
696 The toolkit searches this set first for XmDROP_MOVE, then for
697 XmDROP_COPY, then for XmDROP_LINK, and initializes operation
698 to the first operation it finds in the set. If it finds none
699 of these operations in the set, it initializes operation to
700 XmDROP_NOOP.
701 operations
703 Indicates the set of operations supported for the source
704 data.
705 If the pointer is over an active drop site when the drop
707 begins, the toolkit initializes operations to the bitwise AND
708 of the DropSite's XmNdropOperations and the value of the
709 operations member of the XmDropProcCallbackStruct at the time
710 the DropSite's XmNdropProc returns. If the resulting set of
711 operations is empty, the toolkit initializes operations to
712 XmDROP_NOOP.
713 If the pointer is not over an active drop site when the drop
715 begins and if the user does not select an operation (by
716 pressing a modifier key), the toolkit initializes operations
717 to the value of the DragContext's XmNdragOperations resource.
718 If the pointer is not over an active drop site when the drop
720 begins and if the user does select an operation, the toolkit
721 initializes operations to the bitwise AND of the correspond‐
722 ing operation and the value of the DragContext's XmNdragOper‐
723 ations resource. If the resulting set of operations is
724 empty, the toolkit initializes operations to XmDROP_NOOP.
725 dropSiteStatus
727 Indicates whether or not a drop site is valid.
728 If the pointer is over an active drop site when the drop
730 begins, the toolkit initializes dropSiteStatus to the value
731 of the dropSiteStatus member of the XmDropProcCallbackStruct
732 at the time the DropSite's XmNdropProc returns.
733 If the pointer is not over an active drop site when the drop
735 begins, the toolkit initializes dropSiteStatus to
736 XmNO_DROP_SITE.
737 This field is invalid if the dropAction field is set to
739 XmDROP_CANCEL.
740 dropAction
742 An IN/OUT member that identifies the drop action. The values
743 are XmDROP, XmDROP_CANCEL, XmDROP_HELP, and XmDROP_INTERRUPT.
744 The value of dropAction can be modified to change the action
745 actually initiated. The value XmDROP_INTERRUPT is currently
746 unsupported; if specified, it will be interpreted as an
747 XmDROP_CANCEL.
748 x Indicates the x-coordinate of the pointer in root window
750 coordinates.
751 y Indicates the y-coordinate of the pointer in root window
753 coordinates.
754 A pointer to the following structure is passed to the XmNopera‐
756 tionChangedCallback callback:
757 typedef struct
759 {
760 int reason;
761 XEvent *event;
762 Time timeStamp;
763 unsigned char operation;
764 unsigned char operations;
765 unsigned char dropSiteStatus;
766 }XmOperationChangedCallbackStruct, *XmOperationChangedCallback;
767 reason Indicates why the callback was invoked.
769 event Points to the XEvent that triggered the callback.
771 timeStamp Specifies the time at which the crossing event occurred.
773 operation Identifies an operation.
775 If the toolkit has just called a DropSite's XmNdragProc, the
777 toolkit initializes operation to the value of the operation
778 member of the XmDragProcCallbackStruct at the time the Drop‐
779 Site's XmNdragProc returns.
780 If the toolkit has not called an XmNdragProc, and the pointer
782 is within an active drop site, the toolkit initializes opera‐
783 tion by selecting an operation from the bitwise AND of the
784 initial value of the operations member and the value of the
785 DropSite's XmNdropSiteOperations resource. The toolkit
786 searches this set first for XmDROP_MOVE, then for
787 XmDROP_COPY, then for XmDROP_LINK, and initializes operation
788 to the first operation it finds in the set. If the toolkit
789 finds none of these operations in the set, it initializes
790 operation to XmDROP_NOOP.
791 If the toolkit has not called an XmNdragProc, and the pointer
793 is not within an active drop site, the toolkit initializes
794 operation by selecting an operation from the initial value of
795 the operations member. The toolkit searches this set first
796 for XmDROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK,
797 and initializes operation to the first operation it finds in
798 the set. If the toolkit finds none of these operations in
799 the set, it initializes operation to XmDROP_NOOP.
800 operations
802 Indicates the set of operations supported for the source
803 data.
804 If the toolkit has just called a DropSite's XmNdragProc, the
806 toolkit initializes operations to the bitwise AND of the
807 DropSite's XmNdropOperations and the value of the operations
808 member of the XmDragProcCallbackStruct at the time the Drop‐
809 Site's XmNdragProc returns. If the resulting set of opera‐
810 tions is empty, the toolkit initializes operations to
811 XmDROP_NOOP.
812 If the toolkit has not called an XmNdragProc, and the user
814 does not select an operation (by pressing a modifier key),
815 the toolkit initializes operations to the value of the Drag‐
816 Context's XmNdragOperations resource.
817 If the toolkit has not called an XmNdragProc, and the user
819 does select an operation, the toolkit initializes operations
820 to the bitwise AND of the corresponding operation and the
821 value of the DragContext's XmNdragOperations resource. If
822 the resulting set of operations is empty, the toolkit ini‐
823 tializes operations to XmDROP_NOOP.
824 dropSiteStatus
826 Indicates whether or not a drop site is valid.
827 If the toolkit has just called a DropSite's XmNdragProc, the
829 toolkit initializes dropSiteStatus to the value of the drop‐
830 SiteStatus member of the XmDragProcCallbackStruct at the time
831 the DropSite's XmNdragProc returns.
832 If the toolkit has not called an XmNdragProc it initializes
834 dropSiteStatus to XmNO_DROP_SITE if the pointer is over an
835 inactive drop site or is not over a drop site. The toolkit
836 initializes dropSiteStatus to XmDROP_SITE_VALID if all the
837 following conditions are met:
838 · The pointer is over an active drop site
840 · The DragContext's XmNexportTargets and the DropSite's
842 XmNimportTargets are compatible
843 · The initial value of the operation member is not
845 XmDROP_NOOP
846 Otherwise, the toolkit initializes dropSiteStatus to
848 XmDROP_SITE_INVALID.
849 A pointer to the following structure is passed to callbacks for XmNto‐
851 pLevelEnterCallback:
852 typedef struct
854 {
855 int reason;
856 XEvent *event;
857 Time timeStamp;
858 Screen screen;
859 Window window;
860 Position x;
861 Position y;
862 unsigned char dragProtocolStyle;
863 }XmTopLevelEnterCallbackStruct, *XmTopLevelEnterCallback;
864 reason Indicates why the callback was invoked.
866 event Points to the XEvent that triggered the callback.
868 timeStamp Specifies the timestamp of the logical event.
870 screen Specifies the screen associated with the top-level window or
872 root window being entered.
873 window Specifies the ID of the top-level window or root window being
875 entered.
876 x Indicates the x-coordinate of the pointer in root window
878 coordinates.
879 y Indicates the y-coordinate of the pointer in root window
881 coordinates.
882 dragProtocolStyle
884 Specifies the protocol style adopted by the initiator. The
885 values are XmDRAG_DROP_ONLY, XmDRAG_DYNAMIC, XmDRAG_NONE, and
886 XmDRAG_PREREGISTER.
887 A pointer to the following structure is passed to callbacks for XmNto‐
889 pLevelLeaveCallback:
890 typedef struct
892 {
893 int reason;
894 XEvent *event;
895 Time timeStamp;
896 Screen screen;
897 Window window;
898 }XmTopLevelLeaveCallbackStruct, *XmTopLevelLeaveCallback;
899 reason Indicates why the callback was invoked
901 event Points to the XEvent that triggered the callback
903 timeStamp Specifies the timestamp of the logical event
905 screen Specifies a screen associated with the top-level window or
907 root window being left
908 window Specifies the ID of the top-level window or root window being
910 left
911 Translations
913 The XmDragContext translations are described in the following list.
914 The following key names are listed in the X standard key event transla‐
915 tion table syntax. This format is the one used by Motif to specify the
916 widget actions corresponding to a given key. A brief overview of the
917 format is provided under VirtualBindings(3). For a complete descrip‐
918 tion of the format, please refer to the X Toolkit Instrinsics Documen‐
919 tation.
920 Button1<Enter>:
922 DragMotion()
923 Button1<Leave>:
925 DragMotion()
926 Button1<Motion>:
928 DragMotion()
929 Button2<Enter>:
931 DragMotion()
932 Button2<Leave>:
934 DragMotion()
935 Button2<Motion>:
937 DragMotion()
938 <Btn2Up>: FinishDrag()
940 <Btn1Up>: FinishDrag()
942 <Key>Return:
944 FinishDrag()
945 <Key><osfActivate>:
947 FinishDrag()
948 <BtnDown>:
950 IgnoreButtons()
951 <BtnUp>: IgnoreButtons()
953 :<Key><osfCancel>:
955 CancelDrag()
956 :<Key><osfHelp>:
958 HelpDrag()
959 :<Key><osfUp>:
961 DragKey(Up)
962 :<Key><osfDown>:
964 DragKey(Down)
965 :<Key><osfLeft>:
967 DragKey(Left)
968 :<Key><osfRight>:
970 DragKey(Right)
971 :<KeyUp>: DragKey(Update)
973 :<KeyDown>:
975 DragKey(Update)
976 Action Routines
978 The XmDragContext action routines are
979 CancelDrag():
981 Cancels the drag operation and frees the associated DragCon‐
982 text.
983 DragKey(String)
985 If the value of String is Left, Right, Up, or Down, this
986 action moves the dragged object in the corresponding loca‐
987 tion. Any other values of String are ignored.
988 DragMotion():
990 Drags the selected data as the pointer is moved.
991 FinishDrag():
993 Finishes the drag operation and starts the drop operation.
994 HelpDrag():
996 Initiates a conditional drop that enables the receiver to
997 provide help information to the user. The user can cancel or
998 continue the drop operation in response to this information.
999 Virtual Bindings
1001 The bindings for virtual keys are vendor specific. For information
1002 about bindings for virtual buttons and keys, see VirtualBindings(3).
1003
1005 Core(3), XmDisplay(3), XmDragCancel(3), XmDragIcon(3), XmDragStart(3),
1006 XmDropSite(3), XmDropTransfer(3), and XmScreen(3).
1007 XmDragContext(library call)