interface/wx/chartype.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        chartype.h
   3 // Purpose:     interface of global functions
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /** @addtogroup group_funcmacro_string */
  10 //@{
  11
  12 /**
  13     This macro can be used with character and string literals (in other words,
  14     @c 'x' or @c "foo") to automatically convert them to wide strings in Unicode
  15     builds of wxWidgets. This macro simply returns the value passed to it
  16     without changes in ASCII build. In fact, its definition is:
  17
  18     @code
  19     #ifdef UNICODE
  20     #   define wxT(x)  L##x
  21     #else // !Unicode
  22     #   define wxT(x)  x
  23     #endif
  24     @endcode
  25
  26     Note that since wxWidgets 2.9.0 you shouldn't use wxT() anymore in your
  27     program sources (it was previously required if you wanted to support Unicode).
  28
  29     @see @ref overview_unicode, wxS()
  30
  31     @header{wx/chartype.h}
  32 */
  33 #define wxT(string)
  34
  35 /**
  36     Compatibility macro which expands to wxT() in wxWidgets 2 only.
  37
  38     This macro can be used in the code which needs to compile with both
  39     wxWidgets 2 and 3 versions in places where v2 API requires a Unicode string
  40     (in Unicode build) and v3 API only accepts a standard standard narrow
  41     string as in e.g. wxCmdLineEntryDesc structure objects initializers.
  42
  43     Example of use:
  44     @code
  45     const wxCmdLineEntryDesc cmdLineDesc[] =
  46     {
  47         { wxCMD_LINE_SWITCH, wxT_2("q"), wxT_2("quiet"),
  48           wxT_2("Don't output verbose messages") },
  49         wxCMD_LINE_DESC_END
  50     };
  51     @endcode
  52
  53     Without @c wxT_2 the code above wouldn't compile with wxWidgets 2, with @c
  54     wxT instead of it, it wouldn't compile with wxWidgets 3.
  55
  56     @see wxT()
  57
  58     @header{wx/chartype.h}
  59  */
  60
  61 /**
  62     wxS is macro which can be used with character and string literals (in other words,
  63     @c 'x' or @c "foo") to either convert them to wide characters or wide strings
  64     in @c wchar_t-based (UTF-16) builds or keep them unchanged in @c char-based
  65     (UTF-8) builds.
  66
  67     Basically this macro produces characters or strings of type wxStringCharType.
  68
  69     The use of this macro is optional as the translation will always be done at
  70     run-time even if there is a mismatch between the kind of the literal used
  71     and the string or character type used in the current build.
  72     However using it can be beneficial in <b>performance-sensitive code</b> to
  73     do the conversion at compile-time instead.
  74
  75     @see @ref overview_unicode, wxT()
  76
  77     @header{wx/chartype.h}
  78 */
  79 #define wxS(string)
  80
  81 /**
  82     This macro is exactly the same as wxT() and is defined in wxWidgets simply
  83     because it may be more intuitive for Windows programmers as the standard
  84     Win32 headers also define it (as well as yet another name for the same
  85     macro which is _TEXT()).
  86
  87     Don't confuse this macro with _()!
  88
  89     Note that since wxWidgets 2.9.0 the use of _T() is discouraged just like
  90     for wxT() and also that this macro may conflict with identifiers defined in
  91     standard headers of some compilers (such as Sun CC) so its use should
  92     really be avoided.
  93
  94     @header{wx/chartype.h}
  95 */
  96 #define _T(string)
  97
  98 /**
  99     wxChar is defined to be
 100     - @c char when <tt>wxUSE_UNICODE==0</tt>
 101     - @c wchar_t when <tt>wxUSE_UNICODE==1</tt> (the default).
 102 */
 103 typedef wxUSE_UNICODE_dependent wxChar;
 104
 105 /**
 106     wxSChar is defined to be
 107     - <tt>signed char</tt> when <tt>wxUSE_UNICODE==0</tt>
 108     - @c wchar_t when <tt>wxUSE_UNICODE==1</tt> (the default).
 109 */
 110 typedef wxUSE_UNICODE_dependent wxSChar;
 111
 112 /**
 113     wxUChar is defined to be
 114     - <tt>unsigned char</tt> when <tt>wxUSE_UNICODE==0</tt>
 115     - @c wchar_t when <tt>wxUSE_UNICODE==1</tt> (the default).
 116 */
 117 typedef wxUSE_UNICODE_dependent wxUChar;
 118
 119 /**
 120     wxStringCharType is defined to be:
 121     - @c char when <tt>wxUSE_UNICODE==0</tt>
 122     - @c char when <tt>wxUSE_UNICODE_WCHAR==0</tt> and <tt>wxUSE_UNICODE==1</tt>
 123     - @c wchar_t when <tt>wxUSE_UNICODE_WCHAR==1</tt> and <tt>wxUSE_UNICODE==1</tt>
 124
 125     The @c wxUSE_UNICODE_WCHAR symbol is defined to @c 1 when building on
 126     Windows while it's defined to @c 0 when building on Unix, Linux or OS X.
 127     (Note that @c wxUSE_UNICODE_UTF8 symbol is defined as the opposite of
 128     @c wxUSE_UNICODE_WCHAR.)
 129
 130     Note that wxStringCharType (as the name says) is the type used by wxString
 131     for internal storage of the characters.
 132 */
 133 typedef wxUSE_UNICODE_WCHAR_dependent wxStringCharType;
 134
 135 //@}