1XmDropTransfer(library call) XmDropTransfer(library call)
2
6 XmDropTransfer — The DropTransfer widget class
7
9 #include <Xm/DragDrop.h>
10
12 DropTransfer provides a set of resources that identifies the procedures
13 and associated information required by the toolkit in order to process
14 and complete a drop transaction. Clients should not explicitly create
15 a DropTransfer widget. Instead, a client initiates a transfer by call‐
16 ing XmDropTransferStart, which initializes and returns a DropTransfer
17 widget. If this function is called within an XmNdropProc callback, the
18 actual transfers are initiated after the callback returns. Even if no
19 data needs to be transferred, XmDropTransferStart needs to be called
20 (typically with no arguments, or just setting XmNtransferStatus) to
21 finish the drag and drop transaction.
22 The XmNdropTransfers resource specifies a transfer list that describes
24 the requested target types for the source data. A transfer list is an
25 array of XmDropTransferEntryRec structures, each of which identifies a
26 target type. The transfer list is analogous to the MULTIPLE selections
27 capability defined in the Inter-Client Communication Conventions Manual
28 (ICCCM).
29 The DropTransfer resource, XmNtransferProc, specifies a transfer proce‐
31 dure of type XtSelectionCallbackProc that delivers the requested selec‐
32 tion data. This procedure operates in conjunction with the underlying
33 Xt selection capabilities and is called for each target in the transfer
34 list. Additional target types can be requested after a transfer is ini‐
35 tiated by calling the XmDropTransferAdd function.
36 Structures
38 An XmDropTransferEntry is a pointer to the following structure of type
39 XmDropTransferEntryRec, which identifies a selection target associated
40 with a given drop transaction:
41 typedef struct
43 {
44 XtPointer client_data;
45 Atom target;
46 } XmDropTransferEntryRec, *XmDropTransferEntry;
47 client_data
49 Specifies any additional information required by this selec‐
50 tion target
51 target Specifies a selection target associated with the drop opera‐
53 tion
54 Classes
56 DropTransfer inherits behavior and a resource from Object.
57 The class pointer is xmDropTransferObjectClass.
59 The class name is XmDropTransfer.
61 New Resources
63 The following table defines a set of widget resources used by the pro‐
64 grammer to specify data. The programmer can also set the resource val‐
65 ues for the inherited classes to set attributes for this widget. To
66 reference a resource by name or by class in a .Xdefaults file, remove
67 the XmN or XmC prefix and use the remaining letters. To specify one of
68 the defined values for a resource in a .Xdefaults file, remove the Xm
69 prefix and use the remaining letters (in either lowercase or uppercase,
70 but include any underscores between words). The codes in the access
71 column indicate if the given resource can be set at creation time (C),
72 set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
73 not applicable (N/A).
74 ┌───────────────────────────────────────────────────────────────────────────────────────────────────┐
76 │ │ XmDropT│ransfer Resource Set │ │ │
77 │Name │ Class │ Type │ Default │ Access │
78 ├────────────────────┼─────────────────────┼──────────────────────────┼────────────────────┼────────┤
79 │XmNdropTransfers │ XmCDropTransfers │ XmDropTransferEntryRec * │ NULL │ CG │
80 ├────────────────────┼─────────────────────┼──────────────────────────┼────────────────────┼────────┤
81 │XmNincremental │ XmCIncremental │ Boolean │ False │ CSG │
82 ├────────────────────┼─────────────────────┼──────────────────────────┼────────────────────┼────────┤
83 │XmNnumDropTransfers │ XmCNumDropTransfers │ Cardinal │ 0 │ CSG │
84 ├────────────────────┼─────────────────────┼──────────────────────────┼────────────────────┼────────┤
85 │XmNtransferProc │ XmCTransferProc │ XtSelectionCallbackProc │ NULL │ CSG │
86 ├────────────────────┼─────────────────────┼──────────────────────────┼────────────────────┼────────┤
87 │XmNtransferStatus │ XmCTransferStatus │ unsigned char │ XmTRANSFER_SUCCESS │ CSG │
88 ├────────────────────┼─────────────────────┼──────────────────────────┼────────────────────┼────────┤
89 └────────────────────┴─────────────────────┴──────────────────────────┴────────────────────┴────────┘
90 XmNdropTransfers
91 Specifies the address of an array of drop transfer entry
92 records. The drop transfer is complete when all the entries
93 in the list have been processed.
94 XmNincremental
96 Specifies a Boolean value that indicates whether the transfer
97 on the receiver side uses the Xt incremental selection trans‐
98 fer mechanism described in X Toolkit Intrinsics—C Language
99 Interface. If the value is True, the receiver uses incremen‐
100 tal transfer; if the value is False, the receiver uses atomic
101 transfer.
102 XmNnumDropTransfers
104 Specifies the number of entries in XmNdropTransfers. If this
105 resource is set to 0 at any time, the transfer is considered
106 complete. The value of XmNtransferStatus determines the com‐
107 pletion handshaking process.
108 XmNtransferProc
110 Specifies a procedure of type XtSelectionCallbackProc that
111 delivers the requested selection values. The widget argument
112 passed to this procedure is the DropTransfer widget. The
113 selection atom passed is _MOTIF_DROP. For additional infor‐
114 mation on selection callback procedures, see X Toolkit
115 Intrinsics—C Language Interface.
116 XmNtransferStatus
118 Specifies the current status of the drop transfer. The client
119 updates this value when the transfer ends and communicates
120 the value to the initiator. The possible values are
121 XmTRANSFER_SUCCESS
123 The transfer succeeded.
124 XmTRANSFER_FAILURE
126 The transfer failed.
127 Inherited Resources
129 DropTransfer inherits behavior and a resource from Object. For a com‐
130 plete description of this resource, refer to the Object reference page.
131 ┌─────────────────────────────────────────────────────────────────────┐
133 │ │ Object Re│source Set │ │ │
134 │Name │ Class │ Type │ Default │ Access │
135 ├───────────────────┼─────────────┼────────────────┼─────────┼────────┤
136 │XmNdestroyCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
137 ├───────────────────┼─────────────┼────────────────┼─────────┼────────┤
138 └───────────────────┴─────────────┴────────────────┴─────────┴────────┘
140 Object(3), XmDisplay(3), XmDragContext(3), XmDragIcon(3), XmDrop‐
141 Site(3), XmDropTransferAdd(3), and XmDropTransferStart(3).
142 XmDropTransfer(library call)