X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/50ec54b6564af84ca1280005b6659264a598abb7..0f08aa44323c65b92cbef304c59b742af8fd717c:/interface/wx/dataobj.h diff --git a/interface/wx/dataobj.h b/interface/wx/dataobj.h index 395686a034..6f3951a0d3 100644 --- a/interface/wx/dataobj.h +++ b/interface/wx/dataobj.h @@ -6,6 +6,295 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + +/** + @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 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(). + + @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: + 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. + */ + 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 @@ -80,7 +369,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 @@ -144,9 +433,10 @@ 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 be implemented is reduced. + This is the simplest possible implementation of the wxDataObject class. + The data object of (a class derived from) this class only supports + 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 @@ -181,9 +471,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 its - data. + 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 @@ -199,15 +489,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 +607,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 @@ -367,6 +657,33 @@ 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); + + /** + 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 @@ -420,275 +737,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); -}; -