X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/weakref.h?ds=inline diff --git a/interface/wx/weakref.h b/interface/wx/weakref.h index d576a9877e..e954c26a3a 100644 --- a/interface/wx/weakref.h +++ b/interface/wx/weakref.h @@ -1,33 +1,35 @@ ///////////////////////////////////////////////////////////////////////////// // Name: weakref.h -// Purpose: interface of wxWeakRefDynamic +// Purpose: interface of wxWeakRefDynamic, wxWeakRef // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/** +/** wxWeakRefDynamic is a template class for weak references that is used in the same way as wxWeakRef. The only difference is that wxWeakRefDynamic - defaults to using @c dynamic_cast for establishing the object - reference (while wxWeakRef defaults to @c static_cast). + defaults to using @c dynamic_cast for establishing the object reference + (while wxWeakRef defaults to @c static_cast). So, wxWeakRef will detect a type mismatch during compile time and will have a little better run-time performance. The role of wxWeakRefDynamic is to handle objects which derived type one does not know. - @note wxWeakRef selects an implementation based on the static type - of T. If T does not have wxTrackable statically, it defaults to to a mixed- - mode operation, where it uses @c dynamic_cast as the last measure (if - available from the compiler and enabled when building wxWidgets). + @note wxWeakRef selects an implementation based on the static type of T. + If T does not have wxTrackable statically, it defaults to a mixed- + mode operation, where it uses @c dynamic_cast as the last measure + (if available from the compiler and enabled when building wxWidgets). For general cases, wxWeakRef is the better choice. - For API documentation, see: wxWeakRef + For API documentation, see: wxWeakRef. - @library{wxcore} - @category{FIXME} + @tparam T + The type to which the smart pointer points to. + + @nolibrary + @category{smartpointers} */ template class wxWeakRefDynamic @@ -39,12 +41,10 @@ public: /** - - wxWeakRef is a template class for weak references to wxWidgets objects, - such as wxEvtHandler, wxWindow and - wxObject. A weak reference behaves much like an ordinary - pointer, but when the object pointed is destroyed, the weak reference is - automatically reset to a @NULL pointer. + wxWeakRef is a template class for weak references to wxWidgets objects, + such as wxEvtHandler, wxWindow and wxObject. + A weak reference behaves much like an ordinary pointer, but when the object + pointed is destroyed, the weak reference is automatically reset to a @NULL pointer. wxWeakRef can be used whenever one must keep a pointer to an object that one does not directly own, and that may be destroyed before the object @@ -53,32 +53,33 @@ public: wxWeakRef is a small object and the mechanism behind it is fast (@b O(1)). So the overall cost of using it is small. - Example - + Example: + @code wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" ); - wxWeakRef wr = wnd; + wxWeakRef wr = wnd; wxWindowRef wr2 = wnd; // Same as above, but using a typedef // Do things with window wnd->Show( true ); - // Weak ref is used like an ordinary pointer + // Weak ref is used like an ordinary pointer wr->Show( false ); - wnd->Destroy(); + wnd->Destroy(); // Now the weak ref has been reset, so we don't risk accessing // a dangling pointer: wxASSERT( wr==NULL ); @endcode - wxWeakRef works for any objects that are derived from wxTrackable. By default, - wxEvtHandler and wxWindow derive from wxTrackable. However, wxObject does not, so - types like wxFont and wxColour are not trackable. The example below shows how to - create a wxObject derived class that is trackable: + wxWeakRef works for any objects that are derived from wxTrackable. + By default, wxEvtHandler and wxWindow derive from wxTrackable. + However, wxObject does not, so types like wxFont and wxColour are not + trackable. The example below shows how to create a wxObject derived class + that is trackable: @code class wxMyTrackableObject : public wxObject, public wxTrackable - { - // ... other members here - }; + { + // ... other members here + }; @endcode The following types of weak references are predefined: @@ -88,16 +89,21 @@ public: typedef wxWeakRef wxWindowRef; @endcode + @tparam T + The type to which the smart pointer points to. - @library{wxbase} - @category{FIXME} + @nolibrary + @category{smartpointers} @see wxSharedPtr, wxScopedPtr */ template -class wxWeakRef +class wxWeakRef : public wxTrackerNode { public: + /// Type of the element stored by this reference. + typedef T element_type; + /** Constructor. The weak reference is initialized to @e pobj. */ @@ -107,16 +113,16 @@ public: Copy constructor. */ wxWeakRef(const wxWeakRef& wr); - + /** Destructor. */ - ~wxWeakRef(); + virtual ~wxWeakRef(); /** Called when the tracked object is destroyed. Be default sets - internal pointer to @NULL. You need to call this method if - you override it. + internal pointer to @NULL. + You need to call this method if you override it. */ virtual void OnObjectDestroy(); @@ -137,23 +143,22 @@ public: T* operator =(wxWeakRef& wr); /** - Implicit conversion to T*. Returns pointer to the tracked - object or @NULL. + Implicit conversion to T*. + Returns pointer to the tracked object or @NULL. */ T* operator*() const; /** - Returns a reference to the tracked object. If the internal pointer is @NULL - this method will cause an assert in debug mode. + Returns a reference to the tracked object. + If the internal pointer is @NULL this method will cause an assert in debug mode. */ - T operator*() const; + T& operator*() const; /** - Smart pointer member access. Returns a pointer to the - tracked object. If the internal pointer is @NULL this - method will cause an assert in debug mode. + Smart pointer member access. Returns a pointer to the tracked object. + If the internal pointer is @NULL this method will cause an assert in debug mode. */ - T* operator-(); + T* operator->(); /** Releases the currently tracked object and starts tracking @e pobj.