2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Name: weakref.h
|
2008-09-25 17:31:45 -04:00
|
|
|
// Purpose: interface of wxWeakRefDynamic<T>, wxWeakRef<T>
|
2008-03-08 08:52:38 -05:00
|
|
|
// Author: wxWidgets team
|
|
|
|
// RCS-ID: $Id$
|
|
|
|
// Licence: wxWindows license
|
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
2008-09-25 17:31:45 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
2008-04-07 06:37:32 -04:00
|
|
|
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
|
2008-09-25 17:31:45 -04:00
|
|
|
defaults to using @c dynamic_cast for establishing the object reference
|
|
|
|
(while wxWeakRef defaults to @c static_cast).
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
So, wxWeakRef will detect a type mismatch during compile time and will
|
|
|
|
have a little better run-time performance. The role of wxWeakRefDynamic
|
2008-03-08 09:43:31 -05:00
|
|
|
is to handle objects which derived type one does not know.
|
|
|
|
|
2008-09-25 17:31:45 -04:00
|
|
|
@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).
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-07 06:37:32 -04:00
|
|
|
For general cases, wxWeakRef<T> is the better choice.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-09-25 17:31:45 -04:00
|
|
|
For API documentation, see: wxWeakRef<T>.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-10-09 12:42:52 -04:00
|
|
|
@tparam T
|
2008-12-29 09:14:39 -05:00
|
|
|
The type to which the smart pointer points to.
|
2008-10-09 12:42:52 -04:00
|
|
|
|
2008-09-25 17:31:45 -04:00
|
|
|
@nolibrary
|
2008-12-16 02:15:44 -05:00
|
|
|
@category{smartpointers}
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-04-06 20:17:06 -04:00
|
|
|
template<typename T>
|
2008-03-08 09:43:31 -05:00
|
|
|
class wxWeakRefDynamic<T>
|
2008-03-08 08:52:38 -05:00
|
|
|
{
|
|
|
|
public:
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
2008-09-25 17:31:45 -04:00
|
|
|
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.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-07 06:37:32 -04:00
|
|
|
wxWeakRef<T> can be used whenever one must keep a pointer to an object
|
2008-03-08 08:52:38 -05:00
|
|
|
that one does not directly own, and that may be destroyed before the object
|
2008-03-08 09:43:31 -05:00
|
|
|
holding the reference.
|
|
|
|
|
2008-04-07 06:37:32 -04:00
|
|
|
wxWeakRef<T> is a small object and the mechanism behind it is fast
|
2008-03-08 09:43:31 -05:00
|
|
|
(@b O(1)). So the overall cost of using it is small.
|
|
|
|
|
2008-09-25 17:31:45 -04:00
|
|
|
Example:
|
|
|
|
|
2008-04-07 06:46:15 -04:00
|
|
|
@code
|
|
|
|
wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" );
|
2008-09-25 17:31:45 -04:00
|
|
|
wxWeakRef<wxWindow> wr = wnd;
|
2008-04-07 06:46:15 -04:00
|
|
|
wxWindowRef wr2 = wnd; // Same as above, but using a typedef
|
|
|
|
// Do things with window
|
|
|
|
wnd->Show( true );
|
2008-09-25 17:31:45 -04:00
|
|
|
// Weak ref is used like an ordinary pointer
|
2008-04-07 06:46:15 -04:00
|
|
|
wr->Show( false );
|
2008-09-25 17:31:45 -04:00
|
|
|
wnd->Destroy();
|
2008-04-07 06:46:15 -04:00
|
|
|
// Now the weak ref has been reset, so we don't risk accessing
|
|
|
|
// a dangling pointer:
|
|
|
|
wxASSERT( wr==NULL );
|
|
|
|
@endcode
|
|
|
|
|
2008-09-25 17:31:45 -04:00
|
|
|
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:
|
2008-04-07 06:46:15 -04:00
|
|
|
|
|
|
|
@code
|
|
|
|
class wxMyTrackableObject : public wxObject, public wxTrackable
|
2008-09-25 17:31:45 -04:00
|
|
|
{
|
|
|
|
// ... other members here
|
|
|
|
};
|
2008-04-07 06:46:15 -04:00
|
|
|
@endcode
|
|
|
|
|
|
|
|
The following types of weak references are predefined:
|
|
|
|
|
|
|
|
@code
|
|
|
|
typedef wxWeakRef<wxEvtHandler> wxEvtHandlerRef;
|
|
|
|
typedef wxWeakRef<wxWindow> wxWindowRef;
|
|
|
|
@endcode
|
|
|
|
|
2008-10-09 12:42:52 -04:00
|
|
|
@tparam T
|
2008-12-29 09:14:39 -05:00
|
|
|
The type to which the smart pointer points to.
|
2008-10-09 12:42:52 -04:00
|
|
|
|
2008-09-25 17:31:45 -04:00
|
|
|
@nolibrary
|
2008-12-16 02:15:44 -05:00
|
|
|
@category{smartpointers}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-07 06:37:32 -04:00
|
|
|
@see wxSharedPtr<T>, wxScopedPtr<T>
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-04-06 20:17:06 -04:00
|
|
|
template<typename T>
|
2008-09-25 17:31:45 -04:00
|
|
|
class wxWeakRef<T> : public wxTrackerNode
|
2008-03-08 08:52:38 -05:00
|
|
|
{
|
|
|
|
public:
|
2010-04-10 14:13:23 -04:00
|
|
|
/// Type of the element stored by this reference.
|
|
|
|
typedef T element_type;
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
Constructor. The weak reference is initialized to @e pobj.
|
|
|
|
*/
|
2008-04-06 20:17:06 -04:00
|
|
|
wxWeakRef(T* pobj = NULL);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
2008-05-06 17:04:23 -04:00
|
|
|
/**
|
|
|
|
Copy constructor.
|
|
|
|
*/
|
|
|
|
wxWeakRef(const wxWeakRef<T>& wr);
|
2008-09-25 17:31:45 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
Destructor.
|
|
|
|
*/
|
2010-04-10 14:13:23 -04:00
|
|
|
virtual ~wxWeakRef();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Called when the tracked object is destroyed. Be default sets
|
2008-09-25 17:31:45 -04:00
|
|
|
internal pointer to @NULL.
|
|
|
|
You need to call this method if you override it.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
virtual void OnObjectDestroy();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Release currently tracked object and rests object reference.
|
|
|
|
*/
|
|
|
|
void Release();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns pointer to the tracked object or @NULL.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
T* get() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Release currently tracked object and start tracking the same object as
|
|
|
|
the wxWeakRef @e wr.
|
|
|
|
*/
|
|
|
|
T* operator =(wxWeakRef<T>& wr);
|
|
|
|
|
|
|
|
/**
|
2008-09-25 17:31:45 -04:00
|
|
|
Implicit conversion to T*.
|
|
|
|
Returns pointer to the tracked object or @NULL.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
T* operator*() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-09-25 17:31:45 -04:00
|
|
|
Returns a reference to the tracked object.
|
|
|
|
If the internal pointer is @NULL this method will cause an assert in debug mode.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-25 17:31:45 -04:00
|
|
|
T& operator*() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-09-25 17:31:45 -04:00
|
|
|
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.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
T* operator-();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Releases the currently tracked object and starts tracking @e pobj.
|
|
|
|
A weak reference may be reset by passing @e @NULL as @e pobj.
|
|
|
|
*/
|
|
|
|
T* operator=(T* pobj);
|
|
|
|
};
|
2008-03-10 11:24:38 -04:00
|
|
|
|