// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
+/**
+ @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 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().
+
+ @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:
+ 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.
+ */
+ 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.
+
+ @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;
+};
+
+
/**
@class wxCustomDataObject
/**
@class wxDataObjectSimple
- This is the simplest possible implementation of the wxDataObject class. The
- data object of (a class derived from) this class only supports one format,
- so the number of virtual functions to be implemented is reduced.
+ This is the simplest possible implementation of the wxDataObject class.
+ The data object of (a class derived from) this class only supports
+ <strong>one format</strong>, so the number of virtual functions to
+ be implemented is reduced.
Notice that this is still an abstract base class and cannot be used
directly, it must be derived. The objects supporting rendering the data
wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
/**
- Copy the data to the buffer, return @true on success. Must be
- implemented in the derived class if the object supports rendering its
- data.
+ Copy the data to the buffer, return @true on success.
+ Must be implemented in the derived class if the object supports rendering
+ its data.
@beginWxPythonOnly
When implementing this method in wxPython, no additional parameters are
virtual size_t GetDataSize() const;
/**
- Returns the (one and only one) format supported by this object. It is
- assumed that the format is supported in both directions.
+ Returns the (one and only one) format supported by this object.
+ It is assumed that the format is supported in both directions.
*/
const wxDataFormat& GetFormat() const;
/**
- Copy the data from the buffer, return @true on success. Must be
- implemented in the derived class if the object supports setting its
- data.
+ Copy the data from the buffer, return @true on success.
+ Must be implemented in the derived class if the object supports setting
+ its data.
@beginWxPythonOnly
When implementing this method in wxPython, the data comes as a single
/**
@class wxTextDataObject
- wxTextDataObject is a specialization of wxDataObject for text data. It can
- be used without change to paste data into the wxClipboard or a
+ wxTextDataObject is a specialization of wxDataObjectSimple for text data.
+ It can be used without change to paste data into the wxClipboard or a
wxDropSource. A user may wish to derive a new class from this class for
providing text on-demand in order to minimize memory consumption when
offering data in several formats, such as plain text and RTF because by
length plus 1 for a trailing zero, but this is not strictly required.
*/
virtual size_t GetTextLength() const;
+
+ /**
+ Returns 2 under wxMac and wxGTK, where text data coming from the
+ clipboard may be provided as ANSI (@c wxDF_TEXT) or as Unicode text
+ (@c wxDF_UNICODETEXT, but only when @c wxUSE_UNICODE==1).
+
+ Returns 1 under other platforms (e.g. wxMSW) or when building in ANSI mode
+ (@c wxUSE_UNICODE==0).
+ */
+ virtual size_t GetFormatCount(Direction dir = Get);
+
+ /**
+ Returns the preferred format supported by this object.
+
+ This is @c wxDF_TEXT or @c wxDF_UNICODETEXT depending on the platform
+ and from the build mode (i.e. from @c wxUSE_UNICODE).
+ */
+ const wxDataFormat& GetFormat() const;
+
+ /**
+ Returns all the formats supported by wxTextDataObject.
+
+ Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT,
+ under other ports returns only one of the two, depending on the build mode.
+ */
+ virtual void GetAllFormats(wxDataFormat* formats,
+ Direction dir = Get) const = 0;
/**
Sets the text associated with the data object. This method is called
};
-
-/**
- @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