interface/defs.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        defs.h
   3 // Purpose:     interface of global functions
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /** @ingroup group_funcmacro_byteorder */
  10 //@{
  11
  12 /**
  13     This macro will swap the bytes of the @a value variable from little endian
  14     to big endian or vice versa unconditionally, i.e. independently of the
  15     current platform.
  16
  17     @header{wx/defs.h}
  18 */
  19 #define wxINT32_SWAP_ALWAYS( wxInt32 value )
  20 #define wxUINT32_SWAP_ALWAYS( wxUint32 value )
  21 #define wxINT16_SWAP_ALWAYS( wxInt16 value )
  22 #define wxUINT16_SWAP_ALWAYS( wxUint16 value )
  23
  24 //@}
  25
  26 /** @ingroup group_funcmacro_byteorder */
  27 //@{
  28
  29 /**
  30     This macro will swap the bytes of the @a value variable from little endian
  31     to big endian or vice versa if the program is compiled on a big-endian
  32     architecture (such as Sun work stations). If the program has been compiled
  33     on a little-endian architecture, the value will be unchanged.
  34
  35     Use these macros to read data from and write data to a file that stores
  36     data in little-endian (for example Intel i386) format.
  37
  38     @header{wx/defs.h}
  39 */
  40 #define wxINT32_SWAP_ON_BE( wxInt32 value )
  41 #define wxUINT32_SWAP_ON_BE( wxUint32 value )
  42 #define wxINT16_SWAP_ON_BE( wxInt16 value )
  43 #define wxUINT16_SWAP_ON_BE( wxUint16 value )
  44
  45 //@}
  46
  47 /** @ingroup group_funcmacro_byteorder */
  48 //@{
  49
  50 /**
  51     This macro will swap the bytes of the @a value variable from little endian
  52     to big endian or vice versa if the program is compiled on a little-endian
  53     architecture (such as Intel PCs). If the program has been compiled on a
  54     big-endian architecture, the value will be unchanged.
  55
  56     Use these macros to read data from and write data to a file that stores
  57     data in big-endian format.
  58
  59     @header{wx/defs.h}
  60 */
  61 #define wxINT32_SWAP_ON_LE( wxInt32 value )
  62 #define wxUINT32_SWAP_ON_LE( wxUint32 value )
  63 #define wxINT16_SWAP_ON_LE( wxInt16 value )
  64 #define wxUINT16_SWAP_ON_LE( wxUint16 value )
  65
  66 //@}
  67
  68
  69
  70
  71 /**
  72     This macro is similar to wxDEPRECATED() but can be used
  73     to not only declare the function @a func as deprecated but to also provide
  74     its (inline) implementation @e body.
  75     It can be used as following:
  76
  77     @code
  78     class wxFoo
  79         {
  80         public:
  81             // OldMethod() is deprecated, use NewMethod() instead
  82             void NewMethod();
  83             wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
  84         };
  85     @endcode
  86 */
  87 #define wxDEPRECATED_INLINE(func, body)     /* implementation is private */
  88
  89 /**
  90     @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if
  91     the compiler supports it or nothing otherwise. Thus, it can be used even in the
  92     code which might have to be compiled with an old compiler without support for
  93     this language feature but still take advantage of it when it is available.
  94 */
  95
  96
  97 /**
  98     GNU C++ compiler gives a warning for any class whose destructor is private
  99     unless it has a friend. This warning may sometimes be useful but it doesn't
 100     make sense for reference counted class which always delete themselves (hence
 101     destructor should be private) but don't necessarily have any friends, so this
 102     macro is provided to disable the warning in such case. The @a name parameter
 103     should be the name of the class but is only used to construct a unique friend
 104     class name internally. Example of using the macro:
 105
 106     @code
 107     class RefCounted
 108         {
 109         public:
 110             RefCounted() { m_nRef = 1; }
 111             void IncRef() { m_nRef++ ; }
 112             void DecRef() { if ( !--m_nRef ) delete this; }
 113
 114         private:
 115             ~RefCounted() { }
 116
 117             wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
 118         };
 119     @endcode
 120
 121     Notice that there should be no semicolon after this macro.
 122 */
 123 #define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)     /* implementation is private */
 124
 125 /**
 126     This macro can be used around a function declaration to generate warnings
 127     indicating that this function is deprecated (i.e. obsolete and planned to be
 128     removed in the future) when it is used. Only Visual C++ 7 and higher and g++
 129     compilers currently support this functionality.
 130     Example of use:
 131
 132     @code
 133     // old function, use wxString version instead
 134         wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
 135
 136         // ...
 137         wxString wxGetSomething();
 138     @endcode
 139 */
 140
 141
 142 /**
 143     This macro is the same as the standard C99 @c va_copy for the compilers
 144     which support it or its replacement for those that don't. It must be used to
 145     preserve the value of a @c va_list object if you need to use it after
 146     passing it to another function because it can be modified by the latter.
 147     As with @c va_start, each call to @c wxVaCopy must have a matching
 148     @c va_end.
 149 */
 150 void wxVaCopy(va_list argptrDst, va_list argptrSrc);
 151
 152 /**
 153     This is a special version of wxDEPRECATED() macro which
 154     only does something when the deprecated function is used from the code outside
 155     wxWidgets itself but doesn't generate warnings when it is used from wxWidgets.
 156     It is used with the virtual functions which are called by the library itself --
 157     even if such function is deprecated the library still has to call it to ensure
 158     that the existing code overriding it continues to work, but the use of this
 159     macro ensures that a deprecation warning will be generated if this function is
 160     used from the user code or, in case of Visual C++, even when it is simply
 161     overridden.
 162 */
 163
 164