projects / wxWidgets.git / blame
| Commit | Line | Data |
|---|---|---|
| c03648c2 VZ |
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$ | |
| 8 | %% Copyright: (c) Vadim Zeitlin | |
| 9 | %% Licence: wxWindows licence | |
| 10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 11 | ||
| 12 | \section{\class{wxDataFormat}}\label{wxdataformat} | |
| 13 | ||
| 14 | A wxDataFormat is an encapsulation of a platform-specific format handle which | |
| 15 | is used by the system for the clipboard and drag and drop operations. The | |
| 16 | applications are usually only interested in, for example, pasting data from the | |
| 17 | clipboard only if the data is in a format the program understands and a data | |
| 18 | format is something which uniquely identifies this format. | |
| 19 | ||
| 20 | On the system level, a data format is usually just a number ({\tt CLIPFORMAT} | |
| 21 | under Windows or {\tt Atom} under X11, for example) and the standard formats | |
| 22 | are, indeed, just numbers which can be implicitly converted to wxDataFormat. | |
| 23 | The standard formats are: | |
| 24 | ||
| 25 | \begin{twocollist}\itemsep=1cm | |
| 26 | \twocolitem{wxDF\_INVALID}{An invalid format - used as default argument for | |
| 27 | functions 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 | \end{twocollist} | |
| 33 | ||
| 34 | As mentioned above, these standard formats may be passed to any function taking | |
| 35 | wxDataFormat argument because wxDataFormat has an implicit conversion from | |
| 36 | them (or, to be precise from the type {\tt wxDataFormat::NativeFormat} which is | |
| 37 | the type used by the underlying platform for data formats). | |
| 38 | ||
| 39 | Aside the standard formats, the application may also use custom formats which | |
| 40 | are identified by their names (strings) and not numeric identifiers. Although | |
| 41 | internally custom format must be created (or {\it registered}) first, you | |
| 42 | shouldn't care about it because it is done automatically the first time the | |
| 43 | wxDataFormat object corresponding to a given format name is created. The only | |
| 44 | implication of this is that you should avoid having global wxDataFormat objects | |
| 45 | with non-default constructor because their constructors are executed before the | |
| 46 | program has time to perform all necessary initialisations and so an attempt to | |
| 47 | do clipboard format registration at this time will usually lead to a crash! | |
| 48 | ||
| 49 | \wxheading{Virtual functions to override} | |
| 50 | ||
| 51 | None, this class doesn't have any. | |
| 52 | ||
| 53 | \wxheading{Derived from} | |
| 54 | ||
| 55 | None | |
| 56 | ||
| 57 | \wxheading{See also} | |
| 58 | ||
| 59 | \helpref{Clipboard and drag and drop overview}{wxdndoverview}, | |
| 60 | \helpref{DnD sample}{samplednd}, | |
| 61 | \helpref{wxDataObject}{wxdataobject} | |
| 62 | ||
| 63 | \latexignore{\rtfignore{\wxheading{Members}}} | |
| 64 | ||
| 65 | \membersection{wxDataFormat::wxDataFormat}\label{wxdataformatwxdataformatdef} | |
| 66 | ||
| 67 | \func{}{wxDataFormat}{\param{NativeFormat}{ format = wxDF\_INVALID}} | |
| 68 | ||
| 69 | Constructs a data format object for one of the standard data formats or an | |
| 70 | empty data object (use \helpref{SetType}{wxdataformatsettype} or | |
| 71 | \helpref{SetId}{wxdataformatsetid} later in this case) | |
| 72 | ||
| 73 | \membersection{wxDataFormat::wxDataFormat}\label{wxdataformatwxdataformat} | |
| 74 | ||
| 75 | \func{}{wxDataFormat}{\param{const wxChar }{*format}} | |
| 76 | ||
| 77 | Constructs a data format object for a custom format identified by its name | |
| 78 | {\it format}. | |
| 79 | ||
| 80 | \membersection{wxDataFormat::operator $==$}\label{wxdataformatoperatoreq} | |
| 81 | ||
| 82 | \constfunc{bool}{operator $==$}{\param{const wxDataFormat\&}{ format}} | |
| 83 | ||
| 84 | Returns TRUE if the formats are equal. | |
| 85 | ||
| 86 | \membersection{wxDataFormat::operator $!=$}\label{wxdataformatoperatorneq} | |
| 87 | ||
| 88 | \constfunc{bool}{operator $!=$}{\param{const wxDataFormat\&}{ format}} | |
| 89 | ||
| 90 | Returns TRUE if the formats are different. | |
| 91 | ||
| 92 | \membersection{wxDataFormat::GetId}\label{wxdataformatgetid} | |
| 93 | ||
| 94 | \constfunc{wxString}{GetId}{\void} | |
| 95 | ||
| 96 | Returns the name of a custom format (this function will fail for a standard | |
| 97 | format). | |
| 98 | ||
| 99 | \membersection{wxDataFormat::GetType}\label{wxdataformatgettype} | |
| 100 | ||
| 101 | \constfunc{NativeFormat}{GetType}{\void} | |
| 102 | ||
| 103 | Returns the platform-specific number identifying the format. | |
| 104 | ||
| 105 | \membersection{wxDataFormat::SetId}\label{wxdataformatsetid} | |
| 106 | ||
| 107 | \func{void}{SetId}{\param{const wxChar }{*format}} | |
| 108 | ||
| 109 | Sets the format to be the custom format identified by the given name. | |
| 110 | ||
| 111 | \membersection{wxDataFormat::SetType}\label{wxdataformatsettype} | |
| 112 | ||
| 113 | \func{void}{SetType}{\param{NativeFormat}{ format}} | |
| 114 | ||
| 115 | Sets the format to the given value which should be one of wxDF\_XXX constants. |