1XmDropSite(library call) XmDropSite(library call)
2
6 XmDropSite — The DropSite Registry
7
9 #include <Xm/DragDrop.h>
10
12 A client registers a widget or gadget as a drop site using the XmDrop‐
13 SiteRegister function. In addition, this routine defines the behavior
14 and capabilities of a drop site by specifying appropriate resources.
15 For example, the XmNimportTargets and XmNnumImportTargets resources
16 identify respectively the selection target types and number of types
17 supported by a drop site. The visual animation effects associated with
18 a drop site are also described with DropSite resources.
19 Drop site animation effects that occur in response to the pointer
21 entering a valid drop site are called drag-under effects. A receiver
22 can select from several animation styles supplied by the toolkit or can
23 provide customized animation effects. Drag-under effects supplied by
24 the toolkit include border highlighting, shadow in/out drawing, and
25 pixmap representation.
26 When a preregister drag protocol style is used, the toolkit generates
28 drag-under visual effects based on the value of the XmNanimationStyle
29 resource. In dynamic mode, if the drop site XmNdragProc resource is
30 NULL, the toolkit also provides animation effects based on the XmNani‐
31 mationStyle resource. Otherwise, if the XmNdragProc routine is speci‐
32 fied, the receiver can either assume responsibility for animation
33 effects (through the XmNdragProc routine) or rely on the toolkit to
34 provide animation. An application can either handle all or none of the
35 animation effects for a particular drop site. That is, an application
36 should never do a partial job of animation on a particular drop site.
37 Drop sites may overlap. The initial stacking order corresponds to the
39 order in which the drop sites were registered. When a drop site over‐
40 laps another drop site, the drag-under effects of the drop site under‐
41 neath are clipped by the obscuring drop site(s).
42 The XmDropSiteUpdate routine sets resources for a widget that is regis‐
44 tered as a drop site. XmDropSiteRetrieve gets drop site resource values
45 previously specified for a registered widget. These routines are used
46 instead of XtSetValues and XtGetValues.
47 Classes
49 XmDropSite does not inherit from any widget class.
50 New Resources
52 The following table defines a set of widget resources used by the pro‐
53 grammer to specify data. To reference a resource by name or by class in
54 a .Xdefaults file, remove the XmN or XmC prefix and use the remaining
55 letters. To specify one of the defined values for a resource in a .Xde‐
56 faults file, remove the Xm prefix and use the remaining letters (in
57 either lowercase or uppercase, but include any underscores between
58 words). The codes in the access column indicate if the given resource
59 can be set at creation time (C), set by using XmDropSiteUpdate (S),
60 retrieved by using XmDropSiteRetrieve (G), or is not applicable (N/A).
61 ┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
63 │ │ XmDropSite│Resource Set │ │ │
64 │Name │ Class │ Type │ Default │ Access │
65 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
66 │XmNanimationMask │ XmCAnimationMask │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
67 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
68 │XmNanimationPixmap │ XmCAnimationPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
69 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
70 │XmNanimationPixmapDepth │ XmCAnimationPixmapDepth │ int │ 0 │ CSG │
71 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
72 │XmNanimationStyle │ XmCAnimationStyle │ unsigned char │ XmDRAG_UNDER_HIGHLIGHT │ CSG │
73 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
74 │XmNdragProc │ XmCDragProc │ XtCallbackProc │ NULL │ CSG │
75 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
76 │XmNdropProc │ XmCDropProc │ XtCallbackProc │ NULL │ CSG │
77 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
78 │XmNdropRectangles │ XmCDropRectangles │ XRectangle * │ dynamic │ CSG │
79 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
80 │XmNdropSiteActivity │ XmCDropSiteActivity │ unsigned char │ XmDROP_SITE_ACTIVE │ CSG │
81 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
82 │XmNdropSiteOperations │ XmCDropSiteOperations │ unsigned char │ XmDROP_MOVE | XmDROP_COPY │ CSG │
83 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
84 │XmNdropSiteType │ XmCDropSiteType │ unsigned char │ XmDROP_SITE_SIMPLE │ CG │
85 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
86 │XmNimportTargets │ XmCImportTargets │ Atom * │ NULL │ CSG │
87 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
88 │XmNnumDropRectangles │ XmCNumDropRectangles │ Cardinal │ 1 │ CSG │
89 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
90 │XmNnumImportTargets │ XmCNumImportTargets │ Cardinal │ 0 │ CSG │
91 ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
92 └────────────────────────┴─────────────────────────┴────────────────┴───────────────────────────┴────────┘
93 XmNanimationMask
94 Specifies a mask to use with the pixmap specified by XmNani‐
95 mationPixmap when the animation style is XmDRAG_UNDER_PIXMAP.
96 XmNanimationPixmap
98 Specifies a pixmap for drag-under animation when the anima‐
99 tion style is XmDRAG_UNDER_PIXMAP. The pixmap is drawn with
100 its origin at the upper left corner of the bounding box of
101 the drop site. If the drop site window is larger than the
102 animation pixmap, the portion of the window not covered by
103 the pixmap will be tiled with the window's background color.
104 XmNanimationPixmapDepth
106 Specifies the depth of the pixmap specified by the XmNanima‐
107 tionPixmap resource. When the depth is 1, the colors are
108 taken from the foreground and background of the drop site
109 widget. For any other value, drop site animation occurs only
110 if the XmNanimationPixmapDepth matches the depth of the drop
111 site window. Colors are derived from the current colormap.
112 XmNanimationStyle
114 Specifies the drag-under animation style used when a drag
115 enters a valid drop site. The possible values are
116 XmDRAG_UNDER_HIGHLIGHT
118 The drop site uses highlighting effects.
119 XmDRAG_UNDER_SHADOW_OUT
121 The drop site uses an outset shadow.
122 XmDRAG_UNDER_SHADOW_IN
124 The drop site uses an inset shadow.
125 XmDRAG_UNDER_PIXMAP
127 The drop site uses the pixmap specified by XmNani‐
128 mationPixmap to indicate that it can receive the
129 drop.
130 XmDRAG_UNDER_NONE
132 The drop site does not use animation effects. A
133 client using a dynamic protocol, may provide drag-
134 under effects in its XmNdragProc routine.
135 XmNdragProc
137 Specifies the procedure that is invoked when the drop site
138 receives a crossing, motion, or operation changed message.
139 This procedure is called only when a dynamic protocol is
140 used. The type of structure whose address is passed to this
141 procedure is XmDragProcCallbackStruct. The reason sent to
142 the procedure is one of the following:
143 · XmCR_DROP_SITE_ENTER_MESSAGE
145 · XmCR_DROP_SITE_LEAVE_MESSAGE
147 · XmCR_DRAG_MOTION
149 · XmCR_OPERATION_CHANGED
151 The drag procedure may change the values of some members of
153 the XmDragProcCallbackStruct passed to it. After the drag
154 procedure returns, the toolkit uses the final values in ini‐
155 tializing some members of the callback structure passed to
156 the appropriate callbacks of the initiator (the DragContext's
157 XmNdropSiteEnterCallback, XmNdropSiteLeaveCallback, XmNdrag‐
158 MotionCallback, or XmNoperationChangedCallback callbacks).
159 XmNdropProc
161 Specifies the procedure that is invoked when a drop (exclud‐
162 ing a cancel or interrupt action) occurs on a drop site
163 regardless of the status of the drop site. The type of the
164 structure whose address is passed to this procedure is
165 XmDropProcCallbackStruct. The reason sent to the procedure is
166 XmCR_DROP_MESSAGE.
167 The drop procedure may change the values of some members of
169 the XmDropProcCallbackStruct passed to it. After the drop
170 procedure returns, the toolkit uses the final values in ini‐
171 tializing some members of the XmDropStartCallbackStruct
172 passed to the initiator's drop start callbacks (the DragCon‐
173 text's XmNdropStartCallback callbacks).
174 XmNdropRectangles
176 Specifies a list of rectangles that describe the shape of a
177 drop site. The locations of the rectangles are relative to
178 the origin of the enclosing object. When XmNdropRectangles is
179 NULL, the drop site is assumed to be the sensitive area of
180 the enclosing widget. If XmNdropSiteType is XmDROP_SITE_COM‐
181 POSITE, this resource cannot be specified by the application.
182 Retrieving this resource returns allocated memory that needs
184 to be freed with the XtFree function.
185 XmNdropSiteActivity
187 Indicates whether a drop site is active or inactive. The val‐
188 ues are XmDROP_SITE_ACTIVE, XmDROP_SITE_INACTIVE, and
189 XmDROP_SITE_IGNORE. An active drop site can receive a drop,
190 whereas an inactive drop site is dormant. An inactive drop
191 site is treated as if it was not a registered drop site and
192 any drag-under visuals associated with entering or leaving
193 the drop site do not occur. However, it is still used for
194 clipping drag-under effects. A value of XmDROP_SITE_IGNORE
195 indicates that a drop site should be ignored for all pur‐
196 poses.
197 XmNdropSiteOperations
199 Specifies the set of valid operations associated with a drop
200 site. This resource is a bit mask that is formed by combin‐
201 ing one or more of the following values using a bitwise oper‐
202 ation such as inclusive OR (|): XmDROP_COPY, XmDROP_LINK, and
203 XmDROP_MOVE. The value XmDROP_NOOP for this resource indi‐
204 cates that no operations are valid.
205 XmNdropSiteType
207 Specifies the type of the drop site. The possible values are
208 XmDROP_SITE_SIMPLE
210 The widget does not have any additional children
211 that are registered as drop sites.
212 XmDROP_SITE_COMPOSITE
214 The widget will have children that are registered
215 as drop sites.
216 XmNimportTargets
218 Specifies the list of target atoms that this drop site
219 accepts.
220 XmNnumDropRectangles
222 Specifies the number of rectangles in the XmNdropRectangles
223 list. If the drop site type is XmDROP_SITE_COMPOSITE, this
224 resource can not be specified by the application.
225 XmNnumImportTargets
227 Specifies the number of atoms in the target atom list.
228 Callback Information
230 A pointer to the following structure is passed to the XmNdragProc rou‐
231 tine when the drop site receives crossing, motion, or operation changed
232 messages:
233 typedef struct
235 {
236 int reason;
237 XEvent *event;
238 Time timeStamp;
239 Widget dragContext;
240 Position x;
241 Position y;
242 unsigned char dropSiteStatus;
243 unsigned char operation;
244 unsigned char operations;
245 Boolean animate;
246 } XmDragProcCallbackStruct, *XmDragProcCallback;
247 reason Indicates why the callback was invoked.
249 event Points to the XEvent that triggered the callback.
251 timeStamp Specifies the timestamp of the logical event.
253 dragContext
255 Specifies the ID of the DragContext widget associated with
256 the transaction.
257 x Indicates the x-coordinate of the pointer relative to the
259 drop site.
260 y Indicates the y-coordinate of the pointer relative to the
262 drop site.
263 dropSiteStatus
265 An IN/OUT member that indicates whether or not a drop site is
266 valid.
267 When reason is XmCR_DROP_SITE_ENTER_MESSAGE or XmCR_OPERA‐
269 TION_CHANGED, or reason is XmCR_DRAG_MOTION or
270 XmCR_DROP_SITE_LEAVE_MESSAGE and the pointer is not in the
271 same drop site as on the previous invocation of the drag pro‐
272 cedure, the toolkit initializes dropSiteStatus to
273 XmDROP_SITE_VALID if the DragContext's XmNexportTargets and
274 the DropSite's XmNimportTargets are compatible and if the
275 initial value of the operation member is not XmDROP_NOOP.
276 Otherwise, the toolkit initializes dropSiteStatus to
277 XmDROP_SITE_INVALID.
278 When the reason is XmCR_DRAG_MOTION or
280 XmCR_DROP_SITE_LEAVE_MESSAGE and the pointer is within the
281 same drop site as on the previous invocation of the drag pro‐
282 cedure, the toolkit initializes dropSiteStatus to the value
283 of dropSiteStatus at the time the previous invocation of the
284 drag procedure returns.
285 The drag procedure may change the value of this member.
287 After the drag procedure returns, the toolkit uses the final
288 value in initializing the dropSiteStatus member of the call‐
289 back struct passed to the appropriate callbacks of the ini‐
290 tiator.
291 operation An IN/OUT member that identifies an operation.
293 The toolkit initializes operation by selecting an operation
295 from the bitwise AND of the initial value of the operations
296 member and the value of the DropSite's XmNdropSiteOperations
297 resource. The toolkit searches this set first for
298 XmDROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK, and
299 initializes operation to the first operation it finds in the
300 set. If the toolkit finds none of these operations in the
301 set, it initializes operation to XmDROP_NOOP.
302 The drag procedure may change the value of this member.
304 After the drag procedure returns, the toolkit uses the final
305 value in initializing the operation member of the callback
306 struct passed to the appropriate callbacks of the initiator.
307 operations
309 An IN/OUT member that indicates the set of operations sup‐
310 ported for the source data.
311 If the user does not select an operation (by pressing a modi‐
313 fier key), the toolkit initializes operations to the value of
314 the DragContext's XmNdragOperations resource. If the user
315 does select an operation, the toolkit initializes operations
316 to the bitwise AND of the corresponding operation and the
317 value of the DragContext's XmNdragOperations resource. If
318 the resulting set of operations is empty, the toolkit ini‐
319 tializes operations to XmDROP_NOOP.
320 The drag procedure may change the value of this member.
322 After the drag procedure returns, the toolkit uses the final
323 value in initializing the operations member of the callback
324 struct passed to the appropriate callbacks of the initiator.
325 animate An OUT member that indicates whether the toolkit or the
327 receiver client provides drag-under effects for a valid drop
328 site. If animate is set to True, the toolkit provides drop
329 site animation per the XmNanimationStyle resource value; if
330 it is set to False, the receiver generates drag-under anima‐
331 tion effects.
332 A pointer to the following structure is passed to the XmNdropProc rou‐
334 tine when the drop site receives a drop message:
335 typedef struct
337 {
338 int reason;
339 XEvent *event;
340 Time timeStamp;
341 Widget dragContext;
342 Position x;
343 Position y;
344 unsigned char dropSiteStatus;
345 unsigned char operation;
346 unsigned char operations;
347 unsigned char dropAction;
348 } XmDropProcCallbackStruct, *XmDropProcCallback;
349 reason Indicates why the callback was invoked.
351 event Specifies the XEvent that triggered the callback.
353 timeStamp Specifies the timestamp of the logical event.
355 dragContext
357 Specifies the ID of the DragContext widget associated with
358 the transaction.
359 x Indicates the x-coordinate of the pointer relative to the
361 drop site.
362 y Indicates the y-coordinate of the pointer relative to the
364 drop site.
365 dropSiteStatus
367 An IN/OUT member that indicates whether or not a drop site is
368 valid.
369 The toolkit initializes dropSiteStatus to XmDROP_SITE_VALID
371 if the DragContext's XmNexportTargets and the DropSite's XmN‐
372 importTargets are compatible and if the initial value of the
373 operation member is not XmDROP_NOOP. Otherwise, the toolkit
374 initializes dropSiteStatus to XmDROP_SITE_INVALID.
375 The drop procedure may change the value of this member.
377 After the drop procedure returns, the toolkit uses the final
378 value in initializing the dropSiteStatus member of the
379 XmDropStartCallbackStruct passed to the initiator's drop
380 start callbacks (the DragContext's XmNdropStartCallback call‐
381 backs).
382 operation An IN/OUT member that identifies an operation.
384 The toolkit initializes operation by selecting an operation
386 from the bitwise AND of the initial value of the operations
387 member and the value of the DropSite's XmNdropSiteOperations
388 resource. The toolkit searches this set first for
389 XmDROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK, and
390 initializes operation to the first operation it finds in the
391 set. If it finds none of these operations in the set, it
392 initializes operation to XmDROP_NOOP.
393 The drop procedure may change the value of this member.
395 After the drop procedure returns, the toolkit uses the final
396 value in initializing the operation member of the XmDrop‐
397 StartCallbackStruct passed to the initiator's drop start
398 callbacks (the DragContext's XmNdropStartCallback callbacks).
399 operations
401 An IN/OUT member that indicates the set of operations sup‐
402 ported for the source data.
403 If the user does not select an operation (by pressing a modi‐
405 fier key), the toolkit initializes operations to the value of
406 the DragContext's XmNdragOperations resource. If the user
407 does select an operation, the toolkit initializes operations
408 to the bitwise AND of the corresponding operation and the
409 value of the DragContext's XmNdragOperations resource. If
410 the resulting set of operations is empty, the toolkit ini‐
411 tializes operations to XmDROP_NOOP.
412 The drop procedure may change the value of this member.
414 After the drop procedure returns, the toolkit uses the final
415 value in initializing the operations member of the XmDrop‐
416 StartCallbackStruct passed to the initiator's drop start
417 callbacks (the DragContext's XmNdropStartCallback callbacks).
418 dropAction
420 An IN/OUT member that identifies the action associated with
421 the drop. The possible values are
422 XmDROP A drop was attempted. If the drop site is valid,
424 drop transfer handling proceeds.
425 XmDROP_HELP
427 The user has requested help on the drop site.
428 The drop procedure may change the value of this member.
430 After the drop procedure returns, the toolkit uses the final
431 value in initializing the dropAction member of the XmDrop‐
432 StartCallbackStruct passed to the initiator's drop start
433 callbacks (the DragContext's XmNdropStartCallback callbacks).
434
436 XmDragContext(3), XmDragIcon(3), XmDropSiteConfigureStackingOrder(3),
437 XmDropSiteEndUpdate(3), XmDropSiteQueryStackingOrder(3), XmDropSiteReg‐
438 ister(3), XmDropSiteStartUpdate(3), XmDropSiteUpdate(3), XmDropSiteUn‐
439 register(3), XmDropTransfer(3), and XmTargetsAreCompatible(3).
440 XmDropSite(library call)