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::IsSameAs}\label{wxobjectissameas}
 120
 121 \func{bool}{IsSameAs}{\param{const wxObject\& }{ obj}}
 122
 123 Returns \true if this object has the same data pointer as \arg{obj}. Notice
 124 that \true is returned if the data pointers are \NULL in both objects.
 125
 126 This function only does a \emph{shallow} comparison, i.e. it doesn't compare
 127 the objects pointed to by the data pointers of these objects.
 128
 129 \membersection{wxObject::Ref}\label{wxobjectref}
 130
 131 \func{void}{Ref}{\param{const wxObject\& }{clone}}
 132
 133 Makes this object refer to the data in {\it clone}.
 134
 135 \wxheading{Parameters}
 136
 137 \docparam{clone}{The object to `clone'.}
 138
 139 \wxheading{Remarks}
 140
 141 First this function calls \helpref{wxObject::UnRef}{wxobjectunref} on itself
 142 to decrement (and perhaps free) the data it is currently referring to.
 143
 144 It then sets its own m\_refData to point to that of {\it clone}, and increments the reference count
 145 inside the data.
 146
 147 \wxheading{See also}
 148
 149 \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 150 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 151 \helpref{wxObjectRefData}{wxobjectrefdata}
 152
 153 \membersection{wxObject::SetRefData}\label{wxobjectsetrefdata}
 154
 155 \func{void}{SetRefData}{\param{wxObjectRefData*}{ data}}
 156
 157 Sets the {\bf m\_refData} pointer.
 158
 159 \wxheading{See also}
 160
 161 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 162 \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 163 \helpref{wxObjectRefData}{wxobjectrefdata}
 164
 165 \membersection{wxObject::UnRef}\label{wxobjectunref}
 166
 167 \func{void}{UnRef}{\void}
 168
 169 Decrements the reference count in the associated data, and if it is zero, deletes the data.
 170 The {\bf m\_refData} member is set to NULL.
 171
 172 \wxheading{See also}
 173
 174 \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
 175 \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
 176 \helpref{wxObjectRefData}{wxobjectrefdata}
 177
 178 \membersection{wxObject::UnShare}\label{wxobjectunshare}
 179
 180 \func{void}{UnShare}{\void}
 181
 182 Ensure that this object's data is not shared with any other object.
 183
 184 if we have no
 185 data, it is created using CreateRefData() below, if we have shared data
 186 it is copied using CloneRefData(), otherwise nothing is done.
 187
 188
 189 \membersection{wxObject::operator new}\label{wxobjectnew}
 190
 191 \func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}}
 192
 193 The {\it new} operator is defined for debugging versions of the library only, when
 194 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory allocation, allowing
 195 wxDebugContext operations.
 196
 197 \membersection{wxObject::operator delete}\label{wxobjectdelete}
 198
 199 \func{void}{delete}{\param{void }{buf}}
 200
 201 The {\it delete} operator is defined for debugging versions of the library only, when
 202 the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory deallocation, allowing
 203 wxDebugContext operations.
 204
 205
 206
 207 %% wxObjectRefData
 208
 209 \section{\class{wxObjectRefData}}\label{wxobjectrefdata}
 210
 211 This class is used to store reference-counted data. Derive classes from this to
 212 store your own data. When retrieving information from a {\bf wxObject}'s reference data,
 213 you will need to cast to your own derived class.
 214
 215 \wxheading{Friends}
 216
 217 \helpref{wxObject}{wxobject}
 218
 219 \wxheading{See also}
 220
 221 \helpref{wxObject}{wxobject}
 222
 223 \latexignore{\rtfignore{\wxheading{Members}}}
 224
 225
 226 \membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}
 227
 228 \func{}{wxObjectRefData}{\void}
 229
 230 Default constructor. Initialises the internal reference count to 1.
 231
 232 \membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}
 233
 234 \func{}{wxObjectRefData}{\void}
 235
 236 Destructor. It's declared {\tt protected} so that wxObjectRefData instances will never
 237 be destroyed directly but only as result of a \helpref{DecRef}{wxobjectrefdatadecref} call.
 238
 239 \membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount}
 240
 241 \constfunc{int}{GetRefCount}{\void}
 242
 243 Returns the reference count associated with this shared data.
 244 When this goes to zero during a \helpref{DecRef}{wxobjectrefdatadecref} call, the object
 245 will auto-free itself.
 246
 247 \membersection{wxObjectRefData::DecRef}\label{wxobjectrefdatadecref}
 248
 249 \func{void}{DecRef}{\void}
 250
 251 Decrements the reference count associated with this shared data and, if it reaches zero,
 252 destroys this instance of wxObjectRefData releasing its memory.
 253
 254 Please note that after calling this function, the caller should absolutely avoid to use
 255 the pointer to this instance since it may not be valid anymore.
 256
 257 \membersection{wxObjectRefData::IncRef}\label{wxobjectrefdataincref}
 258
 259 \func{void}{IncRef}{\void}
 260
 261 Increments the reference count associated with this shared data.
 262