git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: weakref.h
	3	// Purpose: interface of wxWeakRefDynamic<T>, wxWeakRef<T>
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9
	10	/**
	11	@class wxWeakRefDynamic<T>
	12
	13	wxWeakRefDynamic<T> is a template class for weak references that is used in
	14	the same way as wxWeakRef<T>. The only difference is that wxWeakRefDynamic
	15	defaults to using @c dynamic_cast for establishing the object reference
	16	(while wxWeakRef defaults to @c static_cast).
	17
	18	So, wxWeakRef will detect a type mismatch during compile time and will
	19	have a little better run-time performance. The role of wxWeakRefDynamic
	20	is to handle objects which derived type one does not know.
	21
	22	@note wxWeakRef<T> selects an implementation based on the static type of T.
	23	If T does not have wxTrackable statically, it defaults to to a mixed-
	24	mode operation, where it uses @c dynamic_cast as the last measure
	25	(if available from the compiler and enabled when building wxWidgets).
	26
	27	For general cases, wxWeakRef<T> is the better choice.
	28
	29	For API documentation, see: wxWeakRef<T>.
	30
	31	@nolibrary
	32	@category{misc}
	33	*/
	34	template<typename T>
	35	class wxWeakRefDynamic<T>
	36	{
	37	public:
	38
	39	};
	40
	41
	42
	43	/**
	44	@class wxWeakRef<T>
	45
	46	wxWeakRef<T> is a template class for weak references to wxWidgets objects,
	47	such as wxEvtHandler, wxWindow and wxObject.
	48	A weak reference behaves much like an ordinary pointer, but when the object
	49	pointed is destroyed, the weak reference is automatically reset to a @NULL pointer.
	50
	51	wxWeakRef<T> can be used whenever one must keep a pointer to an object
	52	that one does not directly own, and that may be destroyed before the object
	53	holding the reference.
	54
	55	wxWeakRef<T> is a small object and the mechanism behind it is fast
	56	(@b O(1)). So the overall cost of using it is small.
	57
	58	Example:
	59
	60	@code
	61	wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" );
	62	wxWeakRef<wxWindow> wr = wnd;
	63	wxWindowRef wr2 = wnd; // Same as above, but using a typedef
	64	// Do things with window
	65	wnd->Show( true );
	66	// Weak ref is used like an ordinary pointer
	67	wr->Show( false );
	68	wnd->Destroy();
	69	// Now the weak ref has been reset, so we don't risk accessing
	70	// a dangling pointer:
	71	wxASSERT( wr==NULL );
	72	@endcode
	73
	74	wxWeakRef<T> works for any objects that are derived from wxTrackable.
	75	By default, wxEvtHandler and wxWindow derive from wxTrackable.
	76	However, wxObject does not, so types like wxFont and wxColour are not
	77	trackable. The example below shows how to create a wxObject derived class
	78	that is trackable:
	79
	80	@code
	81	class wxMyTrackableObject : public wxObject, public wxTrackable
	82	{
	83	// ... other members here
	84	};
	85	@endcode
	86
	87	The following types of weak references are predefined:
	88
	89	@code
	90	typedef wxWeakRef<wxEvtHandler> wxEvtHandlerRef;
	91	typedef wxWeakRef<wxWindow> wxWindowRef;
	92	@endcode
	93
	94	@nolibrary
	95	@category{misc}
	96
	97	@see wxSharedPtr<T>, wxScopedPtr<T>
	98	*/
	99	template<typename T>
	100	class wxWeakRef<T> : public wxTrackerNode
	101	{
	102	public:
	103	/**
	104	Constructor. The weak reference is initialized to @e pobj.
	105	*/
	106	wxWeakRef(T* pobj = NULL);
	107
	108	/**
	109	Copy constructor.
	110	*/
	111	wxWeakRef(const wxWeakRef<T>& wr);
	112
	113	/**
	114	Destructor.
	115	*/
	116	~wxWeakRef();
	117
	118	/**
	119	Called when the tracked object is destroyed. Be default sets
	120	internal pointer to @NULL.
	121	You need to call this method if you override it.
	122	*/
	123	virtual void OnObjectDestroy();
	124
	125	/**
	126	Release currently tracked object and rests object reference.
	127	*/
	128	void Release();
	129
	130	/**
	131	Returns pointer to the tracked object or @NULL.
	132	*/
	133	T* get() const;
	134
	135	/**
	136	Release currently tracked object and start tracking the same object as
	137	the wxWeakRef @e wr.
	138	*/
	139	T* operator =(wxWeakRef<T>& wr);
	140
	141	/**
	142	Implicit conversion to T*.
	143	Returns pointer to the tracked object or @NULL.
	144	*/
	145	T* operator*() const;
	146
	147	/**
	148	Returns a reference to the tracked object.
	149	If the internal pointer is @NULL this method will cause an assert in debug mode.
	150	*/
	151	T& operator*() const;
	152
	153	/**
	154	Smart pointer member access.
	155	Returns a pointer to the tracked object.
	156	If the internal pointer is @NULL this method will cause an assert in debug mode.
	157	*/
	158	T* operator-();
	159
	160	/**
	161	Releases the currently tracked object and starts tracking @e pobj.
	162	A weak reference may be reset by passing @e @NULL as @e pobj.
	163	*/
	164	T* operator=(T* pobj);
	165	};
	166