\section{\class{wxWeakRef<T>}}\label{wxweakref}
-A weak reference to an object of type T, where T has type
-\helpref{wxTrackableBase}{wxtrackablebase} as one of its
-base classes (in a static or dynamic sense).
+{\bf wxWeakRef} is a template class for weak references to wxWidgets objects,
+such as {\bf wxEvtHandler}, {\bf wxWindow} and {\bf wxObject}. A weak
+reference behaves much like an ordinary pointer, but when the object pointed
+to goes out of scope (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 does not directly own, and that may be destroyed before the object
+holding the reference.
+
+wxWeakref<T> is a small object and the mechanism behind it is fast
+({\bf O(1)}). So the overall cost of using it is small.
+
+
+\wxheading{Example}
+
+\begin{verbatim}
+ wxWindow *parent = /* Get parent window from somewhere */;
+ 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 );
+\end{verbatim}
+
+wxWeakref<T> works for any objects that are derived from {\bf wxTrackableBase}
+or {\bf wxTrackable}. By default, wxEvtHandler and wxWindow derive from
+wxTrackableBase. However, wxObject does not, so types like {\bf wxFont} and
+{\bf wxColour} are not trackable. The example below shows how to create a
+wxObject derived class that is trackable:
\begin{verbatim}
-class MyClass: public Foo, public TrackableBase
-{
- // whatever
-}
+ class wxMyTrackableObject : public wxObject, public wxTrackable {
+ // ... other members here
+ };
+\end{verbatim}
+
+{\bf Note:} Custom trackable objects should derive from wxTrackable
+if one wants to reference them from a {\bf wxWeakRef<wxObject>}. The
+difference between the two base classes is that wxTrackableBase
+has no virtual member functions (no VTable), and thus cannot be detected
+through {\bf dynamic_cast<>}.
+
+
+\wxheading{Predefined types}
-typedef wxWeakRef<MyClass> MyClassRef;
+The following types of weak references are predefined:
+
+\begin{verbatim}
+typedef wxWeakRef<wxObject> wxObjectRef;
+typedef wxWeakRef<wxEvtHandler> wxEvtHandlerRef;
+typedef wxWeakRef<wxWindow> wxWindowRef;
\end{verbatim}
+
\wxheading{Derived from}
wxTrackerNode
\func{}{wxWeakRef<T>}{\param{T* }{pobj = NULL}}
-Constructor.
+Constructor. The weak reference is initialized to {\it pobj}.
+
\membersection{wxWeakRef<T>::\destruct{wxWeakRef<T>}}\label{wxweakrefdtor}
Destructor.
-\membersection{wxWeakRef<T>::T*}\label{wxweakreft}
-\func{operator}{T*}{\void}
+\membersection{wxWeakRef<T>::get}\label{wxweakrefget}
+
+\constfunc{T *}{get}{\void}
+
+Returns pointer to the tracked object or NULL.
+
+
+\membersection{wxWeakRef<T>::operator*}\label{wxweakrefoperatorreft}
+
+\constfunc{T \&}{operator*}{\void}
+
+Returns a reference to the tracked object. If the internal pointer is NULL
+this method will cause an assert in debug mode.
-Returns pointer to tracked object or NULL.
\membersection{wxWeakRef<T>::operator->}\label{wxweakrefoperatorderef}
\func{T*}{operator->}{\void}
-Returns pointer to tracked object or NULL.
+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.
+
\membersection{wxWeakRef<T>::operator=}\label{wxweakrefoperatorassign}
\func{T* operator}{operator=}{\param{T* }{pobj}}
-Assigns pointer to trackable object to this weak reference.
-
-\membersection{wxWeakRef<T>::Assign}\label{wxweakrefassign}
+Releases the currently tracked object and starts tracking {\it pobj}.
+A weak reference may be reset by passing {\it NULL} as {\it pobj}.
-\func{void}{Assign}{\param{T* }{pobj}}
-This uses static\_cast if possible or dynamic\_cast otherwise.
+\membersection{wxWeakRef<T>::operator =}\label{wxweakrefoperatorassign2}
-\membersection{wxWeakRef<T>::GetTrackable}\label{wxweakrefgettrackable}
+\func{T* operator}{operator =}{\param{wxWeakRef<T>\& }{wr}}
-\func{wxTrackableBase*}{GetTrackable}{\param{T* }{pobj}}
+Release currently tracked object and start tracking the same object as
+the wxWeakRef {\it wr}.
-Returns the trackable objects to which the weak reference
-points or NULL if it has been destroyed.
\membersection{wxWeakRef<T>::OnObjectDestroy}\label{wxweakrefonobjectdestroy}
// Purpose: wxWeakRef - Generic weak references for wxWidgets
// Author: Arne Steinarson
// Created: 2007-12-27
-// RCS-ID: $Id:$
+// RCS-ID: $Id$
// Copyright: (c) 2007 Arne Steinarson
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
class wxWeakRef : public wxTrackerNode
{
public:
+ typedef T element_type;
+
wxWeakRef(T *pobj = NULL) : m_pobj(NULL) { Assign(pobj); }
virtual ~wxWeakRef() { Assign(NULL); }
- // Smart pointer functions
- operator T*(){ return m_pobj; }
- T* operator->(){ return m_pobj; }
+ T * get() const
+ {
+ return m_pobj;
+ }
+
+ T* operator->()
+ {
+ wxASSERT(m_pobj != NULL);
+ return m_pobj;
+ }
+
+ T& operator*() const
+ {
+ wxASSERT(m_pobj != NULL);
+ return *m_pobj;
+ }
+
T* operator=(T *pobj)
{
Assign(pobj);
return m_pobj;
}
+ // Assign from another weak ref, point to same object
+ T* operator = (const wxWeakRef<T> &wr)
+ {
+ Assign(wr);
+ return m_pobj;
+ }
+
virtual void OnObjectDestroy()
{
// Tracked object itself removes us from list of trackers
m_pobj = NULL;
}
- virtual wxTrackerNodeType GetType() { return WeakRef; }
-
protected:
- wxTrackableBase *GetTrackable(T *pobj)
- {
- // this uses static_cast if possible or dynamic_cast otherwise
- return wxTrackableCaster<T, wxHasBase<T, wxTrackableBase>::value>
- ::Cast(pobj);
- }
+ friend class wxTrackableBase;
+ friend class wxEvtHandler;
+ virtual wxTrackerNodeType GetType() { return WeakRef; }
+
void Assign(T* pobj)
{
if ( m_pobj == pobj )
if ( m_pobj )
{
// Remove ourselves from object tracker list
- GetTrackable(m_pobj)->RemoveNode(this);
+ // This does static_cast if available, otherwise it tries dynamic cast
+ wxTrackableBase *pt = wxTrackableCaster<T,wxHasBase<T,wxTrackableBase>::value >::Cast(m_pobj);
+ wxASSERT(pt);
+ pt->RemoveNode(this);
m_pobj = NULL;
}
// Now set new trackable object
if ( pobj )
{
- wxTrackableBase * const pt = GetTrackable(pobj);
- wxCHECK_RET( pt, "type must derive from wxTrackableBase" );
-
- pt->AddNode(this);
- m_pobj = pobj;
+ wxTrackableBase *pt = wxTrackableCaster<T,wxHasBase<T,wxTrackableBase>::value >::Cast(pobj);
+ if( pt )
+ {
+ pt->AddNode( this );
+ m_pobj = pobj;
+ }
+ else
+ {
+ // If the tracked we want to track does not support wxTackableBase, then
+ // log a message and keep the NULL object pointer.
+ wxLogWarning( _T("wxWeakRef::Assign - Type does not provide wxTrackableBase - resetting tracked object") );
+ }
}
}
projects / wxWidgets.git / commitdiff
