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

... / ...

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