added docs for wxObjectDataPtr<T> and examples for ref counting

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

diff --git a/docs/latex/wx/objectdataptr.tex b/docs/latex/wx/objectdataptr.tex
new file mode 100644 (file)
index 0000000..7ff5cc1
--- /dev/null
+++ b/docs/latex/wx/objectdataptr.tex
@@ -0,0 +1,164 @@
+\section{\class{wxObjectDataPtr<T>}}\label{wxobjectdataptr}
+
+This is helper template class to avoid memleaks 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.
+
+\wxheading{See also}
+
+\helpref{wxObject}{wxobject},
+\helpref{wxObjectRefData}{wxobjectrefdata},
+\helpref{Reference counting}{trefcount}
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<object.h>
+
+\wxheading{Data structures}
+
+{\small \begin{verbatim}
+typedef T element\_type
+\end{verbatim}}
+
+\wxheading{Example}
+
+\begin{verbatim}
+
+// include file
+
+class MyCarRefData: public wxObjectRefData
+{
+public:
+    MyCarRefData()  { m_price = 0; }
+    
+    MyCarRefData( const MyCarRefData& data )
+        : wxObjectRefData()
+    {
+        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; }
+    
+protected:
+    int m_price;
+};
+
+class MyCar
+{
+public:
+    MyCar( int price );
+    
+    bool operator == ( const MyCar& car ) const;
+    bool operator != (const MyCar& car) const { return !(*this == car); }
+
+    void SetPrice( int price );
+    int GetPrice() const;
+
+    wxObjectRefPtr<MyCarRefData> m_data;
+    
+protected:
+    void UnShare();
+};
+
+
+// implementation
+
+MyCar::MyCar( int price )
+{
+    m_data = new MyCarRefData;
+    m_data.get()->SetPrice( price );
+}
+
+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;
+    
+    m_data.reset( new MyCarRefData( *m_data.get() ) );
+}
+
+\end{verbatim}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxObjectDataPtr<T>::wxObjectDataPtr<T>}\label{wxobjectdataptrwxobjectdataptr}
+
+\func{wxEXPLICIT}{wxObjectDataPtr<T>}{\param{T* }{ptr = NULL}}
+
+Constructor. {\it ptr} is a pointer to the reference
+counted object to which this class points.
+
+\func{}{wxObjectDataPtr<T>}{\param{const wxObjectDataPtr<T>\& }{tocopy}}
+
+This copy constructor increases the count of the reference
+counted object to which {\it tocopy} points and then this
+class will point to, as well.
+
+\membersection{wxObjectDataPtr<T>::\destruct{wxObjectDataPtr<T>}}\label{wxobjectdataptrdtor}
+
+\func{}{\destruct{wxObjectDataPtr<T>}}{\void}
+
+Calls \helpref{DecRef}{wxobjectrefdatadecref} on the reference
+counted object to which this class points.
+
+\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}.
+
+\membersection{wxObjectDataPtr<T>::operator=}\label{wxobjectdataptroperatorassign}
+
+\func{wxObjectDataPtr<T>\& operator}{operator=}{\param{const wxObjectDataPtr<T>\& }{tocopy}}
+
+\func{wxObjectDataPtr<T>\& operator}{operator=}{\param{T* }{ptr}}
+
+Assignment operators.
+
+\membersection{wxObjectDataPtr<T>::get}\label{wxobjectdataptrget}
+
+\constfunc{T*}{get}{\void}
+
+Gets a pointer to the reference counted object to which
+this class points.
+
+\membersection{wxObjectDataPtr<T>::reset}\label{wxobjectdataptrreset}
+
+\func{void}{reset}{\param{T* }{ptr}}
+
+Reset this class to {\it ptr} which points to a reference
+counted object.