[wxWidgets.git] / include / wx / mac / corefoundation / 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 <CoreFoundation/CFBase.h>

/*! @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;
}

/*! @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   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 from one wxCFRef to another
    @param  refType     Template parameter.  The destination raw pointer type
    @param  otherRef    Normal parameter.  The source wxCFRef<> object.
    @discussion 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 wxCFRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef);

template <class refType, class otherRefType>
inline wxCFRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef)
{
    return wxCFRef<refType>(static_cast<refType>(wxCFRetain(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
b4e0eabd DE	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/mac/corefoundation/cfref.h
	3	// Purpose: wxCFRef template class
	4	// Author: David Elliott <dfe@cox.net>
fd9cd37f	5	// Modified by: Stefan Csomor
b4e0eabd DE	6	// Created: 2007/05/10
b4e0eabd DE	7	// RCS-ID: $Id$
fd9cd37f	8	// Copyright: (c) 2007 David Elliott <dfe@cox.net>, Stefan Csomor
b4e0eabd DE	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 <CoreFoundation/CFBase.h>
	21
fd9cd37f DE	22	/*! @function wxCFRelease
fd9cd37f DE	23	@abstract A CFRelease variant that checks for NULL before releasing.
69726164 DE	24	@discussion The parameter is template not for type safety but to ensure the argument
69726164 DE	25	is a raw pointer and not a ref holder of any type.
fd9cd37f	26	*/
69726164 DE	27	template <class Type>
69726164 DE	28	inline void wxCFRelease(Type *r)
fd9cd37f DE	29	{
fd9cd37f DE	30	if ( r != NULL )
69726164	31	::CFRelease((CFTypeRef)r);
fd9cd37f DE	32	}
	33
	34	/*! @function wxCFRetain
	35	@abstract A typesafe CFRetain variant that checks for NULL.
	36	*/
	37	template <class Type>
	38	inline Type* wxCFRetain(Type *r)
	39	{
	40	// NOTE(DE): Setting r to the result of CFRetain improves efficiency on both x86 and PPC
	41	// Casting r to CFTypeRef ensures we are calling the real C version defined in CFBase.h
	42	// and not any possibly templated/overloaded CFRetain.
	43	if ( r != NULL )
	44	r = (Type*)::CFRetain((CFTypeRef)r);
	45	return r;
	46	}
	47
b4e0eabd DE	48	/*! @class wxCFRef
	49	@templatefield refType The CF reference type (e.g. CFStringRef, CFRunLoopRef, etc.)
	50	It should already be a pointer. This is different from
	51	shared_ptr where the template parameter is the pointee type.
	52	@discussion Properly retains/releases reference to CoreFoundation objects
	53	*/
	54	template <class refType>
	55	class wxCFRef
	56	{
b4e0eabd DE	57	public:
	58	/*! @method wxCFRef
	59	@abstract Creates a NULL reference
	60	*/
	61	wxCFRef()
	62	: m_ptr(NULL)
	63	{}
	64
	65	/*! @method wxCFRef
	66	@abstract Assumes ownership of p and creates a reference to it.
	67	@templatefield otherType Any type.
	68	@param p The raw pointer to assume ownership of. May be NULL.
	69	@discussion Like shared_ptr, it is assumed that the caller has a strong reference to p and intends
	70	to transfer ownership of that reference to this ref holder. If the object comes from
	71	a Create or Copy method then this is the correct behavior. If the object comes from
	72	a Get method then you must CFRetain it yourself before passing it to this constructor.
	73	A handy way to do this is to use the non-member wxCFRefFromGet factory funcion.
	74	This method is templated and takes an otherType *p. This prevents implicit conversion
	75	using an operator refType() in a different ref-holding class type.
	76	*/
	77	template <class otherType>
	78	explicit wxCFRef(otherType *p)
	79	: m_ptr(p) // Implicit conversion from otherType* to refType should occur.
	80	{}
	81
	82	/*! @method wxCFRef
	83	@abstract Copies a ref holder of the same type
	84	@param otherRef The other ref holder to copy.
	85	@discussion Ownership will be shared by the original ref and the newly created ref. That is,
	86	the object will be explicitly retained by this new ref.
	87	*/
	88	wxCFRef(const wxCFRef& otherRef)
fd9cd37f DE	89	: m_ptr(wxCFRetain(otherRef.m_ptr))
fd9cd37f DE	90	{}
b4e0eabd DE	91
	92	/*! @method wxCFRef
	93	@abstract Copies a ref holder where its type can be converted to ours
	94	@templatefield otherRefType Any type held by another wxCFRef.
	95	@param otherRef The other ref holder to copy.
	96	@discussion Ownership will be shared by the original ref and the newly created ref. That is,
	97	the object will be explicitly retained by this new ref.
	98	*/
	99	template <class otherRefType>
	100	wxCFRef(const wxCFRef<otherRefType>& otherRef)
fd9cd37f DE	101	: m_ptr(wxCFRetain(otherRef.get())) // Implicit conversion from otherRefType to refType should occur
fd9cd37f DE	102	{}
b4e0eabd DE	103
	104	/*! @method ~wxCFRef
	105	@abstract Releases (potentially shared) ownership of the ref.
	106	@discussion A ref holder instance is always assumed to have ownership so ownership is always
	107	released (CFRelease called) upon destruction.
	108	*/
	109	~wxCFRef()
	110	{ reset(); }
	111
	112	/*! @method operator=
	113	@abstract Assigns the other ref's pointer to us when the otherRef is the same type.
	114	@param otherRef The other ref holder to copy.
	115	@discussion The incoming pointer is retained, the original pointer is released, and this object
	116	is made to point to the new pointer.
	117	*/
	118	wxCFRef& operator=(const wxCFRef& otherRef)
	119	{
fd9cd37f DE	120	wxCFRetain(otherRef.m_ptr);
fd9cd37f DE	121	wxCFRelease(m_ptr);
b4e0eabd DE	122	m_ptr = otherRef.m_ptr;
	123	return *this;
	124	}
	125
	126	/*! @method operator=
	127	@abstract Assigns the other ref's pointer to us when the other ref can be converted to our type.
	128	@templatefield otherRefType Any type held by another wxCFRef
	129	@param otherRef The other ref holder to copy.
	130	@discussion The incoming pointer is retained, the original pointer is released, and this object
	131	is made to point to the new pointer.
	132	*/
	133	template <class otherRefType>
	134	wxCFRef& operator=(const wxCFRef<otherRefType>& otherRef)
	135	{
fd9cd37f DE	136	wxCFRetain(otherRef.get());
	137	wxCFRelease(m_ptr);
	138	m_ptr = otherRef.get(); // Implicit conversion from otherRefType to refType should occur
b4e0eabd DE	139	return *this;
	140	}
	141
	142	/*! @method get
	143	@abstract Explicit conversion to the underlying pointer type
	144	@discussion Allows the caller to explicitly get the underlying pointer.
	145	*/
	146	refType get() const
	147	{ return m_ptr; }
	148
	149	/*! @method operator refType
	150	@abstract Implicit conversion to the underlying pointer type
	151	@discussion Allows the ref to be used in CF function calls.
	152	*/
	153	operator refType() const
	154	{ return m_ptr; }
	155
	156	#if 0
	157	< // HeaderDoc is retarded and thinks the GT from operator-> is part of a template param.
	158	// So give it that < outside of a comment to fake it out. (if 0 is not a comment to HeaderDoc)
	159	#endif
	160
	161	/*! @method operator->
	162	@abstract Implicit conversion to the underlying pointer type
	163	@discussion This is nearly useless for CF types which are nearly always opaque
	164	*/
	165	refType operator-> () const
	166	{ return m_ptr; }
	167
	168	/*! @method reset
	169	@abstract Nullifies the reference
	170	@discussion Releases ownership (calls CFRelease) before nullifying the pointer.
	171	*/
	172	void reset()
	173	{
fd9cd37f	174	wxCFRelease(m_ptr);
b4e0eabd DE	175	m_ptr = NULL;
	176	}
	177
	178	/*! @method reset
	179	@abstract Sets this to a new reference
	180	@templatefield otherType Any type.
	181	@param p The raw pointer to assume ownership of
	182	@discussion The existing reference is released (like destruction). It is assumed that the caller
	183	has a strong reference to the new p and intends to transfer ownership of that reference
	184	to this ref holder. Take care to call CFRetain if you received the object from a Get method.
	185	This method is templated and takes an otherType *p. This prevents implicit conversion
	186	using an operator refType() in a different ref-holding class type.
	187	*/
	188	template <class otherType>
	189	void reset(otherType* p)
	190	{
fd9cd37f	191	wxCFRelease(m_ptr);
b4e0eabd DE	192	m_ptr = p; // Automatic conversion should occur
	193	}
	194	protected:
	195	/*! @var m_ptr The raw pointer.
	196	*/
	197	refType m_ptr;
	198	};
	199
	200	/*! @function wxCFRefFromGet
	201	@abstract Factory function to create wxCFRef from a raw pointer obtained from a Get-rule function
	202	@param p The pointer to retain and create a wxCFRef from. May be NULL.
	203	@discussion Unlike the wxCFRef raw pointer constructor, this function explicitly retains its
	204	argument. This can be used for functions such as CFDictionaryGetValue() or
	205	CFAttributedStringGetString() which return a temporary reference (Get-rule functions).
	206	FIXME: Anybody got a better name?
	207	*/
	208	template <typename Type>
	209	inline wxCFRef<Type> wxCFRefFromGet(Type p)
	210	{
fd9cd37f	211	return wxCFRef<Type*>(wxCFRetain(p));
b4e0eabd DE	212	}
	213
	214	/*! @function static_cfref_cast
	215	@abstract Works like static_cast but from one wxCFRef to another
	216	@param refType Template parameter. The destination raw pointer type
	217	@param otherRef Normal parameter. The source wxCFRef<> object.
	218	@discussion This is modeled after shared_ptr's static_pointer_cast. Just as wxCFRef is
	219	parameterized on a pointer to an opaque type so is this class. Note that
	220	this differs from shared_ptr which is parameterized on the pointee type.
	221	FIXME: Anybody got a better name?
	222	*/
	223	template <class refType, class otherRefType>
	224	inline wxCFRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef);
	225
	226	template <class refType, class otherRefType>
	227	inline wxCFRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef)
	228	{
fd9cd37f	229	return wxCFRef<refType>(static_cast<refType>(wxCFRetain(otherRef.get())));
b4e0eabd DE	230	}
	231
	232	/*! @function CFRelease
	233	@abstract Overloads CFRelease so that the user is warned of bad behavior.
	234	@discussion It is rarely appropriate to retain or release a wxCFRef. If one absolutely
	235	must do it he can explicitly get() the raw pointer
	236	Normally, this function is unimplemented resulting in a linker error if used.
	237	*/
	238	template <class T>
	239	inline void CFRelease(const wxCFRef<T*> & cfref) DEPRECATED_ATTRIBUTE;
	240
	241	/*! @function CFRetain
	242	@abstract Overloads CFRetain so that the user is warned of bad behavior.
	243	@discussion It is rarely appropriate to retain or release a wxCFRef. If one absolutely
	244	must do it he can explicitly get() the raw pointer
	245	Normally, this function is unimplemented resulting in a linker error if used.
	246	*/
	247	template <class T>
	248	inline void CFRetain(const wxCFRef<T*>& cfref) DEPRECATED_ATTRIBUTE;
	249
	250	// Change the 0 to a 1 if you want the functions to work (no link errors)
	251	// Neither function will cause retain/release side-effects if implemented.
	252	#if 0
	253	template <class T>
	254	void CFRelease(const wxCFRef<T*> & cfref)
	255	{
	256	CFRelease(cfref.get());
	257	}
	258
	259	template <class T>
	260	void CFRetain(const wxCFRef<T*> & cfref)
	261	{
	262	CFRetain(cfref.get());
	263	}
	264	#endif
	265
	266	#endif //ndef _WX_MAC_COREFOUNDATION_CFREF_H__
	267