Make wxDataObjectComposite::GetObject() public.

Allow retrieving individual wxDataObjects from wxDataObjectComposite and add
an example showing how can this be done to the documentation.

Closes #11692.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@63381 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/dataobj.h

@@ -274,11 +274,17 @@ public:
     void Add(wxDataObjectSimple *dataObject, bool preferred = false);
 
     // 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 this format or NULL.
+    // The returned pointer is owned by wxDataObjectComposite and must
+    // therefore not be destroyed by the caller.
+    wxDataObjectSimple *GetObject(const wxDataFormat& format,
+                                  wxDataObjectBase::Direction dir = Get) const;
+
     // implement base class pure virtuals
     // ----------------------------------
     virtual wxDataFormat GetPreferredFormat(wxDataObjectBase::Direction dir = Get) const;
@@ -295,10 +301,6 @@ public:
     virtual size_t GetBufferOffset( const wxDataFormat& format );
 #endif
 
-protected:
-    // returns the pointer to the object which supports this format or NULL
-    wxDataObjectSimple *GetObject(const wxDataFormat& format, wxDataObjectBase::Direction dir=Get) const;
-
 private:
     // the list of all (simple) data objects whose formats we support
     wxSimpleDataObjectList m_dataObjects;

interface/wx/dataobj.h

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