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 43beb09c317b1000ee2b161a26c7e05aa31942d1..f827d2445cfe0300b9d4d0a401a0ec0ef9d178ec 100644 (file)
--- 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.
 
 
     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
 
 
     @section objectrefdata_example Example
 


@@ -142,7 +147,13 @@ typedef wxRefCounter wxObjectRefData;
 /**
     @class wxRefCounter
 
 /**
     @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}
 
     @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
 
     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.
 
     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
     @section objectdataptr_example Example
 
     @code

-    class MyCarRefData: public wxObjectRefData
+    class MyCarRefData: public wxRefCounter

     {
     public:
     {
     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; }
         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;
         
     protected:
         int m_price;


@@ -513,9 +518,8 @@ public:
     public:
         // initializes this MyCar assigning to the
         // internal data pointer a new instance of MyCarRefData
     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 )
         }
 
         MyCar& operator =( const MyCar& tocopy )


@@ -533,8 +537,7 @@ public:
                 return true; // this instance and the 'other' one share the
                              // same MyCarRefData data...
             
                 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 )
         }
 
         void SetPrice( int price )