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

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@48429 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/latex/wx/object.tex b/docs/latex/wx/object.tex
index 8c8b4e9c3b9ef48659fb23afa7b3774283d1cdd0..8d8c6f07a834b2f453a740987b879bc9f8949efe 100644 (file)
--- a/docs/latex/wx/object.tex
+++ b/docs/latex/wx/object.tex
@@ -1,6 +1,6 @@
 \section{\class{wxObject}}\label{wxobject}
 
-This is the root class of all wxWidgets classes.
+This is the root class of many of the wxWidgets classes.
 It declares a virtual destructor which ensures that
 destructors get called for all derived class objects where necessary.
 
@@ -231,6 +231,8 @@ you will need to cast to your own derived class.
 \wxheading{See also}
 
 \helpref{wxObject}{wxobject}
+\helpref{wxObjectDataPtr<T>}{wxobjectdataptr}
+\helpref{Reference counting}{trefcount}
 
 \wxheading{Derived from}
 
@@ -240,6 +242,104 @@ No base class
 
 <wx/object.h>
 
+\wxheading{Example}
+
+\begin{verbatim}
+
+// include file
+
+class MyCar: public wxObject
+{
+public:
+    MyCar() { }
+    MyCar( int price );
+    
+    bool IsOk() const { return m_refData != NULL; }
+
+    bool operator == ( const MyCar& car ) const;
+    bool operator != (const MyCar& car) const { return !(*this == car); }
+
+    void SetPrice( int price );
+    int GetPrice() const;
+
+protected:
+    virtual wxObjectRefData *CreateRefData() const;
+    virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;
+
+    DECLARE_DYNAMIC_CLASS(MyCar)
+};
+
+
+// implementation
+
+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;
+    }
+
+    int m_price;
+};
+
+
+#define M_CARDATA ((MyCarRefData *)m_refData)
+
+IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject)
+
+MyCar::MyCar( int price )
+{
+    m_refData = new MyCarRefData();
+    M_CARDATA->m_price = price;
+}
+
+wxObjectRefData *MyCar::CreateRefData() const
+{
+    return new MyCarRefData;
+}
+
+wxObjectRefData *MyCar::CloneRefData(const wxObjectRefData *data) const
+{
+    return new MyCarRefData(*(MyCarRefData *)data);
+}
+
+bool MyCar::operator == ( const MyCar& car ) const
+{
+    if (m_refData == car.m_refData) return true;
+
+    if (!m_refData || !car.m_refData) return false;
+
+    return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData );
+}
+
+void MyCar::SetPrice( int price )
+{
+    UnShare();
+
+    M_CARDATA->m_price = price;
+}
+
+int MyCar::GetPrice() const
+{
+    wxCHECK_MSG( IsOk(), -1, "invalid car" );
+    
+    return (M_CARDATA->m_price);
+}
+
+\end{verbatim}
+
 \wxheading{Library}
 
 \helpref{wxBase}{librarieslist}

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.

diff --git a/docs/latex/wx/trefcount.tex b/docs/latex/wx/trefcount.tex
index d240a690e3d0769573e3d293ccfe644a5a647e9e..01ed32c0a168d71470cc426cc2fe9bfe40df3cc9 100644 (file)
--- a/docs/latex/wx/trefcount.tex
+++ b/docs/latex/wx/trefcount.tex
@@ -73,7 +73,8 @@ wxWidgets; some ports may use this tecnique also for other classes.
 \subsection{Make your own reference-counted class}\label{wxobjectoverview}
 
 Reference counting can be implemented easily using \helpref{wxObject}{wxobject}
-and \helpref{wxObjectRefData}{wxobjectrefdata} classes.
+and \helpref{wxObjectRefData}{wxobjectrefdata} classes. Alternatively, you
+can also use the \helpref{wxObjectDataPtr<T>}{wxobjectdataptr} template.
 
 First, derive a new class from \helpref{wxObjectRefData}{wxobjectrefdata} and
 put there the memory-consuming data.