fix LaTeX error (escape underscores); don't abuse bold face

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

diff --git a/docs/latex/wx/object.tex b/docs/latex/wx/object.tex
index 4332aa6a023481475da2fb184926292bdddf161c..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.
 
@@ -20,6 +20,18 @@ such as wxPen, wxBitmap and others (see \helpref{this list}{refcountlist}).
 \helpref{wxClassInfo}{wxclassinfo}, \helpref{Debugging overview}{debuggingoverview},\rtfsp
 \helpref{wxObjectRefData}{wxobjectrefdata}
 
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxObject::wxObject}\label{wxobjectctor}
@@ -116,12 +128,15 @@ this one or is derived from it.
   bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
 \end{verbatim}
 
-\membersection{wxObject::IsRefTo}\label{wxobjectisrefto}
+\membersection{wxObject::IsSameAs}\label{wxobjectissameas}
+
+\func{bool}{IsSameAs}{\param{const wxObject\& }{ obj}}
 
-\func{bool}{IsRefTo}{\param{const wxObject *}{ obj}}
+Returns \true if this object has the same data pointer as \arg{obj}. Notice
+that \true is returned if the data pointers are \NULL in both objects.
 
-Returns \true if this object is referencing the \arg{obj}'s data.
-Note that this function only does a {\tt shallow} comparison.
+This function only does a \emph{shallow} comparison, i.e. it doesn't compare
+the objects pointed to by the data pointers of these objects.
 
 \membersection{wxObject::Ref}\label{wxobjectref}
 
@@ -199,6 +214,10 @@ The {\it delete} operator is defined for debugging versions of the library only,
 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory deallocation, allowing
 wxDebugContext operations.
 
+
+
+%% wxObjectRefData
+
 \section{\class{wxObjectRefData}}\label{wxobjectrefdata}
 
 This class is used to store reference-counted data. Derive classes from this to
@@ -212,6 +231,118 @@ 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}
+
+No base class
+
+\wxheading{Include files}
+
+<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}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
@@ -220,19 +351,36 @@ you will need to cast to your own derived class.
 
 \func{}{wxObjectRefData}{\void}
 
-Default constructor. Initialises the {\bf m\_count} member to 1.
+Default constructor. Initialises the internal reference count to 1.
 
 \membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}
 
 \func{}{wxObjectRefData}{\void}
 
-Destructor.
+Destructor. It's declared {\tt protected} so that wxObjectRefData instances will never
+be destroyed directly but only as result of a \helpref{DecRef}{wxobjectrefdatadecref} call.
 
 \membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount}
 
 \constfunc{int}{GetRefCount}{\void}
 
 Returns the reference count associated with this shared data.
-When this goes to zero during a \helpref{wxObject::UnRef}{wxobjectunref}, an object
-can delete this {\bf wxObjectRefData} object.
+When this goes to zero during a \helpref{DecRef}{wxobjectrefdatadecref} call, the object
+will auto-free itself.
+
+\membersection{wxObjectRefData::DecRef}\label{wxobjectrefdatadecref}
+
+\func{void}{DecRef}{\void}
+
+Decrements the reference count associated with this shared data and, if it reaches zero,
+destroys this instance of wxObjectRefData releasing its memory.
+
+Please note that after calling this function, the caller should absolutely avoid to use
+the pointer to this instance since it may not be valid anymore.
+
+\membersection{wxObjectRefData::IncRef}\label{wxobjectrefdataincref}
+
+\func{void}{IncRef}{\void}
+
+Increments the reference count associated with this shared data.