// Purpose: interface of wx*DataObject
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+
+/**
+ @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;
+};
+
+
/**
@class wxCustomDataObject
/**
Set the data. The data object will make an internal copy.
-
- @beginWxPythonOnly
- This method expects a string in wxPython. You can pass nearly any
- object by pickling it first.
- @endWxPythonOnly
*/
virtual bool SetData(size_t size, const void* data);
/**
Like SetData(), but doesn't copy the data - instead the object takes
ownership of the pointer.
-
- @beginWxPythonOnly
- This method expects a string in wxPython. You can pass nearly any
- object by pickling it first.
- @endWxPythonOnly
*/
void TakeData(size_t size, void* data);
};
wxDataObject directly instead of wxDataObjectComposite for efficiency
reasons.
+ This example shows how a composite data object capable of storing either
+ bitmaps or file names (presumably of bitmap files) can be initialized and
+ used:
+
+ @code
+ MyDropTarget::MyDropTarget()
+ {
+ wxDataObjectComposite* dataobj = new wxDataObjectComposite();
+ dataobj->Add(new wxBitmapDataObject(), true);
+ dataobj->Add(new wxFileDataObject());
+ SetDataObject(dataobj);
+ }
+
+ wxDragResult MyDropTarget::OnData(wxCoord x, wxCoord y,
+ wxDragResult defaultDragResult)
+ {
+ wxDragResult dragResult = wxDropTarget::OnData(x, y, defaultDragResult);
+ if ( dragResult == defaultDragResult )
+ {
+ wxDataObjectComposite *
+ dataobjComp = static_cast<wxDataObjectComposite *>(GetDataObject());
+
+ wxDataFormat format = dataObjects->GetReceivedFormat();
+ wxDataObject *dataobj = dataobjComp->GetObject(format);
+ switch ( format.GetType() )
+ {
+ case wxDF_BITMAP:
+ {
+ wxBitmapDataObject *
+ dataobjBitmap = static_cast<wxBitmapDataObject *>(dataobj);
+
+ ... use dataobj->GetBitmap() ...
+ }
+ break;
+
+ case wxDF_FILENAME:
+ {
+ wxFileDataObject *
+ dataobjFile = static_cast<wxFileDataObject *>(dataobj);
+
+ ... use dataobj->GetFilenames() ...
+ }
+ break;
+
+ default:
+ wxFAIL_MSG( "unexpected data object format" );
+ }
+ }
+
+ return dragResult;
+ }
+ @endcode
+
@library{wxcore}
@category{dnd}
/**
Report the format passed to the SetData() method. This should be the
- format of the data object within the composite that recieved data from
+ format of the data object within the composite that received data from
the clipboard or the DnD operation. You can use this method to find
- out what kind of data object was recieved.
+ out what kind of data object was received.
*/
wxDataFormat GetReceivedFormat() const;
+
+ /**
+ Returns the pointer to the object which supports the passed format for
+ the specified direction.
+
+ @NULL is returned if the specified @a format is not supported for this
+ direction @a dir. The returned pointer is owned by wxDataObjectComposite
+ itself and shouldn't be deleted by caller.
+
+ @since 2.9.1
+ */
+ wxDataObjectSimple *GetObject(const wxDataFormat& format,
+ wxDataObject::Direction dir = wxDataObject::Get) const;
};
/**
@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
be set must override SetData(). Of course, the objects supporting both
operations must override all three methods.
- @beginWxPythonOnly
- If you wish to create a derived wxDataObjectSimple class in wxPython you
- should derive the class from wxPyDataObjectSimple in order to get
- Python-aware capabilities for the various virtual methods.
- @endWxPythonOnly
-
@beginWxPerlOnly
In wxPerl, you need to derive your data object class from
Wx::PlDataObjectSimple.
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.
-
- @beginWxPythonOnly
- When implementing this method in wxPython, no additional parameters are
- required and the data should be returned from the method as a string.
- @endWxPythonOnly
+ Copy the data to the buffer, return @true on success.
+ Must be implemented in the derived class if the object supports rendering
+ its data.
*/
virtual bool GetDataHere(void* buf) const;
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.
-
- @beginWxPythonOnly
- When implementing this method in wxPython, the data comes as a single
- string parameter rather than the two shown here.
- @endWxPythonOnly
+ Copy the data from the buffer, return @true on success.
+ Must be implemented in the derived class if the object supports setting
+ its data.
*/
virtual bool SetData(size_t len, const void* buf);
This class may be used as is, but GetBitmap() may be overridden to increase
efficiency.
- @beginWxPythonOnly
- If you wish to create a derived wxBitmapDataObject class in wxPython you
- should derive the class from wxPyBitmapDataObject in order to get
- Python-aware capabilities for the various virtual methods.
- @endWxPythonOnly
-
@library{wxcore}
@category{dnd}
/**
@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
wxStrings is already a very efficient operation (data is not actually
copied because wxStrings are reference counted).
- @beginWxPythonOnly
- If you wish to create a derived wxTextDataObject class in wxPython you
- should derive the class from wxPyTextDataObject in order to get
- Python-aware capabilities for the various virtual methods.
- @endWxPythonOnly
-
@library{wxcore}
@category{dnd}
*/
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(wxDataObject::Direction dir = wxDataObject::Get) const;
+
+ /**
+ 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,
+ wxDataObject::Direction dir = wxDataObject::Get) const;
+
/**
Sets the text associated with the data object. This method is called
when the data object receives the data and, by default, copies the text
const wxArrayString& GetFilenames() const;
};
-
-
-/**
- @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()
- Both = 0x03 // format is supported by both (unused currently)
- };
- @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
+ @class wxHTMLDataObject
+ wxHTMLDataObject is used for working with HTML-formatted text.
+
@library{wxcore}
@category{dnd}
- @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
- wxTextDataObject, wxBitmapDataObject, wxCustomDataObject,
- wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget
+ @see wxDataObject, wxDataObjectSimple
*/
-class wxDataObject
+class wxHTMLDataObject : public wxDataObjectSimple
{
public:
- enum Direction
- {
- /** Format is supported by GetDataHere() */
- Get = 0x01,
- /** Format is supported by SetData() */
- Set = 0x02,
- };
-
/**
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;
+ wxHTMLDataObject(const wxString& html = wxEmptyString);
/**
- 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.
+ Returns the HTML string.
*/
- virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
-
+ virtual wxString GetHTML() const;
+
/**
- Returns true if this format is supported.
+ Sets the HTML string.
*/
- bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
+ virtual void SetHTML(const wxString& html);
};
-
projects / wxWidgets.git / blobdiff