_TCHAR Mapping
Go Up to Unicode for C++ Index
_TCHAR mapping in C++Builder is intended to make it easier to write source code that can be used with either wide or narrow strings. You can map _TCHAR to either wchar_t or char so that your code uses the correct string type required by RAD Studio frameworks and libraries or the Windows API, and so that RTL functions float to the correct definition (wide or narrow, respectively). To set the _TCHAR maps to option, use the Project > Options > C++ (Shared Options) dialog box.
Your C++ application needs to deal with both wide and narrow strings:
- The C++ RTL contains routines designed for both
charandwchar_t. - The Windows API are typically narrow, requiring
char. - RAD Studio frameworks and libraries use wide string data (Unicode), requiring
wchar_t.
In interactions with RAD Studio frameworks and libraries, you need to use the wide RTL functions, or do proper conversions before passing data to RAD Studio frameworks and libraries. (See UTF-8 Conversion Routines.)
_TCHAR, which is declared conditionally in the tchar.h header file, is defined as a typedef (alias) that maps either to char or to wchar_t. When you want to write portable code (that can interact with the C++ RTL, the Windows API, and RAD Studio frameworks and libraries), you should use _TCHAR (instead of hard coding char or wchar_t data types). Then you can adjust the _TCHAR mapping option to either char or wchar_t (on the C++ (Shared Options) page). For example, the current _TCHAR Mapping setting controls whether your application uses either the ANSI versions or the wide versions of the RTL floating functions.
Contents
The '_TCHAR maps to' Option
The project option _TCHAR maps to controls the floating definition of _TCHAR in your code.
_TCHAR can map or float to either char or wchar_t, as shown in the following table:
Values of the '_TCHAR maps to' Option:
char |
Substitutes char for _TCHAR.
|
wchar_t |
|
Set the '_TCHAR maps to' option on the Directories and Conditionals page
Use the Project > Options > C++ (Shared Options) dialog box.
Use '_TCHAR maps to' wchar_t for RAD Studio Frameworks and Libraries
RAD Studio frameworks and libraries are implemented in Unicode and always expect Unicode. By default, _TCHAR maps to wchar_t.
For example, the following code does not compile unless the '_TCHAR maps to' option is set to to wchar_t:
TResourceStream* res = new
TResourceStream(HInstance, ResourceId, RT_RCDATA);
If the '_TCHAR maps to' option is set to char, RT_RCDATA maps to a char*.
RAD Studio frameworks and libraries expect wchar_t*, so the char setting is a problem if you want to work with RAD Studio frameworks and libraries.
Code Changes Required for Using '_TCHAR maps to' with wchar_t
When _TCHAR maps to wchar_t (the default setting), your project must have an entry point called either _tmain or _tWinMain. New projects created with C++Builder have these entry points by default, but for imported projects you might need to add these entry points by hand.
You must also include the tchar.h header file, which contains the floating definitions and the entry points that you need. For a list of the floating functions contained in tchar.h, see Floating Functions.
Note: If, instead of using
_tmain, you usemainas an entry point, the linker cannot link the executable. For new projects that use RAD Studio frameworks and libraries, the wizards automatically insert a_tmainentry point.
Use _TEXT Macro before Text Literals
To ensure that character and string literals float properly to ANSI or Unicode, use either the _TEXT macro or the _T macro. For example:
::MessageBox(0, _TEXT("The message"), _TEXT("The caption"), MB_OK);
With _UNICODE defined, the _TEXT (or _T) macro translates a literal string (character) to the L-prefixed form; otherwise, _TEXT translates the literal without the L prefix. For example, if you define _UNICODE, then
_TEXT("The message")
translates to the L-prefixed form:
L"The message"
Otherwise, this macro translates without the L prefix:
"The message"