-
-/**
- @class wxDataFormat
-
- A wxDataFormat is an encapsulation of a platform-specific format handle
- which is used by the system for the clipboard and drag and drop operations.
- The applications are usually only interested in, for example, pasting data
- from the clipboard only if the data is in a format the program understands
- and a data format is something which uniquely identifies this format.
-
- On the system level, a data format is usually just a number (@c CLIPFORMAT
- under Windows or @c Atom under X11, for example) and the standard formats
- are, indeed, just numbers which can be implicitly converted to wxDataFormat.
- The standard formats are:
-
- @beginDefList
- @itemdef{wxDF_INVALID,
- An invalid format - used as default argument for functions taking
- a wxDataFormat argument sometimes.}
- @itemdef{wxDF_TEXT,
- Text format (wxString).}
- @itemdef{wxDF_BITMAP,
- A bitmap (wxBitmap).}
- @itemdef{wxDF_METAFILE,
- A metafile (wxMetafile, Windows only).}
- @itemdef{wxDF_FILENAME,
- A list of filenames.}
- @itemdef{wxDF_HTML,
- An HTML string. This is only valid when passed to
- wxSetClipboardData when compiled with Visual C++ in non-Unicode
- mode.}
- @endDefList
-
- As mentioned above, these standard formats may be passed to any function
- taking wxDataFormat argument because wxDataFormat has an implicit
- conversion from them (or, to be precise from the type
- @c wxDataFormat::NativeFormat which is the type used by the underlying
- platform for data formats).
-
- Aside the standard formats, the application may also use custom formats
- which are identified by their names (strings) and not numeric identifiers.
- Although internally custom format must be created (or @e registered) first,
- you shouldn't care about it because it is done automatically the first time
- the wxDataFormat object corresponding to a given format name is created.
- The only implication of this is that you should avoid having global
- wxDataFormat objects with non-default constructor because their
- constructors are executed before the program has time to perform all
- necessary initialisations and so an attempt to do clipboard format
- registration at this time will usually lead to a crash!
-
- @library{wxbase}
- @category{dnd}
-
- @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject
-*/
-class wxDataFormat
-{
-public:
- /**
- Constructs a data format object for one of the standard data formats or
- an empty data object (use SetType() or SetId() later in this case).
- */
- wxDataFormat(wxDataFormatId format = wxDF_INVALID);
-
- /**
- Constructs a data format object for a custom format identified by its
- name @a format.
- */
- wxDataFormat(const wxString& format);
-
- /**
- Returns the name of a custom format (this function will fail for a
- standard format).
- */
- wxString GetId() const;
-
- /**
- Returns the platform-specific number identifying the format.
- */
- wxDataFormatId GetType() const;
-
- /**
- Sets the format to be the custom format identified by the given name.
- */
- void SetId(const wxString& format);
-
- /**
- Sets the format to the given value, which should be one of wxDF_XXX
- constants.
- */
- void SetType(wxDataFormatId type);
-
- /**
- Returns @true if the formats are different.
- */
- bool operator !=(wxDataFormatId format) const;
-
- /**
- Returns @true if the formats are equal.
- */
- bool operator ==(wxDataFormatId format) const;
-};
-
-
-
-/**
- @class wxDataObject
-
- A wxDataObject represents data that can be copied to or from the clipboard,
- or dragged and dropped. The important thing about wxDataObject is that this
- is a 'smart' piece of data unlike '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 its 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 which distinguishes between them:
-
- @code
- enum Direction
- {
- Get = 0x01, // format is supported by GetDataHere()
- Set = 0x02 // format is supported by SetData()
- };
- @endcode
-
- See 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, wxWidgets has two predefined classes
- which derive from wxDataObject: wxDataObjectSimple and
- wxDataObjectComposite. wxDataObjectSimple is the simplest wxDataObject
- possible and only holds data in a single format (such as HTML or text) and
- wxDataObjectComposite is the simplest way to implement a wxDataObject that
- does support multiple formats because it achieves 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):
-
- -# 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.
- -# 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).
- -# 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).
- -# Use wxDataObject Directly
- - This is the solution for maximal flexibility and efficiency, but it
- is also the most difficult to implement.
-
- 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 clipboard and drag
- and drop, nor 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: wxFileDataObject, wxTextDataObject, wxBitmapDataObject
- and wxURLDataObject which can be used without change.
-
- You may also derive your own data object classes from wxCustomDataObject
- for user-defined types. The format of user-defined data is given as a
- 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.
-
- 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 GetFormatCount().
-
- @beginWxPythonOnly
- At this time this class is not directly usable from wxPython. Derive a
- class from wxPyDataObjectSimple() instead.
- @endWxPythonOnly
-
- @beginWxPerlOnly
- This class is not currently usable from wxPerl; you may use
- Wx::PlDataObjectSimple instead.
- @endWxPerlOnly
-
- @library{wxcore}
- @category{dnd}
-
- @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
- wxTextDataObject, wxBitmapDataObject, wxCustomDataObject,
- wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget
-*/
-class wxDataObject
-{
-public:
- /**
- Constructor.
- */
- wxDataObject();
-
- /**
- Destructor.
- */
- virtual ~wxDataObject();
-
- /**
- Copy all supported formats in the given direction to the array pointed
- to by @a formats. There is enough space for GetFormatCount(dir) formats
- in it.
- */
- virtual void GetAllFormats(wxDataFormat* formats,
- Direction dir = Get) const = 0;
-
- /**
- The method will write the data of the format @a format in the buffer
- @a buf and return @true on success, @false on failure.
- */
- virtual bool GetDataHere(const wxDataFormat& format, void* buf) const = 0;
-
- /**
- Returns the data size of the given format @a format.
- */
- virtual size_t GetDataSize(const wxDataFormat& format) const = 0;
-
- /**
- Returns the number of available formats for rendering or setting the
- data.
- */
- virtual size_t GetFormatCount(Direction dir = Get) const = 0;
-
- /**
- Returns the preferred format for either rendering the data (if @a dir
- is @c Get, its default value) or for setting it. Usually this will be
- the native format of the wxDataObject.
- */
- virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0;
-
- /**
- Set the data in the format @a format of the length @a len provided in
- the buffer @a buf.
-
- @return @true on success, @false on failure.
- */
- virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
-};
-
projects / wxWidgets.git / blobdiff