X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/cd4915e2c915d6c7611b38fa5182e2d84d1ca669..10ff9c616e00e4074dfdc2ac9e354605cc129c22:/docs/latex/wx/object.tex?ds=sidebyside diff --git a/docs/latex/wx/object.tex b/docs/latex/wx/object.tex index a93d8e02d1..8d8c6f07a8 100644 --- 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 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. @@ -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. -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{Derived from} + +No base class + +\wxheading{Include files} + + + +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxObject::wxObject}\label{wxobjectconstr} +\membersection{wxObject::wxObject}\label{wxobjectctor} \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} @@ -48,32 +62,29 @@ Pointer to an object which is the object's reference-counted data. \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}} -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. +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} -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 -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} @@ -108,7 +119,7 @@ by using the CLASSINFO macro.} \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} @@ -117,6 +128,16 @@ this one or is derived from it. 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}} @@ -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} +\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}} @@ -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. + + +%% wxObjectRefData + \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} +\helpref{wxObjectDataPtr}{wxobjectdataptr} +\helpref{Reference counting}{trefcount} -\latexignore{\rtfignore{\wxheading{Members}}} +\wxheading{Derived from} + +No base class + +\wxheading{Include files} + + + +\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} -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} -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.