Make storing non-trivial data in wxThreadSpecificInfo possible.

[wxWidgets.git] / interface / wx / dataobj.h

diff --git a/interface/wx/dataobj.h b/interface/wx/dataobj.h
index 7ef7587d87481fe1051df71b1230de032d63be20..8da5c8f237680d61757789b6c43f153ce2376c56 100644 (file)
--- a/interface/wx/dataobj.h
+++ b/interface/wx/dataobj.h
@@ -2,8 +2,7 @@
 // Name:        dataobj.h
 // Purpose:     interface of wx*DataObject
 // Author:      wxWidgets team
 // Name:        dataobj.h
 // Purpose:     interface of wx*DataObject
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -34,9 +33,7 @@
     @itemdef{wxDF_FILENAME,
              A list of filenames.}
     @itemdef{wxDF_HTML,
     @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
     @endDefList
 
     As mentioned above, these standard formats may be passed to any function


@@ -56,7 +53,7 @@
     necessary initialisations and so an attempt to do clipboard format
     registration at this time will usually lead to a crash!
 
     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
     @category{dnd}
 
     @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject


@@ -67,12 +64,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).
     /**
         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.
     */
     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);
 
     */
     wxDataFormat(const wxString& format);
 


@@ -98,11 +103,21 @@ public:
     */
     void SetType(wxDataFormatId type);
 
     */
     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 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.
     */
     /**
         Returns @true if the formats are equal.
     */


@@ -110,6 +125,8 @@ public:
 };
 
 
 };
 
 

+const wxDataFormat wxFormatInvalid;
+

 
 /**
     @class wxDataObject
 
 /**
     @class wxDataObject


@@ -126,7 +143,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.
     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.
     distinguishes between them.
 
     See wxDataFormat documentation for more about formats.


@@ -150,7 +167,7 @@ public:
 
     -# Use one of the built-in classes.
         - You may use wxTextDataObject, wxBitmapDataObject wxFileDataObject,
 
     -# 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
           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 +213,6 @@ public:
     objects which only render their data or only set it (i.e. work in only one
     direction), should return 0 from GetFormatCount().
 
     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.
     @beginWxPerlOnly
     This class is not currently usable from wxPerl; you may use
     Wx::PlDataObjectSimple instead.


@@ -220,13 +232,13 @@ public:
     {
         /** Format is supported by GetDataHere() */
         Get  = 0x01,
     {
         /** Format is supported by GetDataHere() */
         Get  = 0x01,

-        
+

         /** Format is supported by SetData() */
         Set  = 0x02,
         /** 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
     };
          */
         Both = 0x03
     };


@@ -242,16 +254,25 @@ public:
     virtual ~wxDataObject();
 
     /**
     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.
         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;
 
     /**
     */
     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;
 
     */
     virtual bool GetDataHere(const wxDataFormat& format, void* buf) const = 0;
 


@@ -275,9 +296,17 @@ public:
 
     /**
         Set the data in the format @a format of the length @a len provided in
 
     /**
         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);
 
     */
     virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
 


@@ -356,22 +385,12 @@ public:
 
     /**
         Set the data. The data object will make an internal copy.
 
     /**
         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.
     */
     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);
 };
     */
     void TakeData(size_t size, void* data);
 };


@@ -392,6 +411,59 @@ public:
     wxDataObject directly instead of wxDataObjectComposite for efficiency
     reasons.
 
     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<wxDataObjectComposite *>(GetDataObject());
+
+            wxDataFormat format = dataObjects->GetReceivedFormat();
+            wxDataObject *dataobj = dataobjComp->GetObject(format);
+            switch ( format.GetType() )
+            {
+                case wxDF_BITMAP:
+                    {
+                        wxBitmapDataObject *
+                            dataobjBitmap = static_cast<wxBitmapDataObject *>(dataobj);
+
+                        ... use dataobj->GetBitmap() ...
+                    }
+                    break;
+
+                case wxDF_FILENAME:
+                    {
+                        wxFileDataObject *
+                            dataobjFile = static_cast<wxFileDataObject *>(dataobj);
+
+                        ... use dataobj->GetFilenames() ...
+                    }
+                    break;
+
+                default:
+                    wxFAIL_MSG( "unexpected data object format" );
+            }
+        }
+
+        return dragResult;
+    }
+    @endcode
+

     @library{wxcore}
     @category{dnd}
 
     @library{wxcore}
     @category{dnd}
 


@@ -414,11 +486,24 @@ public:
 
     /**
         Report the format passed to the SetData() method.  This should be the
 
     /**
         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
         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;
     */
     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 +511,9 @@ public:
 /**
     @class wxDataObjectSimple
 
 /**
     @class wxDataObjectSimple
 

-    This is the simplest possible implementation of the wxDataObject class. 
-    The data object of (a class derived from) this class only supports 
-    <strong>one format</strong>, 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
+    <strong>one format</strong>, so the number of virtual functions to

     be implemented is reduced.
 
     Notice that this is still an abstract base class and cannot be used
     be implemented is reduced.
 
     Notice that this is still an abstract base class and cannot be used


@@ -437,12 +522,6 @@ public:
     be set must override SetData(). Of course, the objects supporting both
     operations must override all three methods.
 
     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.
     @beginWxPerlOnly
     In wxPerl, you need to derive your data object class from
     Wx::PlDataObjectSimple.


@@ -464,14 +543,9 @@ public:
     wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
 
     /**
     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.
         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;
 
     */
     virtual bool GetDataHere(void* buf) const;
 


@@ -482,20 +556,15 @@ public:
     virtual size_t GetDataSize() const;
 
     /**
     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;
 
     /**
         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.
         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);
 
     */
     virtual bool SetData(size_t len, const void* buf);
 


@@ -519,12 +588,6 @@ public:
     This class may be used as is, but GetBitmap() may be overridden to increase
     efficiency.
 
     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}
 
     @library{wxcore}
     @category{dnd}
 


@@ -600,7 +663,7 @@ public:
 /**
     @class wxTextDataObject
 
 /**
     @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
     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 +677,6 @@ public:
     wxStrings is already a very efficient operation (data is not actually
     copied because wxStrings are reference counted).
 
     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}
 
     @library{wxcore}
     @category{dnd}
 


@@ -650,20 +707,20 @@ public:
         length plus 1 for a trailing zero, but this is not strictly required.
     */
     virtual size_t GetTextLength() const;
         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 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).
     */
         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.
 
     /**
         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).
     */
         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 +728,12 @@ public:
 
     /**
         Returns all the formats supported by wxTextDataObject.
 
     /**
         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,
         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
 
     /**
         Sets the text associated with the data object. This method is called


@@ -729,4 +786,31 @@ public:
     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);
+};