First attempt to document raw bitmap access

[wxWidgets.git] / interface / weakref.h

diff --git a/interface/weakref.h b/interface/weakref.h
index 4041dd0d064e2d95aed2e3c562ace15af23d7878..903de9a87636f4f9cbdd0021a00d4e091dbe4826 100644 (file)
--- a/interface/weakref.h
+++ b/interface/weakref.h
@@ -1,17 +1,16 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        weakref.h
-// Purpose:     documentation for wxWeakRefDynamic<T> class
+// Purpose:     interface of wxWeakRefDynamic<T>
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 /**
-    @class wxWeakRefDynamicT
     @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).
 
@@ -19,18 +18,19 @@
     have a little better run-time performance. The role of wxWeakRefDynamic
     is to handle objects which derived type one does not know.
 
-    @b 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).
 
-    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}
 */
+template<typename T>
 class wxWeakRefDynamic<T>
 {
 public:
@@ -38,8 +38,8 @@ public:
 };
 
 
+
 /**
-    @class wxWeakRefT
     @wxheader{weakref.h}
 
     wxWeakRef is a template class for weak references to wxWidgets objects,
@@ -48,31 +48,67 @@ public:
     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.
 
-    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.
 
+    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}
 
-    @seealso
-    wxSharedPtr, wxScopedPtr
+    @see wxSharedPtr<T>, wxScopedPtr<T>
 */
+template<typename T>
 class wxWeakRef<T>
 {
 public:
     /**
         Constructor. The weak reference is initialized to @e pobj.
     */
-    wxWeakRefT(T* pobj = NULL);
+    wxWeakRef(T* pobj = NULL);
 
     /**
         Destructor.
     */
-    ~wxWeakRefT();
+    ~wxWeakRef();
 
     /**
         Called when the tracked object is destroyed. Be default sets
@@ -88,7 +124,7 @@ public:
     /**
         Returns pointer to the tracked object or @NULL.
     */
-    T* get();
+    T* get() const;
 
     /**
         Release currently tracked object and start tracking the same object as
@@ -100,13 +136,13 @@ public:
         Implicit conversion to T*. Returns pointer to the tracked
         object or @NULL.
     */
-    T* operator*();
+    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.
     */
-    T operator*();
+    T operator*() const;
 
     /**
         Smart pointer member access. Returns a pointer to the
@@ -121,3 +157,4 @@ public:
     */
     T* operator=(T* pobj);
 };
+