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
char so that your code uses the correct string type required by FireMonkey, the VCL, or 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
- The Windows API are typically narrow, requiring
- FireMonkey and the VCL (since 2009) use wide string data (Unicode), requiring
In interactions with FireMonkey and the VCL, you need to use the wide RTL functions, or do proper conversions before passing data to FireMonkey or the VCL. (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, Windows API, FireMonkey, and the VCL), you should use _TCHAR (instead of hard coding
wchar_t data types). Then you can adjust the _TCHAR mapping option to either
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.
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
wchar_t, as shown in the following table:
Values of the '_TCHAR maps to' Option:
Note: This option does not float to wide definitions of standard library and API functions.
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 FireMonkey and VCL
FireMonkey and the VCL are implemented in Unicode and always expect Unicode. By default, _TCHAR maps to
For example, the following code does not compile unless the '_TCHAR maps to' option is set to to
TResourceStream* res = new TResourceStream(HInstance, ResourceId, RT_RCDATA);
If the '_TCHAR maps to' option is set to char,
RT_RCDATA maps to a
FireMonkey and the VCL expect
wchar_t*, so the char setting is a problem if you want to work with FireMonkey or the VCL.
Code Changes Required for Using '_TCHAR maps to' with
When _TCHAR maps to
wchar_t (the default setting), your project must have an entry point called either
_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 use
mainas an entry point, the linker cannot link the executable. For new projects that use FireMonkey or the VCL, the wizards automatically insert a
_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
_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
translates to the L-prefixed form:
Otherwise, this macro translates without the