/////////////////////////////////////////////////////////////////////////////
// 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
- defaults to using @c dynamic_cast for establishing the object
- reference (while wxWeakRef defaults to @c static_cast).
-
+
+ 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).
+
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.
-
- @b Note: wxWeakRefT selects an implementation based on the static type
+ 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).
-
- For general cases, wxWeakRefT is the better choice.
-
- For API documentation, see: wxWeakRef
-
+ 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 API documentation, see: wxWeakRef<T>
+
@library{wxcore}
@category{FIXME}
*/
-class wxWeakRefDynamic<T>
+template<typename T>
+class wxWeakRefDynamic<T>
{
public:
-
+
};
+
/**
- @class wxWeakRefT
@wxheader{weakref.h}
-
- wxWeakRef is a template class for weak references to wxWidgets objects,
- such as wxEvtHandler, wxWindow and
+
+ 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.
-
- wxWeakRefT can be used whenever one must keep a pointer to an object
+ 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
- holding the reference.
-
- wxWeakRefT is a small object and the mechanism behind it is fast
- (@b O(1)). So the overall cost of using it is small.
+ holding the reference.
+
+ 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>
*/
-class wxWeakRef<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
/**
Returns pointer to the tracked object or @NULL.
*/
- T * get();
+ T* get() const;
/**
Release currently tracked object and start tracking the same object as
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
*/
T* operator=(T* pobj);
};
+
projects / wxWidgets.git / blobdiff