[wxWidgets.git] / interface / wx / any.h

/////////////////////////////////////////////////////////////////////////////
// Name:        any.h
// Purpose:     interface of wxAny
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////


/**
    @class wxAny

    The wxAny class represents a container for any type. Its value
    can be changed at run time, possibly to a different type of value.

    wxAny is a backwards incompatible successor class for wxVariant,
    essentially doing the same thing in a more modern, template-based manner
    and with transparent support for any user data type.

    Some pseudo-code'ish example of use with arbitrary user data:

    @code
    void SomeFunction()
    {
        MyClass myObject;
        wxAny any = myObject;

        // Do something
        // ...

        // Let's do a sanity check to make sure that any still holds
        // data of correct type.
        if ( any.CheckType<MyClass>() )
        {
            // Thank goodness, still a correct type.
            MyClass myObject2 = any.As<MyClass>();
        }
        else
        {
            // Something has gone horribly wrong!
            wxFAIL();
        }
    }
    @endcode

    When compared to wxVariant, there are various internal implementation
    differences as well. For instance, wxAny only allocates separate data
    object in heap for large (ie. size in bytes more than
    WX_ANY_VALUE_BUFFER_SIZE) or 'non-movable' data types. Pointers, integers,
    bools etc. are fitted in the wxAny's own buffer without need for any extra
    allocation. Use following code to declare your own data type as 'movable':

    @code
    #include "wx/meta/movable.h"
    WX_DECLARE_TYPE_MOVABLE(MyClass)
    @endcode

    However, you must be aware that 'movable' means such data that can be
    copied with memcpy() without corrupting program integrity. For instance,
    movable objects usually cannot contain pointers or references to other
    data. wxRect, wxPoint, and wxSize are good examples of movable classes.

    Note that pointers to any and all classes are already automatically
    declared as movable data.

    @library{wxbase}
    @category{data}

    @see wxAnyValueType, wxVariant, @ref overview_cpp_rtti_disabled
*/
class wxAny
{
public:
    /**
        Default constructor. It seeds the object with a null value.
    */
    wxAny();

    /**
        Constructs wxAny from data.
    */
    template<typename T>
    wxAny(const T& value);

    /**
        Constructs wxAny from another wxAny.
    */
    wxAny(const wxAny& any);

    /**
        Destructor.
    */
    ~wxAny();

    /**
        This template function converts wxAny into given type. No dynamic
        conversion is performed, so if the type is incorrect an assertion
        failure will occur in debug builds, and a bogus value is returned
        in release ones.

        @remarks This template function may not work properly with Visual C++
                6. For full compiler compatibility, please use
                wxANY_AS(any, T) macro instead.
    */
    template<typename T>
    T As() const;

    /**
        Use this template function for checking if this wxAny holds
        a specific C++ data type.

        @remarks This template function may not work properly with Visual C++
                6. For full compiler compatibility, please use
                wxANY_CHECK_TYPE(any, T) macro instead.

        @see wxAnyValueType::CheckType()
    */
    template<typename T>
    bool CheckType();

    /**
        Template function that retrieves and converts the value of this
        wxAny to the type that T* value is.

        @return Returns @true if conversion was successful.
    */
    template<typename T>
    bool GetAs(T* value) const;

    /**
        Returns the value type as wxAnyValueType instance.

        @remarks You cannot reliably test whether two wxAnys are of
                same value type by simply comparing return values
                of wxAny::GetType(). Instead use
                wxAnyValueType::CheckType<T>() template function.
    */
    const wxAnyValueType* GetType() const;

    /**
        Tests if wxAny is null (that is, whether there is data).
    */
    bool IsNull() const;

    /**
        Makes wxAny null (that is, clears it).
    */
    void MakeNull();

    //@{
    /**
        @name Assignment operators
    */
    template<typename T>
    wxAny& operator=(const T &value);
    wxAny& operator=(const wxAny &any);
    //@}

    //@{
    /**
        @name Equality operators

        @remarks Generic template-based comparison operators have not been
                provided for various code consistency reasons, so for custom
                data types you have do something like this:

                @code
                if ( any.CheckType<MyClass*>() &&
                     any.As<MyClass*>() == myObjectPtr )
                {
                    // Do something if any stores myObjectPtr
                }
                @endcode
    */
    bool operator==(signed char value) const;
    bool operator==(signed short value) const;
    bool operator==(signed int value) const;
    bool operator==(signed long value) const;
    bool operator==(wxLongLong_t value) const;
    bool operator==(unsigned char value) const;
    bool operator==(unsigned short value) const;
    bool operator==(unsigned int value) const;
    bool operator==(unsigned long value) const;
    bool operator==(wxULongLong_t value) const;
    bool operator==(float value) const;
    bool operator==(double value) const;
    bool operator==(bool value) const;
    bool operator==(const char* value) const;
    bool operator==(const wchar_t* value) const;
    bool operator==(const wxString& value) const;
    //@}

    //@{
    /**
        @name Inequality operators
    */
    bool operator!=(signed char value) const;
    bool operator!=(signed short value) const;
    bool operator!=(signed int value) const;
    bool operator!=(signed long value) const;
    bool operator!=(wxLongLong_t value) const;
    bool operator!=(unsigned char value) const;
    bool operator!=(unsigned short value) const;
    bool operator!=(unsigned int value) const;
    bool operator!=(unsigned long value) const;
    bool operator!=(wxULongLong_t value) const;
    bool operator!=(float value) const;
    bool operator!=(double value) const;
    bool operator!=(bool value) const;
    bool operator!=(const char* value) const;
    bool operator!=(const wchar_t* value) const;
    bool operator!=(const wxString& value) const;
    //@}
};

/**
    This is value getter macro that is more compatible with older
    compilers, such as Visual C++ 6.0.
*/
#define wxANY_AS(any, T)


/**
    This is type checking macro that is more compatible with older
    compilers, such as Visual C++ 6.0.
*/
#define wxANY_CHECK_TYPE(any, T)


/**
    Size of the wxAny value buffer.
*/
enum
{
    WX_ANY_VALUE_BUFFER_SIZE = 16
};

/**
    Type for buffer within wxAny for holding data.
*/
union wxAnyValueBuffer
{
    void*   m_ptr;
    wxByte  m_buffer[WX_ANY_VALUE_BUFFER_SIZE];
};


/**
    @class wxAnyValueType

    wxAnyValueType is base class for value type functionality for C++ data
    types used with wxAny. Usually the default template will create a
    satisfactory wxAnyValueType implementation for a data type, but
    sometimes you may need to add some customization. To do this you will need
    to add specialized template of wxAnyValueTypeImpl<>. Often your only
    need may be to add dynamic type conversion which would be done like
    this:

    @code
        template<>
        class wxAnyValueTypeImpl<MyClass> :
            public wxAnyValueTypeImplBase<MyClass>
        {
            WX_DECLARE_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
        public:
            wxAnyValueTypeImpl() :
                wxAnyValueTypeImplBase<MyClass>() { }
            virtual ~wxAnyValueTypeImpl() { }

            virtual bool ConvertValue(const wxAnyValueBuffer& src,
                                      wxAnyValueType* dstType,
                                      wxAnyValueBuffer& dst) const
            {
                // GetValue() is a static member function implemented
                // in wxAnyValueTypeImplBase<>.
                MyClass value = GetValue(src);

                // TODO: Convert value from src buffer to destination
                //       type and buffer. If cannot be done, return
                //       false. This is a simple sample.
                if ( dstType->CheckType<wxString>() )
                {
                    wxString s = value.ToString();
                    wxAnyValueTypeImpl<wxString>::SetValue(s, dst);
                }
                else
                {
                    return false;
                }
            }
        };

        //
        // Following must be placed somewhere in your source code
        WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
    @endcode

    wxAnyValueTypeImplBase<> template, from which we inherit in the above
    example, contains the bulk of the default wxAnyValueTypeImpl<> template
    implementation, and as such allows you to easily add some minor
    customization.

    If you need a have complete control over the type interpretation, you
    will need to derive a class directly from wxAnyValueType, like this:

    @code
        template <>
        class wxAnyValueTypeImpl<MyClass> : public wxAnyValueType
        {
            WX_DECLARE_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
        public:
            virtual void DeleteValue(wxAnyValueBuffer& buf) const
            {
                // TODO: Free the data in buffer
                // It is important to clear the buffer like this
                // at the end of DeleteValue().
                buf.m_ptr = NULL;
            }

            virtual void CopyBuffer(const wxAnyValueBuffer& src,
                                    wxAnyValueBuffer& dst) const
            {
                // TODO: Copy value from one buffer to another.
                //       dst is already uninitialized and does not
                //       need to be freed.
            }

            virtual bool ConvertValue(const wxAnyValueBuffer& src,
                                      wxAnyValueType* dstType,
                                      wxAnyValueBuffer& dst) const
            {
                // TODO: Convert value from src buffer to destination
                //       type and buffer.
            }

            //
            // Following static functions must be implemented
            //

            static void SetValue(const T& value,
                                 wxAnyValueBuffer& buf)
            {
                // TODO: Store value into buf.
            }

            static const T& GetValue(const wxAnyValueBuffer& buf)
            {
                // TODO: Return reference to value stored in buffer.
            }
        };

        //
        // Following must be placed somewhere in your source code
        WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)

    @endcode

    @library{wxbase}
    @category{data}

    @see wxAny
*/
class wxAnyValueType
{
public:
    /**
        Default constructor.
    */
    wxAnyValueType();

    /**
        Destructor.
    */
    virtual ~wxAnyValueType();

    /**
        Use this template function for checking if wxAnyValueType represents
        a specific C++ data type.

        @remarks This template function does not work on some older compilers
                (such as Visual C++ 6.0). For full compiler ccompatibility
                please use wxANY_VALUE_TYPE_CHECK_TYPE(valueTypePtr, T) macro
                instead.

        @see wxAny::CheckType()
    */
    template <typename T>
    bool CheckType();

    /**
        Convert value into buffer of different type. Return false if
        not possible.
    */
    virtual bool ConvertValue(const wxAnyValueBuffer& src,
                              wxAnyValueType* dstType,
                              wxAnyValueBuffer& dst) const = 0;

    /**
        Implement this for buffer-to-buffer copy.

        @param src
            This is the source data buffer.

        @param dst
            This is the destination data buffer that is in either
            uninitialized or freed state.
    */
    virtual void CopyBuffer(const wxAnyValueBuffer& src,
                            wxAnyValueBuffer& dst) const = 0;

    /**
        This function is called every time the data in wxAny
        buffer needs to be freed.
    */
    virtual void DeleteValue(wxAnyValueBuffer& buf) const = 0;

    /**
        This function is used for internal type matching.
    */
    virtual bool IsSameType(const wxAnyValueType* otherType) const = 0;
};

/**
    This is type checking macro that is more compatible with older
    compilers, such as Visual C++ 6.0.
*/
#define wxANY_VALUE_TYPE_CHECK_TYPE(valueTypePtr, T)
Commit	Line	Data
39601a7f VZ	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: any.h
	3	// Purpose: interface of wxAny
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9
	10	/**
	11	@class wxAny
	12
	13	The wxAny class represents a container for any type. Its value
	14	can be changed at run time, possibly to a different type of value.
	15
57f21754 JS	16	wxAny is a backwards incompatible successor class for wxVariant,
	17	essentially doing the same thing in a more modern, template-based manner
	18	and with transparent support for any user data type.
39601a7f VZ	19
	20	Some pseudo-code'ish example of use with arbitrary user data:
	21
	22	@code
	23	void SomeFunction()
	24	{
	25	MyClass myObject;
	26	wxAny any = myObject;
	27
	28	// Do something
	29	// ...
	30
	31	// Let's do a sanity check to make sure that any still holds
	32	// data of correct type.
	33	if ( any.CheckType<MyClass>() )
	34	{
	35	// Thank goodness, still a correct type.
	36	MyClass myObject2 = any.As<MyClass>();
	37	}
	38	else
	39	{
	40	// Something has gone horribly wrong!
	41	wxFAIL();
	42	}
	43	}
	44	@endcode
	45
	46	When compared to wxVariant, there are various internal implementation
	47	differences as well. For instance, wxAny only allocates separate data
	48	object in heap for large (ie. size in bytes more than
	49	WX_ANY_VALUE_BUFFER_SIZE) or 'non-movable' data types. Pointers, integers,
	50	bools etc. are fitted in the wxAny's own buffer without need for any extra
	51	allocation. Use following code to declare your own data type as 'movable':
	52
	53	@code
	54	#include "wx/meta/movable.h"
	55	WX_DECLARE_TYPE_MOVABLE(MyClass)
	56	@endcode
	57
	58	However, you must be aware that 'movable' means such data that can be
	59	copied with memcpy() without corrupting program integrity. For instance,
	60	movable objects usually cannot contain pointers or references to other
	61	data. wxRect, wxPoint, and wxSize are good examples of movable classes.
	62
	63	Note that pointers to any and all classes are already automatically
	64	declared as movable data.
	65
	66	@library{wxbase}
	67	@category{data}
	68
eb23d11e	69	@see wxAnyValueType, wxVariant, @ref overview_cpp_rtti_disabled
39601a7f VZ	70	*/
	71	class wxAny
	72	{
	73	public:
	74	/**
	75	Default constructor. It seeds the object with a null value.
	76	*/
	77	wxAny();
	78
	79	/**
	80	Constructs wxAny from data.
	81	*/
	82	template<typename T>
	83	wxAny(const T& value);
	84
	85	/**
	86	Constructs wxAny from another wxAny.
	87	*/
	88	wxAny(const wxAny& any);
	89
	90	/**
	91	Destructor.
	92	*/
	93	~wxAny();
	94
	95	/**
	96	This template function converts wxAny into given type. No dynamic
	97	conversion is performed, so if the type is incorrect an assertion
	98	failure will occur in debug builds, and a bogus value is returned
	99	in release ones.
	100
	101	@remarks This template function may not work properly with Visual C++
	102	6. For full compiler compatibility, please use
	103	wxANY_AS(any, T) macro instead.
	104	*/
	105	template<typename T>
	106	T As() const;
	107
	108	/**
	109	Use this template function for checking if this wxAny holds
	110	a specific C++ data type.
	111
	112	@remarks This template function may not work properly with Visual C++
	113	6. For full compiler compatibility, please use
	114	wxANY_CHECK_TYPE(any, T) macro instead.
	115
	116	@see wxAnyValueType::CheckType()
	117	*/
	118	template<typename T>
	119	bool CheckType();
	120
	121	/**
	122	Template function that retrieves and converts the value of this
	123	wxAny to the type that T* value is.
	124
57f21754	125	@return Returns @true if conversion was successful.
39601a7f VZ	126	*/
	127	template<typename T>
	128	bool GetAs(T* value) const;
	129
	130	/**
	131	Returns the value type as wxAnyValueType instance.
	132
	133	@remarks You cannot reliably test whether two wxAnys are of
	134	same value type by simply comparing return values
	135	of wxAny::GetType(). Instead use
	136	wxAnyValueType::CheckType<T>() template function.
	137	*/
	138	const wxAnyValueType* GetType() const;
	139
	140	/**
	141	Tests if wxAny is null (that is, whether there is data).
	142	*/
	143	bool IsNull() const;
	144
	145	/**
	146	Makes wxAny null (that is, clears it).
	147	*/
	148	void MakeNull();
	149
	150	//@{
	151	/**
	152	@name Assignment operators
	153	*/
	154	template<typename T>
	155	wxAny& operator=(const T &value);
	156	wxAny& operator=(const wxAny &any);
	157	//@}
	158
	159	//@{
	160	/**
	161	@name Equality operators
	162
	163	@remarks Generic template-based comparison operators have not been
	164	provided for various code consistency reasons, so for custom
	165	data types you have do something like this:
	166
	167	@code
	168	if ( any.CheckType<MyClass*>() &&
	169	any.As<MyClass*>() == myObjectPtr )
	170	{
	171	// Do something if any stores myObjectPtr
	172	}
	173	@endcode
	174	*/
	175	bool operator==(signed char value) const;
	176	bool operator==(signed short value) const;
	177	bool operator==(signed int value) const;
	178	bool operator==(signed long value) const;
	179	bool operator==(wxLongLong_t value) const;
	180	bool operator==(unsigned char value) const;
	181	bool operator==(unsigned short value) const;
	182	bool operator==(unsigned int value) const;
	183	bool operator==(unsigned long value) const;
	184	bool operator==(wxULongLong_t value) const;
	185	bool operator==(float value) const;
	186	bool operator==(double value) const;
	187	bool operator==(bool value) const;
	188	bool operator==(const char* value) const;
	189	bool operator==(const wchar_t* value) const;
190	bool operator==(const wxString& value) const;
191	//@}
192
193	//@{
194	/**
195	@name Inequality operators
196	*/
197	bool operator!=(signed char value) const;
198	bool operator!=(signed short value) const;
199	bool operator!=(signed int value) const;
200	bool operator!=(signed long value) const;
201	bool operator!=(wxLongLong_t value) const;
202	bool operator!=(unsigned char value) const;
203	bool operator!=(unsigned short value) const;
204	bool operator!=(unsigned int value) const;
205	bool operator!=(unsigned long value) const;
206	bool operator!=(wxULongLong_t value) const;
207	bool operator!=(float value) const;
208	bool operator!=(double value) const;
209	bool operator!=(bool value) const;
210	bool operator!=(const char* value) const;
211	bool operator!=(const wchar_t* value) const;
212	bool operator!=(const wxString& value) const;
213	//@}
214	};
215
216	/**
217	This is value getter macro that is more compatible with older
218	compilers, such as Visual C++ 6.0.
219	*/
220	#define wxANY_AS(any, T)
221
222
223	/**
224	This is type checking macro that is more compatible with older
225	compilers, such as Visual C++ 6.0.
226	*/
227	#define wxANY_CHECK_TYPE(any, T)
228
229
230	/**
231	Size of the wxAny value buffer.
232	*/
233	enum
234	{
235	WX_ANY_VALUE_BUFFER_SIZE = 16
236	};
237
238	/**
239	Type for buffer within wxAny for holding data.
240	*/
241	union wxAnyValueBuffer
242	{
243	void* m_ptr;
244	wxByte m_buffer[WX_ANY_VALUE_BUFFER_SIZE];
245	};
246
247
248	/**
249	@class wxAnyValueType
250
251	wxAnyValueType is base class for value type functionality for C++ data
252	types used with wxAny. Usually the default template will create a
253	satisfactory wxAnyValueType implementation for a data type, but
254	sometimes you may need to add some customization. To do this you will need
255	to add specialized template of wxAnyValueTypeImpl<>. Often your only
256	need may be to add dynamic type conversion which would be done like
257	this:
258
259	@code
260	template<>
261	class wxAnyValueTypeImpl<MyClass> :
262	public wxAnyValueTypeImplBase<MyClass>
263	{
264	WX_DECLARE_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
265	public:
266	wxAnyValueTypeImpl() :
267	wxAnyValueTypeImplBase<MyClass>() { }
268	virtual ~wxAnyValueTypeImpl() { }
269
270	virtual bool ConvertValue(const wxAnyValueBuffer& src,
271	wxAnyValueType* dstType,
272	wxAnyValueBuffer& dst) const
273	{
274	// GetValue() is a static member function implemented
275	// in wxAnyValueTypeImplBase<>.
276	MyClass value = GetValue(src);
277
278	// TODO: Convert value from src buffer to destination
279	// type and buffer. If cannot be done, return
280	// false. This is a simple sample.
281	if ( dstType->CheckType<wxString>() )
282	{
283	wxString s = value.ToString();
284	wxAnyValueTypeImpl<wxString>::SetValue(s, dst);
285	}
286	else
287	{
288	return false;
289	}
290	}
291	};
292
293	//
294	// Following must be placed somewhere in your source code
295	WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
296	@endcode
297
298	wxAnyValueTypeImplBase<> template, from which we inherit in the above
299	example, contains the bulk of the default wxAnyValueTypeImpl<> template
300	implementation, and as such allows you to easily add some minor
301	customization.
302
303	If you need a have complete control over the type interpretation, you
304	will need to derive a class directly from wxAnyValueType, like this:
305
306	@code
307	template <>
308	class wxAnyValueTypeImpl<MyClass> : public wxAnyValueType
309	{
310	WX_DECLARE_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
311	public:
312	virtual void DeleteValue(wxAnyValueBuffer& buf) const
313	{
314	// TODO: Free the data in buffer
315	// It is important to clear the buffer like this
316	// at the end of DeleteValue().
317	buf.m_ptr = NULL;
318	}
319
320	virtual void CopyBuffer(const wxAnyValueBuffer& src,
321	wxAnyValueBuffer& dst) const
322	{
323	// TODO: Copy value from one buffer to another.
24985a9b JS	324	// dst is already uninitialized and does not
24985a9b JS	325	// need to be freed.
39601a7f VZ	326	}
	327
	328	virtual bool ConvertValue(const wxAnyValueBuffer& src,
	329	wxAnyValueType* dstType,
	330	wxAnyValueBuffer& dst) const
	331	{
	332	// TODO: Convert value from src buffer to destination
	333	// type and buffer.
	334	}
	335
	336	//
	337	// Following static functions must be implemented
	338	//
	339
	340	static void SetValue(const T& value,
	341	wxAnyValueBuffer& buf)
	342	{
	343	// TODO: Store value into buf.
	344	}
	345
	346	static const T& GetValue(const wxAnyValueBuffer& buf)
	347	{
	348	// TODO: Return reference to value stored in buffer.
	349	}
	350	};
	351
	352	//
	353	// Following must be placed somewhere in your source code
	354	WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
	355
	356	@endcode
	357
	358	@library{wxbase}
	359	@category{data}
	360
	361	@see wxAny
	362	*/
	363	class wxAnyValueType
	364	{
	365	public:
	366	/**
	367	Default constructor.
	368	*/
	369	wxAnyValueType();
	370
	371	/**
	372	Destructor.
	373	*/
	374	virtual ~wxAnyValueType();
	375
	376	/**
	377	Use this template function for checking if wxAnyValueType represents
	378	a specific C++ data type.
	379
	380	@remarks This template function does not work on some older compilers
	381	(such as Visual C++ 6.0). For full compiler ccompatibility
	382	please use wxANY_VALUE_TYPE_CHECK_TYPE(valueTypePtr, T) macro
	383	instead.
	384
	385	@see wxAny::CheckType()
	386	*/
	387	template <typename T>
	388	bool CheckType();
	389
390	/**
391	Convert value into buffer of different type. Return false if
392	not possible.
393	*/
394	virtual bool ConvertValue(const wxAnyValueBuffer& src,
395	wxAnyValueType* dstType,
396	wxAnyValueBuffer& dst) const = 0;
397
398	/**
24985a9b JS	399	Implement this for buffer-to-buffer copy.
	400
	401	@param src
	402	This is the source data buffer.
	403
	404	@param dst
	405	This is the destination data buffer that is in either
	406	uninitialized or freed state.
39601a7f VZ	407	*/
	408	virtual void CopyBuffer(const wxAnyValueBuffer& src,
	409	wxAnyValueBuffer& dst) const = 0;
	410
	411	/**
	412	This function is called every time the data in wxAny
	413	buffer needs to be freed.
	414	*/
	415	virtual void DeleteValue(wxAnyValueBuffer& buf) const = 0;
	416
39601a7f VZ	417	/**
	418	This function is used for internal type matching.
	419	*/
	420	virtual bool IsSameType(const wxAnyValueType* otherType) const = 0;
	421	};
	422
	423	/**
	424	This is type checking macro that is more compatible with older
	425	compilers, such as Visual C++ 6.0.
	426	*/
	427	#define wxANY_VALUE_TYPE_CHECK_TYPE(valueTypePtr, T)