1XmDropSite(library call)                              XmDropSite(library call)
2
3
4

NAME

6       XmDropSite — The DropSite Registry
7

SYNOPSIS

9       #include <Xm/DragDrop.h>
10

DESCRIPTION

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
20       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
27       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
38       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
43       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
48   Classes
49       XmDropSite does not inherit from any widget class.
50
51   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
62       ┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
63       │                        │               XmDropSiteResource Set    │                           │        │
64Name                    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
97       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
105       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
113       XmNanimationStyle
114                 Specifies the drag-under animation style  used  when  a  drag
115                 enters a valid drop site. The possible values are
116
117                 XmDRAG_UNDER_HIGHLIGHT
118                           The drop site uses highlighting effects.
119
120                 XmDRAG_UNDER_SHADOW_OUT
121                           The drop site uses an outset shadow.
122
123                 XmDRAG_UNDER_SHADOW_IN
124                           The drop site uses an inset shadow.
125
126                 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
131                 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
136       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
144                    ·  XmCR_DROP_SITE_ENTER_MESSAGE
145
146                    ·  XmCR_DROP_SITE_LEAVE_MESSAGE
147
148                    ·  XmCR_DRAG_MOTION
149
150                    ·  XmCR_OPERATION_CHANGED
151
152                 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
160       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
168                 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
175       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
183                 Retrieving  this resource returns allocated memory that needs
184                 to be freed with the XtFree function.
185
186       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
198       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
206       XmNdropSiteType
207                 Specifies the type of the drop site. The possible values are
208
209                 XmDROP_SITE_SIMPLE
210                           The widget does not have  any  additional  children
211                           that are registered as drop sites.
212
213                 XmDROP_SITE_COMPOSITE
214                           The  widget  will have children that are registered
215                           as drop sites.
216
217       XmNimportTargets
218                 Specifies the list  of  target  atoms  that  this  drop  site
219                 accepts.
220
221       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
226       XmNnumImportTargets
227                 Specifies the number of atoms in the target atom list.
228
229   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
234       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
248       reason    Indicates why the callback was invoked.
249
250       event     Points to the XEvent that triggered the callback.
251
252       timeStamp Specifies the timestamp of the logical event.
253
254       dragContext
255                 Specifies  the  ID  of the DragContext widget associated with
256                 the transaction.
257
258       x         Indicates the x-coordinate of the  pointer  relative  to  the
259                 drop site.
260
261       y         Indicates  the  y-coordinate  of  the pointer relative to the
262                 drop site.
263
264       dropSiteStatus
265                 An IN/OUT member that indicates whether or not a drop site is
266                 valid.
267
268                 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
279                 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
286                 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
292       operation An IN/OUT member that identifies an operation.
293
294                 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
303                 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
308       operations
309                 An  IN/OUT  member  that indicates the set of operations sup‐
310                 ported for the source data.
311
312                 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
321                 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
326       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
333       A  pointer to the following structure is passed to the XmNdropProc rou‐
334       tine when the drop site receives a drop message:
335
336       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
350       reason    Indicates why the callback was invoked.
351
352       event     Specifies the XEvent that triggered the callback.
353
354       timeStamp Specifies the timestamp of the logical event.
355
356       dragContext
357                 Specifies the ID of the DragContext  widget  associated  with
358                 the transaction.
359
360       x         Indicates  the  x-coordinate  of  the pointer relative to the
361                 drop site.
362
363       y         Indicates the y-coordinate of the  pointer  relative  to  the
364                 drop site.
365
366       dropSiteStatus
367                 An IN/OUT member that indicates whether or not a drop site is
368                 valid.
369
370                 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
376                 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
383       operation An IN/OUT member that identifies an operation.
384
385                 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
394                 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
400       operations
401                 An IN/OUT member that indicates the set  of  operations  sup‐
402                 ported for the source data.
403
404                 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
413                 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
419       dropAction
420                 An IN/OUT member that identifies the action  associated  with
421                 the drop.  The possible values are
422
423                 XmDROP    A  drop  was  attempted. If the drop site is valid,
424                           drop transfer handling proceeds.
425
426                 XmDROP_HELP
427                           The user has requested help on the drop site.
428
429                 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
441
442
443                                                      XmDropSite(library call)
Impressum