X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..23efa4bfb9104d6ef947a217efa80b2bc5bf9e76:/interface/wx/dataobj.h diff --git a/interface/wx/dataobj.h b/interface/wx/dataobj.h index fd5035b5ee..efbd5a98ee 100644 --- a/interface/wx/dataobj.h +++ b/interface/wx/dataobj.h @@ -8,7 +8,6 @@ /** @class wxCustomDataObject - @wxheader{dataobj.h} wxCustomDataObject is a specialization of wxDataObjectSimple for some application-specific data in arbitrary (either custom or one of the @@ -81,7 +80,7 @@ public: 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 @@ -92,14 +91,13 @@ public: 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 @@ -130,7 +128,7 @@ 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 @@ -145,7 +143,6 @@ public: /** @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, @@ -193,7 +190,7 @@ public: required and the data should be returned from the method as a string. @endWxPythonOnly */ - virtual bool GetDataHere(void buf) const; + virtual bool GetDataHere(void* buf) const; /** Gets the size of our data. Must be implemented in the derived class if @@ -205,7 +202,7 @@ public: 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; + const wxDataFormat& GetFormat() const; /** Copy the data from the buffer, return @true on success. Must be @@ -217,7 +214,7 @@ public: string parameter rather than the two shown here. @endWxPythonOnly */ - virtual bool SetData(size_t len, const void buf); + virtual bool SetData(size_t len, const void* buf); /** Sets the supported format. @@ -229,7 +226,6 @@ public: /** @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 @@ -279,9 +275,154 @@ public: +/** + @class wxURLDataObject + + 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 + wxTheClipboard->SetData(new wxURLDataObject(url)); + @endcode + + @note This class is derived from wxDataObjectComposite on Windows rather + than wxTextDataObject on all other platforms. + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, wxDataObject +*/ +class wxURLDataObject: public wxTextDataObject +{ +public: + /** + Constructor, may be used to initialize the URL. If @a url is empty, + SetURL() can be used later. + */ + wxURLDataObject(const wxString& url = wxEmptyString); + + /** + Returns the URL stored by this object, as a string. + */ + wxString GetURL() const; + + /** + Sets the URL stored by this object. + */ + void SetURL(const wxString& url); +}; + + +/** + @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 + 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 + default the text is stored in a string in this class, but it might as well + be generated when requested. For this, GetTextLength() and GetText() will + have to be overridden. + + Note that if you already have the text inside a string, you will not + achieve any efficiency gain by overriding these functions because copying + 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} + + @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, + wxBitmapDataObject +*/ +class wxTextDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor, may be used to initialise the text (otherwise SetText() + should be used later). + */ + wxTextDataObject(const wxString& text = wxEmptyString); + + /** + Returns the text 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 text + form from the wxClipboard. + */ + virtual wxString GetText() const; + + /** + Returns the data size. By default, returns the size of the text data + set in the constructor or using SetText(). This can be overridden to + provide text size data on-demand. It is recommended to return the text + length plus 1 for a trailing zero, but this is not strictly required. + */ + virtual size_t GetTextLength() 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 + into the member variable. If you want to process the text on the fly + you may wish to override this function. + */ + virtual void SetText(const wxString& strText); +}; + + + +/** + @class wxFileDataObject + + 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 + internally it uses the same format as Explorer and other compatible + programs under Windows or GNOME/KDE filemanager under Unix which makes it + possible to receive files from them using this class. + + @warning Under all non-Windows platforms this class is currently + "input-only", i.e. you can receive the files from another + application, but copying (or dragging) file(s) from a wxWidgets + application is not currently supported. PS: GTK2 should work as + well. + + @library{wxcore} + @category{dnd} + + @see wxDataObject, wxDataObjectSimple, wxTextDataObject, + wxBitmapDataObject, wxDataObject +*/ +class wxFileDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor. + */ + wxFileDataObject(); + + /** + Adds a file to the file list represented by this data object (Windows only). + */ + void AddFile(const wxString& file); + + /** + Returns the array of file names. + */ + const wxArrayString& GetFilenames() 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. @@ -341,12 +482,13 @@ 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); + wxDataFormat(wxDataFormatId format = wxDF_INVALID); + /** Constructs a data format object for a custom format identified by its name @a format. */ - wxDataFormat(const wxChar format); + wxDataFormat(const wxString& format); /** Returns the name of a custom format (this function will fail for a @@ -357,76 +499,34 @@ public: /** Returns the platform-specific number identifying the format. */ - NativeFormat GetType() const; + wxDataFormatId GetType() const; /** Sets the format to be the custom format identified by the given name. */ - void SetId(const wxChar format); + void SetId(const wxString& format); /** Sets the format to the given value, which should be one of wxDF_XXX constants. */ - void SetType(NativeFormat format); + void SetType(wxDataFormatId type); /** Returns @true if the formats are different. */ - bool operator !=(const wxDataFormat& format) const; + bool operator !=(wxDataFormatId format) const; /** Returns @true if the formats are equal. */ - bool operator ==(const wxDataFormat& format) const; -}; - - - -/** - @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: - - @code - wxTheClipboard->SetData(new wxURLDataObject(url)); - @endcode - - @note This class is derived from wxDataObjectComposite on Windows rather - than wxTextDataObject on all other platforms. - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, wxDataObject -*/ -class wxURLDataObject: public wxTextDataObject -{ -public: - /** - Constructor, may be used to initialize the URL. If @a url is empty, - SetURL() can be used later. - */ - wxURLDataObject(const wxString& url = wxEmptyString); - - /** - Returns the URL stored by this object, as a string. - */ - wxString GetURL() const; - - /** - Sets the URL stored by this object. - */ - void SetURL(const wxString& url); + bool operator ==(wxDataFormatId format) const; }; /** @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 @@ -549,7 +649,7 @@ public: /** Destructor. */ - ~wxDataObject(); + virtual ~wxDataObject(); /** Copy all supported formats in the given direction to the array pointed @@ -557,31 +657,31 @@ public: in it. */ virtual void GetAllFormats(wxDataFormat* formats, - Direction dir = Get) const; + 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; + 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; + 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; + 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; + virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0; /** Set the data in the format @a format of the length @a len provided in @@ -589,117 +689,6 @@ public: @return @true on success, @false on failure. */ - virtual bool SetData(const wxDataFormat& format, size_t len, - const void buf); -}; - - - -/** - @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 - 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 - default the text is stored in a string in this class, but it might as well - be generated when requested. For this, GetTextLength() and GetText() will - have to be overridden. - - Note that if you already have the text inside a string, you will not - achieve any efficiency gain by overriding these functions because copying - 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} - - @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, - wxBitmapDataObject -*/ -class wxTextDataObject : public wxDataObjectSimple -{ -public: - /** - Constructor, may be used to initialise the text (otherwise SetText() - should be used later). - */ - wxTextDataObject(const wxString& text = wxEmptyString); - - /** - Returns the text 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 text - form from the wxClipboard. - */ - virtual wxString GetText() const; - - /** - Returns the data size. By default, returns the size of the text data - set in the constructor or using SetText(). This can be overridden to - provide text size data on-demand. It is recommended to return the text - length plus 1 for a trailing zero, but this is not strictly required. - */ - virtual size_t GetTextLength() 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 - into the member variable. If you want to process the text on the fly - you may wish to override this function. - */ - virtual void SetText(const wxString& strText); -}; - - - -/** - @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 - internally it uses the same format as Explorer and other compatible - programs under Windows or GNOME/KDE filemanager under Unix which makes it - possible to receive files from them using this class. - - @warning Under all non-Windows platforms this class is currently - "input-only", i.e. you can receive the files from another - application, but copying (or dragging) file(s) from a wxWidgets - application is not currently supported. PS: GTK2 should work as - well. - - @library{wxcore} - @category{dnd} - - @see wxDataObject, wxDataObjectSimple, wxTextDataObject, - wxBitmapDataObject, wxDataObject -*/ -class wxFileDataObject : public wxDataObjectSimple -{ -public: - /** - Constructor. - */ - wxFileDataObject(); - - /** - Adds a file to the file list represented by this data object (Windows - only). - */ - virtual void AddFile(const wxString& file); - - /** - Returns the array of file names. - */ - const wxArrayString GetFilenames() const; + virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf); };