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