+
+/**
+ @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 currently only valid on Mac and MSW.}
+ @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{wxcore}
+ @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).
+
+ @beginWxPerlOnly
+ In wxPerl use Wx::Bitmap->newNative(format).
+ @endWxPerlOnly
+ */
+ wxDataFormat(wxDataFormatId format = wxDF_INVALID);
+
+ /**
+ Constructs a data format object for a custom format identified by its
+ name @a format.
+
+ @beginWxPerlOnly
+ In wxPerl use Wx::Bitmap->newUser(format).
+ @endWxPerlOnly
+ */
+ 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 !=(const wxDataFormat& format) const;
+
+ /**
+ Returns @true if the formats are different.
+ */
+ bool operator !=(wxDataFormatId format) const;
+
+ /**
+ Returns @true if the formats are equal.
+ */
+ bool operator ==(const wxDataFormat& format) const;
+
+ /**
+ Returns @true if the formats are equal.
+ */
+ bool operator ==(wxDataFormatId format) const;
+};
+
+
+const wxDataFormat wxFormatInvalid;
+
+
+/**
+ @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 the wxDataObject::Direction enumeration type which
+ distinguishes between them.
+
+ 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 wxFileDataObject,
+ wxURLDataObject 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 instances 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 maximum 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, @e 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 @e available.
+
+ 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().
+
+ @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:
+ enum Direction
+ {
+ /** Format is supported by GetDataHere() */
+ Get = 0x01,
+
+ /** Format is supported by SetData() */
+ Set = 0x02,
+
+ /**
+ Format is supported by both GetDataHere() and SetData()
+ (unused currently)
+ */
+ Both = 0x03
+ };
+
+ /**
+ Constructor.
+ */
+ wxDataObject();
+
+ /**
+ Destructor.
+ */
+ virtual ~wxDataObject();
+
+ /**
+ Copies all formats supported in the given direction @a dir to the array
+ pointed to by @a formats.
+ There must be enough space for GetFormatCount(dir) formats in it.
+
+ @beginWxPerlOnly
+ In wxPerl this method only takes the @a dir parameter. In scalar
+ context it returns the first format in the list, in list
+ context it returns a list containing all the supported
+ formats.
+ @endWxPerlOnly
+ */
+ virtual void GetAllFormats(wxDataFormat* formats,
+ Direction dir = Get) const = 0;
+
+ /**
+ The method will write the data of the format @a format to the buffer
+ @a buf. In other words, copy the data from this object in the given
+ format to the supplied buffer. Returns @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. In other words, copy length bytes of data from the
+ buffer to this data object.
+
+ @param format
+ The format for which to set the data.
+ @param len
+ The size of data in bytes.
+ @param buf
+ Non-@NULL pointer to the data.
+ @return
+ @true on success, @false on failure.
+ */
+ virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
+
+ /**
+ Returns true if this format is supported.
+ */
+ bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
+};
+
+
projects / wxWidgets.git / blobdiff