1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: dataform.tex 3%% Purpose: wxDataFormat documentation 4%% Author: Vadim Zeitlin 5%% Modified by: 6%% Created: 03.11.99 7%% RCS-ID: $Id: dataform.tex 32309 2005-02-22 15:09:56Z ABX $ 8%% Copyright: (c) Vadim Zeitlin 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxDataFormat}}\label{wxdataformat} 13 14A wxDataFormat is an encapsulation of a platform-specific format handle which 15is used by the system for the clipboard and drag and drop operations. The 16applications are usually only interested in, for example, pasting data from the 17clipboard only if the data is in a format the program understands and a data 18format is something which uniquely identifies this format. 19 20On the system level, a data format is usually just a number ({\tt CLIPFORMAT} 21under Windows or {\tt Atom} under X11, for example) and the standard formats 22are, indeed, just numbers which can be implicitly converted to wxDataFormat. 23The standard formats are: 24 25\begin{twocollist}\itemsep=1cm 26\twocolitem{wxDF\_INVALID}{An invalid format - used as default argument for 27functions taking a wxDataFormat argument sometimes} 28\twocolitem{wxDF\_TEXT}{Text format (wxString)} 29\twocolitem{wxDF\_BITMAP}{A bitmap (wxBitmap)} 30\twocolitem{wxDF\_METAFILE}{A metafile (wxMetafile, Windows only)} 31\twocolitem{wxDF\_FILENAME}{A list of filenames} 32\twocolitem{wxDF\_HTML}{An HTML string. This is only valid when passed to wxSetClipboardData 33when compiled with Visual C++ in non-Unicode mode} 34\end{twocollist} 35 36As mentioned above, these standard formats may be passed to any function taking 37wxDataFormat argument because wxDataFormat has an implicit conversion from 38them (or, to be precise from the type {\tt wxDataFormat::NativeFormat} which is 39the type used by the underlying platform for data formats). 40 41Aside the standard formats, the application may also use custom formats which 42are identified by their names (strings) and not numeric identifiers. Although 43internally custom format must be created (or {\it registered}) first, you 44shouldn't care about it because it is done automatically the first time the 45wxDataFormat object corresponding to a given format name is created. The only 46implication of this is that you should avoid having global wxDataFormat objects 47with non-default constructor because their constructors are executed before the 48program has time to perform all necessary initialisations and so an attempt to 49do clipboard format registration at this time will usually lead to a crash! 50 51\wxheading{Virtual functions to override} 52 53None 54 55\wxheading{Derived from} 56 57None 58 59\wxheading{See also} 60 61\helpref{Clipboard and drag and drop overview}{wxdndoverview}, 62\helpref{DnD sample}{samplednd}, 63\helpref{wxDataObject}{wxdataobject} 64 65\wxheading{Include files} 66 67<wx/dataobj.h> 68 69\latexignore{\rtfignore{\wxheading{Members}}} 70 71\membersection{wxDataFormat::wxDataFormat}\label{wxdataformatwxdataformatdef} 72 73\func{}{wxDataFormat}{\param{NativeFormat}{ format = wxDF\_INVALID}} 74 75Constructs a data format object for one of the standard data formats or an 76empty data object (use \helpref{SetType}{wxdataformatsettype} or 77\helpref{SetId}{wxdataformatsetid} later in this case) 78 79\perlnote{In wxPerl this function is named {\tt newNative}.} 80 81\membersection{wxDataFormat::wxDataFormat}\label{wxdataformatwxdataformat} 82 83\func{}{wxDataFormat}{\param{const wxChar }{*format}} 84 85Constructs a data format object for a custom format identified by its name 86{\it format}. 87 88\perlnote{In wxPerl this function is named {\tt newUser}.} 89 90\membersection{wxDataFormat::operator $==$}\label{wxdataformatoperatoreq} 91 92\constfunc{bool}{operator $==$}{\param{const wxDataFormat\&}{ format}} 93 94Returns true if the formats are equal. 95 96\membersection{wxDataFormat::operator $!=$}\label{wxdataformatoperatorneq} 97 98\constfunc{bool}{operator $!=$}{\param{const wxDataFormat\&}{ format}} 99 100Returns true if the formats are different. 101 102\membersection{wxDataFormat::GetId}\label{wxdataformatgetid} 103 104\constfunc{wxString}{GetId}{\void} 105 106Returns the name of a custom format (this function will fail for a standard 107format). 108 109\membersection{wxDataFormat::GetType}\label{wxdataformatgettype} 110 111\constfunc{NativeFormat}{GetType}{\void} 112 113Returns the platform-specific number identifying the format. 114 115\membersection{wxDataFormat::SetId}\label{wxdataformatsetid} 116 117\func{void}{SetId}{\param{const wxChar }{*format}} 118 119Sets the format to be the custom format identified by the given name. 120 121\membersection{wxDataFormat::SetType}\label{wxdataformatsettype} 122 123\func{void}{SetType}{\param{NativeFormat}{ format}} 124 125Sets the format to the given value, which should be one of wxDF\_XXX constants. 126 127