Show: Delphi C++
Display Preferences

_TCHAR Mapping

From RAD Studio
Jump to: navigation, search

Go Up to Unicode for C++ Index

Contents

_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 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 char and wchar_t.
  • The Windows API are typically narrow, requiring char.
  • FireMonkey and the VCL (since 2009) use wide string data (Unicode), requiring wchar_t.

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 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.

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.
Note: This option does not float to wide definitions of standard library and API functions.
wchar_t
  • Substitutes wchar_t for _TCHAR.
  • Sets both the UNICODE and _UNICODE macro constants.
  • Floats to the 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 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*. 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 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 use main as an entry point, the linker cannot link the executable. For new projects that use FireMonkey or the VCL, the wizards automatically insert a _tmain entry 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"

See Also

Personal tools
In other languages