_TCHAR Mapping

From RAD Studio
Jump to: navigation, search

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 char and wchar_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.

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:

Substitutes char for _TCHAR.

Note: This option does not float to wide definitions of standard library and API functions.

  • 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 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 use main as an entry point, the linker cannot link the executable. For new projects that use RAD Studio frameworks and libraries, 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