interface/wx/chartype.h

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