docs/latex/wx/dataobj.tex

   1 \section{\class{wxDataObject}}\label{wxdataobject}
   2
   3 A wxDataObject represents data that can be copied to or from the clipboard, or
   4 dragged and dropped.
   5
   6 There are several predefined data object classes, such as \helpref{wxFileDataObject}{wxfiledataobject},
   7 \helpref{wxTextDataObject}{wxtextdataobject}, and \helpref{wxBitmapDataObject}{wxbitmapdataobject} which
   8 can be used without change or can be altered (by deriving a new class from them) in order to deliver
   9 data and data size on-demand. There is no need to ever use wxDataObject itself or derive directly from it.
  10
  11 You may also derive your own data object classes from \helpref{wxPrivateDataObject}{wxprivatedataobject}
  12 for user-defined types. The format of user-defined data is given as mime-type string literal,
  13 such as "application/word" or "image/png". These strings are used as they are under Unix (so
  14 far only GTK) to identify a format and are translated into their Windows equivalent under
  15 Win32 (using the OLE IDataObject for data exchange to and from the clipboard and for Drag'n'Drop).
  16 Note that the format string translation under Windows is not yet finnished.
  17
  18 As mentioned above, data may be placed into the \helpref{wxClipboard}{wxclipboard}
  19 or a \helpref{wxDropSource}{wxdropsource} instance either directly or on-demand.
  20 As long as only one format is offerred, putting data directly into the clipboard may
  21 be sufficient. But imagine that you paste a large piece of text to the clipboard and
  22 offer it in "text/plain", "text/rtf", "text/html", "application/word" and your own
  23 format for internal use - here offering data on-demand is required to minimize memory
  24 consumption. This would generally get implemented using a central object that
  25 contains clipboard information in the format with the maximum of information. Note
  26 that neither the GTK data transfer mechanisms for the clipboard and Drag'n'Drop
  27 nor the OLE data transfer copies any data until another application actually
  28 requests the data. This is in contrast to the "feel" offered to the user of a
  29 program who would normally think that the data resides in the clipboard after
  30 having pressed "Copy" - in reality it is only declared to be available.
  31
  32 Let's assume that you have written an HTML editor and want it to paste contents
  33 in the formats "text/plain" and "text/html" to the clipboard. For offering
  34 data on-demand in "text/plain" you would derive your class from \helpref{wxTextDataObject}{wxtextdataobject}
  35 and for offering data on-demand in "text/html" you would derive your own class from
  36 \helpref{wxPrivateDataObject}{wxprivatedataobject} and set its ID string
  37 identifying the format to "text/html" using \helpref{wxPrivateDataObject::SetId}{wxprivatedataobjectsetid}.
  38 In your two derived classed you'd then have a pointer or reference to the central
  39 data container and you'd override the methods returning the size of the
  40 available data and the WriteData() methods in both classes.
  41
  42 \wxheading{Derived from}
  43
  44 \helpref{wxObject}{wxobject}
  45
  46 \wxheading{Include files}
  47
  48 <wx/dataobj.h>
  49
  50 \wxheading{See also}
  51
  52 \helpref{wxFileDataObject}{wxfiledataobject},
  53 \helpref{wxTextDataObject}{wxtextdataobject},
  54 \helpref{wxBitmapDataObject}{wxbitmapdataobject},
  55 \helpref{wxPrivateDataObject}{wxprivatedataobject},
  56 \helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDropTarget}{wxdroptarget},
  57 \helpref{wxDropSource}{wxdropsource},
  58 \helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget}
  59
  60 \latexignore{\rtfignore{\wxheading{Members}}}
  61
  62 \membersection{wxDataObject::wxDataObject}\label{wxdataobjectwxdataobject}
  63
  64 \func{}{wxDataObject}{\void}
  65
  66 Constructor.
  67
  68 \membersection{wxDataObject::\destruct{wxDataObject}}\label{wxdataobjectdtor}
  69
  70 \func{}{\destruct{wxDataObject}}{\void}
  71
  72 Destructor.
  73
  74 \membersection{wxDataObject::WriteData}\label{wxdataobjectwritedata}
  75
  76 \constfunc{virtual void}{WriteData}{\param{void}{*dest} }
  77
  78 Write the data owned by this class to {\it dest}. This method is a pure
  79 virtual function and must be overridden.
  80
  81 \membersection{wxDataObject::GetSize}\label{wxdataobjectgetdatasize}
  82
  83 \constfunc{virtual size\_t}{GetSize}{\void}
  84
  85 Returns the data size. This method is a pure
  86 virtual function and must be overridden.
  87
  88