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