no changes, just come cleanup and more comments

[wxWidgets.git] / docs / latex / wx / objectdataptr.tex

diff --git a/docs/latex/wx/objectdataptr.tex b/docs/latex/wx/objectdataptr.tex
index d75a1bf10c5235560e11c1e0956e3aee3879eed6..7326f3b0ee421d73140b458db823ee4593c98a25 100644 (file)
--- a/docs/latex/wx/objectdataptr.tex
+++ b/docs/latex/wx/objectdataptr.tex
@@ -1,11 +1,17 @@
 \section{\class{wxObjectDataPtr<T>}}\label{wxobjectdataptr}
 
-This is helper template class to avoid memleaks because of missing calls
-to \helpref{wxObjectRefData::DecRef}{wxobjectrefdatadecref}.
+This is helper template class primarily written to avoid memory 
+leaks because of missing calls to \helpref{wxObjectRefData::DecRef}{wxobjectrefdatadecref}.
 
-Despite the name this template can actually be used for any
-class implementing the reference counting interface and it
-does not use or depend on wxObject.
+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 methods
+{\bf T::IncRef()} and {\bf T::DecRef()}.
+
+The difference to \helpref{wxSharedPtr}{wxsharedptr} is that
+wxObjectDataPtr relies on the reference counting to be in
+the class pointed to where as wxSharedPtr implements the
+reference counting itself.
 
 \wxheading{See also}
 
@@ -13,6 +19,11 @@ does not use or depend on wxObject.
 \helpref{wxObjectRefData}{wxobjectrefdata},
 \helpref{Reference counting}{trefcount}
 
+\helpref{wxSharedPtr}{wxsharedptr}, 
+\helpref{wxScopedPtr}{wxscopedptrtemplate},
+\helpref{wxWeakRef}{wxweakref}
+
+
 \wxheading{Derived from}
 
 No base class
@@ -33,8 +44,6 @@ typedef T element_type
 
 \begin{verbatim}
 
-// include file
-
 class MyCarRefData: public wxObjectRefData
 {
 public:
@@ -46,11 +55,6 @@ public:
         m_price = data.m_price;
     }
 
-    bool operator == (const MyCarRefData& data) const
-    {
-        return m_price == data.m_price;
-    }
-    
     void SetPrice( int price )  { m_price = price; }
     int GetPrice()              { return m_price; }
     
@@ -61,61 +65,45 @@ protected:
 class MyCar
 {
 public:
-    MyCar( int price );
-    MyCar( const MyCar& data );
+    MyCar( int price ) : m_data( new MyCarRefData )
+    {
+        m_data->SetPrice( price );
+    }
+    
+    MyCar& operator =( const MyCar& tocopy )
+    {
+        m_data = tocopy.m_data;
+        return *this;
+    }
     
-    bool operator == ( const MyCar& car ) const;
-    bool operator != (const MyCar& car) const { return !(*this == car); }
+    bool operator == ( const MyCar& other ) const
+    {
+        if (m_data.get() == other.m_data.get()) return true;
+        return (m_data->GetPrice() == other.m_data->GetPrice());
+    }
 
-    void SetPrice( int price );
-    int GetPrice() const;
+    void SetPrice( int price )
+    {
+       UnShare();
+       m_data->SetPrice( price );
+    }
+    
+    int GetPrice() const
+    {
+       return m_data->GetPrice();
+    }
 
-    wxObjectRefPtr<MyCarRefData> m_data;
+    wxObjectDataPtr<MyCarRefData> m_data;
     
 protected:
-    void UnShare();
-};
-
-
-// implementation
-
-MyCar::MyCar( int price )
-{
-    m_data = new MyCarRefData;
-    m_data.get()->SetPrice( price );
-}
-
-MyCar::MyCar( const MyCar& car )
-{
-    m_data.reset( car.m_data.get() );
-}
-
-bool MyCar::operator == ( const MyCar& car ) const
-{
-    if (m_data.get() == car.m_data.get()) return true;
-
-    return (*m_data.get() == *car.m_data.get());
-}
-
-void MyCar::SetPrice( int price )
-{
-    UnShare();
-        
-    m_data.get()->SetPrice( price );
-}
-
-int MyCar::GetPrice() const
-{
-    return m_data.get()->GetPrice();
-}
-
-void MyCar::UnShare()
-{
-    if (m_data.get()->GetCount() == 1)
-        return;
+    void UnShare()
+    {
+        if (m_data->GetRefCount() == 1)
+            return;
     
-    m_data.reset( new MyCarRefData( *m_data.get() ) );
-}
+        m_data.reset( new MyCarRefData( *m_data ) );
+    }
+};
 
 \end{verbatim}
 
@@ -127,7 +115,9 @@ void MyCar::UnShare()
 \func{wxEXPLICIT}{wxObjectDataPtr<T>}{\param{T* }{ptr = NULL}}
 
 Constructor. {\it ptr} is a pointer to the reference
-counted object to which this class points.
+counted object to which this class points. If {\it ptr}
+is not NULL {\bf T::IncRef()} will be called on the
+object.
 
 \func{}{wxObjectDataPtr<T>}{\param{const wxObjectDataPtr<T>\& }{tocopy}}
 
@@ -139,15 +129,32 @@ class will point to, as well.
 
 \func{}{\destruct{wxObjectDataPtr<T>}}{\void}
 
-Calls \helpref{DecRef}{wxobjectrefdatadecref} on the reference
-counted object to which this class points.
+Decreases the reference count of the object to which this
+class points.
+
+\membersection{wxObjectDataPtr<T>::operator unspecified\_bool\_type}\label{wxobjectdataptroperatorbool}
+
+\constfunc{}{operator unspecified\_bool\_type}{\void}
+
+Conversion to a boolean expression (in a variant which is not 
+convertable to anything but a boolean expression). If this class
+contains a valid pointer it will return {\it true}, if it contains
+a NULL pointer it will return {\it false}.
+
+\membersection{wxObjectDataPtr<T>::operator*}\label{wxobjectdataptroperatorreft}
+
+\constfunc{T \&}{operator*}{\void}
+
+Returns a reference to the object. If the internal pointer is NULL
+this method will cause an assert in debug mode.
 
 \membersection{wxObjectDataPtr<T>::operator->}\label{wxobjectdataptroperatorpointer}
 
 \constfunc{T*}{operator->}{\void}
 
-Gets a pointer to the reference counted object to which
-this class points. Same as \helpref{get}{wxobjectdataptrget}.
+Returns a pointer to the reference counted object to which
+this class points. If this the internal pointer is NULL,
+this method will assert in debug mode.
 
 \membersection{wxObjectDataPtr<T>::operator=}\label{wxobjectdataptroperatorassign}
 
@@ -169,4 +176,5 @@ this class points.
 \func{void}{reset}{\param{T* }{ptr}}
 
 Reset this class to {\it ptr} which points to a reference
-counted object.
+counted object and calls {\bf T::DecRef()} on the previously
+owned object.