1. wxMenu changes: wxMenuBase appears, several new functions for dynamic menu
handling as well 2. new sample: menu 3. small corrections to wxFileHistory made possible by wxMenu changes 4. ugly fix for panel loaded from resources and TABbing 5. wxDataObject &c doc updates git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4288 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
@@ -1,38 +1,118 @@
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
%% Name: dataobj.tex
|
||||
%% Purpose: wxDataObject documentation
|
||||
%% Author: Vadim Zeitlin
|
||||
%% Modified by:
|
||||
%% Created: 18.10.99
|
||||
%% RCS-ID: $Id$
|
||||
%% Copyright: (c) wxWindows team
|
||||
%% Licence: wxWindows licence
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
|
||||
\section{\class{wxDataObject}}\label{wxdataobject}
|
||||
|
||||
A wxDataObject represents data that can be copied to or from the clipboard, or
|
||||
dragged and dropped. There are two classes directly derived from wxDataObject:
|
||||
wxDataObjectSimple and wxDataObjectComposite. As you will guess, wxDataObjectSimple
|
||||
holds data for a single format (such as HTML or text) and wxDataObjectComposite
|
||||
can hold any number of wxDataObjectSimple classes. Please note that this is an
|
||||
easy way to use Drag'n'Drop and the clipboard with multiple formats, but not the
|
||||
most efficient one as each wxDataObjectSimple would contain the whole data in its
|
||||
respective formars. Now imagine that you want to paste 200 pages of text in 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.
|
||||
dragged and dropped. The important thing about wxDataObject is that this is a
|
||||
"smart" piece of data unlike usual "dumb" data containers such as memory
|
||||
buffers or files. Being "smart" here means that the data object itself should
|
||||
know what data formats it supports and how to render itself in each of
|
||||
supported formats.
|
||||
|
||||
Note that neither the GTK data transfer mechanisms for the clipboard and Drag'n'Drop
|
||||
nor the OLE data transfer copies any data until another application actually
|
||||
requests the data. This is in contrast to the "feel" offered to the user of a
|
||||
program who would normally think that the data resides in the clipboard after
|
||||
having pressed "Copy" - in reality it is only declared to be available.
|
||||
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
|
||||
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
|
||||
created from data on this format or vice versa. wxDataObject defines an
|
||||
enumeration type
|
||||
|
||||
There are several predefined data object classes derived from wxDataObjectSimple:
|
||||
\helpref{wxFileDataObject}{wxfiledataobject}, \helpref{wxTextDataObject}{wxtextdataobject}
|
||||
and \helpref{wxBitmapDataObject}{wxbitmapdataobject} which can be used without change.
|
||||
\begin{verbatim}
|
||||
enum Direction
|
||||
{
|
||||
Get = 0x01, // format is supported by GetDataHere()
|
||||
Set = 0x02 // format is supported by SetData()
|
||||
};
|
||||
\end{verbatim}
|
||||
|
||||
You may also derive your own data object classes from \helpref{wxCustomDataObject}{wxprivatedataobject}
|
||||
for user-defined types. The format of user-defined data is given as mime-type string literal,
|
||||
such as "application/word" or "image/png". These strings are used as they are under Unix (so
|
||||
far only GTK) to identify a format and are translated into their Windows equivalent under
|
||||
Win32 (using the OLE IDataObject for data exchange to and from the clipboard and for Drag'n'Drop).
|
||||
Note that the format string translation under Windows is not yet finnished.
|
||||
which allows to distinguish between them. See
|
||||
\helpref{wxDataFormat}{wxdataformat} documentation for more about formats.
|
||||
|
||||
Not surprizingly, being "smart" comes at a price of added complexity. This is
|
||||
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.
|
||||
|
||||
To provide a solution for both cases, wxWindows has two predefined classes
|
||||
which derive from wxDataObject:
|
||||
\helpref{wxDataObjectSimple}{wxdataobjectsimple} and
|
||||
\helpref{wxDataObjectComposite}{wxdataobjectcomposite}.
|
||||
\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
|
||||
the simplest way to implement wxDataObject which does support multiple formats
|
||||
because it achievs this by simply holding several wxDataObjectSimple objects.
|
||||
|
||||
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):
|
||||
|
||||
\begin{twocollist}
|
||||
\twocolitem{0. Use one of built-in classes}{You may use wxTextDataObject,
|
||||
wxBitmapDataObject or wxFileDataObject in the simplest cases when you only need
|
||||
to support one format and your data is either text, bitmap or list of files}
|
||||
\twocolitem{1. Derive your class from wxDataObjectSimple}{This is the simplest
|
||||
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).}
|
||||
\twocolitem{2. Use wxDataObjectComposite}{This is a quite simple, but rather
|
||||
powerful solution which allows you to support any number of formats (either
|
||||
standard or custom if you combine it with the previous solution).}
|
||||
\twocolitem{3. Derive from wxDataObject directly}{This is the solution of
|
||||
maximal flexibility and efficiency, but it also is the most difficult to
|
||||
implement.}
|
||||
\end{twocollist}
|
||||
|
||||
Please note that the easiest way to use Drag'n'Drop and the clipboard with
|
||||
multiple formats is by using wxDataObjectComposite, but it is not the most
|
||||
efficient one as each wxDataObjectSimple would contain the whole data in its
|
||||
respective formars. Now imagine that you want to paste 200 pages of text in
|
||||
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.
|
||||
|
||||
Note that neither the GTK data transfer mechanisms for the clipboard and
|
||||
Drag'n'Drop nor the OLE data transfer copies any data until another application
|
||||
actually requests the data. This is in contrast to the "feel" offered to the
|
||||
user of a program who would normally think that the data resides in the
|
||||
clipboard after having pressed "Copy" - in reality it is only declared to be
|
||||
available.
|
||||
|
||||
There are several predefined data object classes derived from
|
||||
wxDataObjectSimple: \helpref{wxFileDataObject}{wxfiledataobject},
|
||||
\helpref{wxTextDataObject}{wxtextdataobject} and
|
||||
\helpref{wxBitmapDataObject}{wxbitmapdataobject} which can be used without
|
||||
change.
|
||||
|
||||
You may also derive your own data object classes from
|
||||
\helpref{wxCustomDataObject}{wxprivatedataobject} for user-defined types. The
|
||||
format of user-defined data is given as mime-type string literal, such as
|
||||
"application/word" or "image/png". These strings are used as they are under
|
||||
Unix (so far only GTK) to identify a format and are translated into their
|
||||
Windows equivalent under Win32 (using the OLE IDataObject for data exchange to
|
||||
and from the clipboard and for Drag'n'Drop). Note that the format string
|
||||
translation under Windows is not yet finnished.
|
||||
|
||||
\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
|
||||
only one direction), should return 0 from
|
||||
\helpref{GetFormatCount}{wxdataobjectgetformatcount}.
|
||||
|
||||
\wxheading{Derived from}
|
||||
|
||||
\helpref{wxObject}{wxobject}
|
||||
None
|
||||
|
||||
\wxheading{Include files}
|
||||
|
||||
@@ -40,13 +120,16 @@ Note that the format string translation under Windows is not yet finnished.
|
||||
|
||||
\wxheading{See also}
|
||||
|
||||
\helpref{Clipboard and drag and drop overview}{wxclipboardonfigoverview},
|
||||
\helpref{DnD sample}{samplednd},
|
||||
\helpref{wxFileDataObject}{wxfiledataobject},
|
||||
\helpref{wxTextDataObject}{wxtextdataobject},
|
||||
\helpref{wxBitmapDataObject}{wxbitmapdataobject},
|
||||
\helpref{wxPrivateDataObject}{wxprivatedataobject},
|
||||
\helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDropTarget}{wxdroptarget},
|
||||
\helpref{wxDropTarget}{wxdroptarget},
|
||||
\helpref{wxDropSource}{wxdropsource},
|
||||
\helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget}
|
||||
\helpref{wxTextDropTarget}{wxtextdroptarget},
|
||||
\helpref{wxFileDropTarget}{wxfiledroptarget}
|
||||
|
||||
\latexignore{\rtfignore{\wxheading{Members}}}
|
||||
|
||||
@@ -62,17 +145,21 @@ Constructor.
|
||||
|
||||
Destructor.
|
||||
|
||||
\membersection{wxDataObject::GetFormatCount}\label{wxdataobjectgetformatcount}
|
||||
\membersection{wxDataObject::GetAllFormats}\label{wxdataobjectgetallformats}
|
||||
|
||||
\constfunc{virtual size_t}{GetFormatCount}{\void}
|
||||
\constfunc{virtual void}{GetAllFormats}{
|
||||
\param{wxDataFormat *}{formats},
|
||||
\param{Direction}{ dir = Get}}
|
||||
|
||||
Return the number of available formats.
|
||||
Copy all supported formats in the given direction to the array pointed to by
|
||||
{\it formats} (there is enough place for GetFormatCount(dir) formats in it).
|
||||
|
||||
\membersection{wxDataObject::GetDataHere}\label{wxdataobjectgetdatahere}
|
||||
|
||||
\constfunc{virtual bool}{GetDataHere}{\param{const wxDataFormat\&}{ format}, \param{void}{*buf} }
|
||||
\constfunc{virtual bool}{GetDataHere}{\param{const wxDataFormat\&}{ format}, \param{void }{*buf} }
|
||||
|
||||
The method will write the data of the format {\it format} in the buffer {\it buf}.
|
||||
The method will write the data of the format {\it format} in the buffer {\it
|
||||
buf} and return TRUE on success, FALSE on failure.
|
||||
|
||||
\membersection{wxDataObject::GetDataSize}\label{wxdataobjectgetdatasize}
|
||||
|
||||
@@ -80,16 +167,30 @@ The method will write the data of the format {\it format} in the buffer {\it buf
|
||||
|
||||
Returns the data size of the given format {\it format}.
|
||||
|
||||
\membersection{wxDataObject::GetFormatCount}\label{wxdataobjectgetformatcount}
|
||||
|
||||
\constfunc{virtual size\_t}{GetFormatCount}{\param{Direction}{ dir = Get}}
|
||||
|
||||
Return the number of available formats for rendering or setting the data.
|
||||
|
||||
\membersection{wxDataObject::GetPreferredFormat}\label{wxdataobjectgetpreferredformat}
|
||||
|
||||
\constfunc{virtual wxDataFormat}{GetPreferredFormat}{\void}
|
||||
\constfunc{virtual wxDataFormat}{GetPreferredFormat}{\param{Direction}{ dir = Get}}
|
||||
|
||||
Returns the preferred format. Usually the first format in the list of available formats.
|
||||
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
|
||||
native format of the wxDataObject.
|
||||
|
||||
\membersection{wxDataObject::SetData}\label{wxdataobjectsetdata}
|
||||
|
||||
\func{virtual bool}{SetData}{\param{const wxDataFormat\&}{ format}, \param{size_t}{ len}, \param{const void}{*buf} }
|
||||
\func{virtual bool}{SetData}{
|
||||
\param{const wxDataFormat\&}{ format},
|
||||
\param{size\_t}{ len},
|
||||
\param{const void }{*buf} }
|
||||
|
||||
Set the data of the format {\it format} and the size {\it len} provided in the buffer {\it buf}.
|
||||
Set the data in the format {\it format} of the length {\it len} provided in the
|
||||
buffer {\it buf}.
|
||||
|
||||
Returns TRUE on sucess, FALSE on failure.
|
||||
|
||||
|
||||
|
Reference in New Issue
Block a user