X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/50ec54b6564af84ca1280005b6659264a598abb7..4d98817cfab2654773755cb5c540057c5f3d4fd6:/interface/wx/dataobj.h diff --git a/interface/wx/dataobj.h b/interface/wx/dataobj.h index 395686a034..4ba4e3cfff 100644 --- a/interface/wx/dataobj.h +++ b/interface/wx/dataobj.h @@ -3,192 +3,563 @@ // Purpose: interface of wx*DataObject // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + /** - @class wxCustomDataObject + @class wxDataFormat - wxCustomDataObject is a specialization of wxDataObjectSimple for some - application-specific data in arbitrary (either custom or one of the - standard ones). The only restriction is that it is supposed that this data - can be copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to - make it contain a C++ object (though C struct is fine). + 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. - By default, wxCustomDataObject stores the data inside in a buffer. To put - the data into the buffer you may use either SetData() or TakeData() - depending on whether you want the object to make a copy of data or not. + 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: - This class may be used as is, but if you don't want store the data inside - the object but provide it on demand instead, you should override GetSize(), - GetData() and SetData() (or may be only the first two or only the last one - if you only allow reading/writing the data). + @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 - @library{wxcore} + 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 wxDataObject + @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject */ -class wxCustomDataObject : public wxDataObjectSimple +class wxDataFormat { public: /** - The constructor accepts a @a format argument which specifies the - (single) format supported by this object. If it isn't set here, - wxDataObjectSimple::SetFormat() should be used. + 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 */ - wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid); + wxDataFormat(wxDataFormatId format = wxDF_INVALID); /** - The destructor will free the data held by the object. Notice that - although it calls the virtual Free() function, the base class version - will always be called (C++ doesn't allow calling virtual functions from - constructors or destructors), so if you override Free(), you should - override the destructor in your class as well (which would probably - just call the derived class' version of Free()). + Constructs a data format object for a custom format identified by its + name @a format. + + @beginWxPerlOnly + In wxPerl use Wx::Bitmap->newUser(format). + @endWxPerlOnly */ - virtual ~wxCustomDataObject(); + wxDataFormat(const wxString& format); /** - This function is called to allocate @a size bytes of memory from - SetData(). The default version just uses the operator new. + Returns the name of a custom format (this function will fail for a + standard format). */ - virtual void* Alloc(size_t size); + wxString GetId() const; /** - This function is called when the data is freed, you may override it to - anything you want (or may be nothing at all). The default version calls - operator delete[] on the data. + Returns the platform-specific number identifying the format. */ - virtual void Free(); + wxDataFormatId GetType() const; /** - Returns a pointer to the data. + Sets the format to be the custom format identified by the given name. */ - virtual void* GetData() const; + void SetId(const wxString& format); /** - Returns the data size in bytes. + Sets the format to the given value, which should be one of wxDF_XXX + constants. */ - virtual size_t GetSize() const; + void SetType(wxDataFormatId type); /** - 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 + Returns @true if the formats are different. */ - virtual void SetData(size_t size, const void* data); + bool operator !=(wxDataFormatId format) const; /** - 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 + Returns @true if the formats are equal. */ - void TakeData(size_t size, void* data); + bool operator ==(wxDataFormatId format) const; }; /** - @class wxDataObjectComposite + @class wxDataObject - wxDataObjectComposite is the simplest wxDataObject derivation which may be - used to support multiple formats. It contains several wxDataObjectSimple - objects and supports any format supported by at least one of them. Only one - of these data objects is @e preferred (the first one if not explicitly - changed by using the second parameter of Add()) and its format determines - the preferred format of the composite data object as well. + 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. - See wxDataObject documentation for the reasons why you might prefer to use - wxDataObject directly instead of wxDataObjectComposite for efficiency - reasons. + 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. - @library{wxcore} - @category{dnd} + See wxDataFormat documentation for more about formats. - @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, - wxTextDataObject, wxBitmapDataObject -*/ -class wxDataObjectComposite : public wxDataObject -{ -public: - /** - The default constructor. - */ - wxDataObjectComposite(); + 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. - /** - 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); + 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. - /** - Report the format passed to the SetData() method. This should be the - format of the data object within the composite that recieved data from - the clipboard or the DnD operation. You can use this method to find - out what kind of data object was recieved. - */ - wxDataFormat GetReceivedFormat() const; -}; + 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. -/** - @class wxDataObjectSimple + 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. - 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. + 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. - 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. + 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 - 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. + At this time this class is not directly usable from wxPython. Derive a + class from wxPyDataObjectSimple() instead. @endWxPythonOnly @beginWxPerlOnly - In wxPerl, you need to derive your data object class from - Wx::PlDataObjectSimple. + 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 + wxTextDataObject, wxBitmapDataObject, wxCustomDataObject, + wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget */ -class wxDataObjectSimple : public wxDataObject +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 accepts the supported format (none by default) which may - also be set later with SetFormat(). + Constructor. */ - wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid); + wxDataObject(); /** - 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 + 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 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 + + wxCustomDataObject is a specialization of wxDataObjectSimple for some + application-specific data in arbitrary (either custom or one of the + standard ones). The only restriction is that it is supposed that this data + can be copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to + make it contain a C++ object (though C struct is fine). + + By default, wxCustomDataObject stores the data inside in a buffer. To put + the data into the buffer you may use either SetData() or TakeData() + depending on whether you want the object to make a copy of data or not. + + This class may be used as is, but if you don't want store the data inside + the object but provide it on demand instead, you should override GetSize(), + GetData() and SetData() (or may be only the first two or only the last one + if you only allow reading/writing the data). + + @library{wxcore} + @category{dnd} + + @see wxDataObject +*/ +class wxCustomDataObject : public wxDataObjectSimple +{ +public: + /** + The constructor accepts a @a format argument which specifies the + (single) format supported by this object. If it isn't set here, + wxDataObjectSimple::SetFormat() should be used. + */ + wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid); + + /** + The destructor will free the data held by the object. Notice that + although it calls the virtual Free() function, the base class version + will always be called (C++ doesn't allow calling virtual functions from + constructors or destructors), so if you override Free(), you should + override the destructor in your class as well (which would probably + just call the derived class' version of Free()). + */ + virtual ~wxCustomDataObject(); + + /** + This function is called to allocate @a size bytes of memory from + SetData(). The default version just uses the operator new. + */ + virtual void* Alloc(size_t size); + + /** + This function is called when the data is freed, you may override it to + anything you want (or may be nothing at all). The default version calls + operator delete[] on the data. + */ + virtual void Free(); + + /** + Returns a pointer to the data. + */ + virtual void* GetData() const; + + /** + Returns the data size in bytes. + */ + virtual size_t GetSize() const; + + /** + 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); +}; + + + +/** + @class wxDataObjectComposite + + wxDataObjectComposite is the simplest wxDataObject derivation which may be + used to support multiple formats. It contains several wxDataObjectSimple + objects and supports any format supported by at least one of them. Only one + of these data objects is @e preferred (the first one if not explicitly + changed by using the second parameter of Add()) and its format determines + the preferred format of the composite data object as well. + + See wxDataObject documentation for the reasons why you might prefer to use + 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} + + @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, + wxTextDataObject, wxBitmapDataObject +*/ +class wxDataObjectComposite : public wxDataObject +{ +public: + /** + The default constructor. + */ + wxDataObjectComposite(); + + /** + 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); + + /** + Report the format passed to the SetData() method. This should be the + 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 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, + wxDataObjectBase::Direction dir = 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. + + 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); + + /** + 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 */ virtual bool GetDataHere(void* buf) const; @@ -199,15 +570,15 @@ public: 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 @@ -317,8 +688,8 @@ public: /** @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 @@ -368,6 +739,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(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 when the data object receives the data and, by default, copies the text @@ -420,275 +818,3 @@ public: }; - -/** - @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); -}; -