]> git.saurik.com Git - wxWidgets.git/blame - interface/object.h
use wx-style header and commets; fix indentation to be 4 spaces; move Doxygen comment...
[wxWidgets.git] / interface / object.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: object.h
e54c96f1 3// Purpose: interface of wxObjectRefData
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxObjectRefData
11 @wxheader{object.h}
7c913512 12
23324ae1
FM
13 This class is used to store reference-counted data. Derive classes from this to
14 store your own data. When retrieving information from a @b wxObject's reference
15 data,
16 you will need to cast to your own derived class.
7c913512 17
23324ae1
FM
18 @library{wxbase}
19 @category{FIXME}
7c913512 20
e54c96f1 21 @see wxObject, wxObjectDataPtrT(), @ref overview_trefcount "Reference counting"
23324ae1 22*/
7c913512 23class wxObjectRefData
23324ae1
FM
24{
25public:
26 /**
27 Default constructor. Initialises the internal reference count to 1.
28 */
29 wxObjectRefData();
30
31 /**
32 Destructor. It's declared @c protected so that wxObjectRefData instances will
33 never
34 be destroyed directly but only as result of a DecRef() call.
35 */
36 wxObjectRefData();
37
38 /**
39 Decrements the reference count associated with this shared data and, if it
40 reaches zero,
41 destroys this instance of wxObjectRefData releasing its memory.
23324ae1
FM
42 Please note that after calling this function, the caller should absolutely
43 avoid to use
44 the pointer to this instance since it may not be valid anymore.
45 */
46 void DecRef();
47
48 /**
49 Returns the reference count associated with this shared data.
50 When this goes to zero during a DecRef() call, the object
51 will auto-free itself.
52 */
328f5751 53 int GetRefCount() const;
23324ae1
FM
54
55 /**
56 Increments the reference count associated with this shared data.
57 */
58 void IncRef();
59};
60
61
e54c96f1 62
23324ae1
FM
63/**
64 @class wxObject
65 @wxheader{object.h}
7c913512 66
23324ae1
FM
67 This is the root class of many of the wxWidgets classes.
68 It declares a virtual destructor which ensures that
69 destructors get called for all derived class objects where necessary.
7c913512 70
23324ae1
FM
71 wxObject is the hub of a dynamic object creation
72 scheme, enabling a program to create instances of a class only knowing
73 its string class name, and to query the class hierarchy.
7c913512 74
23324ae1
FM
75 The class contains optional debugging versions
76 of @b new and @b delete, which can help trace memory allocation
77 and deallocation problems.
7c913512 78
23324ae1
FM
79 wxObject can be used to implement @ref overview_trefcount "reference counted"
80 objects,
81 such as wxPen, wxBitmap and others (see @ref overview_refcountlist "this list").
7c913512 82
23324ae1
FM
83 @library{wxbase}
84 @category{rtti}
7c913512 85
e54c96f1 86 @see wxClassInfo, @ref overview_debuggingoverview, wxObjectRefData
23324ae1 87*/
7c913512 88class wxObject
23324ae1
FM
89{
90public:
91 //@{
92 /**
93 Default and copy constructors.
94 */
95 wxObject();
7c913512 96 wxObject(const wxObject& other);
23324ae1
FM
97 //@}
98
99 /**
100 Destructor. Performs dereferencing, for those objects
101 that use reference counting.
102 */
103 wxObject();
104
105 /**
106 A virtual function that may be redefined by derived classes to allow dumping of
107 memory states.
23324ae1
FM
108 This function is only defined in debug build and doesn't exist at all if
109 @c __WXDEBUG__ is not defined.
3c4f71cc 110
7c913512 111 @param stream
4cc4bfaf 112 Stream on which to output dump information.
3c4f71cc 113
23324ae1 114 @remarks Currently wxWidgets does not define Dump for derived classes,
4cc4bfaf
FM
115 but programmers may wish to use it for their own
116 applications. Be sure to call the Dump member of the
117 class's base class to allow all information to be
118 dumped.
23324ae1
FM
119 */
120 void Dump(ostream& stream);
121
122 /**
123 This virtual function is redefined for every class that requires run-time
124 type information, when using DECLARE_CLASS macros.
125 */
4cc4bfaf 126 wxClassInfo* GetClassInfo();
23324ae1
FM
127
128 /**
129 Returns the @b m_refData pointer.
3c4f71cc 130
4cc4bfaf
FM
131 @see Ref(), UnRef(), wxObject::m_refData, SetRefData(),
132 wxObjectRefData
23324ae1 133 */
328f5751 134 wxObjectRefData* GetRefData() const;
23324ae1
FM
135
136 /**
137 Determines whether this class is a subclass of (or the same class as)
138 the given class.
3c4f71cc 139
7c913512 140 @param info
4cc4bfaf
FM
141 A pointer to a class information object, which may be obtained
142 by using the CLASSINFO macro.
3c4f71cc 143
23324ae1 144 @returns @true if the class represented by info is the same class as this
4cc4bfaf 145 one or is derived from it.
23324ae1 146 */
4cc4bfaf 147 bool IsKindOf(wxClassInfo* info);
23324ae1
FM
148
149 /**
150 Returns @true if this object has the same data pointer as @e obj. Notice
151 that @true is returned if the data pointers are @NULL in both objects.
23324ae1
FM
152 This function only does a shallow comparison, i.e. it doesn't compare
153 the objects pointed to by the data pointers of these objects.
154 */
155 bool IsSameAs(const wxObject& obj);
156
157 /**
158 Makes this object refer to the data in @e clone.
3c4f71cc 159
7c913512 160 @param clone
4cc4bfaf 161 The object to 'clone'.
3c4f71cc 162
23324ae1 163 @remarks First this function calls UnRef() on itself to decrement
4cc4bfaf
FM
164 (and perhaps free) the data it is currently referring
165 to.
3c4f71cc 166
4cc4bfaf
FM
167 @see UnRef(), wxObject::m_refData, SetRefData(),
168 GetRefData(), wxObjectRefData
23324ae1 169 */
4cc4bfaf 170 void Ref(const wxObject& clone);
23324ae1
FM
171
172 /**
173 Sets the @b m_refData pointer.
3c4f71cc 174
4cc4bfaf
FM
175 @see Ref(), UnRef(), wxObject::m_refData, GetRefData(),
176 wxObjectRefData
23324ae1
FM
177 */
178 void SetRefData(wxObjectRefData* data);
179
180 /**
181 Decrements the reference count in the associated data, and if it is zero,
182 deletes the data.
183 The @b m_refData member is set to @NULL.
3c4f71cc 184
4cc4bfaf
FM
185 @see Ref(), wxObject::m_refData, SetRefData(),
186 GetRefData(), wxObjectRefData
23324ae1
FM
187 */
188 void UnRef();
189
190 /**
191 Ensure that this object's data is not shared with any other object.
23324ae1
FM
192 if we have no
193 data, it is created using CreateRefData() below, if we have shared data
194 it is copied using CloneRefData(), otherwise nothing is done.
195 */
196 void UnShare();
197
198 /**
199 wxObjectRefData* m_refData
23324ae1 200 Pointer to an object which is the object's reference-counted data.
3c4f71cc 201
4cc4bfaf
FM
202 @see Ref(), UnRef(), SetRefData(),
203 GetRefData(), wxObjectRefData
23324ae1
FM
204 */
205
206
207 /**
208 The @e delete operator is defined for debugging versions of the library only,
209 when
210 the identifier __WXDEBUG__ is defined. It takes over memory deallocation,
211 allowing
212 wxDebugContext operations.
213 */
214 void delete(void buf);
215
216 /**
217 The @e new operator is defined for debugging versions of the library only, when
218 the identifier __WXDEBUG__ is defined. It takes over memory allocation, allowing
219 wxDebugContext operations.
220 */
4cc4bfaf
FM
221 void* new(size_t size, const wxString& filename = NULL,
222 int lineNum = 0);
23324ae1
FM
223};
224
225
e54c96f1 226
23324ae1
FM
227/**
228 @class wxClassInfo
229 @wxheader{object.h}
7c913512 230
23324ae1
FM
231 This class stores meta-information about classes. Instances of this class are
232 not generally defined directly by an application, but indirectly through use
233 of macros such as @b DECLARE_DYNAMIC_CLASS and @b IMPLEMENT_DYNAMIC_CLASS.
7c913512 234
23324ae1
FM
235 @library{wxbase}
236 @category{rtti}
7c913512 237
e54c96f1 238 @see Overview(), wxObject
23324ae1 239*/
7c913512 240class wxClassInfo
23324ae1
FM
241{
242public:
243 /**
244 Constructs a wxClassInfo object. The supplied macros implicitly construct
245 objects of this
246 class, so there is no need to create such objects explicitly in an application.
247 */
4cc4bfaf
FM
248 wxClassInfo(const wxChar* className,
249 const wxClassInfo* baseClass1,
250 const wxClassInfo* baseClass2,
23324ae1
FM
251 int size, wxObjectConstructorFn fn);
252
253 /**
254 Creates an object of the appropriate kind. Returns @NULL if the class has not
255 been declared
256 dynamically creatable (typically, it is an abstract class).
257 */
328f5751 258 wxObject* CreateObject() const;
23324ae1
FM
259
260 /**
261 Finds the wxClassInfo object for a class of the given string name.
262 */
4cc4bfaf 263 static wxClassInfo* FindClass(wxChar* name);
23324ae1
FM
264
265 /**
266 Returns the name of the first base class (@NULL if none).
267 */
328f5751 268 wxChar* GetBaseClassName1() const;
23324ae1
FM
269
270 /**
271 Returns the name of the second base class (@NULL if none).
272 */
328f5751 273 wxChar* GetBaseClassName2() const;
23324ae1
FM
274
275 /**
276 Returns the string form of the class name.
277 */
328f5751 278 wxChar* GetClassName() const;
23324ae1
FM
279
280 /**
281 Returns the size of the class.
282 */
328f5751 283 int GetSize() const;
23324ae1
FM
284
285 /**
286 Initializes pointers in the wxClassInfo objects for fast execution
287 of IsKindOf. Called in base wxWidgets library initialization.
288 */
289 static void InitializeClasses();
290
291 /**
292 Returns @true if this class info can create objects of the associated class.
293 */
328f5751 294 bool IsDynamic() const;
23324ae1
FM
295
296 /**
297 Returns @true if this class is a kind of (inherits from) the given class.
298 */
299 bool IsKindOf(wxClassInfo* info);
300};
301
302
e54c96f1 303
23324ae1
FM
304/**
305 @class wxObjectDataPtrT
306 @wxheader{object.h}
7c913512
FM
307
308 This is helper template class primarily written to avoid memory
23324ae1 309 leaks because of missing calls to wxObjectRefData::DecRef.
7c913512 310
23324ae1
FM
311 Despite the name this template can actually be used as a
312 smart pointer for any class implementing the reference
313 counting interface which only consists of the two methods
314 @b T::IncRef() and @b T::DecRef().
7c913512 315
23324ae1
FM
316 The difference to wxSharedPtr is that
317 wxObjectDataPtr relies on the reference counting to be in
318 the class pointed to where as wxSharedPtr implements the
319 reference counting itself.
7c913512 320
23324ae1
FM
321 @library{wxbase}
322 @category{FIXME}
7c913512 323
e54c96f1 324 @see wxObject, wxObjectRefData, @ref overview_trefcount "Reference counting"
23324ae1 325*/
7c913512 326class wxObjectDataPtr<T>
23324ae1
FM
327{
328public:
329 //@{
330 /**
331 This copy constructor increases the count of the reference
4cc4bfaf 332 counted object to which @a tocopy points and then this
23324ae1
FM
333 class will point to, as well.
334 */
4cc4bfaf 335 wxObjectDataPtrT(T* ptr = NULL);
7c913512 336 wxObjectDataPtrT(const wxObjectDataPtr<T>& tocopy);
23324ae1
FM
337 //@}
338
339 /**
340 Decreases the reference count of the object to which this
341 class points.
342 */
343 ~wxObjectDataPtrT();
344
345 /**
346 Gets a pointer to the reference counted object to which
347 this class points.
348 */
328f5751 349 T* get() const;
23324ae1
FM
350
351 /**
7c913512 352 Conversion to a boolean expression (in a variant which is not
23324ae1
FM
353 convertable to anything but a boolean expression). If this class
354 contains a valid pointer it will return @e @true, if it contains
355 a @NULL pointer it will return @e @false.
356 */
328f5751 357 operator unspecified_bool_type() const;
23324ae1
FM
358
359 /**
360 Returns a reference to the object. If the internal pointer is @NULL
361 this method will cause an assert in debug mode.
362 */
328f5751 363 T operator*() const;
23324ae1
FM
364
365 /**
366 Returns a pointer to the reference counted object to which
367 this class points. If this the internal pointer is @NULL,
368 this method will assert in debug mode.
369 */
328f5751 370 T* operator-() const;
23324ae1
FM
371
372 //@{
373 /**
374 Assignment operators.
375 */
376 wxObjectDataPtrT& operator operator=(const wxObjectDataPtr<T>& tocopy);
7c913512 377 wxObjectDataPtrT& operator operator=(T* ptr);
23324ae1
FM
378 //@}
379};
380
381
e54c96f1 382
23324ae1
FM
383// ============================================================================
384// Global functions/macros
385// ============================================================================
386
8af7f7c1
BP
387/** @ingroup group_funcmacro_rtti */
388//@{
389
23324ae1 390/**
8af7f7c1
BP
391 Returns a pointer to the wxClassInfo object associated with this class.
392
393 @header{wx/object.h}
394*/
395#define CLASSINFO( className )
396
397/**
398 Used inside a class declaration to declare that the class should be made
399 known to the class hierarchy, but objects of this class cannot be created
400 dynamically. The same as DECLARE_ABSTRACT_CLASS().
401
402 @header{wx/object.h}
23324ae1 403*/
8af7f7c1 404#define DECLARE_CLASS( className )
23324ae1
FM
405
406/**
407 Used inside a class declaration to declare that the class should be
408 made known to the class hierarchy, but objects of this class cannot be created
8af7f7c1
BP
409 dynamically. The same as DECLARE_CLASS().
410
411 @header{wx/object.h}
412
23324ae1 413 Example:
4cc4bfaf 414
23324ae1
FM
415 @code
416 class wxCommand: public wxObject
417 {
8af7f7c1 418 DECLARE_ABSTRACT_CLASS(wxCommand)
7c913512 419
8af7f7c1
BP
420 private:
421 ...
422 public:
423 ...
23324ae1
FM
424 };
425 @endcode
426*/
8af7f7c1 427#define DECLARE_ABSTRACT_CLASS( className )
23324ae1
FM
428
429/**
8af7f7c1
BP
430 Used inside a class declaration to make the class known to wxWidgets RTTI
431 system and also declare that the objects of this class should be
432 dynamically creatable from run-time type information. Notice that this
433 implies that the class should have a default constructor, if this is not
434 the case consider using DECLARE_CLASS().
23324ae1 435
8af7f7c1 436 @header{wx/object.h}
7c913512 437
8af7f7c1
BP
438 Example:
439
440 @code
441 class wxFrame: public wxWindow
442 {
443 DECLARE_DYNAMIC_CLASS(wxFrame)
444
445 private:
446 const wxString& frameTitle;
447 public:
448 ...
449 };
450 @endcode
23324ae1 451*/
7baebf86 452#define DECLARE_DYNAMIC_CLASS( className )
23324ae1
FM
453
454/**
8af7f7c1
BP
455 Used in a C++ implementation file to complete the declaration of a class
456 that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS().
457
458 @header{wx/object.h}
23324ae1 459*/
8af7f7c1 460#define IMPLEMENT_CLASS( className, baseClassName )
23324ae1
FM
461
462/**
8af7f7c1
BP
463 Used in a C++ implementation file to complete the declaration of a class
464 that has run-time type information and two base classes. The same as
465 IMPLEMENT_ABSTRACT_CLASS2().
7c913512 466
8af7f7c1 467 @header{wx/object.h}
23324ae1 468*/
8af7f7c1 469#define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 )
23324ae1
FM
470
471/**
8af7f7c1
BP
472 Used in a C++ implementation file to complete the declaration of a class
473 that has run-time type information. The same as IMPLEMENT_CLASS().
474
475 @header{wx/object.h}
476
23324ae1 477 Example:
4cc4bfaf 478
23324ae1
FM
479 @code
480 IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
7c913512 481
23324ae1
FM
482 wxCommand::wxCommand(void)
483 {
8af7f7c1 484 ...
23324ae1
FM
485 }
486 @endcode
487*/
8af7f7c1 488#define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName )
23324ae1
FM
489
490/**
8af7f7c1
BP
491 Used in a C++ implementation file to complete the declaration of a class
492 that has run-time type information and two base classes. The same as
493 IMPLEMENT_CLASS2().
494
495 @header{wx/object.h}
23324ae1 496*/
8af7f7c1 497#define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 )
23324ae1
FM
498
499/**
8af7f7c1
BP
500 Used in a C++ implementation file to complete the declaration of a class
501 that has run-time type information, and whose instances can be created
502 dynamically.
7c913512 503
8af7f7c1
BP
504 @header{wx/object.h}
505
506 Example:
507
508 @code
509 IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
510
511 wxFrame::wxFrame(void)
512 {
513 ...
514 }
515 @endcode
23324ae1 516*/
8af7f7c1 517#define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName )
23324ae1
FM
518
519/**
8af7f7c1
BP
520 Used in a C++ implementation file to complete the declaration of a class
521 that has run-time type information, and whose instances can be created
522 dynamically. Use this for classes derived from two base classes.
523
524 @header{wx/object.h}
23324ae1 525*/
8af7f7c1 526#define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 )
23324ae1
FM
527
528/**
8af7f7c1
BP
529 Same as const_cast<T>(x) if the compiler supports const cast or (T)x for
530 old compilers. Unlike wxConstCast(), the cast it to the type T and not to
531 T * and also the order of arguments is the same as for the standard cast.
532
533 @header{wx/defs.h}
534
535 @see wx_reinterpret_cast(), wx_static_cast()
23324ae1 536*/
8af7f7c1 537#define wx_const_cast(T, x)
23324ae1
FM
538
539/**
8af7f7c1
BP
540 Same as reinterpret_cast<T>(x) if the compiler supports reinterpret cast or
541 (T)x for old compilers.
4cc4bfaf 542
8af7f7c1 543 @header{wx/defs.h}
7c913512 544
8af7f7c1 545 @see wx_const_cast(), wx_static_cast()
23324ae1 546*/
8af7f7c1 547#define wx_reinterpret_cast(T, x)
23324ae1
FM
548
549/**
8af7f7c1
BP
550 Same as static_cast<T>(x) if the compiler supports static cast or (T)x for
551 old compilers. Unlike wxStaticCast(), there are no checks being done and
552 the meaning of the macro arguments is exactly the same as for the standard
553 static cast, i.e. T is the full type name and star is not appended to it.
7c913512 554
8af7f7c1
BP
555 @header{wx/defs.h}
556
557 @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast()
23324ae1 558*/
8af7f7c1 559#define wx_static_cast(T, x)
23324ae1
FM
560
561/**
8af7f7c1
BP
562 This case doesn’t correspond to any standard cast but exists solely to make
563 casts which possibly result in a truncation of an integer value more
564 readable.
565
566 @header{wx/defs.h}
23324ae1 567*/
8af7f7c1 568#define wx_truncate_cast(T, x)
23324ae1
FM
569
570/**
8af7f7c1
BP
571 This macro expands into const_cast<classname *>(ptr) if the compiler
572 supports const_cast or into an old, C-style cast, otherwise.
4cc4bfaf 573
8af7f7c1 574 @header{wx/defs.h}
7c913512 575
8af7f7c1 576 @see wx_const_cast(), wxDynamicCast(), wxStaticCast()
23324ae1 577*/
7baebf86 578#define wxConstCast( ptr, classname )
23324ae1
FM
579
580/**
581 This is defined in debug mode to be call the redefined new operator
582 with filename and line number arguments. The definition is:
4cc4bfaf 583
23324ae1
FM
584 @code
585 #define WXDEBUG_NEW new(__FILE__,__LINE__)
586 @endcode
7c913512 587
23324ae1 588 In non-debug mode, this is defined as the normal new operator.
8af7f7c1
BP
589
590 @header{wx/object.h}
23324ae1 591*/
8af7f7c1 592#define WXDEBUG_NEW( arg )
23324ae1
FM
593
594/**
8af7f7c1
BP
595 This macro returns the pointer @e ptr cast to the type @e classname * if
596 the pointer is of this type (the check is done during the run-time) or
597 @NULL otherwise. Usage of this macro is preferred over obsoleted
598 wxObject::IsKindOf() function.
7c913512 599
8af7f7c1
BP
600 The @e ptr argument may be @NULL, in which case @NULL will be returned.
601
602 @header{wx/object.h}
603
604 Example:
605
606 @code
607 wxWindow *win = wxWindow::FindFocus();
608 wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
609 if ( text )
610 {
611 // a text control has the focus...
612 }
613 else
614 {
615 // no window has the focus or it is not a text control
616 }
617 @endcode
618
619 @see @ref overview_runtimeclassoverview "RTTI Overview",
620 wxDynamicCastThis(), wxConstCast(), wxStaticCast()
23324ae1 621*/
7baebf86 622#define wxDynamicCast( ptr, classname )
23324ae1
FM
623
624/**
8af7f7c1
BP
625 This macro is equivalent to wxDynamicCast() but the latter provokes
626 spurious compilation warnings from some compilers (because it tests whether
627 @c this pointer is non-@NULL which is always true), so this macro should be
628 used to avoid them.
7c913512 629
8af7f7c1
BP
630 @header{wx/object.h}
631
632 @see wxDynamicCast()
23324ae1 633*/
7baebf86 634#define wxDynamicCastThis( classname )
23324ae1
FM
635
636/**
8af7f7c1
BP
637 This macro checks that the cast is valid in debug mode (an assert failure
638 will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the
639 result of executing an equivalent of static_cast<classname *>(ptr).
4cc4bfaf 640
8af7f7c1 641 @header{wx/object.h}
7c913512 642
8af7f7c1 643 @see wx_static_cast(), wxDynamicCast(), wxConstCast()
23324ae1 644*/
7baebf86 645#define wxStaticCast( ptr, classname )
8af7f7c1
BP
646
647/**
648 Creates and returns an object of the given class, if the class has been
649 registered with the dynamic class system using DECLARE... and IMPLEMENT...
650 macros.
651
652 @header{wx/object.h}
653*/
7baebf86 654wxObject *wxCreateDynamicObject(const wxString& className);
8af7f7c1
BP
655
656//@}
23324ae1 657