Initial review of various [q-r] by Utensil Candel.

[wxWidgets.git] / interface / weakref.h

diff --git a/interface/weakref.h b/interface/weakref.h
index a527e1d029c423fe1648cb34b3b019b8365bdfdd..03a96631303608bd1138a6c62c448955c930bef3 100644 (file)
--- a/interface/weakref.h
+++ b/interface/weakref.h
@@ -9,8 +9,8 @@
 /**
     @wxheader{weakref.h}
 
 /**
     @wxheader{weakref.h}
 

-    wxWeakRefDynamicT is a template class for weak references that is used in
-    the same way as wxWeakRefT. 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).
 


@@ -18,14 +18,14 @@
     have a little better run-time performance. The role of wxWeakRefDynamic
     is to handle objects which derived type one does not know.
 
     have a little better run-time performance. The role of wxWeakRefDynamic
     is to handle objects which derived type one does not know.
 

-    @note wxWeakRefT selects an implementation based on the static type
+    @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).
 
     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).
 

-    For general cases, wxWeakRefT is the better choice.
+    For general cases, wxWeakRef<T> is the better choice.

 
 

-    For API documentation, see: wxWeakRef
+    For API documentation, see: wxWeakRef<T>

 
     @library{wxcore}
     @category{FIXME}
 
     @library{wxcore}
     @category{FIXME}


@@ -48,17 +48,53 @@ public:
     pointer, but when the object pointed is destroyed, the weak reference is
     automatically reset to a @NULL pointer.
 
     pointer, but when the object pointed is destroyed, the weak reference is
     automatically reset to a @NULL pointer.
 

-    wxWeakRefT can be used whenever one must keep a pointer to an 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
     holding the reference.
 
     that one does not directly own, and that may be destroyed before the object
     holding the reference.
 

-    wxWeakRefT is a small object and the mechanism behind it is fast
+    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.
 
     (@b O(1)). So the overall cost of using it is small.
 

+    Example
+    
+    @code
+    wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" );
+    wxWeakRef<wxWindow> 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 
+    wr->Show( false );
+    wnd->Destroy(); 
+    // 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:
+
+    @code
+    class wxMyTrackableObject : public wxObject, public wxTrackable
+    { 
+        // ... other members here 
+    }; 
+    @endcode
+
+    The following types of weak references are predefined:
+
+    @code
+    typedef wxWeakRef<wxEvtHandler>  wxEvtHandlerRef;
+    typedef wxWeakRef<wxWindow>      wxWindowRef;
+    @endcode
+
+

     @library{wxbase}
     @category{FIXME}
 
     @library{wxbase}
     @category{FIXME}
 

-    @see wxSharedPtr, wxScopedPtr
+    @see wxSharedPtr<T>, wxScopedPtr<T>

 */
 template<typename T>
 class wxWeakRef<T>
 */
 template<typename T>
 class wxWeakRef<T>


@@ -76,7 +112,8 @@ public:
 
     /**
         Called when the tracked object is destroyed. Be default sets
 
     /**
         Called when the tracked object is destroyed. Be default sets

-        internal pointer to @NULL.
+        internal pointer to @NULL. You need to call this method if
+        you override it.

     */
     virtual void OnObjectDestroy();
 
     */
     virtual void OnObjectDestroy();