X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..e4f1d811cc5b15a148ae7331c033d1749940cac0:/interface/object.h diff --git a/interface/object.h b/interface/object.h index 32f85b35aa..35507bc200 100644 --- a/interface/object.h +++ b/interface/object.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: object.h -// Purpose: documentation for wxObjectRefData class +// Purpose: interface of wxObjectRefData // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -18,8 +18,7 @@ @library{wxbase} @category{FIXME} - @seealso - wxObject, wxObjectDataPtrT, @ref overview_trefcount "Reference counting" + @see wxObject, wxObjectDataPtrT(), @ref overview_trefcount "Reference counting" */ class wxObjectRefData { @@ -34,7 +33,7 @@ public: never be destroyed directly but only as result of a DecRef() call. */ - wxObjectRefData(); + ~wxObjectRefData(); /** Decrements the reference count associated with this shared data and, if it @@ -51,7 +50,7 @@ public: When this goes to zero during a DecRef() call, the object will auto-free itself. */ - int GetRefCount(); + int GetRefCount() const; /** Increments the reference count associated with this shared data. @@ -60,6 +59,7 @@ public: }; + /** @class wxObject @wxheader{object.h} @@ -83,8 +83,7 @@ public: @library{wxbase} @category{rtti} - @seealso - wxClassInfo, @ref overview_debuggingoverview, wxObjectRefData + @see wxClassInfo, @ref overview_debuggingoverview, wxObjectRefData */ class wxObject { @@ -108,10 +107,10 @@ public: memory states. This function is only defined in debug build and doesn't exist at all if @c __WXDEBUG__ is not defined. - + @param stream Stream on which to output dump information. - + @remarks Currently wxWidgets does not define Dump for derived classes, but programmers may wish to use it for their own applications. Be sure to call the Dump member of the @@ -128,20 +127,20 @@ public: /** Returns the @b m_refData pointer. - + @see Ref(), UnRef(), wxObject::m_refData, SetRefData(), wxObjectRefData */ - wxObjectRefData* GetRefData(); + wxObjectRefData* GetRefData() const; /** Determines whether this class is a subclass of (or the same class as) the given class. - + @param info A pointer to a class information object, which may be obtained by using the CLASSINFO macro. - + @returns @true if the class represented by info is the same class as this one or is derived from it. */ @@ -157,14 +156,14 @@ public: /** Makes this object refer to the data in @e clone. - + @param clone The object to 'clone'. - + @remarks First this function calls UnRef() on itself to decrement (and perhaps free) the data it is currently referring to. - + @see UnRef(), wxObject::m_refData, SetRefData(), GetRefData(), wxObjectRefData */ @@ -172,7 +171,7 @@ public: /** Sets the @b m_refData pointer. - + @see Ref(), UnRef(), wxObject::m_refData, GetRefData(), wxObjectRefData */ @@ -182,7 +181,7 @@ public: Decrements the reference count in the associated data, and if it is zero, deletes the data. The @b m_refData member is set to @NULL. - + @see Ref(), wxObject::m_refData, SetRefData(), GetRefData(), wxObjectRefData */ @@ -199,7 +198,7 @@ public: /** wxObjectRefData* m_refData Pointer to an object which is the object's reference-counted data. - + @see Ref(), UnRef(), SetRefData(), GetRefData(), wxObjectRefData */ @@ -224,6 +223,7 @@ public: }; + /** @class wxClassInfo @wxheader{object.h} @@ -235,8 +235,7 @@ public: @library{wxbase} @category{rtti} - @seealso - Overview, wxObject + @see Overview(), wxObject */ class wxClassInfo { @@ -256,7 +255,7 @@ public: been declared dynamically creatable (typically, it is an abstract class). */ - wxObject* CreateObject(); + wxObject* CreateObject() const; /** Finds the wxClassInfo object for a class of the given string name. @@ -266,22 +265,22 @@ public: /** Returns the name of the first base class (@NULL if none). */ - wxChar* GetBaseClassName1(); + wxChar* GetBaseClassName1() const; /** Returns the name of the second base class (@NULL if none). */ - wxChar* GetBaseClassName2(); + wxChar* GetBaseClassName2() const; /** Returns the string form of the class name. */ - wxChar* GetClassName(); + wxChar* GetClassName() const; /** Returns the size of the class. */ - int GetSize(); + int GetSize() const; /** Initializes pointers in the wxClassInfo objects for fast execution @@ -292,7 +291,7 @@ public: /** Returns @true if this class info can create objects of the associated class. */ - bool IsDynamic(); + bool IsDynamic() const; /** Returns @true if this class is a kind of (inherits from) the given class. @@ -301,8 +300,8 @@ public: }; + /** - @class wxObjectDataPtrT @wxheader{object.h} This is helper template class primarily written to avoid memory @@ -321,8 +320,7 @@ public: @library{wxbase} @category{FIXME} - @seealso - wxObject, wxObjectRefData, @ref overview_trefcount "Reference counting" + @see wxObject, wxObjectRefData, @ref overview_trefcount "Reference counting" */ class wxObjectDataPtr { @@ -347,7 +345,7 @@ public: Gets a pointer to the reference counted object to which this class points. */ - T* get(); + T* get() const; /** Conversion to a boolean expression (in a variant which is not @@ -355,20 +353,20 @@ public: contains a valid pointer it will return @e @true, if it contains a @NULL pointer it will return @e @false. */ - operator unspecified_bool_type(); + operator unspecified_bool_type() const; /** Returns a reference to the object. If the internal pointer is @NULL this method will cause an assert in debug mode. */ - T operator*(); + T operator*() const; /** Returns a pointer to the reference counted object to which this class points. If this the internal pointer is @NULL, this method will assert in debug mode. */ - T* operator-(); + T* operator-() const; //@{ /** @@ -380,68 +378,101 @@ public: }; + // ============================================================================ // Global functions/macros // ============================================================================ +/** @ingroup group_funcmacro_rtti */ +//@{ + /** - Used inside a class declaration to declare that the class should be - made known to the class hierarchy, but objects of this class cannot be created - dynamically. The same as DECLARE_ABSTRACT_CLASS. + Returns a pointer to the wxClassInfo object associated with this class. + + @header{wx/object.h} */ -#define DECLARE_CLASS() /* implementation is private */ +#define CLASSINFO( className ) + +/** + Used inside a class declaration to declare that the class should be made + known to the class hierarchy, but objects of this class cannot be created + dynamically. The same as DECLARE_ABSTRACT_CLASS(). + + @header{wx/object.h} +*/ +#define DECLARE_CLASS( className ) /** Used inside a class declaration to declare that the class should be made known to the class hierarchy, but objects of this class cannot be created - dynamically. The same as DECLARE_CLASS. + dynamically. The same as DECLARE_CLASS(). + + @header{wx/object.h} + Example: @code class wxCommand: public wxObject { - DECLARE_ABSTRACT_CLASS(wxCommand) + DECLARE_ABSTRACT_CLASS(wxCommand) - private: - ... - public: - ... + private: + ... + public: + ... }; @endcode */ -#define DECLARE_ABSTRACT_CLASS() /* implementation is private */ +#define DECLARE_ABSTRACT_CLASS( className ) /** - Returns a pointer to the wxClassInfo object associated with this class. -*/ -#define wxClassInfo* CLASSINFO() /* implementation is private */ + Used inside a class declaration to make the class known to wxWidgets RTTI + system and also declare that the objects of this class should be + dynamically creatable from run-time type information. Notice that this + implies that the class should have a default constructor, if this is not + the case consider using DECLARE_CLASS(). -/** - Same as @c reinterpret_castT(x) if the compiler supports reinterpret cast or - @c (T)x for old compilers. + @header{wx/object.h} + + Example: + + @code + class wxFrame: public wxWindow + { + DECLARE_DYNAMIC_CLASS(wxFrame) - @see wx_const_cast, wx_static_cast + private: + const wxString& frameTitle; + public: + ... + }; + @endcode */ -T wx_reinterpret_cast(); +#define DECLARE_DYNAMIC_CLASS( className ) /** - Used in a C++ implementation file to complete the declaration of a - class that has run-time type information and two base classes. The - same as IMPLEMENT_ABSTRACT_CLASS2. + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS(). + + @header{wx/object.h} */ -#define IMPLEMENT_CLASS2() /* implementation is private */ +#define IMPLEMENT_CLASS( className, baseClassName ) /** - This macro expands into @c const_castclassname *(ptr) if the compiler - supports @e const_cast or into an old, C-style cast, otherwise. + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information and two base classes. The same as + IMPLEMENT_ABSTRACT_CLASS2(). - @see wx_const_cast, wxDynamicCast, wxStaticCast + @header{wx/object.h} */ -classname* wxConstCast(); +#define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 ) /** - Used in a C++ implementation file to complete the declaration of - a class that has run-time type information. The same as IMPLEMENT_CLASS. + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information. The same as IMPLEMENT_CLASS(). + + @header{wx/object.h} + Example: @code @@ -449,109 +480,101 @@ classname* wxConstCast(); wxCommand::wxCommand(void) { - ... + ... } @endcode */ -#define IMPLEMENT_ABSTRACT_CLASS() /* implementation is private */ +#define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName ) /** - Used in a C++ implementation file to complete the declaration of - a class that has run-time type information. The same as - IMPLEMENT_ABSTRACT_CLASS. + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information and two base classes. The same as + IMPLEMENT_CLASS2(). + + @header{wx/object.h} */ -#define IMPLEMENT_CLASS() /* implementation is private */ +#define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 ) /** - This macro is equivalent to @c wxDynamicCast(this, classname) but the - latter provokes spurious compilation warnings from some compilers (because it - tests whether @c this pointer is non-@NULL which is always @true), so - this macro should be used to avoid them. + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information, and whose instances can be created + dynamically. + + @header{wx/object.h} + + Example: + + @code + IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) - @see wxDynamicCast + wxFrame::wxFrame(void) + { + ... + } + @endcode */ -classname* wxDynamicCastThis(); +#define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName ) /** - Used in a C++ implementation file to complete the declaration of - a class that has run-time type information, and whose instances - can be created dynamically. Use this for classes derived from two - base classes. + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information, and whose instances can be created + dynamically. Use this for classes derived from two base classes. + + @header{wx/object.h} */ -#define IMPLEMENT_DYNAMIC_CLASS2() /* implementation is private */ +#define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 ) /** - Creates and returns an object of the given class, if the class has been - registered with the dynamic class system using DECLARE... and IMPLEMENT... - macros. + Same as const_cast(x) if the compiler supports const cast or (T)x for + old compilers. Unlike wxConstCast(), the cast it to the type T and not to + T * and also the order of arguments is the same as for the standard cast. + + @header{wx/defs.h} + + @see wx_reinterpret_cast(), wx_static_cast() */ -wxObject* wxCreateDynamicObject(const wxString& className); +#define wx_const_cast(T, x) /** - Used inside a class declaration to make the class known to wxWidgets RTTI - system and also declare that the objects of this class should be dynamically - creatable from run-time type information. Notice that this implies that the - class should have a default constructor, if this is not the case consider using - DECLARE_CLASS. - Example: + Same as reinterpret_cast(x) if the compiler supports reinterpret cast or + (T)x for old compilers. - @code - class wxFrame: public wxWindow - { - DECLARE_DYNAMIC_CLASS(wxFrame) + @header{wx/defs.h} - private: - const wxString& frameTitle; - public: - ... - }; - @endcode + @see wx_const_cast(), wx_static_cast() */ -#define DECLARE_DYNAMIC_CLASS() /* implementation is private */ +#define wx_reinterpret_cast(T, x) /** - Same as @c const_castT(x) if the compiler supports const cast or - @c (T)x for old compilers. Unlike wxConstCast, - the cast it to the type @e T and not to @c T * and also the order of - arguments is the same as for the standard cast. + Same as static_cast(x) if the compiler supports static cast or (T)x for + old compilers. Unlike wxStaticCast(), there are no checks being done and + the meaning of the macro arguments is exactly the same as for the standard + static cast, i.e. T is the full type name and star is not appended to it. - @see wx_reinterpret_cast, wx_static_cast + @header{wx/defs.h} + + @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast() */ -T wx_const_cast(); +#define wx_static_cast(T, x) /** - Used in a C++ implementation file to complete the declaration of - a class that has run-time type information and two base classes. The same as - IMPLEMENT_CLASS2. + This case doesn’t correspond to any standard cast but exists solely to make + casts which possibly result in a truncation of an integer value more + readable. + + @header{wx/defs.h} */ -#define IMPLEMENT_ABSTRACT_CLASS2() /* implementation is private */ +#define wx_truncate_cast(T, x) /** - This macro returns the pointer @e ptr cast to the type @e classname * if - the pointer is of this type (the check is done during the run-time) or - @NULL otherwise. Usage of this macro is preferred over obsoleted - wxObject::IsKindOf() function. - The @e ptr argument may be @NULL, in which case @NULL will be - returned. - Example: + This macro expands into const_cast(ptr) if the compiler + supports const_cast or into an old, C-style cast, otherwise. - @code - wxWindow *win = wxWindow::FindFocus(); - wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl); - if ( text ) - { - // a text control has the focus... - } - else - { - // no window has the focus or it is not a text control - } - @endcode + @header{wx/defs.h} - @see @ref overview_runtimeclassoverview "RTTI overview", wxDynamicCastThis, - wxConstCast, wxStaticCast + @see wx_const_cast(), wxDynamicCast(), wxStaticCast() */ -classname* wxDynamicCast(); +#define wxConstCast( ptr, classname ) /** This is defined in debug mode to be call the redefined new operator @@ -562,43 +585,72 @@ classname* wxDynamicCast(); @endcode In non-debug mode, this is defined as the normal new operator. + + @header{wx/object.h} */ -#define WXDEBUG_NEW() /* implementation is private */ +#define WXDEBUG_NEW( arg ) /** - This macro checks that the cast is valid in debug mode (an assert failure will - result if @c wxDynamicCast(ptr, classname) == @NULL) and then returns the - result of executing an equivalent of @c static_castclassname *(ptr). + This macro returns the pointer @e ptr cast to the type @e classname * if + the pointer is of this type (the check is done during the run-time) or + @NULL otherwise. Usage of this macro is preferred over obsoleted + wxObject::IsKindOf() function. + + The @e ptr argument may be @NULL, in which case @NULL will be returned. - @see wx_static_cast, wxDynamicCast, wxConstCast + @header{wx/object.h} + + Example: + + @code + wxWindow *win = wxWindow::FindFocus(); + wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl); + if ( text ) + { + // a text control has the focus... + } + else + { + // no window has the focus or it is not a text control + } + @endcode + + @see @ref overview_runtimeclassoverview "RTTI Overview", + wxDynamicCastThis(), wxConstCast(), wxStaticCast() */ -classname* wxStaticCast(); +#define wxDynamicCast( ptr, classname ) /** - Same as @c static_castT(x) if the compiler supports static cast or - @c (T)x for old compilers. Unlike wxStaticCast, - there are no checks being done and the meaning of the macro arguments is exactly - the same as for the standard static cast, i.e. @e T is the full type name and - star is not appended to it. + This macro is equivalent to wxDynamicCast() but the latter provokes + spurious compilation warnings from some compilers (because it tests whether + @c this pointer is non-@NULL which is always true), so this macro should be + used to avoid them. - @see wx_const_cast, wx_reinterpret_cast, wx_truncate_cast + @header{wx/object.h} + + @see wxDynamicCast() */ -T wx_static_cast(); +#define wxDynamicCastThis( classname ) /** - Used in a C++ implementation file to complete the declaration of - a class that has run-time type information, and whose instances - can be created dynamically. - Example: + This macro checks that the cast is valid in debug mode (an assert failure + will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the + result of executing an equivalent of static_cast(ptr). - @code - IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) + @header{wx/object.h} - wxFrame::wxFrame(void) - { - ... - } - @endcode + @see wx_static_cast(), wxDynamicCast(), wxConstCast() */ -#define IMPLEMENT_DYNAMIC_CLASS() /* implementation is private */ +#define wxStaticCast( ptr, classname ) + +/** + Creates and returns an object of the given class, if the class has been + registered with the dynamic class system using DECLARE... and IMPLEMENT... + macros. + + @header{wx/object.h} +*/ +wxObject *wxCreateDynamicObject(const wxString& className); + +//@}