]>
git.saurik.com Git - wxWidgets.git/blob - interface/object.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxObjectRefData
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxObjectRefData
13 This class is used to store reference-counted data. Derive classes from this
14 to store your own data. When retrieving information from a wxObject's reference
15 data, you will need to cast to your own derived class.
20 @see wxObject, wxObjectDataPtr<T>, @ref overview_refcount "Reference counting"
27 class MyCar: public wxObject
33 bool IsOk() const { return m_refData != NULL; }
35 bool operator == ( const MyCar& car ) const;
36 bool operator != (const MyCar& car) const { return !(*this == car); }
38 void SetPrice( int price );
42 virtual wxObjectRefData *CreateRefData() const;
43 virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;
45 DECLARE_DYNAMIC_CLASS(MyCar)
51 class MyCarRefData: public wxObjectRefData
59 MyCarRefData( const MyCarRefData& data )
62 m_price = data.m_price;
65 bool operator == (const MyCarRefData& data) const
67 return m_price == data.m_price;
74 #define M_CARDATA ((MyCarRefData *)m_refData)
76 IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject)
78 MyCar::MyCar( int price )
80 m_refData = new MyCarRefData();
81 M_CARDATA->m_price = price;
84 wxObjectRefData *MyCar::CreateRefData() const
86 return new MyCarRefData;
89 wxObjectRefData *MyCar::CloneRefData(const wxObjectRefData *data) const
91 return new MyCarRefData(*(MyCarRefData *)data);
94 bool MyCar::operator == ( const MyCar& car ) const
96 if (m_refData == car.m_refData) return true;
98 if (!m_refData || !car.m_refData) return false;
100 return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData );
103 void MyCar::SetPrice( int price )
107 M_CARDATA->m_price = price;
110 int MyCar::GetPrice() const
112 wxCHECK_MSG( IsOk(), -1, "invalid car" );
114 return (M_CARDATA->m_price);
119 class wxObjectRefData
123 Default constructor. Initialises the internal reference count to 1.
128 Destructor. It's declared @c protected so that wxObjectRefData instances
129 will never be destroyed directly but only as result of a DecRef() call.
134 Decrements the reference count associated with this shared data and, if
135 it reaches zero, destroys this instance of wxObjectRefData releasing its
138 Please note that after calling this function, the caller should
139 absolutely avoid to use the pointer to this instance since it may not be
145 Returns the reference count associated with this shared data.
146 When this goes to zero during a DecRef() call, the object will auto-free
149 int GetRefCount() const;
152 Increments the reference count associated with this shared data.
163 This is the root class of many of the wxWidgets classes.
164 It declares a virtual destructor which ensures that destructors get called
165 for all derived class objects where necessary.
167 wxObject is the hub of a dynamic object creation scheme, enabling a program
168 to create instances of a class only knowing its string class name, and to
169 query the class hierarchy.
171 The class contains optional debugging versions of @b new and @b delete, which
172 can help trace memory allocation and deallocation problems.
174 wxObject can be used to implement @ref overview_refcount "reference counted"
175 objects, such as wxPen, wxBitmap and others (see @ref overview_refcount_list
181 @see wxClassInfo, @ref overview_debugging, wxObjectRefData
189 Default and copy constructors.
191 wxObject(const wxObject
& other
);
195 Destructor. Performs dereferencing, for those objects
196 that use reference counting.
201 A virtual function that may be redefined by derived classes to allow dumping of
204 This function is only defined in debug build and doesn't exist at all if
205 @c __WXDEBUG__ is not defined.
208 Stream on which to output dump information.
210 @remarks Currently wxWidgets does not define Dump for derived classes,
211 but programmers may wish to use it for their own
212 applications. Be sure to call the Dump member of the
213 class's base class to allow all information to be
216 The implementation of this function in wxObject just writes
217 the class name of the object.
221 void Dump(ostream
& stream
);
224 This virtual function is redefined for every class that requires run-time
225 type information, when using @c DECLARE_CLASS macros.
227 wxClassInfo
* GetClassInfo();
230 Returns the @b m_refData pointer.
232 @see Ref(), UnRef(), wxObject::m_refData, SetRefData(),
235 wxObjectRefData
* GetRefData() const;
238 Determines whether this class is a subclass of (or the same class as)
242 A pointer to a class information object, which may be obtained
243 by using the @c CLASSINFO macro.
245 @returns @true if the class represented by info is the same class as this
246 one or is derived from it.
250 bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
253 bool IsKindOf(wxClassInfo
* info
);
256 @returns @true if this object has the same data pointer as @e obj. Notice
257 that @true is returned if the data pointers are @NULL in both objects.
259 This function only does a shallow comparison, i.e. it doesn't compare
260 the objects pointed to by the data pointers of these objects.
262 bool IsSameAs(const wxObject
& obj
);
265 Makes this object refer to the data in @e clone.
268 The object to 'clone'.
270 @remarks First this function calls UnRef() on itself to decrement
271 (and perhaps free) the data it is currently referring
274 It then sets its own m_refData to point to that of clone,
275 and increments the reference count inside the data.
277 @see UnRef(), wxObject::m_refData, SetRefData(),
278 GetRefData(), wxObjectRefData
280 void Ref(const wxObject
& clone
);
283 Sets the @b m_refData pointer.
285 @see Ref(), UnRef(), wxObject::m_refData, GetRefData(),
288 void SetRefData(wxObjectRefData
* data
);
291 Decrements the reference count in the associated data, and if it is zero,
293 The @b m_refData member is set to @NULL.
295 @see Ref(), wxObject::m_refData, SetRefData(),
296 GetRefData(), wxObjectRefData
301 Ensure that this object's data is not shared with any other object.
303 If we have no data, it is created using CreateRefData() below,
304 if we have shared data, it is copied using CloneRefData(),
305 otherwise nothing is done.
310 The @e delete operator is defined for debugging versions of the library only,
311 when the identifier @c __WXDEBUG__ is defined.
312 It takes over memory deallocation, allowing wxDebugContext operations.
314 void operator delete(void *buf
);
317 The @e new operator is defined for debugging versions of the library only, when
318 the identifier @c __WXDEBUG__ is defined. It takes over memory allocation, allowing
319 wxDebugContext operations.
321 void* operator new(size_t size
, const wxString
& filename
= NULL
,
327 Pointer to an object which is the object's reference-counted data.
329 @see Ref(), UnRef(), SetRefData(),
330 GetRefData(), wxObjectRefData
332 wxObjectRefData
* m_refData
;
341 This class stores meta-information about classes. Instances of this class are
342 not generally defined directly by an application, but indirectly through use
343 of macros such as @b DECLARE_DYNAMIC_CLASS and @b IMPLEMENT_DYNAMIC_CLASS.
348 @see @ref overview_rtti_classinfo "Overview", wxObject
354 Constructs a wxClassInfo object. The supplied macros implicitly construct
356 class, so there is no need to create such objects explicitly in an application.
358 wxClassInfo(const wxChar
* className
,
359 const wxClassInfo
* baseClass1
,
360 const wxClassInfo
* baseClass2
,
361 int size
, wxObjectConstructorFn fn
);
364 Creates an object of the appropriate kind. Returns @NULL if the class has not
366 dynamically creatable (typically, it is an abstract class).
368 wxObject
* CreateObject() const;
371 Finds the wxClassInfo object for a class of the given string name.
373 static wxClassInfo
* FindClass(wxChar
* name
);
376 Returns the name of the first base class (@NULL if none).
378 wxChar
* GetBaseClassName1() const;
381 Returns the name of the second base class (@NULL if none).
383 wxChar
* GetBaseClassName2() const;
386 Returns the string form of the class name.
388 wxChar
* GetClassName() const;
391 Returns the size of the class.
396 Initializes pointers in the wxClassInfo objects for fast execution
397 of IsKindOf. Called in base wxWidgets library initialization.
399 static void InitializeClasses();
402 Returns @true if this class info can create objects of the associated class.
404 bool IsDynamic() const;
407 Returns @true if this class is a kind of (inherits from) the given class.
409 bool IsKindOf(wxClassInfo
* info
);
417 This is helper template class primarily written to avoid memory
418 leaks because of missing calls to wxObjectRefData::DecRef.
420 Despite the name this template can actually be used as a
421 smart pointer for any class implementing the reference
422 counting interface which only consists of the two methods
423 @b T::IncRef() and @b T::DecRef().
425 The difference to wxSharedPtr<T> is that
426 wxObjectDataPtr<T> relies on the reference counting to be in
427 the class pointed to where as wxSharedPtr<T> implements the
428 reference counting itself.
431 @category{rtti,smartpointers}
433 @see wxObject, wxObjectRefData, @ref overview_refcount "Reference counting",
434 wxSharedPtr<T>, wxScopedPtr<T>, wxWeakRef<T>
436 <b>Data structures:</b>
439 typedef T element_type
445 class MyCarRefData: public wxObjectRefData
448 MyCarRefData() { m_price = 0; }
450 MyCarRefData( const MyCarRefData& data )
453 m_price = data.m_price;
456 void SetPrice( int price ) { m_price = price; }
457 int GetPrice() { return m_price; }
466 MyCar( int price ) : m_data( new MyCarRefData )
468 m_data->SetPrice( price );
471 MyCar& operator =( const MyCar& tocopy )
473 m_data = tocopy.m_data;
477 bool operator == ( const MyCar& other ) const
479 if (m_data.get() == other.m_data.get()) return true;
480 return (m_data->GetPrice() == other.m_data->GetPrice());
483 void SetPrice( int price )
486 m_data->SetPrice( price );
491 return m_data->GetPrice();
494 wxObjectDataPtr<MyCarRefData> m_data;
499 if (m_data->GetRefCount() == 1)
502 m_data.reset( new MyCarRefData( *m_data ) );
509 class wxObjectDataPtr
<T
>
514 Constructor. @a ptr is a pointer to the reference counted object
515 to which this class points.
516 If @a ptr is not NULL @b T::IncRef() will be called on the object.
518 wxObjectDataPtr
<T
>(T
* ptr
= NULL
);
521 This copy constructor increases the count of the reference
522 counted object to which @a tocopy points and then this
523 class will point to, as well.
525 wxObjectDataPtr
<T
>(const wxObjectDataPtr
<T
>& tocopy
);
529 Decreases the reference count of the object to which this
535 Gets a pointer to the reference counted object to which
541 Conversion to a boolean expression (in a variant which is not
542 convertable to anything but a boolean expression). If this class
543 contains a valid pointer it will return @e @true, if it contains
544 a @NULL pointer it will return @e @false.
546 operator unspecified_bool_type() const;
549 Returns a reference to the object. If the internal pointer is @NULL
550 this method will cause an assert in debug mode.
552 T
& operator*() const;
555 Returns a pointer to the reference counted object to which
556 this class points. If this the internal pointer is @NULL,
557 this method will assert in debug mode.
559 T
* operator-() const;
563 Assignment operators.
565 wxObjectDataPtr
<T
>& operator=(const wxObjectDataPtr
<T
>& tocopy
);
566 wxObjectDataPtr
<T
>& operator=(T
* ptr
);
572 // ============================================================================
573 // Global functions/macros
574 // ============================================================================
576 /** @ingroup group_funcmacro_rtti */
580 Returns a pointer to the wxClassInfo object associated with this class.
584 #define CLASSINFO( className )
587 Used inside a class declaration to declare that the class should be made
588 known to the class hierarchy, but objects of this class cannot be created
589 dynamically. The same as DECLARE_ABSTRACT_CLASS().
593 #define DECLARE_CLASS( className )
596 Used inside a class declaration to declare that the class should be
597 made known to the class hierarchy, but objects of this class cannot be created
598 dynamically. The same as DECLARE_CLASS().
605 class wxCommand: public wxObject
607 DECLARE_ABSTRACT_CLASS(wxCommand)
616 #define DECLARE_ABSTRACT_CLASS( className )
619 Used inside a class declaration to make the class known to wxWidgets RTTI
620 system and also declare that the objects of this class should be
621 dynamically creatable from run-time type information. Notice that this
622 implies that the class should have a default constructor, if this is not
623 the case consider using DECLARE_CLASS().
630 class wxFrame: public wxWindow
632 DECLARE_DYNAMIC_CLASS(wxFrame)
635 const wxString& frameTitle;
641 #define DECLARE_DYNAMIC_CLASS( className )
644 Used in a C++ implementation file to complete the declaration of a class
645 that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS().
649 #define IMPLEMENT_CLASS( className, baseClassName )
652 Used in a C++ implementation file to complete the declaration of a class
653 that has run-time type information and two base classes. The same as
654 IMPLEMENT_ABSTRACT_CLASS2().
658 #define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 )
661 Used in a C++ implementation file to complete the declaration of a class
662 that has run-time type information. The same as IMPLEMENT_CLASS().
669 IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
671 wxCommand::wxCommand(void)
677 #define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName )
680 Used in a C++ implementation file to complete the declaration of a class
681 that has run-time type information and two base classes. The same as
686 #define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 )
689 Used in a C++ implementation file to complete the declaration of a class
690 that has run-time type information, and whose instances can be created
698 IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
700 wxFrame::wxFrame(void)
706 #define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName )
709 Used in a C++ implementation file to complete the declaration of a class
710 that has run-time type information, and whose instances can be created
711 dynamically. Use this for classes derived from two base classes.
715 #define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 )
718 Same as @c const_cast<T>(x) if the compiler supports const cast or @c (T)x for
719 old compilers. Unlike wxConstCast(), the cast it to the type @c T and not to
720 <tt>T *</tt> and also the order of arguments is the same as for the standard cast.
724 @see wx_reinterpret_cast(), wx_static_cast()
726 #define wx_const_cast(T, x)
729 Same as @c reinterpret_cast<T>(x) if the compiler supports reinterpret cast or
730 @c (T)x for old compilers.
734 @see wx_const_cast(), wx_static_cast()
736 #define wx_reinterpret_cast(T, x)
739 Same as @c static_cast<T>(x) if the compiler supports static cast or @c (T)x for
740 old compilers. Unlike wxStaticCast(), there are no checks being done and
741 the meaning of the macro arguments is exactly the same as for the standard
742 static cast, i.e. @a T is the full type name and star is not appended to it.
746 @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast()
748 #define wx_static_cast(T, x)
751 This case doesn’t correspond to any standard cast but exists solely to make
752 casts which possibly result in a truncation of an integer value more
757 #define wx_truncate_cast(T, x)
760 This macro expands into <tt>const_cast<classname *>(ptr)</tt> if the compiler
761 supports const_cast or into an old, C-style cast, otherwise.
765 @see wx_const_cast(), wxDynamicCast(), wxStaticCast()
767 #define wxConstCast( ptr, classname )
770 This is defined in debug mode to be call the redefined new operator
771 with filename and line number arguments. The definition is:
774 #define WXDEBUG_NEW new(__FILE__,__LINE__)
777 In non-debug mode, this is defined as the normal new operator.
781 #define WXDEBUG_NEW( arg )
784 This macro returns the pointer @e ptr cast to the type @e classname * if
785 the pointer is of this type (the check is done during the run-time) or
786 @NULL otherwise. Usage of this macro is preferred over obsoleted
787 wxObject::IsKindOf() function.
789 The @e ptr argument may be @NULL, in which case @NULL will be returned.
796 wxWindow *win = wxWindow::FindFocus();
797 wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
800 // a text control has the focus...
804 // no window has the focus or it is not a text control
808 @see @ref overview_rtti "RTTI Overview",
809 wxDynamicCastThis(), wxConstCast(), wxStaticCast()
811 #define wxDynamicCast( ptr, classname )
814 This macro is equivalent to <tt>wxDynamicCast(this, classname)</tt> but the latter provokes
815 spurious compilation warnings from some compilers (because it tests whether
816 @c this pointer is non-@NULL which is always true), so this macro should be
823 #define wxDynamicCastThis( classname )
826 This macro checks that the cast is valid in debug mode (an assert failure
827 will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the
828 result of executing an equivalent of <tt>static_cast<classname *>(ptr)</tt>.
832 @see wx_static_cast(), wxDynamicCast(), wxConstCast()
834 #define wxStaticCast( ptr, classname )
837 Creates and returns an object of the given class, if the class has been
838 registered with the dynamic class system using DECLARE... and IMPLEMENT...
843 wxObject
*wxCreateDynamicObject(const wxString
& className
);