X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/954b8ae60391d18b87a604e7919c87c0c6ae208b..a663cce7f9ca84a82f1f7359ce1dcd898040a4c1:/docs/latex/wx/dataobj.tex diff --git a/docs/latex/wx/dataobj.tex b/docs/latex/wx/dataobj.tex index bec42f8c47..066447ba1b 100644 --- a/docs/latex/wx/dataobj.tex +++ b/docs/latex/wx/dataobj.tex @@ -1,47 +1,124 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: dataobj.tex +%% Purpose: wxDataObject documentation +%% Author: Vadim Zeitlin +%% Modified by: +%% Created: 18.10.99 +%% RCS-ID: $Id$ +%% Copyright: (c) wxWindows team +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \section{\class{wxDataObject}}\label{wxdataobject} A wxDataObject represents data that can be copied to or from the clipboard, or -dragged and dropped. - -There are several predefined data object classes, such as \helpref{wxFileDataObject}{wxfiledataobject}, -\helpref{wxTextDataObject}{wxtextdataobject}, and \helpref{wxBitmapDataObject}{wxbitmapdataobject} which -can be used without change or can be altered (by deriving a new class from them) in order to deliver -data and data size on-demand. There is no need to ever use wxDataObject itself or derive directly from it. - -You may also derive your own data object classes from \helpref{wxPrivateDataObject}{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. - -As mentioned above, data may be placed into the \helpref{wxClipboard}{wxclipboard} -or a \helpref{wxDropSource}{wxdropsource} instance either directly or on-demand. -As long as only one format is offerred, putting data directly into the clipboard may -be sufficient. But imagine that you paste a large piece of text to the clipboard and -offer it in "text/plain", "text/rtf", "text/html", "application/word" and your own -format for internal use - here offering data on-demand is required to minimize memory -consumption. This would generally get implemented using a central object that -contains clipboard information in the format with the maximum of information. 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. - -Let's assume that you have written an HTML editor and want it to paste contents -in the formats "text/plain" and "text/html" to the clipboard. For offering -data on-demand in "text/plain" you would derive your class from \helpref{wxTextDataObject}{wxtextdataobject} -and for offering data on-demand in "text/html" you would derive your own class from -\helpref{wxPrivateDataObject}{wxprivatedataobject} and set its ID string -identifying the format to "text/html" using \helpref{wxPrivateDataObject::SetId}{wxprivatedataobjectsetid}. -In your two derived classed you'd then have a pointer or reference to the central -data container and you'd override the methods returning the size of the -available data and the WriteData() methods in both classes. +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. + +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 + +\begin{verbatim} +enum Direction +{ + Get = 0x01, // format is supported by GetDataHere() + Set = 0x02 // format is supported by SetData() +}; +\end{verbatim} + +which allows to distinguish between them. See +\helpref{wxDataFormat}{wxdataformat} documentation for more about formats. + +Not surprisingly, 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}\itemsep=1cm +\twocolitem{{\bf 1. Use one of the 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{{\bf 2. Use wxDataObjectSimple}}{Deriving from wxDataObjectSimple 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{{\bf 3. Use wxDataObjectComposite}}{This is a simple but powerful +solution which allows you to support any number of formats (either +standard or custom if you combine it with the previous solution).} +\twocolitem{{\bf 4. Use wxDataObject directly}}{This is the solution for +maximal flexibility and efficiency, but it is also is the most difficult to +implement.} +\end{twocollist} + +Please note that the easiest way to use drag and 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 formats. 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 and drop, nor the OLE data transfer copy 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}{wxcustomdataobject} 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 and drop). Note that the format string +translation under Windows is not yet finished. + +\pythonnote{At this time this class is not directly usable from wxPython. +Derive a class from \helpref{wxPyDataObjectSimple}{wxdataobjectsimple} +instead.} + +\perlnote{This class is not currently usable from wxPerl; you may +use \helpref{Wx::PlDataObjectSimple}{wxdataobjectsimple} instead.} + +\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} @@ -49,13 +126,16 @@ available data and the WriteData() methods in both classes. \wxheading{See also} +\helpref{Clipboard and drag and drop overview}{wxdndoverview}, +\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{wxCustomDataObject}{wxcustomdataobject}, +\helpref{wxDropTarget}{wxdroptarget}, \helpref{wxDropSource}{wxdropsource}, -\helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget} +\helpref{wxTextDropTarget}{wxtextdroptarget}, +\helpref{wxFileDropTarget}{wxfiledroptarget} \latexignore{\rtfignore{\wxheading{Members}}} @@ -71,18 +151,50 @@ Constructor. Destructor. -\membersection{wxDataObject::WriteData}\label{wxdataobjectwritedata} +\membersection{wxDataObject::GetAllFormats}\label{wxdataobjectgetallformats} + +\constfunc{virtual void}{GetAllFormats}{ \param{wxDataFormat *}{formats}, \param{Direction}{ dir = Get}} + +Copy all supported formats in the given direction to the array pointed to by +{\it formats}. There is enough space for GetFormatCount(dir) formats in it. + +\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.} + +\membersection{wxDataObject::GetDataHere}\label{wxdataobjectgetdatahere} + +\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} and return true on success, false on failure. + +\membersection{wxDataObject::GetDataSize}\label{wxdataobjectgetdatasize} + +\constfunc{virtual size\_t}{GetDataSize}{\param{const wxDataFormat\&}{ format} } + +Returns the data size of the given format {\it format}. + +\membersection{wxDataObject::GetFormatCount}\label{wxdataobjectgetformatcount} + +\constfunc{virtual size\_t}{GetFormatCount}{\param{Direction}{ dir = Get}} + +Returns the number of available formats for rendering or setting the data. + +\membersection{wxDataObject::GetPreferredFormat}\label{wxdataobjectgetpreferredformat} -\constfunc{virtual void}{WriteData}{\param{void}{*dest} } +\constfunc{virtual wxDataFormat}{GetPreferredFormat}{\param{Direction}{ dir = Get}} -Write the data owned by this class to {\it dest}. This method is a pure -virtual function and must be overridden. +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::GetSize}\label{wxdataobjectgetdatasize} +\membersection{wxDataObject::SetData}\label{wxdataobjectsetdata} -\constfunc{virtual size\_t}{GetSize}{\void} +\func{virtual bool}{SetData}{ \param{const wxDataFormat\&}{ format}, \param{size\_t}{ len}, \param{const void }{*buf} } -Returns the data size. This method is a pure -virtual function and must be overridden. +Set the data in the format {\it format} of the length {\it len} provided in the +buffer {\it buf}. +Returns true on success, false on failure.