docs/latex/wx/object.tex

   1 \section{\class{wxObject}}\label{wxobject}
   2
   3 This is the root class of many of the 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 \helpref{wxObjectDataPtr<T>}{wxobjectdataptr}
 235 \helpref{Reference counting}{trefcount}
 236
 237 \wxheading{Derived from}
 238
 239 No base class
 240
 241 \wxheading{Include files}
 242
 243 <wx/object.h>
 244
 245 \wxheading{Example}
 246
 247 \begin{verbatim}
 248
 249 // include file
 250
 251 class MyCar: public wxObject
 252 {
 253 public:
 254     MyCar() { }
 255     MyCar( int price );
 256
 257     bool IsOk() const { return m_refData != NULL; }
 258
 259     bool operator == ( const MyCar& car ) const;
 260     bool operator != (const MyCar& car) const { return !(*this == car); }
 261
 262     void SetPrice( int price );
 263     int GetPrice() const;
 264
 265 protected:
 266     virtual wxObjectRefData *CreateRefData() const;
 267     virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;
 268
 269     DECLARE_DYNAMIC_CLASS(MyCar)
 270 };
 271
 272
 273 // implementation
 274
 275 class MyCarRefData: public wxObjectRefData
 276 {
 277 public:
 278     MyCarRefData()
 279     {
 280         m_price = 0;
 281     }
 282
 283     MyCarRefData( const MyCarRefData& data )
 284         : wxObjectRefData()
 285     {
 286         m_price = data.m_price;
 287     }
 288
 289     bool operator == (const MyCarRefData& data) const
 290     {
 291         return m_price == data.m_price;
 292     }
 293
 294     int m_price;
 295 };
 296
 297
 298 #define M_CARDATA ((MyCarRefData *)m_refData)
 299
 300 IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject)
 301
 302 MyCar::MyCar( int price )
 303 {
 304     m_refData = new MyCarRefData();
 305     M_CARDATA->m_price = price;
 306 }
 307
 308 wxObjectRefData *MyCar::CreateRefData() const
 309 {
 310     return new MyCarRefData;
 311 }
 312
 313 wxObjectRefData *MyCar::CloneRefData(const wxObjectRefData *data) const
 314 {
 315     return new MyCarRefData(*(MyCarRefData *)data);
 316 }
 317
 318 bool MyCar::operator == ( const MyCar& car ) const
 319 {
 320     if (m_refData == car.m_refData) return true;
 321
 322     if (!m_refData || !car.m_refData) return false;
 323
 324     return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData );
 325 }
 326
 327 void MyCar::SetPrice( int price )
 328 {
 329     UnShare();
 330
 331     M_CARDATA->m_price = price;
 332 }
 333
 334 int MyCar::GetPrice() const
 335 {
 336     wxCHECK_MSG( IsOk(), -1, "invalid car" );
 337
 338     return (M_CARDATA->m_price);
 339 }
 340
 341 \end{verbatim}
 342
 343 \wxheading{Library}
 344
 345 \helpref{wxBase}{librarieslist}
 346
 347 \latexignore{\rtfignore{\wxheading{Members}}}
 348
 349
 350 \membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}
 351
 352 \func{}{wxObjectRefData}{\void}
 353
 354 Default constructor. Initialises the internal reference count to 1.
 355
 356 \membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}
 357
 358 \func{}{wxObjectRefData}{\void}
 359
 360 Destructor. It's declared {\tt protected} so that wxObjectRefData instances will never
 361 be destroyed directly but only as result of a \helpref{DecRef}{wxobjectrefdatadecref} call.
 362
 363 \membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount}
 364
 365 \constfunc{int}{GetRefCount}{\void}
 366
 367 Returns the reference count associated with this shared data.
 368 When this goes to zero during a \helpref{DecRef}{wxobjectrefdatadecref} call, the object
 369 will auto-free itself.
 370
 371 \membersection{wxObjectRefData::DecRef}\label{wxobjectrefdatadecref}
 372
 373 \func{void}{DecRef}{\void}
 374
 375 Decrements the reference count associated with this shared data and, if it reaches zero,
 376 destroys this instance of wxObjectRefData releasing its memory.
 377
 378 Please note that after calling this function, the caller should absolutely avoid to use
 379 the pointer to this instance since it may not be valid anymore.
 380
 381 \membersection{wxObjectRefData::IncRef}\label{wxobjectrefdataincref}
 382
 383 \func{void}{IncRef}{\void}
 384
 385 Increments the reference count associated with this shared data.
 386