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 7414b06526c578bde47bdb8ecd4b51d9699cb048..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}
 
 \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}
 
 
 \wxheading{See also}
 


@@ -13,6 +19,11 @@ does not use or depend on wxObject.
 \helpref{wxObjectRefData}{wxobjectrefdata},
 \helpref{Reference counting}{trefcount}
 
 \helpref{wxObjectRefData}{wxobjectrefdata},
 \helpref{Reference counting}{trefcount}
 

+\helpref{wxSharedPtr}{wxsharedptr}, 
+\helpref{wxScopedPtr}{wxscopedptrtemplate},
+\helpref{wxWeakRef}{wxweakref}
+
+

 \wxheading{Derived from}
 
 No base class
 \wxheading{Derived from}
 
 No base class


@@ -23,16 +34,16 @@ No base class
 
 \wxheading{Data structures}
 
 
 \wxheading{Data structures}
 

-{\small \begin{verbatim}
-typedef T element\_type
-\end{verbatim}}
+{\small%
+\begin{verbatim}
+typedef T element_type
+\end{verbatim}
+}%

 
 \wxheading{Example}
 
 \begin{verbatim}
 
 
 \wxheading{Example}
 
 \begin{verbatim}
 

-// include file
-

 class MyCarRefData: public wxObjectRefData
 {
 public:
 class MyCarRefData: public wxObjectRefData
 {
 public:


@@ -44,11 +55,6 @@ public:
         m_price = data.m_price;
     }
 
         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; }
     
     void SetPrice( int price )  { m_price = price; }
     int GetPrice()              { return m_price; }
     


@@ -59,61 +65,45 @@ protected:
 class MyCar
 {
 public:
 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:
     
 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}
 
 
 \end{verbatim}
 


@@ -125,7 +115,9 @@ void MyCar::UnShare()
 \func{wxEXPLICIT}{wxObjectDataPtr<T>}{\param{T* }{ptr = NULL}}
 
 Constructor. {\it ptr} is a pointer to the reference
 \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}}
 
 
 \func{}{wxObjectDataPtr<T>}{\param{const wxObjectDataPtr<T>\& }{tocopy}}
 


@@ -137,15 +129,32 @@ class will point to, as well.
 
 \func{}{\destruct{wxObjectDataPtr<T>}}{\void}
 
 
 \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}
 
 
 \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}
 
 
 \membersection{wxObjectDataPtr<T>::operator=}\label{wxobjectdataptroperatorassign}
 


@@ -167,4 +176,5 @@ this class points.
 \func{void}{reset}{\param{T* }{ptr}}
 
 Reset this class to {\it ptr} which points to a reference
 \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.