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 \wxheading{Derived from}
  24
  25 No base class
  26
  27 \wxheading{Include files}
  28
  29 <wx/object.h>
  30
  31 \latexignore{\rtfignore{\wxheading{Members}}}
  32
  33 \membersection{wxObject::wxObject}\label{wxobjectctor}
  34
  35 \func{}{wxObject}{\void}
  36
  37 \func{}{wxObject}{\param{const wxObject\&}{ other}}
  38
  39 Default and copy constructors.
  40
  41 \membersection{wxObject::\destruct{wxObject}}\label{wxobjectdtor}
  42
  43 \func{}{wxObject}{\void}
  44
  45 Destructor. Performs dereferencing, for those objects
  46 that use reference counting.
  47
  48 \membersection{wxObject::m\_refData}\label{wxobjectmrefdata}
  49
  50 \member{wxObjectRefData* }{m\_refData}
  51
  52 Pointer to an object which is the object's reference-counted data.
  53
  54 \wxheading{See also}
  55
  56 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref},\rtfsp
  57 \helpref{wxObject::SetRefData}{wxobjectsetrefdata},\rtfsp
  58 \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
  59 \helpref{wxObjectRefData}{wxobjectrefdata}
  60
  61 \membersection{wxObject::Dump}\label{wxobjectdump}
  62
  63 \func{void}{Dump}{\param{ostream\&}{ stream}}
  64
  65 A virtual function that may be redefined by derived classes to allow dumping of
  66 memory states.
  67
  68 This function is only defined in debug build and doesn't exist at all if
  69 {\tt \_\_WXDEBUG\_\_} is not defined.
  70
  71 \wxheading{Parameters}
  72
  73 \docparam{stream}{Stream on which to output dump information.}
  74
  75 \wxheading{Remarks}
  76
  77 Currently wxWidgets does not define Dump for derived classes, but
  78 programmers may wish to use it for their own applications. Be sure to
  79 call the Dump member of the class's base class to allow all information to be
  80 dumped.
  81
  82 The implementation of this function in wxObject just writes the class name of
  83 the object.
  84
  85 \membersection{wxObject::GetClassInfo}\label{wxobjectgetclassinfo}
  86
  87 \func{wxClassInfo *}{GetClassInfo}{\void}
  88
  89 This virtual function is redefined for every class that requires run-time
  90 type information, when using DECLARE\_CLASS macros.
  91
  92 \membersection{wxObject::GetRefData}\label{wxobjectgetrefdata}
  93
  94 \constfunc{wxObjectRefData*}{GetRefData}{\void}
  95
  96 Returns the {\bf m\_refData} pointer.
  97
  98 \wxheading{See also}
  99
 100 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 101 \helpref{wxObject::SetRefData}{wxobjectsetrefdata},\rtfsp
 102 \helpref{wxObjectRefData}{wxobjectrefdata}
 103
 104 \membersection{wxObject::IsKindOf}\label{wxobjectiskindof}
 105
 106 \func{bool}{IsKindOf}{\param{wxClassInfo *}{info}}
 107
 108 Determines whether this class is a subclass of (or the same class as)
 109 the given class.
 110
 111 \wxheading{Parameters}
 112
 113 \docparam{info}{A pointer to a class information object, which may be obtained
 114 by using the CLASSINFO macro.}
 115
 116 \wxheading{Return value}
 117
 118 true if the class represented by {\it info} is the same class as
 119 this one or is derived from it.
 120
 121 \wxheading{Example}
 122
 123 \begin{verbatim}
 124   bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
 125 \end{verbatim}
 126
 127 \membersection{wxObject::IsSameAs}\label{wxobjectissameas}
 128
 129 \func{bool}{IsSameAs}{\param{const wxObject\& }{ obj}}
 130
 131 Returns \true if this object has the same data pointer as \arg{obj}. Notice
 132 that \true is returned if the data pointers are \NULL in both objects.
 133
 134 This function only does a \emph{shallow} comparison, i.e. it doesn't compare
 135 the objects pointed to by the data pointers of these objects.
 136
 137 \membersection{wxObject::Ref}\label{wxobjectref}
 138
 139 \func{void}{Ref}{\param{const wxObject\& }{clone}}
 140
 141 Makes this object refer to the data in {\it clone}.
 142
 143 \wxheading{Parameters}
 144
 145 \docparam{clone}{The object to `clone'.}
 146
 147 \wxheading{Remarks}
 148
 149 First this function calls \helpref{wxObject::UnRef}{wxobjectunref} on itself
 150 to decrement (and perhaps free) the data it is currently referring to.
 151
 152 It then sets its own m\_refData to point to that of {\it clone}, and increments the reference count
 153 inside the data.
 154
 155 \wxheading{See also}
 156
 157 \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 158 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 159 \helpref{wxObjectRefData}{wxobjectrefdata}
 160
 161 \membersection{wxObject::SetRefData}\label{wxobjectsetrefdata}
 162
 163 \func{void}{SetRefData}{\param{wxObjectRefData*}{ data}}
 164
 165 Sets the {\bf m\_refData} pointer.
 166
 167 \wxheading{See also}
 168
 169 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 170 \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 171 \helpref{wxObjectRefData}{wxobjectrefdata}
 172
 173 \membersection{wxObject::UnRef}\label{wxobjectunref}
 174
 175 \func{void}{UnRef}{\void}
 176
 177 Decrements the reference count in the associated data, and if it is zero, deletes the data.
 178 The {\bf m\_refData} member is set to NULL.
 179
 180 \wxheading{See also}
 181
 182 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 183 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 184 \helpref{wxObjectRefData}{wxobjectrefdata}
 185
 186 \membersection{wxObject::UnShare}\label{wxobjectunshare}
 187
 188 \func{void}{UnShare}{\void}
 189
 190 Ensure that this object's data is not shared with any other object.
 191
 192 if we have no
 193 data, it is created using CreateRefData() below, if we have shared data
 194 it is copied using CloneRefData(), otherwise nothing is done.
 195
 196
 197 \membersection{wxObject::operator new}\label{wxobjectnew}
 198
 199 \func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}}
 200
 201 The {\it new} operator is defined for debugging versions of the library only, when
 202 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory allocation, allowing
 203 wxDebugContext operations.
 204
 205 \membersection{wxObject::operator delete}\label{wxobjectdelete}
 206
 207 \func{void}{delete}{\param{void }{buf}}
 208
 209 The {\it delete} operator is defined for debugging versions of the library only, when
 210 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory deallocation, allowing
 211 wxDebugContext operations.
 212
 213
 214
 215 %% wxObjectRefData
 216
 217 \section{\class{wxObjectRefData}}\label{wxobjectrefdata}
 218
 219 This class is used to store reference-counted data. Derive classes from this to
 220 store your own data. When retrieving information from a {\bf wxObject}'s reference data,
 221 you will need to cast to your own derived class.
 222
 223 \wxheading{Friends}
 224
 225 \helpref{wxObject}{wxobject}
 226
 227 \wxheading{See also}
 228
 229 \helpref{wxObject}{wxobject}
 230
 231 \wxheading{Derived from}
 232
 233 No base class
 234
 235 \wxheading{Include files}
 236
 237 <wx/object.h>
 238
 239 \latexignore{\rtfignore{\wxheading{Members}}}
 240
 241
 242 \membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}
 243
 244 \func{}{wxObjectRefData}{\void}
 245
 246 Default constructor. Initialises the internal reference count to 1.
 247
 248 \membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}
 249
 250 \func{}{wxObjectRefData}{\void}
 251
 252 Destructor. It's declared {\tt protected} so that wxObjectRefData instances will never
 253 be destroyed directly but only as result of a \helpref{DecRef}{wxobjectrefdatadecref} call.
 254
 255 \membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount}
 256
 257 \constfunc{int}{GetRefCount}{\void}
 258
 259 Returns the reference count associated with this shared data.
 260 When this goes to zero during a \helpref{DecRef}{wxobjectrefdatadecref} call, the object
 261 will auto-free itself.
 262
 263 \membersection{wxObjectRefData::DecRef}\label{wxobjectrefdatadecref}
 264
 265 \func{void}{DecRef}{\void}
 266
 267 Decrements the reference count associated with this shared data and, if it reaches zero,
 268 destroys this instance of wxObjectRefData releasing its memory.
 269
 270 Please note that after calling this function, the caller should absolutely avoid to use
 271 the pointer to this instance since it may not be valid anymore.
 272
 273 \membersection{wxObjectRefData::IncRef}\label{wxobjectrefdataincref}
 274
 275 \func{void}{IncRef}{\void}
 276
 277 Increments the reference count associated with this shared data.
 278