1999-11-01 20:25:43 -05:00
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
%% Name: dataobj.tex
|
|
|
|
%% Purpose: wxDataObject documentation
|
|
|
|
%% Author: Vadim Zeitlin
|
|
|
|
%% Modified by:
|
|
|
|
%% Created: 18.10.99
|
|
|
|
%% RCS-ID: $Id$
|
2004-05-04 04:27:20 -04:00
|
|
|
%% Copyright: (c) wxWidgets team
|
2005-02-22 10:09:56 -05:00
|
|
|
%% License: wxWindows license
|
1999-11-01 20:25:43 -05:00
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
|
1999-01-13 09:23:31 -05:00
|
|
|
\section{\class{wxDataObject}}\label{wxdataobject}
|
|
|
|
|
|
|
|
A wxDataObject represents data that can be copied to or from the clipboard, or
|
1999-11-01 20:25:43 -05:00
|
|
|
dragged and dropped. The important thing about wxDataObject is that this is a
|
2004-11-16 15:48:11 -05:00
|
|
|
'smart' piece of data unlike 'dumb' data containers such as memory
|
1999-11-02 05:02:01 -05:00
|
|
|
buffers or files. Being 'smart' here means that the data object itself should
|
1999-11-01 20:25:43 -05:00
|
|
|
know what data formats it supports and how to render itself in each of
|
2004-11-16 15:48:11 -05:00
|
|
|
its supported formats.
|
1999-11-01 20:25:43 -05:00
|
|
|
|
|
|
|
A supported format, incidentally, is exactly the format in which the data can
|
|
|
|
be requested from a data object or from which the data object may be set. In
|
1999-11-02 05:02:01 -05:00
|
|
|
the general case, an object may support different formats on 'input' and
|
|
|
|
'output', i.e. it may be able to render itself in a given format but not be
|
1999-11-01 20:25:43 -05:00
|
|
|
created from data on this format or vice versa. wxDataObject defines an
|
|
|
|
enumeration type
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
enum Direction
|
|
|
|
{
|
|
|
|
Get = 0x01, // format is supported by GetDataHere()
|
|
|
|
Set = 0x02 // format is supported by SetData()
|
|
|
|
};
|
|
|
|
\end{verbatim}
|
|
|
|
|
2004-11-16 15:48:11 -05:00
|
|
|
which distinguishes between them. See
|
1999-11-01 20:25:43 -05:00
|
|
|
\helpref{wxDataFormat}{wxdataformat} documentation for more about formats.
|
|
|
|
|
2002-06-07 16:15:28 -04:00
|
|
|
Not surprisingly, being 'smart' comes at a price of added complexity. This is
|
1999-11-01 20:25:43 -05:00
|
|
|
reasonable for the situations when you really need to support multiple formats,
|
|
|
|
but may be annoying if you only want to do something simple like cut and paste
|
|
|
|
text.
|
|
|
|
|
2004-05-04 04:27:20 -04:00
|
|
|
To provide a solution for both cases, wxWidgets has two predefined classes
|
2000-03-14 19:21:49 -05:00
|
|
|
which derive from wxDataObject: \helpref{wxDataObjectSimple}{wxdataobjectsimple} and
|
|
|
|
\helpref{wxDataObjectComposite}{wxdataobjectcomposite}.
|
1999-11-01 20:25:43 -05:00
|
|
|
\helpref{wxDataObjectSimple}{wxdataobjectsimple} is
|
|
|
|
the simplest wxDataObject possible and only holds data in a single format (such
|
|
|
|
as HTML or text) and \helpref{wxDataObjectComposite}{wxdataobjectcomposite} is
|
2004-12-11 16:33:17 -05:00
|
|
|
the simplest way to implement a wxDataObject that does support multiple formats
|
2004-11-16 15:48:11 -05:00
|
|
|
because it achieves this by simply holding several wxDataObjectSimple objects.
|
1999-11-01 20:25:43 -05:00
|
|
|
|
|
|
|
So, you have several solutions when you need a wxDataObject class (and you need
|
|
|
|
one as soon as you want to transfer data via the clipboard or drag and drop):
|
|
|
|
|
1999-11-02 19:29:20 -05:00
|
|
|
\begin{twocollist}\itemsep=1cm
|
2000-03-14 19:21:49 -05:00
|
|
|
\twocolitem{{\bf 1. Use one of the built-in classes}}{You may use wxTextDataObject,
|
1999-11-01 20:25:43 -05:00
|
|
|
wxBitmapDataObject or wxFileDataObject in the simplest cases when you only need
|
1999-11-02 05:02:01 -05:00
|
|
|
to support one format and your data is either text, bitmap or list of files.}
|
2000-03-14 19:21:49 -05:00
|
|
|
\twocolitem{{\bf 2. Use wxDataObjectSimple}}{Deriving from wxDataObjectSimple is the simplest
|
1999-11-01 20:25:43 -05:00
|
|
|
solution for custom data - you will only support one format and so probably
|
|
|
|
won't be able to communicate with other programs, but data transfer will work
|
|
|
|
in your program (or between different copies of it).}
|
2000-03-14 19:21:49 -05:00
|
|
|
\twocolitem{{\bf 3. Use wxDataObjectComposite}}{This is a simple but powerful
|
1999-11-02 05:02:01 -05:00
|
|
|
solution which allows you to support any number of formats (either
|
1999-11-01 20:25:43 -05:00
|
|
|
standard or custom if you combine it with the previous solution).}
|
2000-03-14 19:21:49 -05:00
|
|
|
\twocolitem{{\bf 4. Use wxDataObject directly}}{This is the solution for
|
2004-11-16 15:48:11 -05:00
|
|
|
maximal flexibility and efficiency, but it is also the most difficult to
|
1999-11-01 20:25:43 -05:00
|
|
|
implement.}
|
|
|
|
\end{twocollist}
|
|
|
|
|
1999-11-02 05:02:01 -05:00
|
|
|
Please note that the easiest way to use drag and drop and the clipboard with
|
1999-11-01 20:25:43 -05:00
|
|
|
multiple formats is by using wxDataObjectComposite, but it is not the most
|
|
|
|
efficient one as each wxDataObjectSimple would contain the whole data in its
|
1999-12-29 04:48:10 -05:00
|
|
|
respective formats. Now imagine that you want to paste 200 pages of text in
|
1999-11-01 20:25:43 -05:00
|
|
|
your proprietary format, as well as Word, RTF, HTML, Unicode and plain text to
|
|
|
|
the clipboard and even today's computers are in trouble. For this case, you
|
|
|
|
will have to derive from wxDataObject directly and make it enumerate its
|
|
|
|
formats and provide the data in the requested format on demand.
|
|
|
|
|
2004-11-16 15:48:11 -05:00
|
|
|
Note that neither the GTK+ data transfer mechanisms for clipboard and
|
|
|
|
drag and drop, nor OLE data transfer, copy any data until another application
|
1999-11-02 05:02:01 -05:00
|
|
|
actually requests the data. This is in contrast to the 'feel' offered to the
|
1999-11-01 20:25:43 -05:00
|
|
|
user of a program who would normally think that the data resides in the
|
1999-11-02 05:02:01 -05:00
|
|
|
clipboard after having pressed 'Copy' - in reality it is only declared to be
|
1999-11-01 20:25:43 -05:00
|
|
|
available.
|
|
|
|
|
|
|
|
There are several predefined data object classes derived from
|
2000-03-14 19:21:49 -05:00
|
|
|
wxDataObjectSimple: \helpref{wxFileDataObject}{wxfiledataobject},
|
|
|
|
\helpref{wxTextDataObject}{wxtextdataobject} and
|
1999-11-01 20:25:43 -05:00
|
|
|
\helpref{wxBitmapDataObject}{wxbitmapdataobject} which can be used without
|
|
|
|
change.
|
|
|
|
|
2000-03-14 19:21:49 -05:00
|
|
|
You may also derive your own data object classes from
|
1999-11-06 05:22:11 -05:00
|
|
|
\helpref{wxCustomDataObject}{wxcustomdataobject} for user-defined types. The
|
2004-11-16 15:48:11 -05:00
|
|
|
format of user-defined data is given as a mime-type string literal, such as
|
1999-11-01 20:25:43 -05:00
|
|
|
"application/word" or "image/png". These strings are used as they are under
|
2004-11-16 15:48:11 -05:00
|
|
|
Unix (so far only GTK+) to identify a format and are translated into their
|
1999-11-01 20:25:43 -05:00
|
|
|
Windows equivalent under Win32 (using the OLE IDataObject for data exchange to
|
1999-11-02 05:02:01 -05:00
|
|
|
and from the clipboard and for drag and drop). Note that the format string
|
|
|
|
translation under Windows is not yet finished.
|
1999-11-01 20:25:43 -05:00
|
|
|
|
1999-12-23 15:09:58 -05:00
|
|
|
\pythonnote{At this time this class is not directly usable from wxPython.
|
2000-03-14 19:21:49 -05:00
|
|
|
Derive a class from \helpref{wxPyDataObjectSimple}{wxdataobjectsimple}
|
1999-11-06 03:30:23 -05:00
|
|
|
instead.}
|
|
|
|
|
2002-07-05 12:43:21 -04:00
|
|
|
\perlnote{This class is not currently usable from wxPerl; you may
|
|
|
|
use \helpref{Wx::PlDataObjectSimple}{wxdataobjectsimple} instead.}
|
|
|
|
|
1999-11-01 20:25:43 -05:00
|
|
|
\wxheading{Virtual functions to override}
|
|
|
|
|
|
|
|
Each class derived directly from wxDataObject must override and implement all
|
|
|
|
of its functions which are pure virtual in the base class.
|
|
|
|
|
|
|
|
The data objects which only render their data or only set it (i.e. work in
|
2000-03-14 19:21:49 -05:00
|
|
|
only one direction), should return 0 from
|
1999-11-01 20:25:43 -05:00
|
|
|
\helpref{GetFormatCount}{wxdataobjectgetformatcount}.
|
1999-01-29 19:15:17 -05:00
|
|
|
|
1999-01-13 09:23:31 -05:00
|
|
|
\wxheading{Derived from}
|
|
|
|
|
1999-11-01 20:25:43 -05:00
|
|
|
None
|
1999-01-13 09:23:31 -05:00
|
|
|
|
1999-02-15 15:41:29 -05:00
|
|
|
\wxheading{Include files}
|
|
|
|
|
|
|
|
<wx/dataobj.h>
|
|
|
|
|
2007-07-28 08:21:03 -04:00
|
|
|
\wxheading{Library}
|
|
|
|
|
|
|
|
\helpref{wxCore}{librarieslist}
|
|
|
|
|
1999-01-13 09:23:31 -05:00
|
|
|
\wxheading{See also}
|
|
|
|
|
2000-03-14 19:21:49 -05:00
|
|
|
\helpref{Clipboard and drag and drop overview}{wxdndoverview},
|
|
|
|
\helpref{DnD sample}{samplednd},
|
|
|
|
\helpref{wxFileDataObject}{wxfiledataobject},
|
|
|
|
\helpref{wxTextDataObject}{wxtextdataobject},
|
|
|
|
\helpref{wxBitmapDataObject}{wxbitmapdataobject},
|
|
|
|
\helpref{wxCustomDataObject}{wxcustomdataobject},
|
|
|
|
\helpref{wxDropTarget}{wxdroptarget},
|
|
|
|
\helpref{wxDropSource}{wxdropsource},
|
|
|
|
\helpref{wxTextDropTarget}{wxtextdroptarget},
|
1999-11-01 20:25:43 -05:00
|
|
|
\helpref{wxFileDropTarget}{wxfiledroptarget}
|
1999-01-13 09:23:31 -05:00
|
|
|
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
|
|
|
\membersection{wxDataObject::wxDataObject}\label{wxdataobjectwxdataobject}
|
|
|
|
|
|
|
|
\func{}{wxDataObject}{\void}
|
|
|
|
|
|
|
|
Constructor.
|
|
|
|
|
|
|
|
\membersection{wxDataObject::\destruct{wxDataObject}}\label{wxdataobjectdtor}
|
|
|
|
|
|
|
|
\func{}{\destruct{wxDataObject}}{\void}
|
|
|
|
|
|
|
|
Destructor.
|
|
|
|
|
1999-11-01 20:25:43 -05:00
|
|
|
\membersection{wxDataObject::GetAllFormats}\label{wxdataobjectgetallformats}
|
1999-11-01 13:20:39 -05:00
|
|
|
|
1999-11-02 05:02:01 -05:00
|
|
|
\constfunc{virtual void}{GetAllFormats}{ \param{wxDataFormat *}{formats}, \param{Direction}{ dir = Get}}
|
1999-11-01 13:20:39 -05:00
|
|
|
|
2000-03-14 19:21:49 -05:00
|
|
|
Copy all supported formats in the given direction to the array pointed to by
|
1999-11-02 05:02:01 -05:00
|
|
|
{\it formats}. There is enough space for GetFormatCount(dir) formats in it.
|
1999-11-01 13:20:39 -05:00
|
|
|
|
2001-11-23 17:08:45 -05:00
|
|
|
\perlnote{In wxPerl this method only takes the {\tt dir} parameter.
|
|
|
|
In scalar context it returns the first format,
|
|
|
|
in list context it returns a list containing all the supported formats.}
|
|
|
|
|
1999-11-01 13:20:39 -05:00
|
|
|
\membersection{wxDataObject::GetDataHere}\label{wxdataobjectgetdatahere}
|
|
|
|
|
1999-11-01 20:25:43 -05:00
|
|
|
\constfunc{virtual bool}{GetDataHere}{\param{const wxDataFormat\&}{ format}, \param{void }{*buf} }
|
1999-11-01 13:20:39 -05:00
|
|
|
|
1999-11-01 20:25:43 -05:00
|
|
|
The method will write the data of the format {\it format} in the buffer {\it
|
2003-01-17 19:16:34 -05:00
|
|
|
buf} and return true on success, false on failure.
|
1999-11-01 13:20:39 -05:00
|
|
|
|
|
|
|
\membersection{wxDataObject::GetDataSize}\label{wxdataobjectgetdatasize}
|
|
|
|
|
|
|
|
\constfunc{virtual size\_t}{GetDataSize}{\param{const wxDataFormat\&}{ format} }
|
|
|
|
|
|
|
|
Returns the data size of the given format {\it format}.
|
|
|
|
|
1999-11-01 20:25:43 -05:00
|
|
|
\membersection{wxDataObject::GetFormatCount}\label{wxdataobjectgetformatcount}
|
|
|
|
|
|
|
|
\constfunc{virtual size\_t}{GetFormatCount}{\param{Direction}{ dir = Get}}
|
|
|
|
|
1999-11-02 05:02:01 -05:00
|
|
|
Returns the number of available formats for rendering or setting the data.
|
1999-11-01 20:25:43 -05:00
|
|
|
|
1999-11-01 13:20:39 -05:00
|
|
|
\membersection{wxDataObject::GetPreferredFormat}\label{wxdataobjectgetpreferredformat}
|
1999-01-29 19:15:17 -05:00
|
|
|
|
1999-11-01 20:25:43 -05:00
|
|
|
\constfunc{virtual wxDataFormat}{GetPreferredFormat}{\param{Direction}{ dir = Get}}
|
1999-01-29 19:15:17 -05:00
|
|
|
|
1999-11-02 05:02:01 -05:00
|
|
|
Returns the preferred format for either rendering the data (if {\it dir} is {\tt Get},
|
|
|
|
its default value) or for setting it. Usually this will be the
|
1999-11-01 20:25:43 -05:00
|
|
|
native format of the wxDataObject.
|
1999-01-29 19:15:17 -05:00
|
|
|
|
1999-11-01 13:20:39 -05:00
|
|
|
\membersection{wxDataObject::SetData}\label{wxdataobjectsetdata}
|
1999-01-29 19:15:17 -05:00
|
|
|
|
1999-11-02 05:02:01 -05:00
|
|
|
\func{virtual bool}{SetData}{ \param{const wxDataFormat\&}{ format}, \param{size\_t}{ len}, \param{const void }{*buf} }
|
1999-11-01 20:25:43 -05:00
|
|
|
|
|
|
|
Set the data in the format {\it format} of the length {\it len} provided in the
|
|
|
|
buffer {\it buf}.
|
1999-01-13 09:23:31 -05:00
|
|
|
|
2003-01-17 19:16:34 -05:00
|
|
|
Returns true on success, false on failure.
|
1999-01-13 09:23:31 -05:00
|
|
|
|