[wxWidgets.git] / include / wx / osx / core / cfref.h

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/mac/corefoundation/cfref.h
// Purpose:     wxCFRef template class
// Author:      David Elliott <dfe@cox.net>
// Modified by: Stefan Csomor
// Created:     2007/05/10
// RCS-ID:      $Id$
// Copyright:   (c) 2007 David Elliott <dfe@cox.net>, Stefan Csomor
// Licence:     wxWindows licence
// Notes:       See http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFMemoryMgmt/index.html
/////////////////////////////////////////////////////////////////////////////
/*! @header     wx/mac/corefoundation/cfref.h
    @abstract   wxCFRef template class
    @discussion FIXME: Convert doc tags to something less buggy with C++
*/

#ifndef _WX_MAC_COREFOUNDATION_CFREF_H__
#define _WX_MAC_COREFOUNDATION_CFREF_H__

// Include unistd to ensure that NULL is defined
#include <unistd.h>
// Include AvailabilityMacros for DEPRECATED_ATTRIBUTE
#include <AvailabilityMacros.h>

// #include <CoreFoundation/CFBase.h>
/* Don't include CFBase.h such that this header can be included from public
 * headers with minimal namespace pollution.
 * Note that Darwin CF uses extern for CF_EXPORT.  If we need this on Win32
 * or non-Darwin Mac OS we'll need to define the appropriate __declspec.
 */
typedef const void *CFTypeRef;
extern "C" {
extern /* CF_EXPORT */
CFTypeRef CFRetain(CFTypeRef cf);
extern /* CF_EXPORT */
void CFRelease(CFTypeRef cf);
} // extern "C"


/*! @function   wxCFRelease
    @abstract   A CFRelease variant that checks for NULL before releasing.
    @discussion The parameter is template not for type safety but to ensure the argument
                is a raw pointer and not a ref holder of any type.
*/
template <class Type>
inline void wxCFRelease(Type *r)
{
    if ( r != NULL )
        ::CFRelease((CFTypeRef)r);
}

/*! @function   wxCFRetain
    @abstract   A typesafe CFRetain variant that checks for NULL.
*/
template <class Type>
inline Type* wxCFRetain(Type *r)
{
    // NOTE(DE): Setting r to the result of CFRetain improves efficiency on both x86 and PPC
    // Casting r to CFTypeRef ensures we are calling the real C version defined in CFBase.h
    // and not any possibly templated/overloaded CFRetain.
    if ( r != NULL )
        r = (Type*)::CFRetain((CFTypeRef)r);
    return r;
}

template <class refType>
class wxCFRef;

/*! @class wxCFWeakRef
    @templatefield  refType     The CF reference type (e.g. CFStringRef, CFRunLoopRef, etc.)
                                It should already be a pointer.  This is different from
                                shared_ptr where the template parameter is the pointee type.
    @discussion Wraps a raw pointer without any retain or release.
                Provides a way to get what amounts to a raw pointer from a wxCFRef without
                using a raw pointer.  Unlike a raw pointer, constructing a wxCFRef from this
                class will cause it to be retained because it is assumed that a wxCFWeakRef
                does not own its pointer.
*/
template <class refType>
class wxCFWeakRef
{
    template <class refTypeA, class otherRefType>
    friend wxCFWeakRef<refTypeA> static_cfref_cast(const wxCFRef<otherRefType> &otherRef);
public:
    /*! @method     wxCFWeakRef
        @abstract   Creates a NULL reference
    */
    wxCFWeakRef()
    :   m_ptr(NULL)
    {}

    // Default copy constructor is fine.
    // Default destructor is fine but we'll set NULL to avoid bugs
    ~wxCFWeakRef()
    {   m_ptr = NULL; }

    // Do not implement a raw-pointer constructor.

    /*! @method     wxCFWeakRef
        @abstract   Copies another ref holder where its type can be converted to ours
        @templatefield otherRefType     Any type held by another wxCFWeakRef.
        @param otherRef The other weak ref holder to copy.
        @discussion This is merely a copy or implicit cast.
    */
    template <class otherRefType>
    wxCFWeakRef(const wxCFWeakRef<otherRefType>& otherRef)
    :   m_ptr(otherRef.get()) // Implicit conversion from otherRefType to refType should occur
    {}

    /*! @method     wxCFWeakRef
        @abstract   Copies a strong ref holder where its type can be converted to ours
        @templatefield otherRefType     Any type held by a wxCFRef.
        @param otherRef The strong ref holder to copy.
        @discussion This ref is merely a pointer copy, the strong ref still holds the pointer.
    */
    template <class otherRefType>
    wxCFWeakRef(const wxCFRef<otherRefType>& otherRef)
    :   m_ptr(otherRef.get()) // Implicit conversion from otherRefType to refType should occur
    {}

    /*! @method     get
        @abstract   Explicit conversion to the underlying pointer type
        @discussion Allows the caller to explicitly get the underlying pointer.
    */
    refType get() const
    {   return m_ptr; }

    /*! @method     operator refType
        @abstract   Implicit conversion to the underlying pointer type
        @discussion Allows the ref to be used in CF function calls.
    */
    operator refType() const
    {   return m_ptr; }

protected:
    /*! @method     wxCFWeakRef
        @abstract   Constructs a weak reference to the raw pointer
        @templatefield otherType    Any type.
        @param p        The raw pointer to assume ownership of.  May be NULL.
        @discussion This method is private so that the friend static_cfref_cast can use it
    */
    template <class otherType>
    explicit wxCFWeakRef(otherType *p)
    :   m_ptr(p) // Implicit conversion from otherType* to refType should occur.
    {}

    /*! @var m_ptr      The raw pointer.
    */
    refType m_ptr;
};

/*! @class wxCFRef
    @templatefield  refType     The CF reference type (e.g. CFStringRef, CFRunLoopRef, etc.)
                                It should already be a pointer.  This is different from
                                shared_ptr where the template parameter is the pointee type.
    @discussion Properly retains/releases reference to CoreFoundation objects
*/
template <class refType>
class wxCFRef
{
public:
    /*! @method     wxCFRef
        @abstract   Creates a NULL reference
    */
    wxCFRef()
    :   m_ptr(NULL)
    {}

    /*! @method     wxCFRef
        @abstract   Assumes ownership of p and creates a reference to it.
        @templatefield otherType    Any type.
        @param p        The raw pointer to assume ownership of.  May be NULL.
        @discussion Like shared_ptr, it is assumed that the caller has a strong reference to p and intends
                    to transfer ownership of that reference to this ref holder.  If the object comes from
                    a Create or Copy method then this is the correct behavior.  If the object comes from
                    a Get method then you must CFRetain it yourself before passing it to this constructor.
                    A handy way to do this is to use the non-member wxCFRefFromGet factory funcion.
                    This method is templated and takes an otherType *p.  This prevents implicit conversion
                    using an operator refType() in a different ref-holding class type.
    */
    template <class otherType>
    explicit wxCFRef(otherType *p)
    :   m_ptr(p) // Implicit conversion from otherType* to refType should occur.
    {}

    /*! @method     wxCFRef
        @abstract   Copies a ref holder of the same type
        @param otherRef The other ref holder to copy.
        @discussion Ownership will be shared by the original ref and the newly created ref. That is,
                    the object will be explicitly retained by this new ref.
    */
    wxCFRef(const wxCFRef& otherRef)
    :   m_ptr(wxCFRetain(otherRef.m_ptr))
    {}

    /*! @method     wxCFRef
        @abstract   Copies a ref holder where its type can be converted to ours
        @templatefield otherRefType     Any type held by another wxCFRef.
        @param otherRef The other ref holder to copy.
        @discussion Ownership will be shared by the original ref and the newly created ref. That is,
                    the object will be explicitly retained by this new ref.
    */
    template <class otherRefType>
    wxCFRef(const wxCFRef<otherRefType>& otherRef)
    :   m_ptr(wxCFRetain(otherRef.get())) // Implicit conversion from otherRefType to refType should occur
    {}

    /*! @method     wxCFRef
        @abstract   Copies a weak ref holder where its type can be converted to ours
        @templatefield otherRefType     Any type held by a wxCFWeakRef.
        @param otherRef The weak ref holder to copy.
        @discussion Ownership will be taken by this newly created ref. That is,
                    the object will be explicitly retained by this new ref.
                    Ownership is most likely shared with some other ref as well.
    */
    template <class otherRefType>
    wxCFRef(const wxCFWeakRef<otherRefType>& otherRef)
    :   m_ptr(wxCFRetain(otherRef.get())) // Implicit conversion from otherRefType to refType should occur
    {}

    /*! @method     ~wxCFRef
        @abstract   Releases (potentially shared) ownership of the ref.
        @discussion A ref holder instance is always assumed to have ownership so ownership is always
                    released (CFRelease called) upon destruction.
    */
    ~wxCFRef()
    {   reset(); }

    /*! @method     operator=
        @abstract   Assigns the other ref's pointer to us when the otherRef is the same type.
        @param otherRef The other ref holder to copy.
        @discussion The incoming pointer is retained, the original pointer is released, and this object
                    is made to point to the new pointer.
    */
    wxCFRef& operator=(const wxCFRef& otherRef)
    {
        wxCFRetain(otherRef.m_ptr);
        wxCFRelease(m_ptr);
        m_ptr = otherRef.m_ptr;
        return *this;
    }

    /*! @method     operator=
        @abstract   Assigns the other ref's pointer to us when the other ref can be converted to our type.
        @templatefield otherRefType     Any type held by another wxCFRef
        @param otherRef The other ref holder to copy.
        @discussion The incoming pointer is retained, the original pointer is released, and this object
                    is made to point to the new pointer.
    */
    template <class otherRefType>
    wxCFRef& operator=(const wxCFRef<otherRefType>& otherRef)
    {
        wxCFRetain(otherRef.get());
        wxCFRelease(m_ptr);
        m_ptr = otherRef.get(); // Implicit conversion from otherRefType to refType should occur
        return *this;
    }

    /*! @method     get
        @abstract   Explicit conversion to the underlying pointer type
        @discussion Allows the caller to explicitly get the underlying pointer.
    */
    refType get() const
    {   return m_ptr; }

    /*! @method     operator refType
        @abstract   Implicit conversion to the underlying pointer type
        @discussion Allows the ref to be used in CF function calls.
    */
    operator refType() const
    {   return m_ptr; }

#if 0
    <   // HeaderDoc is retarded and thinks the GT from operator-> is part of a template param.
        // So give it that < outside of a comment to fake it out. (if 0 is not a comment to HeaderDoc)
#endif

    /*! @method     operator-&gt;
        @abstract   Implicit conversion to the underlying pointer type
        @discussion This is nearly useless for CF types which are nearly always opaque
    */
    refType operator-> () const
    {   return m_ptr; }

    /*! @method     reset
        @abstract   Nullifies the reference
        @discussion Releases ownership (calls CFRelease) before nullifying the pointer.
    */
    void reset()
    {
        wxCFRelease(m_ptr);
        m_ptr = NULL;
    }

    /*! @method     reset
        @abstract   Sets this to a new reference
        @templatefield otherType    Any type.
        @param p        The raw pointer to assume ownership of
        @discussion The existing reference is released (like destruction).  It is assumed that the caller
                    has a strong reference to the new p and intends to transfer ownership of that reference
                    to this ref holder.  Take care to call CFRetain if you received the object from a Get method.
                    This method is templated and takes an otherType *p.  This prevents implicit conversion
                    using an operator refType() in a different ref-holding class type.
    */
    template <class otherType>
    void reset(otherType* p)
    {
        wxCFRelease(m_ptr);
        m_ptr = p; // Automatic conversion should occur
    }
protected:
    /*! @var m_ptr      The raw pointer.
    */
    refType m_ptr;
};

/*! @function   wxCFRefFromGet
    @abstract   Factory function to create wxCFRef from a raw pointer obtained from a Get-rule function
    @param  p           The pointer to retain and create a wxCFRef from.  May be NULL.
    @discussion Unlike the wxCFRef raw pointer constructor, this function explicitly retains its
                argument.  This can be used for functions such as CFDictionaryGetValue() or
                CFAttributedStringGetString() which return a temporary reference (Get-rule functions).
                FIXME: Anybody got a better name?
*/
template <typename Type>
inline wxCFRef<Type*> wxCFRefFromGet(Type *p)
{
    return wxCFRef<Type*>(wxCFRetain(p));
}

/*! @function   static_cfref_cast
    @abstract   Works like static_cast but with a wxCFRef as the argument.
    @param  refType     Template parameter.  The destination raw pointer type
    @param  otherRef    Normal parameter.  The source wxCFRef<> object.
    @discussion This is intended to be a clever way to make static_cast work while allowing
                the return value to be converted to either a strong ref or a raw pointer
                while ensuring that the retain count is updated appropriately.

                This is modeled after shared_ptr's static_pointer_cast.  Just as wxCFRef is
                parameterized on a pointer to an opaque type so is this class.  Note that
                this differs from shared_ptr which is parameterized on the pointee type.

                FIXME: Anybody got a better name?
*/
template <class refType, class otherRefType>
inline wxCFWeakRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef);

template <class refType, class otherRefType>
inline wxCFWeakRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef)
{
    return wxCFWeakRef<refType>(static_cast<refType>(otherRef.get()));
}

/*! @function   CFRelease
    @abstract   Overloads CFRelease so that the user is warned of bad behavior.
    @discussion It is rarely appropriate to retain or release a wxCFRef.  If one absolutely
                must do it he can explicitly get() the raw pointer
                Normally, this function is unimplemented resulting in a linker error if used.
*/
template <class T>
inline void CFRelease(const wxCFRef<T*> & cfref) DEPRECATED_ATTRIBUTE;

/*! @function   CFRetain
    @abstract   Overloads CFRetain so that the user is warned of bad behavior.
    @discussion It is rarely appropriate to retain or release a wxCFRef.  If one absolutely
                must do it he can explicitly get() the raw pointer
                Normally, this function is unimplemented resulting in a linker error if used.
*/
template <class T>
inline void CFRetain(const wxCFRef<T*>& cfref) DEPRECATED_ATTRIBUTE;

// Change the 0 to a 1 if you want the functions to work (no link errors)
// Neither function will cause retain/release side-effects if implemented.
#if 0
template <class T>
void CFRelease(const wxCFRef<T*> & cfref)
{
    CFRelease(cfref.get());
}

template <class T>
void CFRetain(const wxCFRef<T*> & cfref)
{
    CFRetain(cfref.get());
}
#endif

#endif //ndef _WX_MAC_COREFOUNDATION_CFREF_H__
Commit	Line	Data
5c6eb3a8 SC	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/mac/corefoundation/cfref.h
	3	// Purpose: wxCFRef template class
	4	// Author: David Elliott <dfe@cox.net>
	5	// Modified by: Stefan Csomor
	6	// Created: 2007/05/10
	7	// RCS-ID: $Id$
	8	// Copyright: (c) 2007 David Elliott <dfe@cox.net>, Stefan Csomor
	9	// Licence: wxWindows licence
	10	// Notes: See http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFMemoryMgmt/index.html
	11	/////////////////////////////////////////////////////////////////////////////
	12	/*! @header wx/mac/corefoundation/cfref.h
	13	@abstract wxCFRef template class
	14	@discussion FIXME: Convert doc tags to something less buggy with C++
	15	*/
	16
	17	#ifndef _WX_MAC_COREFOUNDATION_CFREF_H__
	18	#define _WX_MAC_COREFOUNDATION_CFREF_H__
	19
	20	// Include unistd to ensure that NULL is defined
	21	#include <unistd.h>
	22	// Include AvailabilityMacros for DEPRECATED_ATTRIBUTE
	23	#include <AvailabilityMacros.h>
	24
	25	// #include <CoreFoundation/CFBase.h>
	26	/* Don't include CFBase.h such that this header can be included from public
	27	* headers with minimal namespace pollution.
	28	* Note that Darwin CF uses extern for CF_EXPORT. If we need this on Win32
	29	* or non-Darwin Mac OS we'll need to define the appropriate __declspec.
	30	*/
	31	typedef const void *CFTypeRef;
	32	extern "C" {
	33	extern /* CF_EXPORT */
	34	CFTypeRef CFRetain(CFTypeRef cf);
	35	extern /* CF_EXPORT */
	36	void CFRelease(CFTypeRef cf);
	37	} // extern "C"
	38
	39
	40	/*! @function wxCFRelease
	41	@abstract A CFRelease variant that checks for NULL before releasing.
	42	@discussion The parameter is template not for type safety but to ensure the argument
	43	is a raw pointer and not a ref holder of any type.
	44	*/
	45	template <class Type>
	46	inline void wxCFRelease(Type *r)
	47	{
	48	if ( r != NULL )
	49	::CFRelease((CFTypeRef)r);
	50	}
	51
	52	/*! @function wxCFRetain
	53	@abstract A typesafe CFRetain variant that checks for NULL.
	54	*/
	55	template <class Type>
	56	inline Type* wxCFRetain(Type *r)
	57	{
	58	// NOTE(DE): Setting r to the result of CFRetain improves efficiency on both x86 and PPC
	59	// Casting r to CFTypeRef ensures we are calling the real C version defined in CFBase.h
	60	// and not any possibly templated/overloaded CFRetain.
	61	if ( r != NULL )
	62	r = (Type*)::CFRetain((CFTypeRef)r);
	63	return r;
	64	}
65
66	template <class refType>
67	class wxCFRef;
68
69	/*! @class wxCFWeakRef
70	@templatefield refType The CF reference type (e.g. CFStringRef, CFRunLoopRef, etc.)
71	It should already be a pointer. This is different from
72	shared_ptr where the template parameter is the pointee type.
73	@discussion Wraps a raw pointer without any retain or release.
74	Provides a way to get what amounts to a raw pointer from a wxCFRef without
75	using a raw pointer. Unlike a raw pointer, constructing a wxCFRef from this
76	class will cause it to be retained because it is assumed that a wxCFWeakRef
77	does not own its pointer.
78	*/
79	template <class refType>
80	class wxCFWeakRef
81	{
82	template <class refTypeA, class otherRefType>
83	friend wxCFWeakRef<refTypeA> static_cfref_cast(const wxCFRef<otherRefType> &otherRef);
84	public:
85	/*! @method wxCFWeakRef
86	@abstract Creates a NULL reference
87	*/
88	wxCFWeakRef()
89	: m_ptr(NULL)
90	{}
91
92	// Default copy constructor is fine.
93	// Default destructor is fine but we'll set NULL to avoid bugs
94	~wxCFWeakRef()
95	{ m_ptr = NULL; }
96
97	// Do not implement a raw-pointer constructor.
98
99	/*! @method wxCFWeakRef
100	@abstract Copies another ref holder where its type can be converted to ours
101	@templatefield otherRefType Any type held by another wxCFWeakRef.
102	@param otherRef The other weak ref holder to copy.
103	@discussion This is merely a copy or implicit cast.
104	*/
105	template <class otherRefType>
106	wxCFWeakRef(const wxCFWeakRef<otherRefType>& otherRef)
107	: m_ptr(otherRef.get()) // Implicit conversion from otherRefType to refType should occur
108	{}
109
110	/*! @method wxCFWeakRef
111	@abstract Copies a strong ref holder where its type can be converted to ours
112	@templatefield otherRefType Any type held by a wxCFRef.
113	@param otherRef The strong ref holder to copy.
114	@discussion This ref is merely a pointer copy, the strong ref still holds the pointer.
115	*/
116	template <class otherRefType>
117	wxCFWeakRef(const wxCFRef<otherRefType>& otherRef)
118	: m_ptr(otherRef.get()) // Implicit conversion from otherRefType to refType should occur
119	{}
120
121	/*! @method get
122	@abstract Explicit conversion to the underlying pointer type
123	@discussion Allows the caller to explicitly get the underlying pointer.
124	*/
125	refType get() const
126	{ return m_ptr; }
127
128	/*! @method operator refType
129	@abstract Implicit conversion to the underlying pointer type
130	@discussion Allows the ref to be used in CF function calls.
131	*/
132	operator refType() const
133	{ return m_ptr; }
134
135	protected:
136	/*! @method wxCFWeakRef
137	@abstract Constructs a weak reference to the raw pointer
138	@templatefield otherType Any type.
139	@param p The raw pointer to assume ownership of. May be NULL.
140	@discussion This method is private so that the friend static_cfref_cast can use it
141	*/
142	template <class otherType>
143	explicit wxCFWeakRef(otherType *p)
144	: m_ptr(p) // Implicit conversion from otherType* to refType should occur.
145	{}
146
147	/*! @var m_ptr The raw pointer.
148	*/
149	refType m_ptr;
150	};
151
152	/*! @class wxCFRef
153	@templatefield refType The CF reference type (e.g. CFStringRef, CFRunLoopRef, etc.)
154	It should already be a pointer. This is different from
155	shared_ptr where the template parameter is the pointee type.
156	@discussion Properly retains/releases reference to CoreFoundation objects
157	*/
158	template <class refType>
159	class wxCFRef
160	{
161	public:
162	/*! @method wxCFRef
163	@abstract Creates a NULL reference
164	*/
165	wxCFRef()
166	: m_ptr(NULL)
167	{}
168
169	/*! @method wxCFRef
170	@abstract Assumes ownership of p and creates a reference to it.
171	@templatefield otherType Any type.
172	@param p The raw pointer to assume ownership of. May be NULL.
173	@discussion Like shared_ptr, it is assumed that the caller has a strong reference to p and intends
174	to transfer ownership of that reference to this ref holder. If the object comes from
175	a Create or Copy method then this is the correct behavior. If the object comes from
176	a Get method then you must CFRetain it yourself before passing it to this constructor.
177	A handy way to do this is to use the non-member wxCFRefFromGet factory funcion.
178	This method is templated and takes an otherType *p. This prevents implicit conversion
179	using an operator refType() in a different ref-holding class type.
180	*/
181	template <class otherType>
182	explicit wxCFRef(otherType *p)
183	: m_ptr(p) // Implicit conversion from otherType* to refType should occur.
184	{}
185
186	/*! @method wxCFRef
187	@abstract Copies a ref holder of the same type
188	@param otherRef The other ref holder to copy.
189	@discussion Ownership will be shared by the original ref and the newly created ref. That is,
190	the object will be explicitly retained by this new ref.
191	*/
192	wxCFRef(const wxCFRef& otherRef)
193	: m_ptr(wxCFRetain(otherRef.m_ptr))
194	{}
195
196	/*! @method wxCFRef
197	@abstract Copies a ref holder where its type can be converted to ours
198	@templatefield otherRefType Any type held by another wxCFRef.
199	@param otherRef The other ref holder to copy.
200	@discussion Ownership will be shared by the original ref and the newly created ref. That is,
201	the object will be explicitly retained by this new ref.
202	*/
203	template <class otherRefType>
204	wxCFRef(const wxCFRef<otherRefType>& otherRef)
205	: m_ptr(wxCFRetain(otherRef.get())) // Implicit conversion from otherRefType to refType should occur
206	{}
207
208	/*! @method wxCFRef
209	@abstract Copies a weak ref holder where its type can be converted to ours
210	@templatefield otherRefType Any type held by a wxCFWeakRef.
211	@param otherRef The weak ref holder to copy.
212	@discussion Ownership will be taken by this newly created ref. That is,
213	the object will be explicitly retained by this new ref.
214	Ownership is most likely shared with some other ref as well.
215	*/
216	template <class otherRefType>
217	wxCFRef(const wxCFWeakRef<otherRefType>& otherRef)
218	: m_ptr(wxCFRetain(otherRef.get())) // Implicit conversion from otherRefType to refType should occur
219	{}
220
221	/*! @method ~wxCFRef
222	@abstract Releases (potentially shared) ownership of the ref.
223	@discussion A ref holder instance is always assumed to have ownership so ownership is always
224	released (CFRelease called) upon destruction.
225	*/
226	~wxCFRef()
227	{ reset(); }
228
229	/*! @method operator=
230	@abstract Assigns the other ref's pointer to us when the otherRef is the same type.
231	@param otherRef The other ref holder to copy.
232	@discussion The incoming pointer is retained, the original pointer is released, and this object
233	is made to point to the new pointer.
234	*/
235	wxCFRef& operator=(const wxCFRef& otherRef)
236	{
237	wxCFRetain(otherRef.m_ptr);
238	wxCFRelease(m_ptr);
239	m_ptr = otherRef.m_ptr;
240	return *this;
241	}
242
243	/*! @method operator=
244	@abstract Assigns the other ref's pointer to us when the other ref can be converted to our type.
245	@templatefield otherRefType Any type held by another wxCFRef
246	@param otherRef The other ref holder to copy.
247	@discussion The incoming pointer is retained, the original pointer is released, and this object
248	is made to point to the new pointer.
249	*/
250	template <class otherRefType>
251	wxCFRef& operator=(const wxCFRef<otherRefType>& otherRef)
252	{
253	wxCFRetain(otherRef.get());
254	wxCFRelease(m_ptr);
255	m_ptr = otherRef.get(); // Implicit conversion from otherRefType to refType should occur
256	return *this;
257	}
258
259	/*! @method get
260	@abstract Explicit conversion to the underlying pointer type
261	@discussion Allows the caller to explicitly get the underlying pointer.
262	*/
263	refType get() const
264	{ return m_ptr; }
265
266	/*! @method operator refType
267	@abstract Implicit conversion to the underlying pointer type
268	@discussion Allows the ref to be used in CF function calls.
269	*/
270	operator refType() const
271	{ return m_ptr; }
272
273	#if 0
274	< // HeaderDoc is retarded and thinks the GT from operator-> is part of a template param.
275	// So give it that < outside of a comment to fake it out. (if 0 is not a comment to HeaderDoc)
276	#endif
277
278	/*! @method operator->
279	@abstract Implicit conversion to the underlying pointer type
280	@discussion This is nearly useless for CF types which are nearly always opaque
281	*/
282	refType operator-> () const
283	{ return m_ptr; }
284
285	/*! @method reset
286	@abstract Nullifies the reference
287	@discussion Releases ownership (calls CFRelease) before nullifying the pointer.
288	*/
289	void reset()
290	{
291	wxCFRelease(m_ptr);
292	m_ptr = NULL;
293	}
294
295	/*! @method reset
296	@abstract Sets this to a new reference
297	@templatefield otherType Any type.
298	@param p The raw pointer to assume ownership of
299	@discussion The existing reference is released (like destruction). It is assumed that the caller
300	has a strong reference to the new p and intends to transfer ownership of that reference
301	to this ref holder. Take care to call CFRetain if you received the object from a Get method.
302	This method is templated and takes an otherType *p. This prevents implicit conversion
303	using an operator refType() in a different ref-holding class type.
304	*/
305	template <class otherType>
306	void reset(otherType* p)
307	{
308	wxCFRelease(m_ptr);
309	m_ptr = p; // Automatic conversion should occur
310	}
311	protected:
312	/*! @var m_ptr The raw pointer.
313	*/
314	refType m_ptr;
315	};
316
317	/*! @function wxCFRefFromGet
318	@abstract Factory function to create wxCFRef from a raw pointer obtained from a Get-rule function
319	@param p The pointer to retain and create a wxCFRef from. May be NULL.
320	@discussion Unlike the wxCFRef raw pointer constructor, this function explicitly retains its
321	argument. This can be used for functions such as CFDictionaryGetValue() or
322	CFAttributedStringGetString() which return a temporary reference (Get-rule functions).
323	FIXME: Anybody got a better name?
324	*/
325	template <typename Type>
326	inline wxCFRef<Type> wxCFRefFromGet(Type p)
327	{
328	return wxCFRef<Type*>(wxCFRetain(p));
329	}
330
331	/*! @function static_cfref_cast
332	@abstract Works like static_cast but with a wxCFRef as the argument.
333	@param refType Template parameter. The destination raw pointer type
334	@param otherRef Normal parameter. The source wxCFRef<> object.
335	@discussion This is intended to be a clever way to make static_cast work while allowing
336	the return value to be converted to either a strong ref or a raw pointer
337	while ensuring that the retain count is updated appropriately.
338
339	This is modeled after shared_ptr's static_pointer_cast. Just as wxCFRef is
340	parameterized on a pointer to an opaque type so is this class. Note that
341	this differs from shared_ptr which is parameterized on the pointee type.
342
343	FIXME: Anybody got a better name?
344	*/
345	template <class refType, class otherRefType>
346	inline wxCFWeakRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef);
347
348	template <class refType, class otherRefType>
349	inline wxCFWeakRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef)
350	{
351	return wxCFWeakRef<refType>(static_cast<refType>(otherRef.get()));
352	}
353
354	/*! @function CFRelease
355	@abstract Overloads CFRelease so that the user is warned of bad behavior.
356	@discussion It is rarely appropriate to retain or release a wxCFRef. If one absolutely
357	must do it he can explicitly get() the raw pointer
358	Normally, this function is unimplemented resulting in a linker error if used.
359	*/
360	template <class T>
361	inline void CFRelease(const wxCFRef<T*> & cfref) DEPRECATED_ATTRIBUTE;
362
363	/*! @function CFRetain
364	@abstract Overloads CFRetain so that the user is warned of bad behavior.
365	@discussion It is rarely appropriate to retain or release a wxCFRef. If one absolutely
366	must do it he can explicitly get() the raw pointer
367	Normally, this function is unimplemented resulting in a linker error if used.
368	*/
369	template <class T>
370	inline void CFRetain(const wxCFRef<T*>& cfref) DEPRECATED_ATTRIBUTE;
371
372	// Change the 0 to a 1 if you want the functions to work (no link errors)
373	// Neither function will cause retain/release side-effects if implemented.
374	#if 0
375	template <class T>
376	void CFRelease(const wxCFRef<T*> & cfref)
377	{
378	CFRelease(cfref.get());
379	}
380
381	template <class T>
382	void CFRetain(const wxCFRef<T*> & cfref)
383	{
384	CFRetain(cfref.get());
385	}
386	#endif
387
388	#endif //ndef _WX_MAC_COREFOUNDATION_CFREF_H__
389