X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/dataobj.h diff --git a/interface/wx/dataobj.h b/interface/wx/dataobj.h index fd5035b5ee..8da5c8f237 100644 --- a/interface/wx/dataobj.h +++ b/interface/wx/dataobj.h @@ -2,13 +2,323 @@ // Name: dataobj.h // 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 - @wxheader{dataobj.h} wxCustomDataObject is a specialization of wxDataObjectSimple for some application-specific data in arbitrary (either custom or one of the @@ -75,31 +385,20 @@ public: /** 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 void SetData(size_t size, const void data); + 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 */ - virtual void TakeData(size_t size, const void data); + void TakeData(size_t size, void* data); }; /** @class wxDataObjectComposite - @wxheader{dataobj.h} wxDataObjectComposite is the simplest wxDataObject derivation which may be used to support multiple formats. It contains several wxDataObjectSimple @@ -112,6 +411,59 @@ public: 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(GetDataObject()); + + wxDataFormat format = dataObjects->GetReceivedFormat(); + wxDataObject *dataobj = dataobjComp->GetObject(format); + switch ( format.GetType() ) + { + case wxDF_BITMAP: + { + wxBitmapDataObject * + dataobjBitmap = static_cast(dataobj); + + ... use dataobj->GetBitmap() ... + } + break; + + case wxDF_FILENAME: + { + wxFileDataObject * + dataobjFile = static_cast(dataobj); + + ... use dataobj->GetFilenames() ... + } + break; + + default: + wxFAIL_MSG( "unexpected data object format" ); + } + } + + return dragResult; + } + @endcode + @library{wxcore} @category{dnd} @@ -130,477 +482,189 @@ public: Adds the @a dataObject to the list of supported objects and it becomes the preferred object if @a preferred is @true. */ - void Add(wxDataObjectSimple dataObject, bool preferred = false); + void Add(wxDataObjectSimple* dataObject, bool preferred = false); /** 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; -}; - - - -/** - @class wxDataObjectSimple - @wxheader{dataobj.h} - - 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. - - Notice that this is still an abstract base class and cannot be used - directly, it must be derived. The objects supporting rendering the data - must override GetDataSize() and GetDataHere() while the objects which may - 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. - @endWxPerlOnly - - @library{wxcore} - @category{dnd} - @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject, - wxTextDataObject, wxBitmapDataObject -*/ -class wxDataObjectSimple : public wxDataObject -{ -public: /** - Constructor accepts the supported format (none by default) which may - also be set later with SetFormat(). - */ - wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid); + Returns the pointer to the object which supports the passed format for + the specified direction. - /** - Copy the data to the buffer, return @true on success. Must be - implemented in the derived class if the object supports rendering its - data. + @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. - @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 + @since 2.9.1 */ - virtual bool GetDataHere(void buf) const; - - /** - Gets the size of our data. Must be implemented in the derived class if - the object supports rendering its data. - */ - 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. - */ - 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 - */ - virtual bool SetData(size_t len, const void buf); - - /** - Sets the supported format. - */ - void SetFormat(const wxDataFormat& format); -}; - - - -/** - @class wxBitmapDataObject - @wxheader{dataobj.h} - - wxBitmapDataObject is a specialization of wxDataObject for bitmap 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 a bitmap on-demand in order to minimize memory consumption when - offering data in several formats, such as a bitmap and GIF. - - 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} - - @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, - wxTextDataObject, wxDataObject -*/ -class wxBitmapDataObject : public wxDataObjectSimple -{ -public: - /** - Constructor, optionally passing a bitmap (otherwise use SetBitmap() - later). - */ - wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap); - - /** - Returns the bitmap associated with the data object. You may wish to - override this method when offering data on-demand, but this is not - required by wxWidgets' internals. Use this method to get data in bitmap - form from the wxClipboard. - */ - virtual wxBitmap GetBitmap() const; - - /** - Sets the bitmap associated with the data object. This method is called - when the data object receives data. Usually there will be no reason to - override this function. - */ - virtual void SetBitmap(const wxBitmap& bitmap); + wxDataObjectSimple *GetObject(const wxDataFormat& format, + wxDataObject::Direction dir = wxDataObject::Get) const; }; /** - @class wxDataFormat - @wxheader{dataobj.h} - - 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). + @class wxDataObjectSimple - 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! + 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. + + Notice that this is still an abstract base class and cannot be used + directly, it must be derived. The objects supporting rendering the data + must override GetDataSize() and GetDataHere() while the objects which may + be set must override SetData(). Of course, the objects supporting both + operations must override all three methods. + + @beginWxPerlOnly + In wxPerl, you need to derive your data object class from + Wx::PlDataObjectSimple. + @endWxPerlOnly - @library{wxbase} + @library{wxcore} @category{dnd} - @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject + @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject, + wxTextDataObject, wxBitmapDataObject */ -class wxDataFormat +class wxDataObjectSimple : public wxDataObject { 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(NativeFormat format = wxDF_INVALID); - /** - Constructs a data format object for a custom format identified by its - name @a format. - */ - wxDataFormat(const wxChar format); - - /** - Returns the name of a custom format (this function will fail for a - standard format). + Constructor accepts the supported format (none by default) which may + also be set later with SetFormat(). */ - wxString GetId() const; + wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid); /** - Returns the platform-specific number identifying the format. + Copy the data to the buffer, return @true on success. + Must be implemented in the derived class if the object supports rendering + its data. */ - NativeFormat GetType() const; + virtual bool GetDataHere(void* buf) const; /** - Sets the format to be the custom format identified by the given name. + Gets the size of our data. Must be implemented in the derived class if + the object supports rendering its data. */ - void SetId(const wxChar format); + virtual size_t GetDataSize() const; /** - Sets the format to the given value, which should be one of wxDF_XXX - constants. + Returns the (one and only one) format supported by this object. + It is assumed that the format is supported in both directions. */ - void SetType(NativeFormat format); + const wxDataFormat& GetFormat() const; /** - Returns @true if the formats are different. + Copy the data from the buffer, return @true on success. + Must be implemented in the derived class if the object supports setting + its data. */ - bool operator !=(const wxDataFormat& format) const; + virtual bool SetData(size_t len, const void* buf); /** - Returns @true if the formats are equal. + Sets the supported format. */ - bool operator ==(const wxDataFormat& format) const; + void SetFormat(const wxDataFormat& format); }; /** - @class wxURLDataObject - @wxheader{dataobj.h} - - wxURLDataObject is a wxDataObject containing an URL and can be used e.g. - when you need to put an URL on or retrieve it from the clipboard: + @class wxBitmapDataObject - @code - wxTheClipboard->SetData(new wxURLDataObject(url)); - @endcode + wxBitmapDataObject is a specialization of wxDataObject for bitmap 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 a bitmap on-demand in order to minimize memory consumption when + offering data in several formats, such as a bitmap and GIF. - @note This class is derived from wxDataObjectComposite on Windows rather - than wxTextDataObject on all other platforms. + This class may be used as is, but GetBitmap() may be overridden to increase + efficiency. @library{wxcore} @category{dnd} - @see @ref overview_dnd, wxDataObject + @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, + wxTextDataObject, wxDataObject */ -class wxURLDataObject: public wxTextDataObject +class wxBitmapDataObject : public wxDataObjectSimple { public: /** - Constructor, may be used to initialize the URL. If @a url is empty, - SetURL() can be used later. + Constructor, optionally passing a bitmap (otherwise use SetBitmap() + later). */ - wxURLDataObject(const wxString& url = wxEmptyString); + wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap); /** - Returns the URL stored by this object, as a string. + Returns the bitmap associated with the data object. You may wish to + override this method when offering data on-demand, but this is not + required by wxWidgets' internals. Use this method to get data in bitmap + form from the wxClipboard. */ - wxString GetURL() const; + virtual wxBitmap GetBitmap() const; /** - Sets the URL stored by this object. + Sets the bitmap associated with the data object. This method is called + when the data object receives data. Usually there will be no reason to + override this function. */ - void SetURL(const wxString& url); + virtual void SetBitmap(const wxBitmap& bitmap); }; /** - @class wxDataObject - @wxheader{dataobj.h} - - 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. + @class wxURLDataObject - 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: + wxURLDataObject is a wxDataObject containing an URL and can be used e.g. + when you need to put an URL on or retrieve it from the clipboard: @code - enum Direction - { - Get = 0x01, // format is supported by GetDataHere() - Set = 0x02 // format is supported by SetData() - }; + wxTheClipboard->SetData(new wxURLDataObject(url)); @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 + @note This class is derived from wxDataObjectComposite on Windows rather + than wxTextDataObject on all other platforms. @library{wxcore} @category{dnd} - @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject, - wxTextDataObject, wxBitmapDataObject, wxCustomDataObject, - wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget + @see @ref overview_dnd, wxDataObject */ -class wxDataObject +class wxURLDataObject: public wxTextDataObject { public: /** - Constructor. - */ - wxDataObject(); - - /** - Destructor. - */ - ~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; - - /** - 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; - - /** - Returns the data size of the given format @a format. - */ - virtual size_t GetDataSize(const wxDataFormat& format) const; - - /** - Returns the number of available formats for rendering or setting the - data. + Constructor, may be used to initialize the URL. If @a url is empty, + SetURL() can be used later. */ - virtual size_t GetFormatCount(Direction dir = Get) const; + wxURLDataObject(const wxString& url = wxEmptyString); /** - 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. + Returns the URL stored by this object, as a string. */ - virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const; + wxString GetURL() const; /** - 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. + Sets the URL stored by this object. */ - virtual bool SetData(const wxDataFormat& format, size_t len, - const void buf); + void SetURL(const wxString& url); }; - /** @class wxTextDataObject - @wxheader{dataobj.h} - 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 @@ -613,12 +677,6 @@ public: 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} @@ -650,6 +708,33 @@ public: */ 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 @@ -663,7 +748,6 @@ public: /** @class wxFileDataObject - @wxheader{dataobj.h} wxFileDataObject is a specialization of wxDataObject for file names. The program works with it just as if it were a list of absolute file names, but @@ -692,14 +776,41 @@ public: wxFileDataObject(); /** - Adds a file to the file list represented by this data object (Windows - only). + Adds a file to the file list represented by this data object (Windows only). */ - virtual void AddFile(const wxString& file); + void AddFile(const wxString& file); /** Returns the array of file names. */ - const wxArrayString GetFilenames() const; + const wxArrayString& GetFilenames() const; }; +/** + @class wxHTMLDataObject + + wxHTMLDataObject is used for working with HTML-formatted text. + + @library{wxcore} + @category{dnd} + + @see wxDataObject, wxDataObjectSimple +*/ +class wxHTMLDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor. + */ + wxHTMLDataObject(const wxString& html = wxEmptyString); + + /** + Returns the HTML string. + */ + virtual wxString GetHTML() const; + + /** + Sets the HTML string. + */ + virtual void SetHTML(const wxString& html); +};