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