Document that wxComboBox::Dismiss() and Popup() generate events.

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

diff --git a/interface/wx/object.h b/interface/wx/object.h
index 43beb09c317b1000ee2b161a26c7e05aa31942d1..787e5f7a135c62644a81b8ee9856a0ce2c2205b8 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
 


@@ -86,7 +91,7 @@
         m_refData = new MyCarRefData();
         M_CARDATA->m_price = price;
     }
         m_refData = new MyCarRefData();
         M_CARDATA->m_price = price;
     }

-    
+

     wxObjectRefData *MyCar::CreateRefData() const
     {
         return new MyCarRefData;
     wxObjectRefData *MyCar::CreateRefData() const
     {
         return new MyCarRefData;


@@ -101,7 +106,7 @@
     {
         if (m_refData == car.m_refData)
             return true;
     {
         if (m_refData == car.m_refData)
             return true;

-        if (!m_refData || !car.m_refData) 
+        if (!m_refData || !car.m_refData)

             return false;
 
         // here we use the MyCarRefData::operator==() function.
             return false;
 
         // here we use the MyCarRefData::operator==() function.


@@ -130,7 +135,7 @@
     }
     @endcode
 
     }
     @endcode
 

-    
+

     @library{wxbase}
     @category{rtti}
 
     @library{wxbase}
     @category{rtti}
 


@@ -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-derived classes.

 
     @library{wxbase}
     @category{rtti}
 
     @library{wxbase}
     @category{rtti}


@@ -216,7 +227,7 @@ public:
     @library{wxbase}
     @category{rtti}
 
     @library{wxbase}
     @category{rtti}
 

-    @see wxClassInfo, @ref overview_debugging, @ref overview_refcount, 
+    @see wxClassInfo, @ref overview_debugging, @ref overview_refcount,

          wxObjectDataRef, wxObjectDataPtr<T>
 */
 class wxObject
          wxObjectDataRef, wxObjectDataPtr<T>
 */
 class wxObject


@@ -346,10 +357,10 @@ protected:
         Ensure that this object's data is not shared with any other object.
 
         If we have no data, it is created using CreateRefData();
         Ensure that this object's data is not shared with any other object.
 
         If we have no data, it is created using CreateRefData();

-        if we have shared data (i.e. data with a reference count greater than 1), 
+        if we have shared data (i.e. data with a reference count greater than 1),

         it is copied using CloneRefData(); otherwise nothing is done (the data
         is already present and is not shared by other object instances).
         it is copied using CloneRefData(); otherwise nothing is done (the data
         is already present and is not shared by other object instances).

-        
+

         If you use this function you should make sure that you override the
         CreateRefData() and CloneRefData() functions in your class otherwise
         an assertion will fail at runtime.
         If you use this function you should make sure that you override the
         CreateRefData() and CloneRefData() functions in your class otherwise
         an assertion will fail at runtime.


@@ -359,7 +370,7 @@ protected:
     /**
         Creates a new instance of the wxObjectRefData-derived class specific to
         this object and returns it.
     /**
         Creates a new instance of the wxObjectRefData-derived class specific to
         this object and returns it.

-        
+

         This is usually implemented as a one-line call:
         @code
         wxObjectRefData *MyObject::CreateRefData() const
         This is usually implemented as a one-line call:
         @code
         wxObjectRefData *MyObject::CreateRefData() const


@@ -373,7 +384,7 @@ protected:
     /**
         Creates a new instance of the wxObjectRefData-derived class specific to
         this object and initializes it copying @a data.
     /**
         Creates a new instance of the wxObjectRefData-derived class specific to
         this object and initializes it copying @a data.

-        
+

         This is usually implemented as a one-line call:
         @code
         wxObjectRefData *MyObject::CloneRefData(const wxObjectRefData *data) const
         This is usually implemented as a one-line call:
         @code
         wxObjectRefData *MyObject::CloneRefData(const wxObjectRefData *data) const


@@ -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,28 +493,22 @@ 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 )


@@ -532,9 +536,8 @@ public:
             if (m_data.get() == other.m_data.get())
                 return true; // this instance and the 'other' one share the
                              // same MyCarRefData data...
             if (m_data.get() == other.m_data.get())
                 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 )


@@ -542,7 +545,7 @@ public:
             // make sure changes to this class do not affect other instances
             // currently sharing our same refcounted data:
             UnShare();
             // make sure changes to this class do not affect other instances
             // currently sharing our same refcounted data:
             UnShare();

-           
+

             m_data->SetPrice( price );
         }
 
             m_data->SetPrice( price );
         }