X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/98b04f2112f86a233da48ac41d62a556f6c0cdb5..38534f596974042130716a26276e9564b0b72295:/interface/wx/dataobj.h?ds=sidebyside diff --git a/interface/wx/dataobj.h b/interface/wx/dataobj.h index 7ef7587d87..3e33e4e3b2 100644 --- a/interface/wx/dataobj.h +++ b/interface/wx/dataobj.h @@ -3,7 +3,7 @@ // Purpose: interface of wx*DataObject // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -34,9 +34,7 @@ @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.} + 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 @@ -56,7 +54,7 @@ necessary initialisations and so an attempt to do clipboard format registration at this time will usually lead to a crash! - @library{wxbase} + @library{wxcore} @category{dnd} @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject @@ -67,12 +65,20 @@ 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); @@ -98,11 +104,21 @@ public: */ 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. */ @@ -110,6 +126,8 @@ public: }; +const wxDataFormat wxFormatInvalid; + /** @class wxDataObject @@ -126,7 +144,7 @@ public: 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 + wxDataObject defines the wxDataObject::Direction enumeration type which distinguishes between them. See wxDataFormat documentation for more about formats. @@ -150,7 +168,7 @@ public: -# Use one of the built-in classes. - You may use wxTextDataObject, wxBitmapDataObject wxFileDataObject, - wxURLDataObject in the simplest cases when you only need to support + 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 @@ -196,11 +214,6 @@ public: 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. @@ -220,13 +233,13 @@ public: { /** Format is supported by GetDataHere() */ Get = 0x01, - + /** Format is supported by SetData() */ Set = 0x02, - - /** - Format is supported by both GetDataHere() and SetData() - (unused currently) + + /** + Format is supported by both GetDataHere() and SetData() + (unused currently) */ Both = 0x03 }; @@ -242,16 +255,25 @@ public: virtual ~wxDataObject(); /** - Copies all formats supported in the given direction @a dir to the array - pointed to by @a formats. + 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. + 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; @@ -275,9 +297,17 @@ public: /** 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. + 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); @@ -356,22 +386,12 @@ 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 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); }; @@ -392,6 +412,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} @@ -414,11 +487,24 @@ public: /** 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; }; @@ -426,9 +512,9 @@ public: /** @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 + 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 @@ -437,12 +523,6 @@ public: 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. @@ -464,14 +544,9 @@ public: 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 + 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; @@ -482,20 +557,15 @@ public: virtual size_t GetDataSize() const; /** - Returns the (one and only one) format supported by this object. + 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 + 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); @@ -519,12 +589,6 @@ public: 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} @@ -600,7 +664,7 @@ public: /** @class wxTextDataObject - wxTextDataObject is a specialization of wxDataObjectSimple for text data. + 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 @@ -614,12 +678,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,20 +708,20 @@ public: length plus 1 for a trailing zero, but this is not strictly required. */ virtual size_t GetTextLength() const; - + /** Returns 2 under wxMac and wxGTK, where text data coming from the clipboard may be provided as ANSI (@c wxDF_TEXT) or as Unicode text (@c wxDF_UNICODETEXT, but only when @c wxUSE_UNICODE==1). - + Returns 1 under other platforms (e.g. wxMSW) or when building in ANSI mode (@c wxUSE_UNICODE==0). */ - virtual size_t GetFormatCount(Direction dir = Get); + 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). */ @@ -671,12 +729,12 @@ public: /** Returns all the formats supported by wxTextDataObject. - - Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT, + + 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; + wxDataObject::Direction dir = wxDataObject::Get) const; /** Sets the text associated with the data object. This method is called @@ -729,4 +787,31 @@ public: 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); +};