interface/defs.h

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