]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/weakref.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / interface / wx / weakref.h
index f6522aa39928afd17226f585e3c86566bc39e4ee..e954c26a3a90b11c761377e7f3000f43dfe26b9a 100644 (file)
@@ -1,34 +1,35 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        weakref.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        weakref.h
-// Purpose:     interface of wxWeakRefDynamic<T>
+// Purpose:     interface of wxWeakRefDynamic<T>, wxWeakRef<T>
 // Author:      wxWidgets team
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 
-/**
-    @wxheader{weakref.h}
 
 
+/**
     wxWeakRefDynamic<T> is a template class for weak references that is used in
     the same way as wxWeakRef<T>. The only difference is that wxWeakRefDynamic
     wxWeakRefDynamic<T> is a template class for weak references that is used in
     the same way as wxWeakRef<T>. 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.
 
 
     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<T> 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<T> 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<T> is the better choice.
 
 
     For general cases, wxWeakRef<T> is the better choice.
 
-    For API documentation, see: wxWeakRef<T>
+    For API documentation, see: wxWeakRef<T>.
 
 
-    @library{wxcore}
-    @category{FIXME}
+    @tparam T
+        The type to which the smart pointer points to.
+
+    @nolibrary
+    @category{smartpointers}
 */
 template<typename T>
 class wxWeakRefDynamic<T>
 */
 template<typename T>
 class wxWeakRefDynamic<T>
@@ -40,13 +41,10 @@ public:
 
 
 /**
 
 
 /**
-    @wxheader{weakref.h}
-
-    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<T> 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<T> 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
 
     wxWeakRef<T> 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
@@ -55,32 +53,33 @@ public:
     wxWeakRef<T> is a small object and the mechanism behind it is fast
     (@b O(1)). So the overall cost of using it is small.
 
     wxWeakRef<T> 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" );
     @code
     wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" );
-    wxWeakRef<wxWindow> wr = wnd;  
+    wxWeakRef<wxWindow> wr = wnd;
     wxWindowRef wr2 = wnd;        // Same as above, but using a typedef
     // Do things with window
     wnd->Show( true );
     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 );
     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
 
     // Now the weak ref has been reset, so we don't risk accessing
     // a dangling pointer:
     wxASSERT( wr==NULL );
     @endcode
 
-    wxWeakRef<T> 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<T> 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
 
     @code
     class wxMyTrackableObject : public wxObject, public wxTrackable
-    { 
-        // ... other members here 
-    }; 
+    {
+        // ... other members here
+    };
     @endcode
 
     The following types of weak references are predefined:
     @endcode
 
     The following types of weak references are predefined:
@@ -90,16 +89,21 @@ public:
     typedef wxWeakRef<wxWindow>      wxWindowRef;
     @endcode
 
     typedef wxWeakRef<wxWindow>      wxWindowRef;
     @endcode
 
+    @tparam T
+        The type to which the smart pointer points to.
 
 
-    @library{wxbase}
-    @category{FIXME}
+    @nolibrary
+    @category{smartpointers}
 
     @see wxSharedPtr<T>, wxScopedPtr<T>
 */
 template<typename T>
 
     @see wxSharedPtr<T>, wxScopedPtr<T>
 */
 template<typename T>
-class wxWeakRef<T>
+class wxWeakRef<T> : public wxTrackerNode
 {
 public:
 {
 public:
+    /// Type of the element stored by this reference.
+    typedef T element_type;
+
     /**
         Constructor. The weak reference is initialized to @e pobj.
     */
     /**
         Constructor. The weak reference is initialized to @e pobj.
     */
@@ -109,16 +113,16 @@ public:
         Copy constructor.
     */
     wxWeakRef(const wxWeakRef<T>& wr);
         Copy constructor.
     */
     wxWeakRef(const wxWeakRef<T>& wr);
-    
+
     /**
         Destructor.
     */
     /**
         Destructor.
     */
-    ~wxWeakRef();
+    virtual ~wxWeakRef();
 
     /**
         Called when the tracked object is destroyed. Be default sets
 
     /**
         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();
 
     */
     virtual void OnObjectDestroy();
 
@@ -139,23 +143,22 @@ public:
     T* operator =(wxWeakRef<T>& wr);
 
     /**
     T* operator =(wxWeakRef<T>& 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;
 
     /**
     */
     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.
 
     /**
         Releases the currently tracked object and starts tracking @e pobj.