implement * and / operators for wxPoint, not only wxSize.

[wxWidgets.git] / interface / wx / weakref.h

diff --git a/interface/wx/weakref.h b/interface/wx/weakref.h
index f6522aa39928afd17226f585e3c86566bc39e4ee..d6eb9fe4d89dbc27cb82c053c4009a2e9611f567 100644 (file)
--- a/interface/wx/weakref.h
+++ b/interface/wx/weakref.h
@@ -1,34 +1,36 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        weakref.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        weakref.h

-// Purpose:     interface of wxWeakRefDynamic<T>
+// Purpose:     interface of wxWeakRefDynamic<T>, wxWeakRef<T>

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

-/**
-    @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 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 +42,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 +54,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 +90,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 +114,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,21 +144,21 @@ 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-();