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 licence
   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 (but convertible) successor class for
  17     wxVariant, essentially doing the same thing in a more modern, template-
  18     based manner 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 objects (i.e. ones with size more than
  49     WX_ANY_VALUE_BUFFER_SIZE, which at the time of writing is 16 bytes).
  50
  51     @library{wxbase}
  52     @category{data}
  53
  54     @see wxAnyValueType, wxVariant, @ref overview_cpp_rtti_disabled
  55 */
  56 class wxAny
  57 {
  58 public:
  59     /**
  60         Default constructor. It seeds the object with a null value.
  61     */
  62     wxAny();
  63
  64     /**
  65         Constructs wxAny from data.
  66     */
  67     template<typename T>
  68     wxAny(const T& value);
  69
  70     /**
  71         Constructs wxAny from another wxAny.
  72     */
  73     wxAny(const wxAny& any);
  74
  75     /**
  76         Constructs wxAny, converting value from wxVariant.
  77
  78         @remarks Because of this conversion, it is not usually possible to
  79                  have wxAny that actually holds a wxVariant. If wxVariant
  80                  cannot be converted to a specific data type, wxAny will then
  81                  hold and manage reference to wxVariantData* similar to how
  82                  wxVariant does.
  83     */
  84     wxAny(const wxVariant& variant);
  85
  86     /**
  87         Destructor.
  88     */
  89     ~wxAny();
  90
  91     /**
  92         This template function converts wxAny into given type. In most cases
  93         no type conversion is performed, so if the type is incorrect an
  94         assertion failure will occur.
  95
  96         @remarks For conveniency, conversion is done when T is wxString. This
  97                  is useful when a string literal (which are treated as
  98                  const char* and const wchar_t*) has been assigned to wxAny.
  99
 100                  This template function may not work properly with Visual C++
 101                  6. For full compiler compatibility, please use
 102                  wxANY_AS(any, T) macro instead.
 103     */
 104     template<typename T>
 105     T As() const;
 106
 107     /**
 108         Use this template function for checking if this wxAny holds
 109         a specific C++ data type.
 110
 111         @remarks This template function may not work properly with Visual C++
 112                 6. For full compiler compatibility, please use
 113                 wxANY_CHECK_TYPE(any, T) macro instead.
 114
 115         @see wxAnyValueType::CheckType()
 116     */
 117     template<typename T>
 118     bool CheckType() const;
 119
 120     /**
 121         Template function that retrieves and converts the value of this
 122         wxAny to the type that T* value is.
 123
 124         @return Returns @true if conversion was successful.
 125     */
 126     template<typename T>
 127     bool GetAs(T* value) const;
 128
 129     /**
 130         Specialization of GetAs() that allows conversion of wxAny into
 131         wxVariant.
 132
 133         @return Returns @true if conversion was successful. Conversion usually
 134                 only fails if variant used custom wxVariantData that did not
 135                 implement the wxAny to wxVariant conversion functions.
 136     */
 137     bool GetAs(wxVariant* value) const;
 138
 139     /**
 140         Returns the value type as wxAnyValueType instance.
 141
 142         @remarks You cannot reliably test whether two wxAnys are of
 143                  same value type by simply comparing return values
 144                  of wxAny::GetType(). Instead, use wxAny::HasSameType().
 145
 146         @see HasSameType()
 147     */
 148     const wxAnyValueType* GetType() const;
 149
 150     /**
 151         Returns @true if this and another wxAny have the same
 152         value type.
 153     */
 154     bool HasSameType(const wxAny& other) const;
 155
 156     /**
 157         Tests if wxAny is null (that is, whether there is no data).
 158     */
 159     bool IsNull() const;
 160
 161     /**
 162         Makes wxAny null (that is, clears it).
 163     */
 164     void MakeNull();
 165
 166     //@{
 167     /**
 168         @name Assignment operators
 169     */
 170     template<typename T>
 171     wxAny& operator=(const T &value);
 172     wxAny& operator=(const wxAny &any);
 173     wxAny& operator=(const wxVariant &variant);
 174     //@}
 175
 176     //@{
 177     /**
 178         @name Equality operators
 179
 180         @remarks Generic template-based comparison operators have not been
 181                 provided for various code consistency reasons, so for custom
 182                 data types you have do something like this:
 183
 184                 @code
 185                 if ( any.CheckType<MyClass*>() &&
 186                      any.As<MyClass*>() == myObjectPtr )
 187                 {
 188                     // Do something if any stores myObjectPtr
 189                 }
 190                 @endcode
 191     */
 192     bool operator==(signed char value) const;
 193     bool operator==(signed short value) const;
 194     bool operator==(signed int value) const;
 195     bool operator==(signed long value) const;
 196     bool operator==(wxLongLong_t value) const;
 197     bool operator==(unsigned char value) const;
 198     bool operator==(unsigned short value) const;
 199     bool operator==(unsigned int value) const;
 200     bool operator==(unsigned long value) const;
 201     bool operator==(wxULongLong_t value) const;
 202     bool operator==(float value) const;
 203     bool operator==(double value) const;
 204     bool operator==(bool value) const;
 205     bool operator==(const char* value) const;
 206     bool operator==(const wchar_t* value) const;
 207     bool operator==(const wxString& value) const;
 208     //@}
 209
 210     //@{
 211     /**
 212         @name Inequality operators
 213     */
 214     bool operator!=(signed char value) const;
 215     bool operator!=(signed short value) const;
 216     bool operator!=(signed int value) const;
 217     bool operator!=(signed long value) const;
 218     bool operator!=(wxLongLong_t value) const;
 219     bool operator!=(unsigned char value) const;
 220     bool operator!=(unsigned short value) const;
 221     bool operator!=(unsigned int value) const;
 222     bool operator!=(unsigned long value) const;
 223     bool operator!=(wxULongLong_t value) const;
 224     bool operator!=(float value) const;
 225     bool operator!=(double value) const;
 226     bool operator!=(bool value) const;
 227     bool operator!=(const char* value) const;
 228     bool operator!=(const wchar_t* value) const;
 229     bool operator!=(const wxString& value) const;
 230     //@}
 231 };
 232
 233 /**
 234     This is value getter macro that is more compatible with older
 235     compilers, such as Visual C++ 6.0.
 236 */
 237 #define wxANY_AS(any, T)
 238
 239
 240 /**
 241     This is type checking macro that is more compatible with older
 242     compilers, such as Visual C++ 6.0.
 243 */
 244 #define wxANY_CHECK_TYPE(any, T)
 245
 246
 247 /**
 248     Size of the wxAny value buffer.
 249 */
 250 enum
 251 {
 252     WX_ANY_VALUE_BUFFER_SIZE = 16
 253 };
 254
 255 /**
 256     Type for buffer within wxAny for holding data.
 257 */
 258 union wxAnyValueBuffer
 259 {
 260     void*   m_ptr;
 261     wxByte  m_buffer[WX_ANY_VALUE_BUFFER_SIZE];
 262 };
 263
 264
 265 /**
 266     @class wxAnyValueType
 267
 268     wxAnyValueType is base class for value type functionality for C++ data
 269     types used with wxAny. Usually the default template will create a
 270     satisfactory wxAnyValueType implementation for a data type, but
 271     sometimes you may need to add some customization. To do this you will need
 272     to add specialized template of wxAnyValueTypeImpl<>. Often your only
 273     need may be to add dynamic type conversion which would be done like
 274     this:
 275
 276     @code
 277         template<>
 278         class wxAnyValueTypeImpl<MyClass> :
 279             public wxAnyValueTypeImplBase<MyClass>
 280         {
 281             WX_DECLARE_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
 282         public:
 283             wxAnyValueTypeImpl() :
 284                 wxAnyValueTypeImplBase<MyClass>() { }
 285             virtual ~wxAnyValueTypeImpl() { }
 286
 287             virtual bool ConvertValue(const wxAnyValueBuffer& src,
 288                                       wxAnyValueType* dstType,
 289                                       wxAnyValueBuffer& dst) const
 290             {
 291                 // GetValue() is a static member function implemented
 292                 // in wxAnyValueTypeImplBase<>.
 293                 MyClass value = GetValue(src);
 294
 295                 // TODO: Convert value from src buffer to destination
 296                 //       type and buffer. If cannot be done, return
 297                 //       false. This is a simple sample.
 298                 if ( dstType->CheckType<wxString>() )
 299                 {
 300                     wxString s = value.ToString();
 301                     wxAnyValueTypeImpl<wxString>::SetValue(s, dst);
 302                 }
 303                 else
 304                 {
 305                     return false;
 306                 }
 307             }
 308         };
 309
 310         //
 311         // Following must be placed somewhere in your source code
 312         WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
 313     @endcode
 314
 315     wxAnyValueTypeImplBase<> template, from which we inherit in the above
 316     example, contains the bulk of the default wxAnyValueTypeImpl<> template
 317     implementation, and as such allows you to easily add some minor
 318     customization.
 319
 320     If you need a have complete control over the type interpretation, you
 321     will need to derive a class directly from wxAnyValueType, like this:
 322
 323     @code
 324         template <>
 325         class wxAnyValueTypeImpl<MyClass> : public wxAnyValueType
 326         {
 327             WX_DECLARE_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
 328         public:
 329             virtual void DeleteValue(wxAnyValueBuffer& buf) const
 330             {
 331                 // TODO: Free the data in buffer
 332                 // It is important to clear the buffer like this
 333                 // at the end of DeleteValue().
 334                 buf.m_ptr = NULL;
 335             }
 336
 337             virtual void CopyBuffer(const wxAnyValueBuffer& src,
 338                                     wxAnyValueBuffer& dst) const
 339             {
 340                 // TODO: Copy value from one buffer to another.
 341                 //       dst is already uninitialized and does not
 342                 //       need to be freed.
 343             }
 344
 345             virtual bool ConvertValue(const wxAnyValueBuffer& src,
 346                                       wxAnyValueType* dstType,
 347                                       wxAnyValueBuffer& dst) const
 348             {
 349                 // TODO: Convert value from src buffer to destination
 350                 //       type and buffer.
 351             }
 352
 353             //
 354             // Following static functions must be implemented
 355             //
 356
 357             static void SetValue(const T& value,
 358                                  wxAnyValueBuffer& buf)
 359             {
 360                 // TODO: Store value into buf.
 361             }
 362
 363             static const T& GetValue(const wxAnyValueBuffer& buf)
 364             {
 365                 // TODO: Return reference to value stored in buffer.
 366             }
 367         };
 368
 369         //
 370         // Following must be placed somewhere in your source code
 371         WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
 372
 373     @endcode
 374
 375     @library{wxbase}
 376     @category{data}
 377
 378     @see wxAny
 379 */
 380 class wxAnyValueType
 381 {
 382 public:
 383     /**
 384         Default constructor.
 385     */
 386     wxAnyValueType();
 387
 388     /**
 389         Destructor.
 390     */
 391     virtual ~wxAnyValueType();
 392
 393     /**
 394         Use this template function for checking if wxAnyValueType represents
 395         a specific C++ data type.
 396
 397         @remarks This template function does not work on some older compilers
 398                 (such as Visual C++ 6.0). For full compiler compatibility
 399                 please use wxANY_VALUE_TYPE_CHECK_TYPE(valueTypePtr, T) macro
 400                 instead.
 401
 402         @see wxAny::CheckType()
 403     */
 404     template <typename T>
 405     bool CheckType() const;
 406
 407     /**
 408         Convert value into buffer of different type. Return false if
 409         not possible.
 410     */
 411     virtual bool ConvertValue(const wxAnyValueBuffer& src,
 412                               wxAnyValueType* dstType,
 413                               wxAnyValueBuffer& dst) const = 0;
 414
 415     /**
 416         Implement this for buffer-to-buffer copy.
 417
 418         @param src
 419             This is the source data buffer.
 420
 421         @param dst
 422             This is the destination data buffer that is in either
 423             uninitialized or freed state.
 424     */
 425     virtual void CopyBuffer(const wxAnyValueBuffer& src,
 426                             wxAnyValueBuffer& dst) const = 0;
 427
 428     /**
 429         This function is called every time the data in wxAny
 430         buffer needs to be freed.
 431     */
 432     virtual void DeleteValue(wxAnyValueBuffer& buf) const = 0;
 433
 434     /**
 435         This function is used for internal type matching.
 436     */
 437     virtual bool IsSameType(const wxAnyValueType* otherType) const = 0;
 438 };
 439
 440 /**
 441     This is type checking macro that is more compatible with older
 442     compilers, such as Visual C++ 6.0.
 443 */
 444 #define wxANY_VALUE_TYPE_CHECK_TYPE(valueTypePtr, T)