← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to samples/dnd/d_and_d.txt

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
samples/dnd/d_and_d.txt
 
1
                        Drag-and-Drop Support in wxWindows
 
2
                        ==================================
 
3
 
 
4
1. Overview
 
5
   --------
 
6
 
 
7
 a) What is it?
 
8
 
 
9
    We're calling drag-and-drop (or d&d for short) the OLE mechanism of data
 
10
transfer. Please note that it's not the same thing as the file oriented d&d
 
11
of Windows 3.1 "File Manager" which is designed for and limited to the file
 
12
names only.
 
13
 
 
14
    OLE d&d allows application to transfer data of any type to the same or
 
15
another process.
 
16
 
 
17
 
 
18
 b) How is it done? (user's point of view)
 
19
 
 
20
    To start a d&d operation the user presses the mouse button 1 (left) and
 
21
drags the selected object to another window (which must be at least partially
 
22
visible on the screen) or to an icon on the taskbar in which case the 
 
23
corresponding window will be automatically restored. To finish the operation,
 
24
the user releases the button. Default d&d operation is "move", but several key
 
25
act as modifiers: keeping down the <Ctrl> key at the moment of drop does 
 
26
"copy", while <Shift> or <Alt> force the "move" (makes sense if default isn't
 
27
"move"). 
 
28
 
 
29
 
 
30
 c) How is it done? (programmer's point of view)
 
31
 
 
32
    There are several objects participating in a d&d operation. First of all,
 
33
there is the data object itself. Second, there is the drop source which is
 
34
responsible for creating the data object (if it doesn't exist yet) and starting
 
35
the d&d operation. Finally, the drop target receives the notification when
 
36
the data is dropped onto the associated window (see below) and is responsible
 
37
for pasting the data and returning the result code (copy, move or failure).
 
38
There is one class for each one of these roles in wxWindows d&d implementation,
 
39
plese see their descriptions below for details.
 
40
 
 
41
 
 
42
 
 
43
2. Drop Target
 
44
   -----------
 
45
 
 
46
 a) Being a drop target
 
47
 
 
48
    ... is as easy as deriving your window class from wxDropTarget and 
 
49
associating it with a wxWindow object (or perhaps some wxWindow-derived class, 
 
50
such as wxFrame). The pure virtual function wxDropTarget::OnDrop() must be 
 
51
implemented in your application and will be called whenever the mouse button 
 
52
is released over the window in question. Other virtual functions that will be 
 
53
called in the process of the d&d operation are OnEnter and OnLeave.
 
54
 
 
55
@@ should OnDragOver() be user overridable also?
 
56
 
 
57
  You should associate wxDropTarget and wxWindow calling SetDropTarget:
 
58
    wxWindow *pWindow = GetTopWindow();
 
59
    pWindow->SetDropTarget(new MyDropTarget);
 
60
 
 
61
The object created passed to SetDropTarget becomes the propriety of wxWindow
 
62
and will be deleted with the window (or when you call SetDropTarget next
 
63
time). You can always break the association by calling SetDropTarget(NULL).
 
64
 
 
65
  When some data is dragged over a window, the program must decide if it's
 
66
going to accept this data or not. The virtual function IsAcceptedData() is
 
67
called to do it. The default implementation takes care of OLE interface
 
68
pointer manipulations and only requires you to override GetCountFormats()
 
69
and GetFormat(n) functions to let it know what data formats you support.
 
70
If it's not flexible enough for your application (i.e. the set of supported
 
71
formats changes over time...), you should override IsAcceptedData(). In 99%
 
72
of cases the default implementation is ok and you only have to return count
 
73
of supported formats (CF_xxx constants or one of your custom formats which
 
74
must have been registered) and their values.
 
75
 
 
76
 b) OnDrop(long x, long y, const void *pData)
 
77
 
 
78
    (x, y) are drop point (client) coordinates, pData is the pointer to data
 
79
    (whatever it is).
 
80
 
 
81
    If 'true' is returned from OnDrop, the operation is considered to be
 
82
    successful and the corresponding code (MOVE or COPY depending on the
 
83
    keyboard control keys) is returned. Otherwise, the operation is cancelled.
 
84
 
 
85
    Please remember that returning 'true' here may mean 'move' and so the
 
86
    drop source will delete the corresponding data - which would lead to
 
87
    data loss if you didn't paste it properly.
 
88
 
 
89
 c) OnEnter()
 
90
 
 
91
    called when the mouse enters the window: you might use this function to
 
92
    give some additional visual feedback.
 
93
 
 
94
 d) OnLeave()
 
95
 
 
96
    called when the mouse leaves the window; might be a good place to clean
 
97
up things allocated in OnEnter.
 
98
 
 
99
 e) Simple wxDropTarget specializations
 
100
 
 
101
    Two (very simple) wxDropTarget-derived classes are provided for two most
 
102
common situations: d&d of text and file d&d. To use them you only need to
 
103
override one virtual function OnDropText in wxTextDropTarget's case and
 
104
OnDropFiles for wxFileDropTarget.
 
105
 
 
106
    The (x, y) are the same as for OnDrop() function. OnDropText's last
 
107
parameter points to a (always ANSI, not Unicode) text string, while
 
108
OnDropFiles() parameter is the array of file names just dropped (and the
 
109
count of them is passed in the 3rd parameter).
 
110
 
 
111
3. Data Object
 
112
   -----------
 
113
 
 
114
 a) Drag and drop and clipboard
 
115
 
 
116
    The effect of a d&d operation is the same as using the clipboard to
 
117
cut/copy and paste data and it would be nice to use the same code to implement
 
118
these two data transfer mechanisms. The wxDataObject allows you to do exactly
 
119
this. It encapsulates the data which can be passed either through the clipboard
 
120
or d&d.
 
121
 
 
122
 
 
123
 b) Data format
 
124
 
 
125
    There are several standard clipboard formats, such as text, bitmap or 
 
126
metafile picture. All of them are defined in wxDataObject::StdFormats 
 
127
enumeration. Of course, it's not always enough and you'll often need your
 
128
own format for data transfer. The simple helper class wxDataFormat may help
 
129
you: when you create an object of this class, it registers a new clipboard
 
130
data format identified by the string passed to its ctor.
 
131
 
 
132
    After your new format is registered, you may use it as any other one.
 
133
 
 
134
4. Drop Source
 
135
   -----------
 
136
 
 
137
 a) Starting the d&d operation
 
138
 
 
139
    In order to start the d&d operation you should call the DoDragDrop function
 
140
(typically in reply to a "mouse button press" message). NB: DoDragDrop() is a
 
141
blocking function which enters into its own message loop and may return after
 
142
an arbitrarily long time interval. During it, the QueryContinueDrag() is called
 
143
whenever the mouse or keyboard state changes. The default behaviour is quite
 
144
reasonable for 99% of cases: the drag operation is cancelled if the <Esc> key
 
145
is preessed and the drop is initiated if the mouse button is released.
 
146
 
 
147
 b) After the end of d&d
 
148
 
 
149
    The drop source behaviour depends on DoDragDrop() return code. If it 
 
150
returns wxDropSource::None or wxDropSource::Copy there is normally nothing to
 
151
do, but you shouldn't forget to delete your data if it returns the 
 
152
wxDropSource::Move code.
 
153
 
 
154
 c) DoDragDrop
 
155
 
 
156
 d) QueryContinueDrag
 
157
 
 
158
 
 
159
5. Remarks
 
160
   -------
 
161
 
 
162
 
 
163
@@@@ TODO: support tymed != TYMED_HGLOBAL;
 
164
           better support of CF_BMP, CF_METAFILE
 
165
           scrolling support!! (how?)
 
166
           sample demonstrating use of user-defined formats
 
167
           sample which really does something useful