4c51a665c6
Applied patch by snowleopard2 fixing a bunch of typos such as misspellings and double words in the documentation. Combined the patch with some local queued typos waiting to be committed as well as adding new typo fixes inspired by the patch.
Function names with American spelling were not changed nor was third-party code touched. The only code changes involve some changes in strings that are translated ("Can not" -> "Cannot").
Closes #13063 (again).
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@67280 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
168 lines
6.7 KiB
Plaintext
168 lines
6.7 KiB
Plaintext
Drag-and-Drop Support in wxWindows
|
|
==================================
|
|
|
|
1. Overview
|
|
--------
|
|
|
|
a) What is it?
|
|
|
|
We're calling drag-and-drop (or d&d for short) the OLE mechanism of data
|
|
transfer. Please note that it's not the same thing as the file oriented d&d
|
|
of Windows 3.1 "File Manager" which is designed for and limited to the file
|
|
names only.
|
|
|
|
OLE d&d allows application to transfer data of any type to the same or
|
|
another process.
|
|
|
|
|
|
b) How is it done? (user's point of view)
|
|
|
|
To start a d&d operation the user presses the mouse button 1 (left) and
|
|
drags the selected object to another window (which must be at least partially
|
|
visible on the screen) or to an icon on the taskbar in which case the
|
|
corresponding window will be automatically restored. To finish the operation,
|
|
the user releases the button. Default d&d operation is "move", but several key
|
|
act as modifiers: keeping down the <Ctrl> key at the moment of drop does
|
|
"copy", while <Shift> or <Alt> force the "move" (makes sense if default isn't
|
|
"move").
|
|
|
|
|
|
c) How is it done? (programmer's point of view)
|
|
|
|
There are several objects participating in a d&d operation. First of all,
|
|
there is the data object itself. Second, there is the drop source which is
|
|
responsible for creating the data object (if it doesn't exist yet) and starting
|
|
the d&d operation. Finally, the drop target receives the notification when
|
|
the data is dropped onto the associated window (see below) and is responsible
|
|
for pasting the data and returning the result code (copy, move or failure).
|
|
There is one class for each one of these roles in wxWindows d&d implementation,
|
|
plese see their descriptions below for details.
|
|
|
|
|
|
|
|
2. Drop Target
|
|
-----------
|
|
|
|
a) Being a drop target
|
|
|
|
... is as easy as deriving your window class from wxDropTarget and
|
|
associating it with a wxWindow object (or perhaps some wxWindow-derived class,
|
|
such as wxFrame). The pure virtual function wxDropTarget::OnDrop() must be
|
|
implemented in your application and will be called whenever the mouse button
|
|
is released over the window in question. Other virtual functions that will be
|
|
called in the process of the d&d operation are OnEnter and OnLeave.
|
|
|
|
@@ should OnDragOver() be user overridable also?
|
|
|
|
You should associate wxDropTarget and wxWindow calling SetDropTarget:
|
|
wxWindow *pWindow = GetTopWindow();
|
|
pWindow->SetDropTarget(new MyDropTarget);
|
|
|
|
The object created passed to SetDropTarget becomes the propriety of wxWindow
|
|
and will be deleted with the window (or when you call SetDropTarget next
|
|
time). You can always break the association by calling SetDropTarget(NULL).
|
|
|
|
When some data is dragged over a window, the program must decide if it's
|
|
going to accept this data or not. The virtual function IsAcceptedData() is
|
|
called to do it. The default implementation takes care of OLE interface
|
|
pointer manipulations and only requires you to override GetCountFormats()
|
|
and GetFormat(n) functions to let it know what data formats you support.
|
|
If it's not flexible enough for your application (i.e. the set of supported
|
|
formats changes over time...), you should override IsAcceptedData(). In 99%
|
|
of cases the default implementation is ok and you only have to return count
|
|
of supported formats (CF_xxx constants or one of your custom formats which
|
|
must have been registered) and their values.
|
|
|
|
b) OnDrop(long x, long y, const void *pData)
|
|
|
|
(x, y) are drop point (client) coordinates, pData is the pointer to data
|
|
(whatever it is).
|
|
|
|
If 'true' is returned from OnDrop, the operation is considered to be
|
|
successful and the corresponding code (MOVE or COPY depending on the
|
|
keyboard control keys) is returned. Otherwise, the operation is cancelled.
|
|
|
|
Please remember that returning 'true' here may mean 'move' and so the
|
|
drop source will delete the corresponding data - which would lead to
|
|
data loss if you didn't paste it properly.
|
|
|
|
c) OnEnter()
|
|
|
|
called when the mouse enters the window: you might use this function to
|
|
give some additional visual feedback.
|
|
|
|
d) OnLeave()
|
|
|
|
called when the mouse leaves the window; might be a good place to clean
|
|
up things allocated in OnEnter.
|
|
|
|
e) Simple wxDropTarget specializations
|
|
|
|
Two (very simple) wxDropTarget-derived classes are provided for two most
|
|
common situations: d&d of text and file d&d. To use them you only need to
|
|
override one virtual function OnDropText in wxTextDropTarget's case and
|
|
OnDropFiles for wxFileDropTarget.
|
|
|
|
The (x, y) are the same as for OnDrop() function. OnDropText's last
|
|
parameter points to a (always ANSI, not Unicode) text string, while
|
|
OnDropFiles() parameter is the array of file names just dropped (and the
|
|
count of them is passed in the 3rd parameter).
|
|
|
|
3. Data Object
|
|
-----------
|
|
|
|
a) Drag and drop and clipboard
|
|
|
|
The effect of a d&d operation is the same as using the clipboard to
|
|
cut/copy and paste data and it would be nice to use the same code to implement
|
|
these two data transfer mechanisms. The wxDataObject allows you to do exactly
|
|
this. It encapsulates the data which can be passed either through the clipboard
|
|
or d&d.
|
|
|
|
|
|
b) Data format
|
|
|
|
There are several standard clipboard formats, such as text, bitmap or
|
|
metafile picture. All of them are defined in wxDataObject::StdFormats
|
|
enumeration. Of course, it's not always enough and you'll often need your
|
|
own format for data transfer. The simple helper class wxDataFormat may help
|
|
you: when you create an object of this class, it registers a new clipboard
|
|
data format identified by the string passed to it's ctor.
|
|
|
|
After your new format is registered, you may use it as any other one.
|
|
|
|
4. Drop Source
|
|
-----------
|
|
|
|
a) Starting the d&d operation
|
|
|
|
In order to start the d&d operation you should call the DoDragDrop function
|
|
(typically in reply to a "mouse button press" message). NB: DoDragDrop() is a
|
|
blocking function which enters into it's own message loop and may return after
|
|
an arbitrarily long time interval. During it, the QueryContinueDrag() is called
|
|
whenever the mouse or keyboard state changes. The default behaviour is quite
|
|
reasonable for 99% of cases: the drag operation is cancelled if the <Esc> key
|
|
is preessed and the drop is initiated if the mouse button is released.
|
|
|
|
b) After the end of d&d
|
|
|
|
The drop source behaviour depends on DoDragDrop() return code. If it
|
|
returns wxDropSource::None or wxDropSource::Copy there is normally nothing to
|
|
do, but you shouldn't forget to delete your data if it returns the
|
|
wxDropSource::Move code.
|
|
|
|
c) DoDragDrop
|
|
|
|
d) QueryContinueDrag
|
|
|
|
|
|
5. Remarks
|
|
-------
|
|
|
|
|
|
@@@@ TODO: support tymed != TYMED_HGLOBAL;
|
|
better support of CF_BMP, CF_METAFILE
|
|
scrolling support!! (how?)
|
|
sample demonstrating use of user-defined formats
|
|
sample which really does something useful
|