docs/latex/wx/object.tex

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