From: Robert Roebling <robert@roebling.de>
Date: Sun, 14 Jun 2009 14:45:20 +0000 (+0000)
Subject: Updated info on wxRefCounter and related classes
X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/04558943953dd545e6000816877f54e0128e5879?ds=sidebyside

Updated info on wxRefCounter and related classes

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

diff --git a/interface/wx/object.h b/interface/wx/object.h
index 43beb09c31..f827d2445c 100644
--- a/interface/wx/object.h
+++ b/interface/wx/object.h
@@ -10,8 +10,13 @@
 
     This class is just a typedef to wxRefCounter and is used by wxObject.
 
-    Derive classes from this to store your own data. When retrieving information
-    from a wxObject's reference data, you will need to cast to your own derived class.
+    Derive classes from this to store your own data in wxObject derived 
+    classes. When retrieving information from a wxObject's reference data,
+    you will need to cast to your own derived class.
+    
+    Below is an example illustrating how to store reference counted
+    data in a class derived from wxObject including copy-on-write
+    semantics.
 
     @section objectrefdata_example Example
 
@@ -142,7 +147,13 @@ typedef wxRefCounter wxObjectRefData;
 /**
     @class wxRefCounter
 
-    This class is used to manage reference-counting.
+    This class is used to manage reference-counting providing a simple
+    interface and a counter. wxRefCounter can be easily used together
+    with wxObjectDataPtr<T> to ensure that no calls to wxRefCounter::DecRef()
+    are missed - thus avoiding memory leaks.
+    
+    wxObjectRefData is a typedef to wxRefCounter and is used as the
+    built-in reference counted storage for wxObject derive classes.
 
     @library{wxbase}
     @category{rtti}
@@ -471,8 +482,8 @@ public:
 
 /**
 
-    This is an helper template class primarily written to avoid memory leaks because of
-    missing calls to wxObjectRefData::DecRef().
+    This is an helper template class primarily written to avoid memory leaks because
+    of missing calls to wxRefCounter::DecRef() and wxObjectRefData::DecRef().
 
     Despite the name this template can actually be used as a smart pointer for any
     class implementing the reference counting interface which only consists of the two
@@ -482,27 +493,21 @@ public:
     counting to be in the class pointed to, where instead wxSharedPtr<T> implements the
     reference counting itself.
 
+    Below is an example illustrating how to implement reference counted
+    data using wxRefCounter and wxObjectDataPtr<T> with copy-on-write
+    semantics.
+
     @section objectdataptr_example Example
 
     @code
-    class MyCarRefData: public wxObjectRefData
+    class MyCarRefData: public wxRefCounter
     {
     public:
-        MyCarRefData()  { m_price = 0; }
-
-        MyCarRefData( const MyCarRefData& data )
-            : wxObjectRefData()
-        {
-            m_price = data.m_price;
-        }
-
+        MyCarRefData( int price = 0 ) : m_price(price) { }
+        MyCarRefData( const MyCarRefData& data ) : m_price(data.m_price) { }
+        
         void SetPrice( int price )  { m_price = price; }
         int GetPrice() const        { return m_price; }
-
-        bool operator == ( const MyCarRefData& other ) const
-        {
-            return m_price == other.m_price;
-        }
         
     protected:
         int m_price;
@@ -513,9 +518,8 @@ public:
     public:
         // initializes this MyCar assigning to the
         // internal data pointer a new instance of MyCarRefData
-        MyCar( int price ) : m_data( new MyCarRefData )
+        MyCar( int price = 0 ) : m_data( new MyCarRefData(price) )
         {
-            m_data->SetPrice( price );
         }
 
         MyCar& operator =( const MyCar& tocopy )
@@ -533,8 +537,7 @@ public:
                 return true; // this instance and the 'other' one share the
                              // same MyCarRefData data...
             
-            // rely on the MyCarRefData::operator==()
-            return (*m_data.get()) == (*other.m_data.get());
+            return (m_data.GetPrice() == other.m_data.GetPrice());
         }
 
         void SetPrice( int price )