Add wxUSE_UIACTIONSIMULATOR and turn it off by default.

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

diff --git a/interface/wx/dataobj.h b/interface/wx/dataobj.h
index 7ef7587d87481fe1051df71b1230de032d63be20..462a595264874e5ee163e53c4b0b6e20f3ef6a03 100644 (file)
--- a/interface/wx/dataobj.h
+++ b/interface/wx/dataobj.h
@@ -67,12 +67,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);
 


@@ -126,7 +134,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 +158,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


@@ -220,13 +228,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,9 +250,16 @@ 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;


@@ -277,7 +292,14 @@ public:
         Set the data in the format @a format of the length @a len provided in
         the buffer @a buf.
 
         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.
+        @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);
 


@@ -392,6 +414,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 +489,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,
+                                  wxDataObjectBase::Direction dir = Get) const;

 };
 
 
 };
 
 


@@ -426,9 +514,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


@@ -464,8 +552,8 @@ 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.
 
         @beginWxPythonOnly
         its data.
 
         @beginWxPythonOnly


@@ -482,14 +570,14 @@ 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.
 
         @beginWxPythonOnly
         its data.
 
         @beginWxPythonOnly


@@ -600,7 +688,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


@@ -650,12 +738,12 @@ 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).
     */


@@ -663,7 +751,7 @@ public:
 
     /**
         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,8 +759,8 @@ 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,