docs/latex/wx/object.tex

   1 \section{\class{wxObject}}\label{wxobject}
   2
   3 This is the root class of all wxWidgets classes.
   4 It declares a virtual destructor which ensures that
   5 destructors get called for all derived class objects where necessary.
   6
   7 wxObject is the hub of a dynamic object creation
   8 scheme, enabling a program to create instances of a class only knowing
   9 its string class name, and to query the class hierarchy.
  10
  11 The class contains optional debugging versions
  12 of {\bf new} and {\bf delete}, which can help trace memory allocation
  13 and deallocation problems.
  14
  15 wxObject can be used to implement \helpref{reference counted}{trefcount} objects,
  16 such as wxPen, wxBitmap and others (see \helpref{this list}{refcountlist}).
  17
  18 \wxheading{See also}
  19
  20 \helpref{wxClassInfo}{wxclassinfo}, \helpref{Debugging overview}{debuggingoverview},\rtfsp
  21 \helpref{wxObjectRefData}{wxobjectrefdata}
  22
  23 \latexignore{\rtfignore{\wxheading{Members}}}
  24
  25 \membersection{wxObject::wxObject}\label{wxobjectctor}
  26
  27 \func{}{wxObject}{\void}
  28
  29 \func{}{wxObject}{\param{const wxObject\&}{ other}}
  30
  31 Default and copy constructors.
  32
  33 \membersection{wxObject::\destruct{wxObject}}\label{wxobjectdtor}
  34
  35 \func{}{wxObject}{\void}
  36
  37 Destructor. Performs dereferencing, for those objects
  38 that use reference counting.
  39
  40 \membersection{wxObject::m\_refData}\label{wxobjectmrefdata}
  41
  42 \member{wxObjectRefData* }{m\_refData}
  43
  44 Pointer to an object which is the object's reference-counted data.
  45
  46 \wxheading{See also}
  47
  48 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref},\rtfsp
  49 \helpref{wxObject::SetRefData}{wxobjectsetrefdata},\rtfsp
  50 \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
  51 \helpref{wxObjectRefData}{wxobjectrefdata}
  52
  53 \membersection{wxObject::Dump}\label{wxobjectdump}
  54
  55 \func{void}{Dump}{\param{ostream\&}{ stream}}
  56
  57 A virtual function that may be redefined by derived classes to allow dumping of
  58 memory states.
  59
  60 This function is only defined in debug build and doesn't exist at all if
  61 {\tt \_\_WXDEBUG\_\_} is not defined.
  62
  63 \wxheading{Parameters}
  64
  65 \docparam{stream}{Stream on which to output dump information.}
  66
  67 \wxheading{Remarks}
  68
  69 Currently wxWidgets does not define Dump for derived classes, but
  70 programmers may wish to use it for their own applications. Be sure to
  71 call the Dump member of the class's base class to allow all information to be
  72 dumped.
  73
  74 The implementation of this function in wxObject just writes the class name of
  75 the object.
  76
  77 \membersection{wxObject::GetClassInfo}\label{wxobjectgetclassinfo}
  78
  79 \func{wxClassInfo *}{GetClassInfo}{\void}
  80
  81 This virtual function is redefined for every class that requires run-time
  82 type information, when using DECLARE\_CLASS macros.
  83
  84 \membersection{wxObject::GetRefData}\label{wxobjectgetrefdata}
  85
  86 \constfunc{wxObjectRefData*}{GetRefData}{\void}
  87
  88 Returns the {\bf m\_refData} pointer.
  89
  90 \wxheading{See also}
  91
  92 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
  93 \helpref{wxObject::SetRefData}{wxobjectsetrefdata},\rtfsp
  94 \helpref{wxObjectRefData}{wxobjectrefdata}
  95
  96 \membersection{wxObject::IsKindOf}\label{wxobjectiskindof}
  97
  98 \func{bool}{IsKindOf}{\param{wxClassInfo *}{info}}
  99
 100 Determines whether this class is a subclass of (or the same class as)
 101 the given class.
 102
 103 \wxheading{Parameters}
 104
 105 \docparam{info}{A pointer to a class information object, which may be obtained
 106 by using the CLASSINFO macro.}
 107
 108 \wxheading{Return value}
 109
 110 true if the class represented by {\it info} is the same class as
 111 this one or is derived from it.
 112
 113 \wxheading{Example}
 114
 115 \begin{verbatim}
 116   bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
 117 \end{verbatim}
 118
 119 \membersection{wxObject::Ref}\label{wxobjectref}
 120
 121 \func{void}{Ref}{\param{const wxObject\& }{clone}}
 122
 123 Makes this object refer to the data in {\it clone}.
 124
 125 \wxheading{Parameters}
 126
 127 \docparam{clone}{The object to `clone'.}
 128
 129 \wxheading{Remarks}
 130
 131 First this function calls \helpref{wxObject::UnRef}{wxobjectunref} on itself
 132 to decrement (and perhaps free) the data it is currently referring to.
 133
 134 It then sets its own m\_refData to point to that of {\it clone}, and increments the reference count
 135 inside the data.
 136
 137 \wxheading{See also}
 138
 139 \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 140 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 141 \helpref{wxObjectRefData}{wxobjectrefdata}
 142
 143 \membersection{wxObject::SetRefData}\label{wxobjectsetrefdata}
 144
 145 \func{void}{SetRefData}{\param{wxObjectRefData*}{ data}}
 146
 147 Sets the {\bf m\_refData} pointer.
 148
 149 \wxheading{See also}
 150
 151 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 152 \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 153 \helpref{wxObjectRefData}{wxobjectrefdata}
 154
 155 \membersection{wxObject::UnRef}\label{wxobjectunref}
 156
 157 \func{void}{UnRef}{\void}
 158
 159 Decrements the reference count in the associated data, and if it is zero, deletes the data.
 160 The {\bf m\_refData} member is set to NULL.
 161
 162 \wxheading{See also}
 163
 164 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 165 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 166 \helpref{wxObjectRefData}{wxobjectrefdata}
 167
 168 \membersection{wxObject::operator new}\label{wxobjectnew}
 169
 170 \func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}}
 171
 172 The {\it new} operator is defined for debugging versions of the library only, when
 173 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory allocation, allowing
 174 wxDebugContext operations.
 175
 176 \membersection{wxObject::operator delete}\label{wxobjectdelete}
 177
 178 \func{void}{delete}{\param{void }{buf}}
 179
 180 The {\it delete} operator is defined for debugging versions of the library only, when
 181 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory deallocation, allowing
 182 wxDebugContext operations.
 183
 184 \section{\class{wxObjectRefData}}\label{wxobjectrefdata}
 185
 186 This class is used to store reference-counted data. Derive classes from this to
 187 store your own data. When retrieving information from a {\bf wxObject}'s reference data,
 188 you will need to cast to your own derived class.
 189
 190 \wxheading{Friends}
 191
 192 \helpref{wxObject}{wxobject}
 193
 194 \wxheading{See also}
 195
 196 \helpref{wxObject}{wxobject}
 197
 198 \latexignore{\rtfignore{\wxheading{Members}}}
 199
 200
 201 \membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}
 202
 203 \func{}{wxObjectRefData}{\void}
 204
 205 Default constructor. Initialises the {\bf m\_count} member to 1.
 206
 207 \membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}
 208
 209 \func{}{wxObjectRefData}{\void}
 210
 211 Destructor.
 212
 213 \membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount}
 214
 215 \constfunc{int}{GetRefCount}{\void}
 216
 217 Returns the reference count associated with this shared data.
 218 When this goes to zero during a \helpref{wxObject::UnRef}{wxobjectunref}, an object
 219 can delete this {\bf wxObjectRefData} object.
 220