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

NAME

6       XmDragContext — The DragContext widget class
7

SYNOPSIS

9       #include <Xm/DragDrop.h>
10

DESCRIPTION

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
21       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
31       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
41       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
46       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
55   Classes
56       DragContext inherits behavior and resources from Core.
57
58       The class pointer is xmDragContextClass.
59
60       The class name is XmDragContext.
61
62   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
75       ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
76       │                            │                 XmDragC│ontext Resource Set          │                           │        │
77Name                        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
134                 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
141                 XmBLEND_STATE_SOURCE
142                           Blends the state and source icons only. The hotspot
143                           is derived from the state icon.
144
145                 XmBLEND_JUST_SOURCE
146                           Specifies that only the source icon is used,  which
147                           the initiator updates as required.
148
149                 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
155       XmNclientData
156                 Specifies the client data to be passed to XmNconvertProc when
157                 it is invoked.
158
159       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
173       XmNcursorBackground
174                 Specifies the background pixel value of the cursor.
175
176       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
182       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
189       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
195       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
206       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
212       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
219       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
226       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
232       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
237       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
245       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
250       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
255       XmNnumExportTargets
256                 Specifies  the  number  of entries in the list of export tar‐
257                 gets.
258
259       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
267       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
273       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
279       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
285       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
290       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
297       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
304       XmNvalidCursorForeground
305                 Specifies the foreground pixel value of the cursor designated
306                 as a valid cursor icon.
307
308   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
313       ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
314       │                              │               Core Resource Se│t                │                      │        │
315Name                          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
359       A  pointer  to the following structure is passed to the XmNdragDropFin‐
360       ishCallback callback:
361
362       typedef struct
363       {
364               int reason;
365               XEvent  *event;
366               Time timeStamp;
367       }XmDragDropFinishCallbackStruct, *XmDragDropFinishCallback;
368
369       reason    Indicates why the callback was invoked
370
371       event     Points to the XEvent that triggered the callback
372
373       timeStamp Specifies the time at which either the drag or the  drop  was
374                 completed
375
376       A  pointer  to  the following structure is passed to callbacks for XmN‐
377       dragMotionCallback:
378
379       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
391       reason    Indicates why the callback was invoked.
392
393       event     Points to the XEvent that triggered the callback.
394
395       timeStamp Specifies the timestamp of the logical event.
396
397       operation Identifies an operation.
398
399                 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
404                 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
415                 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
424       operations
425                 Indicates  the  set  of  operations  supported for the source
426                 data.
427
428                 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
436                 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
441                 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
448       dropSiteStatus
449                 Indicates whether or not a drop site is valid.
450
451                 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
456                 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
463                    ·  The pointer is over an active drop site.
464
465                    ·  The DragContext's XmNexportTargets and  the  DropSite's
466                       XmNimportTargets are compatible.
467
468                    ·  The  initial  value  of  the  operation  member  is not
469                       XmDROP_NOOP.
470
471                 Otherwise,  the   toolkit   initializes   dropSiteStatus   to
472                 XmDROP_SITE_INVALID.
473
474       A  pointer  to the following structure is passed for the XmNdropFinish‐
475       Callback callback:
476
477       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
489       reason    Indicates why the callback was invoked.
490
491       event     Points to the XEvent that triggered the callback.
492
493       timeStamp Specifies the time at which the drop was completed.
494
495       operation Identifies an operation.
496
497                 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
502                 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
511       operations
512                 Indicates the set of  operations  supported  for  the  source
513                 data.
514
515                 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
523                 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
528                 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
535       dropSiteStatus
536                 Indicates whether or not a drop site is valid.
537
538                 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
543                 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
547       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
553       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
559                 XmDROP_SUCCESS
560                           The drop was successful.
561
562                 XmDROP_FAILURE
563                           The drop was unsuccessful.
564
565       A pointer to the following structure is passed to  callbacks  for  XmN‐
566       dropSiteEnterCallback:
567
568       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
580       reason    Indicates why the callback was invoked.
581
582       event     Points to the XEvent that triggered the callback.
583
584       timeStamp Specifies the time the crossing event occurred.
585
586       operation Identifies an operation.
587
588                 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
593                 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
603       operations
604                 Indicates the set of  operations  supported  for  the  source
605                 data.
606
607                 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
615                 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
620                 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
627       dropSiteStatus
628                 Indicates whether or not a drop site is valid.
629
630                 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
635                 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
642       x         Indicates  the  x-coordinate  of  the  pointer in root window
643                 coordinates.
644
645       y         Indicates the y-coordinate of  the  pointer  in  root  window
646                 coordinates.
647
648       A  pointer  to  the following structure is passed to callbacks for XmN‐
649       dropSiteLeaveCallback:
650
651       typedef struct
652       {
653               int reason;
654               XEvent *event;
655               Time timeStamp;
656       }XmDropSiteLeaveCallbackStruct, *XmDropSiteLeaveCallback;
657
658       reason    Indicates why the callback was invoked
659
660       event     Points to the XEvent that triggered the callback
661
662       timeStamp Specifies the timestamp of the logical event
663
664       A pointer to the following structure is passed  for  the  XmNdropStart‐
665       Callback callback:
666
667       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
680       reason    Indicates why the callback was invoked.
681
682       event     Points to the XEvent that triggered the callback.
683
684       timeStamp Specifies the time at which the drag was completed.
685
686       operation Identifies an operation.
687
688                 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
693                 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
702       operations
703                 Indicates  the  set  of  operations  supported for the source
704                 data.
705
706                 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
714                 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
719                 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
726       dropSiteStatus
727                 Indicates whether or not a drop site is valid.
728
729                 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
734                 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
738                 This  field  is  invalid  if  the  dropAction field is set to
739                 XmDROP_CANCEL.
740
741       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
749       x         Indicates  the  x-coordinate  of  the  pointer in root window
750                 coordinates.
751
752       y         Indicates the y-coordinate of  the  pointer  in  root  window
753                 coordinates.
754
755       A  pointer  to  the  following  structure  is  passed  to the XmNopera‐
756       tionChangedCallback callback:
757
758       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
768       reason    Indicates why the callback was invoked.
769
770       event     Points to the XEvent that triggered the callback.
771
772       timeStamp Specifies the time at which the crossing event occurred.
773
774       operation Identifies an operation.
775
776                 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
781                 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
792                 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
801       operations
802                 Indicates  the  set  of  operations  supported for the source
803                 data.
804
805                 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
813                 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
818                 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
825       dropSiteStatus
826                 Indicates whether or not a drop site is valid.
827
828                 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
833                 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
839                    ·  The pointer is over an active drop site
840
841                    ·  The  DragContext's  XmNexportTargets and the DropSite's
842                       XmNimportTargets are compatible
843
844                    ·  The initial  value  of  the  operation  member  is  not
845                       XmDROP_NOOP
846
847                 Otherwise,   the   toolkit   initializes   dropSiteStatus  to
848                 XmDROP_SITE_INVALID.
849
850       A pointer to the following structure is passed to callbacks for  XmNto‐
851       pLevelEnterCallback:
852
853       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
865       reason    Indicates why the callback was invoked.
866
867       event     Points to the XEvent that triggered the callback.
868
869       timeStamp Specifies the timestamp of the logical event.
870
871       screen    Specifies  the screen associated with the top-level window or
872                 root window being entered.
873
874       window    Specifies the ID of the top-level window or root window being
875                 entered.
876
877       x         Indicates  the  x-coordinate  of  the  pointer in root window
878                 coordinates.
879
880       y         Indicates the y-coordinate of  the  pointer  in  root  window
881                 coordinates.
882
883       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
888       A  pointer to the following structure is passed to callbacks for XmNto‐
889       pLevelLeaveCallback:
890
891       typedef struct
892       {
893               int reason;
894               XEvent  *event;
895               Time timeStamp;
896               Screen screen;
897               Window window;
898       }XmTopLevelLeaveCallbackStruct, *XmTopLevelLeaveCallback;
899
900       reason    Indicates why the callback was invoked
901
902       event     Points to the XEvent that triggered the callback
903
904       timeStamp Specifies the timestamp of the logical event
905
906       screen    Specifies a screen associated with the  top-level  window  or
907                 root window being left
908
909       window    Specifies the ID of the top-level window or root window being
910                 left
911
912   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
921       Button1<Enter>:
922                 DragMotion()
923
924       Button1<Leave>:
925                 DragMotion()
926
927       Button1<Motion>:
928                 DragMotion()
929
930       Button2<Enter>:
931                 DragMotion()
932
933       Button2<Leave>:
934                 DragMotion()
935
936       Button2<Motion>:
937                 DragMotion()
938
939       <Btn2Up>: FinishDrag()
940
941       <Btn1Up>: FinishDrag()
942
943       <Key>Return:
944                 FinishDrag()
945
946       <Key><osfActivate>:
947                 FinishDrag()
948
949       <BtnDown>:
950                 IgnoreButtons()
951
952       <BtnUp>:  IgnoreButtons()
953
954       :<Key><osfCancel>:
955                 CancelDrag()
956
957       :<Key><osfHelp>:
958                 HelpDrag()
959
960       :<Key><osfUp>:
961                 DragKey(Up)
962
963       :<Key><osfDown>:
964                 DragKey(Down)
965
966       :<Key><osfLeft>:
967                 DragKey(Left)
968
969       :<Key><osfRight>:
970                 DragKey(Right)
971
972       :<KeyUp>: DragKey(Update)
973
974       :<KeyDown>:
975                 DragKey(Update)
976
977   Action Routines
978       The XmDragContext action routines are
979
980       CancelDrag():
981                 Cancels the drag operation and frees the associated  DragCon‐
982                 text.
983
984       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
989       DragMotion():
990                 Drags the selected data as the pointer is moved.
991
992       FinishDrag():
993                 Finishes the drag operation and starts the drop operation.
994
995       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
1000   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
1008
1009
1010                                                   XmDragContext(library call)
Impressum