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 /** @ingroup group_funcmacro_misc */
  71 //@{
  72
  73 /**
  74     This macro can be used around a function declaration to generate warnings
  75     indicating that this function is deprecated (i.e. obsolete and planned to
  76     be removed in the future) when it is used. Only Visual C++ 7 and higher and
  77     g++ compilers currently support this functionality.
  78
  79     Example of use:
  80
  81     @code
  82     // old function, use wxString version instead
  83     wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
  84
  85     // ...
  86     wxString wxGetSomething();
  87     @endcode
  88
  89     @header{wx/defs.h}
  90 */
  91 #define wxDEPRECATED(function)
  92
  93 /**
  94     This is a special version of wxDEPRECATED() macro which only does something
  95     when the deprecated function is used from the code outside wxWidgets itself
  96     but doesn't generate warnings when it is used from wxWidgets.
  97
  98     It is used with the virtual functions which are called by the library
  99     itself -- even if such function is deprecated the library still has to call
 100     it to ensure that the existing code overriding it continues to work, but
 101     the use of this macro ensures that a deprecation warning will be generated
 102     if this function is used from the user code or, in case of Visual C++, even
 103     when it is simply overridden.
 104
 105     @header{wx/defs.h}
 106 */
 107 #define wxDEPRECATED_BUT_USED_INTERNALLY(function)
 108
 109 /**
 110     This macro is similar to wxDEPRECATED() but can be used to not only declare
 111     the function @a function as deprecated but to also provide its (inline)
 112     implementation @a body.
 113
 114     It can be used as following:
 115
 116     @code
 117     class wxFoo
 118     {
 119     public:
 120         // OldMethod() is deprecated, use NewMethod() instead
 121         void NewMethod();
 122         wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
 123     };
 124     @endcode
 125
 126     @header{wx/defs.h}
 127 */
 128 #define wxDEPRECATED_INLINE(func, body)
 129
 130 /**
 131     @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if
 132     the compiler supports it or nothing otherwise. Thus, it can be used even in
 133     the code which might have to be compiled with an old compiler without
 134     support for this language feature but still take advantage of it when it is
 135     available.
 136
 137     @header{wx/defs.h}
 138 */
 139 #define wxEXPLICIT
 140
 141 /**
 142     GNU C++ compiler gives a warning for any class whose destructor is private
 143     unless it has a friend. This warning may sometimes be useful but it doesn't
 144     make sense for reference counted class which always delete themselves
 145     (hence destructor should be private) but don't necessarily have any
 146     friends, so this macro is provided to disable the warning in such case. The
 147     @a name parameter should be the name of the class but is only used to
 148     construct a unique friend class name internally.
 149
 150     Example of using the macro:
 151
 152     @code
 153     class RefCounted
 154     {
 155     public:
 156         RefCounted() { m_nRef = 1; }
 157         void IncRef() { m_nRef++ ; }
 158         void DecRef() { if ( !--m_nRef ) delete this; }
 159
 160     private:
 161         ~RefCounted() { }
 162
 163         wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
 164     };
 165     @endcode
 166
 167     Notice that there should be no semicolon after this macro.
 168
 169     @header{wx/defs.h}
 170 */
 171 #define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)
 172
 173 /**
 174     This macro is the same as the standard C99 @c va_copy for the compilers
 175     which support it or its replacement for those that don't. It must be used
 176     to preserve the value of a @c va_list object if you need to use it after
 177     passing it to another function because it can be modified by the latter.
 178
 179     As with @c va_start, each call to @c wxVaCopy must have a matching
 180     @c va_end.
 181
 182     @header{wx/defs.h}
 183 */
 184 void wxVaCopy(va_list argptrDst, va_list argptrSrc);
 185
 186 //@}
 187