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::IsRefTo}\label{wxobjectisrefto}
 120
 121 \func{bool}{IsRefTo}{\param{const wxObject *}{ obj}}
 122
 123 Returns \true if this object is referencing the \arg{obj}'s data.
 124 Note that this function only does a {\tt shallow} comparison.
 125
 126 \membersection{wxObject::Ref}\label{wxobjectref}
 127
 128 \func{void}{Ref}{\param{const wxObject\& }{clone}}
 129
 130 Makes this object refer to the data in {\it clone}.
 131
 132 \wxheading{Parameters}
 133
 134 \docparam{clone}{The object to `clone'.}
 135
 136 \wxheading{Remarks}
 137
 138 First this function calls \helpref{wxObject::UnRef}{wxobjectunref} on itself
 139 to decrement (and perhaps free) the data it is currently referring to.
 140
 141 It then sets its own m\_refData to point to that of {\it clone}, and increments the reference count
 142 inside the data.
 143
 144 \wxheading{See also}
 145
 146 \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 147 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 148 \helpref{wxObjectRefData}{wxobjectrefdata}
 149
 150 \membersection{wxObject::SetRefData}\label{wxobjectsetrefdata}
 151
 152 \func{void}{SetRefData}{\param{wxObjectRefData*}{ data}}
 153
 154 Sets the {\bf m\_refData} pointer.
 155
 156 \wxheading{See also}
 157
 158 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 159 \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 160 \helpref{wxObjectRefData}{wxobjectrefdata}
 161
 162 \membersection{wxObject::UnRef}\label{wxobjectunref}
 163
 164 \func{void}{UnRef}{\void}
 165
 166 Decrements the reference count in the associated data, and if it is zero, deletes the data.
 167 The {\bf m\_refData} member is set to NULL.
 168
 169 \wxheading{See also}
 170
 171 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 172 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 173 \helpref{wxObjectRefData}{wxobjectrefdata}
 174
 175 \membersection{wxObject::UnShare}\label{wxobjectunshare}
 176
 177 \func{void}{UnShare}{\void}
 178
 179 Ensure that this object's data is not shared with any other object.
 180
 181 if we have no
 182 data, it is created using CreateRefData() below, if we have shared data
 183 it is copied using CloneRefData(), otherwise nothing is done.
 184
 185
 186 \membersection{wxObject::operator new}\label{wxobjectnew}
 187
 188 \func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}}
 189
 190 The {\it new} operator is defined for debugging versions of the library only, when
 191 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory allocation, allowing
 192 wxDebugContext operations.
 193
 194 \membersection{wxObject::operator delete}\label{wxobjectdelete}
 195
 196 \func{void}{delete}{\param{void }{buf}}
 197
 198 The {\it delete} operator is defined for debugging versions of the library only, when
 199 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory deallocation, allowing
 200 wxDebugContext operations.
 201
 202 \section{\class{wxObjectRefData}}\label{wxobjectrefdata}
 203
 204 This class is used to store reference-counted data. Derive classes from this to
 205 store your own data. When retrieving information from a {\bf wxObject}'s reference data,
 206 you will need to cast to your own derived class.
 207
 208 \wxheading{Friends}
 209
 210 \helpref{wxObject}{wxobject}
 211
 212 \wxheading{See also}
 213
 214 \helpref{wxObject}{wxobject}
 215
 216 \latexignore{\rtfignore{\wxheading{Members}}}
 217
 218
 219 \membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}
 220
 221 \func{}{wxObjectRefData}{\void}
 222
 223 Default constructor. Initialises the {\bf m\_count} member to 1.
 224
 225 \membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}
 226
 227 \func{}{wxObjectRefData}{\void}
 228
 229 Destructor.
 230
 231 \membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount}
 232
 233 \constfunc{int}{GetRefCount}{\void}
 234
 235 Returns the reference count associated with this shared data.
 236 When this goes to zero during a \helpref{wxObject::UnRef}{wxobjectunref}, an object
 237 can delete this {\bf wxObjectRefData} object.
 238