f9b1708cf5
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1527 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
103 lines
5.1 KiB
TeX
103 lines
5.1 KiB
TeX
\section{Drag-and-drop and clipboard overview}\label{wxdndoverview}
|
|
|
|
Classes: \helpref{wxDataObject}{wxdataobject},
|
|
\helpref{wxTextDataObject}{wxtextdataobject},
|
|
\helpref{wxDropSource}{wxdropsource},
|
|
\helpref{wxDropTarget}{wxdroptarget},
|
|
\helpref{wxTextDropTarget}{wxtextdroptarget},
|
|
\helpref{wxFileDropTarget}{wxfiledroptarget}
|
|
|
|
It has to be noted that the API for drag and drop in wxWindows is not
|
|
yet finished which is mostly due to the fact that DnD support under
|
|
GTK 1.0 is very rudimentary and entirely different from the XDnD
|
|
protocoll used by GTK 1.2. This also entails that not all of the documentation
|
|
concerning DnD might be correct and some of the code might get broken
|
|
in the future. The next release of wxWindows will be based on GTK 1.2
|
|
and will hopefully include a much improved DnD support. The general
|
|
design on the wxDropSource side will be the same but especially the
|
|
wxDropTarget is almost certain to change.
|
|
|
|
Note that wxUSE\_DRAG\_AND\_DROP must be defined in setup.h in order
|
|
to use Drag'n'Drop in wxWindows.
|
|
|
|
This overview describes wxWindows support for drag and drop and clipboard
|
|
operations. Both of these topics are discussed here because, in fact, they're
|
|
quite related. Drag and drop and clipboard are just two ways of passing the
|
|
data around and so the code required to implement both types of the operations
|
|
is almost the same.
|
|
|
|
Both operations involve passing some data from one program to another,
|
|
although the data can be received in the same program as the source. In the case
|
|
of clipboard transfer, the data is first placed on the clipboard and then
|
|
pasted into the destination program, while for a drag-and-drop operation the
|
|
data object is not stored anywhere but is created when the user starts
|
|
dragging and is destroyed as soon as he ends it, whether the operation was
|
|
ended successfully or cancelled.
|
|
|
|
To be a {\it drag source}, i.e. to provide the data which may be dragged by
|
|
user elsewhere, you should implement the following steps:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item {\bf Preparation:} First of all, the data object must be created and
|
|
initialized with the data you wish to drag. For example:
|
|
|
|
\begin{verbatim}
|
|
wxDataObject *my_data = new wxTextDataObject data("This string will be dragged.");
|
|
\end{verbatim}
|
|
|
|
\item{\bf Drag start:} To start dragging process (typically in response to a
|
|
mouse click) you must call \helpref{DoDragDrop}{wxdropsourcedodragdrop} function
|
|
of wxDropSource object which should be constructed like this:
|
|
|
|
\begin{verbatim}
|
|
wxDropSource dragSource( this );
|
|
dragSource.SetData( my_data );
|
|
\end{verbatim}
|
|
|
|
\item {\bf Dragging:} The call to DoDragDrop() blocks until the user release the
|
|
mouse button (unless you override \helpref{GiveFeedback}{wxdropsourcegivefeedback} function
|
|
to do something special). When the mouse moves in a window of a program which understands the
|
|
same drag-and-drop protocol (any program under Windows or any program supporting GTK 1.0
|
|
DnD protocol under X Windows), the corresponding \helpref{wxDropTarget}{wxdroptarget} methods
|
|
are called - see below.
|
|
|
|
\item {\bf Processing the result:} DoDragDrop() returns an {\it effect code} which
|
|
is one of the values of \helpref{wxDragResult}{wxdropsource} enum. Codes
|
|
of wxDragError, wxDragNone and wxDragCancel have the obvious meaning and mean
|
|
that there is nothing to do on the sending end (except of possibly logging the
|
|
error in the first case). wxDragCopy means that the data has been successfully
|
|
copied and doesn't require any specific actions neither. But wxDragMove is
|
|
special because it means that the data must be deleted from where it was
|
|
copied. If it doesn't make sense (dragging selected text from a read-only
|
|
file) you should pass FALSE as parameter to DoDragDrop() in the previous step.
|
|
\end{itemize}
|
|
|
|
To be a {\it drop target}, i.e. to receive the data dropped by user you should
|
|
follow the instructions below:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item {\bf Initialization:} For a window to be drop target, it needs to have
|
|
an associated \helpref{wxDropTarget}{wxdroptarget} object. Normally, you will
|
|
call \helpref{wxWindow::SetDropTarget}{wxwindowsetdroptarget} during window
|
|
creation associating you drop target with it. You must derive a class from
|
|
wxDropTarget and override its pure virtual methods. Alternatively, you may
|
|
derive from \helpref{wxTextDropTarget}{wxtextdroptarget} or
|
|
\helpref{wxFileDropTarget}{wxfiledroptarget} and override their OnDropText()
|
|
or OnDropFiles() method.
|
|
|
|
\item {\bf Drop:} When the user releases the mouse over a window, wxWindows
|
|
queries the associated wxDropTarget object if it accepts the data. For
|
|
this, \helpref{GetFormatCount}{wxdroptargetgetformatcount} and \helpref{GetFormat}{wxdroptargetgetformat} are
|
|
used and if the format is
|
|
supported (i.e. is one of returned by GetFormat()),
|
|
then \helpref{OnDrop}{wxdroptargetondrop} is called.
|
|
Otherwise, wxDragNone is returned by DoDragDrop() and
|
|
nothing happens.
|
|
|
|
\item {\bf The end:} After processing the data, DoDragDrop() returns either
|
|
wxDragCopy or wxDragMove depending on the state of the keys (<Ctrl>, <Shift>
|
|
and <Alt>) at the moment of drop. There is currently no way for the drop
|
|
target to change this return code.
|
|
\end{itemize}
|
|
|