Document wxBitmapToggleButton, add update UI event in Base class for all toggle buttons

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

diff --git a/docs/latex/wx/object.tex b/docs/latex/wx/object.tex
index a93d8e02d1919886e98070b6165b7b4ad2013a6d..8d8c6f07a834b2f453a740987b879bc9f8949efe 100644 (file)
--- a/docs/latex/wx/object.tex
+++ b/docs/latex/wx/object.tex
@@ -1,6 +1,6 @@
 \section{\class{wxObject}}\label{wxobject}
 
 \section{\class{wxObject}}\label{wxobject}
 

-This is the root class of all wxWindows 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.
 
 It declares a virtual destructor which ensures that
 destructors get called for all derived class objects where necessary.
 


@@ -12,23 +12,37 @@ The class contains optional debugging versions
 of {\bf new} and {\bf delete}, which can help trace memory allocation
 and deallocation problems.
 
 of {\bf new} and {\bf delete}, which can help trace memory allocation
 and deallocation problems.
 

-wxObject can be used to implement reference counted objects, such as
-wxPen, wxBitmap and others.
+wxObject can be used to implement \helpref{reference counted}{trefcount} objects,
+such as wxPen, wxBitmap and others (see \helpref{this list}{refcountlist}).

 
 \wxheading{See also}
 
 \helpref{wxClassInfo}{wxclassinfo}, \helpref{Debugging overview}{debuggingoverview},\rtfsp
 \helpref{wxObjectRefData}{wxobjectrefdata}
 
 
 \wxheading{See also}
 
 \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}}}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxObject::wxObject}\label{wxobjectconstr}
+\membersection{wxObject::wxObject}\label{wxobjectctor}

 
 \func{}{wxObject}{\void}
 
 
 \func{}{wxObject}{\void}
 

-Default constructor.
+\func{}{wxObject}{\param{const wxObject\&}{ other}}
+
+Default and copy constructors.

 
 

-\membersection{wxObject::\destruct{wxObject}}
+\membersection{wxObject::\destruct{wxObject}}\label{wxobjectdtor}

 
 \func{}{wxObject}{\void}
 
 
 \func{}{wxObject}{\void}
 


@@ -48,32 +62,29 @@ Pointer to an object which is the object's reference-counted data.
 \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 \helpref{wxObjectRefData}{wxobjectrefdata}
 
 \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 \helpref{wxObjectRefData}{wxobjectrefdata}
 

-\membersection{wxObject::CopyObject}\label{wxobjectcopyobject}
-
-\func{virtual void}{CopyObject}{\param{wxObject\&}{ object\_dest}}
-
-Create a copy of this object in object\_dest. Must perform a full copy of self
-so that object\_dest will be valid after this object is deleted
-

 \membersection{wxObject::Dump}\label{wxobjectdump}
 
 \func{void}{Dump}{\param{ostream\&}{ stream}}
 
 \membersection{wxObject::Dump}\label{wxobjectdump}
 
 \func{void}{Dump}{\param{ostream\&}{ stream}}
 

-A virtual function that should be redefined by derived classes to allow dumping of
+A virtual function that may be redefined by derived classes to allow dumping of

 memory states.
 
 memory states.
 

+This function is only defined in debug build and doesn't exist at all if
+{\tt \_\_WXDEBUG\_\_} is not defined.
+

 \wxheading{Parameters}
 
 \docparam{stream}{Stream on which to output dump information.}
 
 \wxheading{Remarks}
 
 \wxheading{Parameters}
 
 \docparam{stream}{Stream on which to output dump information.}
 
 \wxheading{Remarks}
 

-Currently wxWindows does not define Dump for derived classes, but
+Currently wxWidgets does not define Dump for derived classes, but

 programmers may wish to use it for their own applications. Be sure to
 programmers may wish to use it for their own applications. Be sure to

-call the Dump member of the class's base class to allow all information to be dumped.
+call the Dump member of the class's base class to allow all information to be
+dumped.

 
 

-The implementation of this function just writes the class name of the object
-in debug build (\_\_WXDEBUG\_\_ defined), otherwise it does nothing.
+The implementation of this function in wxObject just writes the class name of
+the object.

 
 \membersection{wxObject::GetClassInfo}\label{wxobjectgetclassinfo}
 
 
 \membersection{wxObject::GetClassInfo}\label{wxobjectgetclassinfo}
 


@@ -108,7 +119,7 @@ by using the CLASSINFO macro.}
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if the class represented by {\it info} is the same class as
+true if the class represented by {\it info} is the same class as

 this one or is derived from it.
 
 \wxheading{Example}
 this one or is derived from it.
 
 \wxheading{Example}


@@ -117,6 +128,16 @@ this one or is derived from it.
   bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
 \end{verbatim}
 
   bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
 \end{verbatim}
 

+\membersection{wxObject::IsSameAs}\label{wxobjectissameas}
+
+\func{bool}{IsSameAs}{\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.
+
+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}
 
 \func{void}{Ref}{\param{const wxObject\& }{clone}}
 \membersection{wxObject::Ref}\label{wxobjectref}
 
 \func{void}{Ref}{\param{const wxObject\& }{clone}}


@@ -166,6 +187,17 @@ The {\bf m\_refData} member is set to NULL.
 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 \helpref{wxObjectRefData}{wxobjectrefdata}
 
 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 \helpref{wxObjectRefData}{wxobjectrefdata}
 

+\membersection{wxObject::UnShare}\label{wxobjectunshare}
+
+\func{void}{UnShare}{\void}
+
+Ensure that this object's data is not shared with any other object.
+
+if we have no
+data, it is created using CreateRefData() below, if we have shared data
+it is copied using CloneRefData(), otherwise nothing is done.
+
+

 \membersection{wxObject::operator new}\label{wxobjectnew}
 
 \func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}}
 \membersection{wxObject::operator new}\label{wxobjectnew}
 
 \func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}}


@@ -182,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.
 
 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
 \section{\class{wxObjectRefData}}\label{wxobjectrefdata}
 
 This class is used to store reference-counted data. Derive classes from this to


@@ -195,26 +231,156 @@ you will need to cast to your own derived class.
 \wxheading{See also}
 
 \helpref{wxObject}{wxobject}
 \wxheading{See also}
 
 \helpref{wxObject}{wxobject}

+\helpref{wxObjectDataPtr<T>}{wxobjectdataptr}
+\helpref{Reference counting}{trefcount}

 
 

-\latexignore{\rtfignore{\wxheading{Members}}}
+\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); }

 
 

-\membersection{wxObjectRefData::m\_count}
+    void SetPrice( int price );
+    int GetPrice() const;

 
 

-\member{int}{m\_count}
+protected:
+    virtual wxObjectRefData *CreateRefData() const;
+    virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;

 
 

-Reference count. When this goes to zero during a \helpref{wxObject::UnRef}{wxobjectunref}, an object
-can delete the {\bf wxObjectRefData} object.
+    DECLARE_DYNAMIC_CLASS(MyCar)
+};

 
 

-\membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdataconstr}
+
+// 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}}}
+
+
+\membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}

 
 \func{}{wxObjectRefData}{\void}
 
 
 \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}}
+\membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}

 
 \func{}{wxObjectRefData}{\void}
 
 
 \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{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.