interface/wx/any.h

   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
  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.
  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
  69     @see wxAnyValueType, wxVariant, @ref overview_cpp_rtti_disabled
  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
 125         @return Returns @true if conversion was successful.
 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.
 324                 //       dst is already uninitialized and does not
 325                 //       need to be freed.
 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     /**
 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.
 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
 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)