End-User-Defined Characters

End user–defined characters (EUDC) are customized characters that users install for viewing and printing documents.

This overview discusses the TrueType fonts that support end user–defined characters and describes the functions used to access and manage these characters in Win32®-based applications:

  • About End-User-Defined Characters
  • End-User-Defined Character Reference
Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


About End-User-Defined Characters

End–user–defined characters give users a way to form names and other words using characters that are not available in standard screen and printer fonts. These characters are available only in Asian-language versions of the system.

End user–defined characters are discussed in the following topics:

  • Character Sets and Fonts
  • Writing, Mapping, and Sorting Characters


Character Sets and Fonts

An end user–defined character is always associated with a double-byte character set (DBCS) and a TrueType font. Applications identify the specified character by using the character's assigned DBCS character value, and the system uses this value to locate shape and style information in a corresponding TrueType font. The shape and style information specifies how the character is drawn on the screen or printed page.

The DBCS character values that can be assigned depend on the specified character set. Each set has at least one range of reserved values for use as end user–defined characters. The system or applications explicitly define these ranges by setting appropriate values under the EUDCCodeRange key in the registry. In the registry, each character set is identified by a unique code-page number.

To create an end user–defined character, the user chooses a character value that is within the specified range and adds the shape and style information to the TrueType font in the entry that corresponds to that character value. Users create the shape and style information using an EUDC editor or by purchasing end user–defined font packages from font vendors. Any DBCS TrueType font can contain end user–defined characters. The font is called a separate EUDC font if it contains only end user–defined characters. The font is an integrated EUDC font if it contains standard characters as well as end user–defined characters.

Separate EUDC fonts are said to be either font-aware or font-unaware. A font-unaware font is designed to be a general purpose font that can be used with fonts of different font styles and of different implementations, such as GDI raster, WIFE, device, and TrueType fonts. A font-aware font is designed for use with a specific TrueType font.

The system default EUDC font is a font-unaware font that the system automatically associates with all DBCS fonts except those TrueType fonts that have explicitly associated font-aware fonts. Applications set the system default EUDC font by setting the value of the SystemDefaultEUDCFont name under the EUDC key in the registry. Similarly, applications can associate font-aware fonts with corresponding TrueType fonts by specifying a font name and associated font file under the EUDC key. Separate EUDC fonts cannot be associated with integrated EUDC fonts.

The system hides the system default EUDC and font-aware fonts. This means applications cannot enumerate or otherwise examine these fonts using GDI functions. Applications, such as EUDC editors and Control Panel, must use the registry entries to add, modify, and delete EUDC fonts.

End user–defined characters can also be used in Unicode-enabled applications. The reserved ranges for each character set are mapped to corresponding values in the Unicode private use area (values 0xE000 and higher).


Writing, Mapping, and Sorting Characters

Applications write end user–defined characters to the screen or printer the same way as writing other characters, by using output functions such as TextOut and ExtTextOut. These functions automatically retrieve character information from EUDC fonts if EUDC is enabled.

When writing end user–defined characters, the action of the text output function depends on the currently selected font. If the selected font is an integrated EUDC font, the function retrieves character information from that font. If the selected font is a DBCS TrueType font that has an associated font-aware EUDC font, the function retrieves information from the specified font-aware font. If the selected font does not have an associated font-aware font, the function retrieves information from the system default EUDC font. If the character is not in the system default EUDC font or there is no system default EUDC font, the function writes the default character defined by the selected font.

Applications can map end user–defined characters to and from Unicode by using the MultiByteToWideChar and WideCharToMultiByte functions. The MultiByteToWideChar function maps an end user–defined character to a character position in the Unicode private use area. The WideCharToMultiByte function maps a character in the private use area to its multibyte-character counterpart, if such a mapping exists. The code page specified in this function must contain an EUDC code range for the mapping to occur. If it does not, the function returns the default character for any characters in the Unicode private use area.

Both MultiByteToWideChar and WideCharToMultiByte preserve the round trip mapping of end user–defined characters from a code page to Unicode and back to the original code page. But these functions do not necessarily preserve mapping to other code pages. For example, if a character from code page 932 is mapped to Unicode, then mapped from Unicode to another code page with an EUDC range, it is likely that the original character will be mapped to a different end user–defined character in the destination code page. Similarly, mapping a Unicode string to a code page that has an EUDC range may have unintended results. If the Unicode string contains a private-use code point, that code point may be mapped to an end user–defined character whether or not the code point actually represents such a character.

Applications can compare strings that contain end user–defined characters by using the CompareStringA function. The function maps the characters to the Unicode end user zone before comparing character values. Applications can create a sort key for the string by using the LCMapStringA function and the LCMAP_SORTKEY value. This function maps characters to Unicode first. All characters in the private use area are sorted after all other Unicode characters. Within the area, characters are sorted in numerical order. If an application attempts to retrieve CTYPE information for an end user–defined character by using the GetStringTypeA function, the function returns NULL for each character.


End-User-Defined Character Reference

This following elements are used with end user–defined characters:

  • Registry entries


Registry Entries

The following topics describe the registry entries for use with end user–defined characters:

  • EUDCCodeRange
  • EUDC


EUDCCodeRange

The EUDCCodeRange registry entry contains entries that define end user–defined characters (EUDC) code ranges for the various code pages (character sets).

EUDCCodeRange
  CodePage=FromTo[,FromTo]

The EUDCCodeRange key has the following location:

HKEY_LOCAL_MACHINE\
System\CurrentControlSet\Control\NLS\CodePage\EUDCCodeRange

The key contains one or more values specifying the range of character values within a code page that are available for end user–defined characters. Under this key, a value name is one of these code-page values.

Value | Meaning
932 | Japanese
936 | Simplified Chinese
949 | Unified Hangeul Code (Hangeul TongHabHyung Code)
950 | Traditional Chinese
1361 | Johab

The value associated with each name is a string consisting of one or more pairs of 4-digit hexadecimal numbers, with the numbers in each pair separated by a hyphen (-) and each pair separated from any preceding pair by a comma (,). The following example illustrates this format:

HKEY_LOCAL_MACHINE\
    System\CurrentControlSet\Control\NLS\CodePage\EUDCCodeRange
923=F040-F9FC
950=FA40-FEFE, 8E40-A0FE, 8140-8DFE, C6A1-C8FE
CodePage
A user-defined value name that identifies the code page. It must be the letters, CP followed by 5 decimal digits specifying the code page.
FromTo
A string value consisting of a pair of 4-digit hexadecimal values separated by a hyphen (-). Multiple FromTo values may be specified, but each must be separated from the previous by a comma (,).

The following examples show possible EUDC ranges for code pages 923 and 950:

CP00923=F040-F9FC
CP00950=FA40-FEFE,8E40-A0FE,8140-8DFE,C6A1-C8FE


EUDC

The EUDC key contains one or more subkeys with each subkey containing values defining the fonts associated with end user–defined characters for a given code page.

EUDC
    SystemDefaultEUDCFont=TrueTypeEUDCFontFileName
    TrueTypeFontTypeface=TrueTypeEUDCFontFileName

The EUDC registry key has the following location in the registry:

HKEY_CURRENT_USER\EUDC

Under the EUDC, a subkey name can be one of these code-page numbers.

Value | Meaning
932 | Japanese
936 | Simplified Chinese
949 | Unified Hangeul Code (Hangeul TongHabHyung Code)
950 | Traditional Chinese
1361 | Johab

One value under the subkey has the name SystemDefaultEUDCFont. Other values, if any, have names that identify a font. The values associated with these names are strings specifying the name of TrueType font file containing the given font. The following example shows the EUDC key for code page 932:

HKEY_CURRENT_USER\EUDC\932
SystemDefaultEUDCFont=EUDC.TTF
MS Mincho=MINEUDC.TTF
MS Gothic=GTEUDC.TTF
SystemDefaultEUDCFont
Predefined value name used to set the system default font. The corresponding value must be a string that identifies a font-unaware EUDC font. There is no system default EUDC font unless this entry is explicitly specified.
TrueTypeFontTypeface
A user-defined value name that identifies the font name associated with a TrueType font. The corresponding value must be a string that identifies a font-aware EUDC font.
TrueTypeEUDCFontFileName
A string value consisting of the file name of a separate EUDC font file.

The following example sets the system default EUDC font to be Eudc.ttf and associates the font-aware fonts, Mineudc.ttf and Goteudc.ttf, with the font names MS Mincho and MS Gothic:

SystemDefaultEUDCFont=EUDC.TTF
MS Mincho=MINEUDC.TTF
MS Gothic=GOTEUDC.TTF


Input Method Editor

An input method editor (IME) is a program that allows computer users to enter complex characters and symbols, such as Japanese Kanji characters, by using a standard keyboard.

This overview describes the IME and explains how to use the input method manager functions to create and manage IME windows.

  • About Input Method Editor
  • Using Input Method Editor
  • Input Method Editor Reference


About Input Method Editor

The input method editor relieves users of the need to remember all possible character values. Instead, the IME monitors the user's keystrokes, anticipates the characters the user may want, and presents a list of candidate characters from which to choose.

By default, the IME provides an IME window through which users enter keystrokes and view and select candidates. Win32®-based applications can use the input method manager (IMM) functions and messages to create and manage their own IME windows, providing a custom interface while using the conversion capabilities of the IME.

IMM is only enabled on East Asian (Chinese, Japanese, Korean) localized Windows 95/98 and Windows NT4.0/3.51 platforms. On these systems, call GetSystemMetrics with SM_DBCSENABLED to determine if IMM is enabled. Windows 2000 provides full-featured IME support in all localized language versions. Note, however, that IMM is enabled only when an Asian language pack is installed. An IME-enabled application can call GetSystemMetrics with SM_IMMENABLED to determine if IMM is enabled.

The following topics are covered in this section:

  • Status, Composition, and Candidates Windows
  • IME Window Class
  • IME Messages
  • Input Context
  • Composition String
  • Candidate Lists
  • Hot Keys


Status, Composition, and Candidates Windows

The status, composition, and candidates windows form the user interface for the IME. The status window indicates that the IME is open and provides the user the means to set the conversion modes. The composition window appears when the user enters text and, depending on the conversion mode, either displays the text as entered or displays converted text. The candidates window appears in conjunction with the composition window. It contains a list of "candidates" (alternative characters) for the selected character or characters in the composition window. The user can scroll through the candidates list and select the desired characters, then return to the composition window. The user can compose the desired text in this way until the composition string is finalized and the window is closed. The IME sends the composed characters to the application in the form of WM_IME_CHAR or WM_IME_COMPOSITION/GCS_RESULT messages. If the application does not process these messages, the DefWindowProc function translates them into one or more WM_CHAR messages.

By default, the system automatically creates and manages status, composition, and candidates windows for all windows that require text input. For many applications, this default processing is sufficient. These applications rely entirely on the system for IME support and are said to be IME-unaware because they are unaware of the many tasks the system carries out to manage the IME windows.

An IME-aware application, on the other hand, participates in the creation and management of IME windows. Such applications control the operation, position, and appearance of the default windows by sending messages to and by intercepting and processing messages intended for these windows. In some cases, applications create their own IME windows and provide complete processing for their custom status, composition and candidates windows.


IME Window Class

The "IME" window class is a predefined system global class that defines the appearance and behavior of the standard IME windows. The class is similar to common control classes in that you create a window of this class by using the CreateWindowEx function. Like static controls, an IME window does not respond to user input by itself. Instead, it notifies the IME of user input actions and processes control messages sent to it by the IME or applications to carry out a response to the user action.

IME-aware applications sometimes create their own IME windows using the IME class. This allows the application to take advantage of the default processing of the IME window while having control of the positioning of the window.


IME Messages

The system sends IME window messages to the window procedure of the application when certain events occur that affect the IME windows. For example, the system sends the WM_IME_SETCONTEXT message to the application when a window is activated. IME-unaware application pass these messages to the DefWindowProc function which sends them to the corresponding default IME window. IME-aware applications either process these messages or forward them to their own IME windows.

You can direct an IME window to carry out a command, such as change the position of composition window, by using the WM_IME_CONTROL message. The IME notifies the application about changes to the composition string by using the WM_IME_COMPOSITION message and about general changes to the status of the IME windows by sending the WM_IME_NOTIFY message.


Input Context

An input context is an internal structure, maintained by the IME, that contains information about the status of the IME and is used by IME windows. By default, the system creates and assigns an input context to each thread. Within the thread, this default input context is a shared resource and is associated with each newly created window.

To retrieve or set information in the IME, an application must first retrieve a handle to the input context associated with a specified window. You retrieve the handle by using the ImmGetContext function. You can use the retrieved handle in subsequent calls to the input method manager functions to retrieve and set IME values, such as the composition window style, the composition style, and the status window position. Once you have finished using the context, you must release it using the ImmReleaseContext function.

Because the default input context is a shared resource, any changes you make to it apply to all windows in the thread. However, you can override this default behavior by creating and associating your own input context to one or more windows of the thread. The changes you make to your own input context apply only to the windows with which it is associated.

You can create an input context by using the ImmCreateContext function. To assign the context to a window, call the ImmAssociateContext function. This function returns a handle to the previously associated input context. If you have not associated an input context with the window before, the returned handle is for the default input context. Typically, you save this handle and later reassociate it with the window when you no longer want to use your own input context.

Once an input context is associated with a window, the system automatically selects that context when the window is activated and receives the input focus. The style and other information in the input context affects subsequent keyboard input for that window, determining whether and how the IME operates.

You must destroy any input context you create before terminating your application. First, you must remove the input context from any association it has with windows in the thread by using the ImmAssociateContext function. Then, call the ImmDestroyContext function.


Composition String

The composition string is the current text in the composition window. This is the text that the IME converts to final characters. Each composition string consists of one or more clauses, where a clause is the smallest combination of characters that the IME can convert to a final character. To get and set the composition string, call the ImmGetCompositionString and ImmSetCompositionString functions.

As the user enters text in the composition window, the IME tracks the status of the composition string. This status includes attribute information, clause information, typing information, and cursor position. You can retrieve the composition status by using the ImmGetCompositionString function.

In the attribute information array, all characters of one clause must have the same attribute. The attribute information is an array of 8-bit values that specifies the status of characters in the composition string. There is one value for each byte in the string, including one byte each for the lead and second bytes of any double-byte characters in the string. For each value in the array, bits 0 through 3 can be one combination of the following values.

Value | Meaning
ATTR_INPUT | Character being entered by the user. It is yet to be converted by the IME.
ATTR_INPUT_ERROR | Character is an error character and cannot be converted by the IME. For example, some consonants cannot be put together.
ATTR_TARGET_CONVERTED | Character converted by the IME. The user has selected this character and the IME has converted it.
ATTR_CONVERTED | A converted character. The IME has already converted this character.
ATTR_TARGET_NOTCONVERTED | Character being converted. The user has selected this character but the IME has not yet converted it.
ATTR_FIXEDCONVERTED | Characters that will not be converted. The IME will not convert these characters anymore.

All other values are reserved. In Japanese, any unconverted character having the ATTR_INPUT attribute is a Hiragana, Katakana, or alphanumeric character. In Korean, this character is a Hangeul character that is not converted by IME yet. In Traditional and Simplified Chinese, each IME may limit its character in some range.

The clause information is an array of 32-bit values that specifies the positions of the clauses in the composition string. There is one value for each clause and a final value that specifies the length of the full string. Each value in the array specifies the offset, in bytes, from the beginning of the string to the clause. The first value is always 0 because the first clause always starts at the beginning of the string. For example, if a string has two clauses, the clause information has three values: the first value is 0, the second value is the offset of the second clause, and the third value is the length of the string. For Unicode, the position of a clause is the position counted in Unicode characters, and the length of a string is the size in Unicode characters.

The typing information is a null-terminated character string representing the characters entered at the keyboard.

The cursor position is a value indicating the position of the cursor relative to the characters in the composition string. The value is the offset, in bytes, from the beginning of the string. If this value is 0, the cursor is immediately before the first character in the string. If the value is equal to the length of the string, the cursor is immediately after the last character. If –1, the cursor is not present. For Unicode, both position and length are measured in Unicode characters.

You can set the composition string or elements of the composition status by using the ImmSetCompositionString function. To ensure that the composition window updates its appearance based on these changes, the function allows you to send a notification message to the window. Applications that set a combination of composition status elements typically set the fNotify parameter to FALSE for all but the last call to this function so that only one notification message is generated for the composition window.

Finally, the edit control supports two messages for changing the IME's handling of composition strings. For more information, see EM_GETIMESTATUS and EM_SETIMESTATUS. For more information on the edit control, see Edit Controls.


Candidate Lists

A candidate list is a CANDIDATELIST structure consisting of an array of strings that specifies the characters or character strings that the user may choose from. You can retrieve the candidate lists by using the ImmGetCandidateListCount and ImmGetCandidateList functions.


Hot Keys

Hot keys give the user a way to quickly change the input mode of the IME or to switch to another IME. Although applications cannot add hot keys to the system, they can initiate the same action as a hot key by using the ImmSimulateHotKey function.

The HexToUnicode IME also permits conversion between hexadecimal and Unicode characters. For an explanation, see HexToUnicode IME.


HexToUnicode IME

Rich Edit 3.0 supports the HexToUnicode IME, which allows a user to convert between hexadecimal and Unicode characters by using hot keys in one of two ways.

In the first method, the user types the character code in hexadecimal and then types ALT+X. The IME replaces the hexadecimal digits preceding the insertion point with the Unicode character. If the current font does not support the character code, an appropriate font is chosen that does support it. To convert from Unicode to hexadecimal, type SHIFT+ALT+X. This replaces the Unicode character that precedes the insertion point with the hexadecimal digits. In particular, this allows you to determine the character that is indicated by a "missing glyph" indicator. If the hexadecimal character code immediately follows some legitimate (noncharacter) hexadecimal characters, select the specific digits that you want to convert before typing ALT+X. A problem with this first method is that ALT+X is sometimes used as a key combination for the exit command (that is, eXit). For example, in Microsoft Office, this only happens as an option of the File menu.

The second method involves the number pad. Here the user types ALT+NumPad numbers (with values greater than 255) to enter Unicode characters using decimal values. This method is not as useful as the first method because you cannot see what hexadecimal digits you typed. Also, you cannot correct them except by reentering them all again.


Using Input Method Editor

The discussion on using the Input Method Editor is divided into the following sections:

  • Processing the WM_IME_COMPOSITION message
  • The Input Method Editor and Unicode
  • Using Reconversion with the Input Method Editor
  • Developing IME-Aware Multiple Thread Applications
  • IME on Windows 2000


Processing the WM_IME_COMPOSITION Message

Applications that process the WM_IME_COMPOSITION message test the bits in lParam parameter and call the ImmGetCompositionString function to retrieve the indicated string or data. The following example checks for the result string, allocates sufficient memory for the string, and retrieves the result string from the IME:

HIMC hIMC;
HWND hWnd;
DWORD dwSize;
HGLOBAL hstr;
LPSTR lpstr;

case WM_IME_COMPOSITION:
    if (lParam & GCS_RESULTSTR)
    {
        hIMC = ImmGetContext(hWnd);

        If (!hIMC)
            MyError(ERROR_NULLCONTEXT);

        // Get the size of the result string.
        dwSize = ImmGetCompositionString(hIMC, GCS_RESULTSTR, NULL, 0);

        // increase buffer size for NULL terminator,
        //   maybe it is in UNICODE
        dwSize += sizeof(WCHAR);

        hstr = GlobalAlloc(GHND,dwSize);
        if (hstr == NULL)
             MyError(ERROR_GLOBALALLOC);

        lpstr = GlobalLock(hstr);
        if (lpstr == NULL)
             MyError(ERROR_GLOBALLOCK);

        // Get the result strings that is generated by IME into lpstr.
        ImmGetCompositionString(hIMC, GCS_RESULTSTR, lpstr, dwSize);
        ImmReleaseContext(hWnd, hIMC);

        // add this string into text buffer of application

        GlobalUnlock(hstr);
        GlobalFree(hstr);
    }


The Input Method Editor and Unicode

Microsoft® Windows NT®/2000 and Microsoft Windows® 98: Both platforms support a Unicode interface for the IME, in addition to the ANSI interface originally supported by Windows 95. Windows 98 supports all the Unicode functions except ImmIsUIMessage. Also, all the messages in Windows 98 are ANSI based. Since Windows 98 does not support Unicode messages, applications can use ImmGetCompositionString to receive Unicode characters from a Unicode based IME on Windows 98.

There are two issues involved with Unicode handling and the IME. One is that the Unicode versions of IME routines return the size of a buffer in bytes rather than 16-bit Unicode characters,and the other is the IME normally returns Unicode characters (rather than DBCS) in the WM_CHAR and WM_IME_CHAR messages.

Use RegisterClassW to cause the WM_CHAR and WM_IME_CHAR messages to return Unicode characters in the wParam parameter rather than DBCS characters. This is only available under Windows NT/Windows 2000; it is stubbed out in Windows 95/Windows 98.


Using Recoversion with the Input Method Editor

Platform SDK: International Features

Using Reconversion with the Input Method Editor

In Windows 98 and Windows 2000, the IME implements a new feature called reconversion. Normally the IME determines the lists of candidates based only on what is typed. Reconversion allows the IME to determine candidates (or only one candidate) based on the sentence it is in (its context). There are three types of reconversion: simple, normal, and enhanced.

Reconversion is useful when a user notices a composition error in the document. In this case the user can select the error, choose reconversion from a menu, and the IME will use the context to determine the best replacement. ImmSetCompositionString can be used to support reconversion.


Developing IME-Aware Multiple Thread Applications

The current Input Method Manager (IMM) architecture does not provide a synchronization facility for access to IMM handles.

The Input Method Manager in Windows 2000 includes thread identification checking, which checks whether the calling thread is the creator of the specified Input Method Context handle (hIMC) or window handle (hWnd). If it is not, the function call will fail and return ERROR_INVALID_ACCESS from the GetLastError function.

This implementation requires application developers to adhere to the following guidelines:

  • A thread should not access the input context created by another thread.
  • A thread should not associate an input context to a window created by another thread or vice versa.


IME on Windows 2000

Windows 2000 provides full-featured IME support in any localized language version. Therefore, you can install and use an IME on any version of Windows 2000, not just Windows 2000 localized for Asian languages.

However, IMM is enabled only when the user has installed an Asian language pack on Windows 2000. An IME-enabled application can call the GetSystemMetrics function with SM_IMMENABLED to determine whether IMM is enabled.


Input Method Editor Reference

The following elements are used with the input method editor:

  • Input Method Editor Functions
  • Input Method Editor Messages
  • Input Method Editor Commands
  • Input Method Editor Structures
  • Input Method Editor Constants


Input Method Editor Functions

This section describes the input method editor functions.

Function | Description
EnumInputContext | An application defined–callback function used with the ImmEnumInputContext function.
EnumRegisterWordProc | An application-defined callback function used with the ImmEnumRegisterWord function.
ImmAssociateContext | Associates the specified input context with the specified window.
ImmAssociateContextEx | Changes the association between the input method context and the specified window or its children.
ImmConfigureIME | Displays the configuration dialog box for the IME of the specified input locale identifier.
ImmCreateContext | Creates a new input context.
ImmDestroyContext | Releases the input context and frees any memory associated with it.
ImmDisableIME | Disables the input method editor.
ImmEnumInputContext | Retrieves the input context for the specified thread.
ImmEnumRegisterWord | Enumerates the register strings having the specified reading string, style, and register string.
ImmEscape | Accesses capabilities of particular IMEs that are not available through other IMM APIs. and is used mainly for country-specific operations.
ImmGetCandidateList | Retrieves a specified candidate list, copying the list to the specified buffer.
ImmGetCandidateListCount | Retrieves the size of the candidate lists.
ImmGetCandidateWindow | Retrieves information about the candidate list window.
ImmGetCompositionFont | Retrieves information about the logical font currently used to display characters in the composition window.
ImmGetCompositionString | Retrieves information about the composition string.
ImmGetCompositionWindow | Retrieves information about the composition window.
ImmGetContext | Retrieves the input context associated with the specified window.
ImmGetConversionList | Retrieves the conversion result list of characters or words without generating any IME-related messages.
ImmGetConversionStatus | Retrieves the current conversion status.
ImmGetDefaultIMEWnd | Retrieves the default window handle for the IME class.
ImmGetDescription | Copies the description of the IME to the specified buffer.
ImmGetGuideLine | Retrieves information about errors.
ImmGetIMEFileName | Retrieves the file name of the IME associated with the specified input locale.
ImmGetImeMenuItems | Retrieves the menu items that are registered in the IME menu of a specified input context.
ImmGetOpenStatus | Determines whether the IME is open or closed.
ImmGetProperty | Retrieves the property and capabilities of the IME associated with the specified input locale.
ImmGetRegisterWordStyle | Retrieves a list of the styles support by the IME associated with the specified input locale.
ImmGetStatusWindowPos | Retrieves the position of the status window.
ImmGetVirtualKey | Retrieves the original virtual-key value associated with a key input message that has already been processed by the IME.
ImmInstallIME | Installs an IME.
ImmIsIME | Determines whether the specified input locale has an IME.
ImmIsUIMessage | Checks for messages intended for the IME window and sends those messages to the specified window.
ImmNotifyIME | Notifies the IME about changes to the status of the input context.
ImmRegisterWord | Registers a string into the dictionary of the IME associated with the specified input locale.
ImmReleaseContext | Releases the input context and unlocks the memory associated in the input context.
ImmSetCandidateWindow | Sets information about the candidate list window.
ImmSetCompositionFont | Sets the logical font to be used to display characters in the composition window.
ImmSetCompositionString | Sets the characters, attributes, and clauses of the composition and reading strings.
ImmSetCompositionWindow | Sets the position of the composition window.
ImmSetConversionStatus | Sets the current conversion status.
ImmSetOpenStatus | Opens or closes the IME.
ImmSetStatusWindowPos | Sets the position of the status window.
ImmSimulateHotKey | Simulates the specified IME hot key, causing the same response as if the user had pressed the hot key in the specified window.
ImmUnregisterWord | Removes a register string from the dictionary of the IME associated with the specified input locale.


EnumInputContext

The EnumInputContext function is an application defined–callback function used with the ImmEnumInputContext function. It is used to process input contexts. The IMCENUMPROC type defines a pointer to this callback function. EnumInputContext is a placeholder for the application defined–function name.

BOOL CALLBACK EnumInputContext(
  HIMC hIMC,
  LPARAM lParam
);

Parameters

hIMC
[in] Handle to the input context.
lParam
[in] Application-supplied data.

Return Values

Returns a nonzero value to continue enumeration and zero to stop enumeration.

Remarks

An application must register this function by passing its address to the ImmEnumInputContext function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmEnumInputContext


EnumRegisterWordProc

The EnumRegisterWordProc function is an application-defined callback function used with the ImmEnumRegisterWord function. It is used to process data of register strings. The REGISTERWORDENUMPROC type defines a pointer to this callback function. EnumRegisterWordProc is a placeholder for the application-defined function name.

UINT CALLBACK EnumRegisterWordProc(
  LPCTSTR lpszReading,
  DWORD dwStyle,
  LPCTSTR lpszString,
  LPVOID lpData
);

Parameters

lpszReading
[in] Pointer to a null-terminated string specifying the matched reading string.
dwStyle
[in] Specifies the style of register string.
lpszString
[in] Pointer to a null-terminated string specifying the matched register string.
lpData
[in] Application-supplied data.

Return Values

Returns a nonzero value to continue enumeration; zero to stop enumeration.

Remarks

An application must register this function by passing its address to the ImmEnumRegisterWord function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmEnumRegisterWord


ImmAssociateContext

The ImmAssociateContext function associates the specified input context with the specified window. By default, the system associates the default input context with each window as it is created.

To specify a type of association, use the ImmAssociateContextEx function.

HIMC ImmAssociateContext(
  HWND hWnd,
  HIMC hIMC
);

Parameters

hWnd
[in] Handle to the window to be associated with the input context.
hIMC
[in] Handle to the input context. If hIMC is NULL, the function removes any association the window may have with an input context and thus IME cannot be used in the window.

Return Values

Returns the handle to the input context previously associated with the window.

Remarks

If an application associates an input context with a window, the application must remove that association before destroying the input context. One way to do this is to save and reassociate the handle to the default input context with the window.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmAssociateContextEx


ImmAssociateContextEx

The ImmAssociateContextEx function changes the association between the input method context and the specified window or its children.

BOOL ImmAssociateContextEx(
  HWND hWnd,
  HINC hIMC,
  DWORD dwFlags
);

Parameters

hWnd
[in] Handle to the window to be associated with the input context.
hIMC
[in] Handle to the input method context.
dwFlags
[in] Specifies the type of association between the window and the input method context. This parameter can be one of the following values.
Value | Meaning
IACE_CHILDREN | Associate the input method context to the child windows of hWnd only.
IACE_DEFAULT | Restore the window's default input method context.
IACE_IGNORENOCONTEXT | Do not associate the input method context with windows that are not associated with any input method context.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

If the application calls this function with IACE_CHILDREN, the system associates the specified input method context with child windows of hWnd. It associates the input method context only with child windows of the thread that created hWnd. Any child window that is created after this function has been called will not be affected. Instead, the default input method context will be associated with it.

If the application calls this function with IACE_DEFAULT, the system restores the window's default input method context. In this case, the hIMC parameter is ignored.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmConfigureIME

The ImmConfigureIME function displays the configuration dialog box for the IME of the specified input locale identifier (HKL).

BOOL ImmConfigureIME(
  HKL hKL,
  HWND hWnd,
  DWORD dwMode,
  LPVOID lpData
);

Parameters

hKL
[in] Input locale identifier of an IME.
hWnd
[in] Handle to the parent window for the dialog box.
dwMode
[in] Specifies the type of dialog box to be displayed. This parameter can be one of the following values.
Value | Meaning
IME_CONFIG_GENERAL | Displays general purpose configuration dialog box.
IME_CONFIG_REGISTERWORD | Displays register word dialog box.
IME_CONFIG_SELECTDICTIONARY | Displays dictionary selection dialog box.

lpData
[in] Pointer to supplemental data. If dwMode is IME_CONFIG_REGISTERWORD, this parameter must be a pointer to a REGISTERWORD structure.

If dwMode is not IME_CONFIG_REGISTERWORD, this parameter is ignored.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, REGISTERWORD


ImmCreateContext

The ImmCreateContext function creates a new input context, allocating memory for the context and initializing it. An application calls this function to prepare its own input context.

HIMC ImmCreateContext(void);

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle to the new input context.

If the function fails, the return value is NULL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmDestroyContext

The ImmDestroyContext function releases the input context and frees any memory associated with it.

BOOL ImmDestroyContext(
  HIMC hIMC
);

Parameters

hIMC
[in] Handle to the input context to free.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

Any application that creates an input context by using the ImmCreateContext function must call this function to free the context before it terminates. However, before calling ImmDestroyContext you must remove the input context from any association it has with windows in the thread by using the ImmAssociateContext function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmAssociateContext, ImmCreateContext


ImmDisableIME

The ImmDisableIME function disables the input method editor (IME) for a thread or all threads in a process.

BOOL ImmDisableIME(
  DWORD idThread
);

Parameters

idThread
[in] Identifier of the thread for which the IME is to be disabled. The thread must be in the same process as the caller of this function. If idThread is zero, the IME for the current thread is disabled. If idThread is –1, the IME is disabled for all threads in the current process.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The application must call this function before the first top-level window in the thread receives the WM_CREATE message. This means the application must call this function in one of the following places:

  • Any time before calling CreateWindow to create the first top-level window
  • In the first top-level window's WM_NCCREATE handler

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, CreateWindow, WM_CREATE, WM_NCCREATE


ImmEnumInputContext

The ImmEnumInputContext function retrieves the input context for the specified thread.

BOOL WINAPI ImmEnumInputContext(
  DWORD idThread,
  IMCENUMPROC lpfn,
  LPARAM lParam
);

Parameters

idThread
[in] Specifies the thread identifier. This parameter can be one of the following values.
Value | Meaning
0 | Current thread.
–1 | Current process.
Thread ID | ID of the thread whose context is to be enumerated. This thread ID can belong to another process.

lpfn
[in] Pointer to the enumeration callback function. For more information, see EnumInputContext.
lParam
[in] Application-supplied data. The function passes this parameter to the callback function.

Return Values

Returns TRUE if successful; otherwise returns FALSE.

Remarks

The callback function will be called for each enumerated input context and passed the specified lParam value.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, EnumInputContext


ImmEnumRegisterWord

The ImmEnumRegisterWord function enumerates the register strings having the specified reading string, style, and register string.

UINT ImmEnumRegisterWord(
  HKL hKL,
  REGISTERWORDENUMPROC lpfnEnumProc,
  LPCTSTR lpszReading,
  DWORD dwStyle,
  LPCTSTR lpszRegister,
  LPVOID lpData
);

Parameters

hKL
[in] Input locale identifier.
lpfnEnumProc
[in] Pointer to the callback function. For more information, see EnumRegisterWordProc.
lpszReading
[in] Pointer to the reading string to be enumerated. If NULL, this function enumerates all available reading strings that match the specified dwStyle and lpszRegister.
dwStyle
[in] Specifies the style to enumerate. If zero, this function enumerates all available styles that match the specified lpszReading and lpszRegister.
lpszRegister
[in] Pointer to the register string to enumerate. If NULL, this function enumerates all register strings that match the specified lpszReading and dwStyle.
lpData
[in] Pointer to the application-supplied data. The function passes this parameter to the callback function.

Return Values

Returns the last value return by the callback function. Its meaning is defined by the application. The function returns zero if it cannot enumerate the register strings.

Remarks

If dwStyle is zero and both lpszReading and lpszRegister are NULL, the ImmEnumRegisterWord function enumerates all register strings in the IME dictionary.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, EnumRegisterWordProc


ImmEscape

The ImmEscape function accesses capabilities of particular IMEs that are not available through other IMM APIs. and is used mainly for country-specific operations.

LRESULT ImmEscape(
  HKL hKL,
  HIMC hIMC,
  UINT uEscape,
  LPVOID lpData
);

Parameters

hKL
[in] Input locale identifier.
hIMC
[in] Handle to the input context.
uEscape
[in] Index of the operations. For more information, see IME Escapes.
lpData
[in] Pointer to the data required for the escape specified in uEscape. Depending on the escape, when the function returns lpData may contain the result of the escape. For more information, see IME Escapes.

Return Values

Returns zero on error; otherwise, returns an operation-specific value.

Remarks

When uEscape is IME_ESC_QUERY_SUPPORT, lpData points to a buffer containing the IME escape value. For example, to see if the current IME supports IME_ESC_GETHELPFILENAME, you would use:

DWORD dwEsc = IME_ESC_GETHELPFILENAME;
LRESULT lRet = ImmEscape(hKL, hIMC, IME_ESC_QUERYSUPPORT,
     (LPVOID)&dwEsc);

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmGetCandidateList

The ImmGetCandidateList function retrieves a specified candidate list, copying the list to the specified buffer.

DWORD ImmGetCandidateList(
  HIMC hIMC,
  DWORD dwIndex,
  LPCANDIDATELIST lpCandList,
  DWORD dwBufLen
);

Parameters

hIMC
[in] Handle to the input context.
dwIndex
[in] Zero-based index of the candidate list.
lpCandList
[out] Pointer to a CANDIDATELIST structure that receives the candidate list.
dwBufLen
[in] Specifies the size of the buffer, in bytes. If zero, the function returns the size in bytes required to receive the complete candidate list.

Return Values

If the function succeeds, the return value is the number of bytes copied to the buffer specified by lpCandList.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, CANDIDATELIST


ImmGetCandidateListCount

The ImmGetCandidateListCount function retrieves the size of the candidate lists.

DWORD ImmGetCandidateListCount(
  HIMC hIMC,
  LPDWORD lpdwListCount
);

Parameters

hIMC
[in] Handle to the input context.
lpdwListCount
[out] Pointer to the buffer that receives the size of the candidate lists.

Return Values

If successful, returns the number of bytes required to receive all candidate lists.

If the function fails, it returns zero.

Remarks

Applications typically call this function in response to a IMN_OPENCANDIDATE or IMN_CHANGECANDIDATE command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, IMN_CHANGECANDIDATE, IMN_OPENCANDIDATE


ImmGetCandidateWindow

The ImmGetCandidateWindow function retrieves information about the candidate list window.

BOOL ImmGetCandidateWindow(
  HIMC hIMC,
  DWORD dwIndex,
  LPCANDIDATEFORM lpCandidate
);

Parameters

hIMC
[in] Handle to the input context.
dwIndex
[in] Index of the candidate window.
lpCandidate
[out] Pointer to a CANDIDATEFORM structure that receives information about the candidate window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, CANDIDATEFORM


ImmGetCompositionFont

The ImmGetCompositionFont function retrieves information about the logical font currently used to display characters in the composition window.

BOOL ImmGetCompositionFont(
  HIMC hIMC,
  LPLOGFONT lplf
);

Parameters

hIMC
[in] Handle to the input context.
lplf
[out] Pointer to a LOGFONT structure that receives the font information.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, LOGFONT


ImmGetCompositionString

The ImmGetCompositionString function retrieves information about the composition string.

LONG ImmGetCompositionString(
  HIMC hIMC,
  DWORD dwIndex,
  LPVOID lpBuf,
  DWORD dwBufLen
);

Parameters

hIMC
[in] Handle to the input context.
dwIndex
[in] Index of the information to retrieve. This parameter can be one of the values specified in IME Composition String Values. For each value except GCS_CURSORPOS and GCS_DELTASTART, the function copies the requested information to the specified buffer. The function returns the cursor and delta position values in the low 16-bits of the return value.
lpBuf
[out] Pointer to a buffer that receives the requested information.
dwBufLen
[in] Specifies the size of the buffer, in bytes. This is true even if the buffer contains a Unicode string. If zero, this function returns the buffer size needed for the complete information.

Return Values

Returns the number of bytes copied to the destination buffer or, if dwBufLen is zero, the buffer size, in bytes, needed to receive all of the requested information, not including the null terminating character. The return value is always the size in bytes, even if the requested data is a Unicode string. On an error, the function returns one of the following negative error values.

Value | Meaning
IMM_ERROR_NODATA | Composition data is not ready in the input context.
IMM_ERROR_GENERAL | General error detected by IME.

Remarks

An application calls this function in response to the WM_IME_COMPOSITION or WM_IME_STARTCOMPOSITION message. The IMM removes the information when an application calls the ImmReleaseContext function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmReleaseContext, WM_IME_COMPOSITION, WM_IME_STARTCOMPOSITION


ImmGetCompositionWindow

The ImmGetCompositionWindow function retrieves information about the composition window.

BOOL ImmGetCompositionWindow(
  HIMC hIMC,
  LPCOMPOSITIONFORM lpCompForm
);

Parameters

hIMC
[in] Handle to the input context.
lpCompForm
[out] Pointer to a COMPOSITIONFORM structure that receives information about the composition window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, COMPOSITIONFORM


ImmGetContext

The ImmGetContext function retrieves the input context associated with the specified window.

HIMC ImmGetContext(
  HWND hWnd
);

Parameters

hWnd
[in] Handle to the window for which to retrieve the input context.

Return Values

Returns the handle to the input context.

Remarks

An application should routinely use this function to retrieve the current input context before attempting to access information in the context.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmGetConversionList

The ImmGetConversionList function retrieves the conversion result list of characters or words without generating any IME-related messages.

DWORD ImmGetConversionList(
  HKL hKL,
  HIMC hIMC,
  LPCTSTR lpSrc,
  LPCANDIDATELIST lpDst,
  DWORD dwBufLen,
  UINT uFlag
);

Parameters

hKL
[in] Input locale identifier.
hIMC
[in] Handle to the input context.
lpSrc
[in] Pointer to a null-terminated character string.
lpDst
[out] Pointer to a CANDIDATELIST structure that receives the conversion result.
dwBufLen
[in] Specifies the size of the destination buffer, in bytes. If this parameter is zero, the function returns the buffer size needed for the complete conversion result.
uFlag
[in] Action flag. This parameter can be one of the following values.
Value | Meaning
GCL_CONVERSION | Source string is the reading string. The function copies the result string to the destination buffer.
GCL_REVERSECONVERSION | Source string is the result string. The function copies the reading string to the destination buffer.
GCL_REVERSE_LENGTH | Source string is the result string. The function returns the size in bytes of the reading string that would be created if GCL_REVERSECONVERSION were specified.

Return Values

Returns the number of bytes copied to the specified buffer or, if dwBufLen is zero, the buffer size needed to receive the list.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, CANDIDATELIST


ImmGetConversionStatus

The ImmGetConversionStatus function retrieves the current conversion status.

BOOL ImmGetConversionStatus(
  HIMC hIMC,
  LPDWORD lpfdwConversion,
  LPDWORD lpfdwSentence
);

Parameters

hIMC
[in] Handle to the input context for which to retrieve information.
lpfdwConversion
[out] Pointer to a variable that receives a combination of conversion mode values. For more information, see IME Conversion Mode Values.
lpfdwSentence
[out] Pointer to a variable that receives a sentence mode value. For more information, see IME Sentence Mode Values.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

Conversion and sentence mode values are set only if the IME supports those modes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmGetDefaultIMEWnd

The ImmGetDefaultIMEWnd function retrieves the default window handle for the IME class.

HWND ImmGetDefaultIMEWnd(
  HWND hWnd
);

Parameters

hWnd
[in] Handle to the window for the application.

Return Values

If the function succeeds, the return value is the default window handle to the IME class.

If the function fails, the return value is NULL.

Remarks

The system creates a default IME window for every thread. The IME window is created based on the IME class. The application can send the WM_IME_CONTROL message to this window.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, WM_IME_CONTROL


ImmGetDescription

The ImmGetDescription function copies the description of the IME to the specified buffer.

UINT ImmGetDescription(
  HKL hKL,
  LPTSTR lpszDescription,
  UINT uBufLen
);

Parameters

hKL
[in] Input locale identifier.
lpszDescription
[out] Pointer to a buffer that receives the null-terminated string describing the IME.
uBufLen
[in] Specifies the size of the buffer, in characters. If zero, the function returns the buffer size needed for the complete description, not including terminating null character.

Windows NT/2000 or later: The size of the buffer is in Unicode characters (each character is two bytes). If zero, the function returns the size of the buffer required in unicode characters, not including the Unicode NULL terminator.

Return Values

Returns the number of characters copied to the buffer or, if uBufLen is zero, the buffer size in characters needed to receive the description. Neither value includes the terminating null character.

For Unicode, the function returns the number of Unicode characters, not including the Unicode NULL terminator.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmGetGuideLine

The ImmGetGuideLine function retrieves information about errors. Applications use the information to notify users.

DWORD ImmGetGuideLine(
  HIMC hIMC,
  DWORD dwIndex,
  LPTSTR lpBuf,
  DWORD dwBufLen
);

Parameters

hIMC
[in] Handle to the input context.
dwIndex
[in] Specifies the type of guideline information to retrieve. This parameter can be one of the following values.
Value | Meaning
GGL_LEVEL | Returns the error level.
GGL_INDEX | Returns the error index.
GGL_STRING | Retrieves the error message string.
GGL_PRIVATE | Returns information about reverse conversion.

lpBuf
[out] Pointer to a buffer that receives the error message string. This parameter can be NULL if dwIndex is not GGL_STRING or GGL_PRIVATE if dwBufLen is zero.
dwBufLen
[in] Specifies the size, in bytes, of the buffer pointed to by lpBuf. If zero, the function returns the buffer size needed to receive the error message string, not including the terminating null character.

Return Values

The function returns an error level, an error index, or the size of an error message string, depending on the value of the dwIndex parameter. If dwIndex is GGL_LEVEL, the return value is one of the following values.

Value | Meaning
GL_LEVEL_ERROR | Error. The IME may not be able to continue.
GL_LEVEL_FATAL | Fatal error. The IME cannot continue, and data may be lost.
GL_LEVEL_INFORMATION | No error, but information is available for the user.
GL_LEVEL_NOGUIDELINE | No error. Remove previous error message if still visible.
GL_LEVEL_WARNING | Unexpected input or other result. The user should be warned, but the IME can continue.

If dwIndex is GGL_INDEX, the return value is one of the following values.

Value | Meaning
GL_ID_CANNOTSAVE | The dictionary or the statistics data cannot be saved.
GL_ID_NOCONVERT | The IME cannot convert any more.
GL_ID_NODICTIONARY | The IME cannot find the dictionary, or the dictionary has an unexpected format.
GL_ID_NOMODULE | The IME can not find the module that IME needs.
GL_ID_READINGCONFLICT | A reading conflict occurred. For example, some vowels cannot be put together to form one character.
GL_ID_TOOMANYSTROKE | There are too many strokes for one character or one clause.
GL_ID_TYPINGERROR | Typing error. The IME can not handle this typing.
GL_ID_UNKNOWN | Unknown error. The application should refer to the error message string.
GL_ID_INPUTREADING | IME is accepting reading character input from the end user.
GL_ID_INPUTRADICAL | IME is accepting radical character input from the end user.
GL_ID_INPUTCODE | IME is accepting character code input from the end user.
GL_ID_CHOOSECANDIDATE | IME is accepting candidate string selection from the end user.
GL_ID_REVERSECONVERSION | Information about reverse conversion is available by calling ImmGetGuideLine (hIMC, GGL_PRIVATE, lpBuf, dwBufLen). The information returned in lpBuf is in CANDIDATELIST format.

If dwIndex is GGL_STRING, the return value is the number of bytes of the string copied to the buffer. However, if dwBufLen is zero, the return value is the buffer size needed to receive the string, not including the NULL terminator. For Unicode, if dwBufLen is 0, the return value is the size in bytes, not including the Unicode NULL terminator.

If dwIndex is GGL_PRIVATE, the return value is the number of bytes of information copied to the buffer. If dwIndex is GGL_PRIVATE and dwBufLen is zero, the return value is the buffer size needed to receive the information.

Remarks

Applications typically call this function after receiving a IMN_GUIDELINE command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmGetGuideLine, IMN_GUIDELINE, CANDIDATELIST


ImmGetIMEFileName

The ImmGetIMEFileName function retrieves the file name of the IME associated with the specified input locale.

UINT ImmGetIMEFileName(
  HKL hKL,
  LPTSTR lpszFileName,
  UINT uBufLen
);

Parameters

hKL
[in] Input locale identifier.
lpszFileName
[out] Pointer to a buffer that receives the file name. It can be NULL when uBufLen is NULL.
uBufLen
[in] Specifies the size, in bytes, of the buffer. If zero, the function returns the buffer size needed to receive the file name, not including the terminating null character. If Unicode, uBufLen specifies the length in unicode characters, not including the terminating null character.

Return Values

The function returns the number of bytes in the file name copied to the buffer, or if uBufLen is zero, the return value is the buffer size needed for the file name. In either case, the terminating null character is not included.

If Unicode, it returns the number of Unicode characters copied into the buffer specified with lpszFileName not including the Unicode NULL terminator.

Remarks

In the registry, the system stores the file name as the IME name value in HKEY_LOCAL_MACHINE root under the \System\CurrentControlSet\control\keyboard layouts\hKL key.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmGetImeMenuItems

The ImmGetImeMenuItems function retrieves the menu items that are registered in the IME menu of a specified input context.

DWORD WINAPI ImmGetImeMenuItems(
  HIMC hIMC,
  DWORD dwFlags,
  DWORD dwType,
  LPIMEMENUITEMINFO lpImeParentMenu,
  LPIMEMENUITEMINFO lpImeMenu,
  DWORD dwSize
);

Parameters

hIMC
[in] Handle to the input context that is related to the lpMenuItem menu items.
dwFlags
[in] Specifies menu information options. The following value is defined.
Value | Meaning
IGIMIF_RIGHTMENU | If set, the function returns the menu items for the context menu (obtained by a right mouse click).

dwType
[in] Specifies the type of menu to be returned. This parameter can be one or more of the following values.
Value | Meaning
IGIMII_CMODE | Returns the menu items that control the conversion mode.
IGIMII_SMODE | Returns the menu items that control sentence mode.
IGIMII_CONFIGURE | Returns the menu items that are related to IME configuration.
IGIMII_TOOLS | Returns the menu items that are related to IME tools.
IGIMII_HELP | Returns the menu items that control IME Help.
IGIMII_OTHER | Returns the menu items that control other IME functions.
IGIMII_INPUTTOOLS | Returns the menu items that control menu items related to IME input tools that provide an extended way to input characters.

lpImeParentMenu
[out] Pointer to an IMEMENUITEMINFO stucture that receives the parent-menu information. To return information about the submenu items of this parent menu, set the fType member to MFT_SUBMENU. If this parameter is NULL, the function returns only top-level menu items.
lpImeMenu
[out] Pointer to an array of IMEMENUITEMINFO structures that receives the menu-item information. If this parameter is NULL, the function returns the number of registered menu items.
dwSize
[in] Specifies the size of the buffer to receive the IMEMENUITEMINFO structure.

Return Values

The function returns the number of menu items that were copied into lpImeMenu. If lpImeMenu is NULL, the function returns the number of registered menu items in the specified input context.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, IMEMENUITEMINFO


ImmGetOpenStatus

The ImmGetOpenStatus function determines whether the IME is open or closed.

BOOL WINAPI ImmGetOpenStatus(
  HIMC hIMC
);

Parameters

hIMC
[in] Handle to the input context.

Return Values

The function returns a nonzero value if the IME is open, and zero otherwise.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmGetProperty

The ImmGetProperty function retrieves the property and capabilities of the IME associated with the specified input locale.

DWORD ImmGetProperty(
  HKL hKL,
  DWORD fdwIndex
);

Parameters

hKL
[in] Input locale identifier.
fdwIndex
[in] Specifies the type of property information to retrieve. This parameter can be one of the following values.
Value | Meaning
IGP_PROPERTY | Property information.
IGP_CONVERSION | Conversion capabilities.
IGP_SENTENCE | Sentence mode capabilities.
IGP_UI | User interface capabilities.
IGP_SETCOMPSTR | Composition string capabilities.
IGP_SELECT | Selection inheritance capabilities.
IGP_GETIMEVERSION | Retrieves the system version number for which the specified IME was created.

Return Values

Returns the property or capability value, depending on the value of the dwIndex parameter. If dwIndex is IGP_PROPERTY, it returns one or more of the following values.

Value | Meaning
IME_PROP_AT_CARET | If set, conversion window is at the caret position. If clear, the window is near caret position.
IME_PROP_SPECIAL_UI | If set, IME has a nonstandard user interface. The application should not draw in the IME window.
IME_PROP_CANDLIST_START_FROM_1 | If set, strings in the candidate list are numbered starting at 1. If clear, strings start at 0.
IME_PROP_UNICODE | If set, the IME is viewed as a Unicode IME. The system and the IME will communicate through the Unicode IME interface. If clear, IME will use the ANSI interface to communicate with the system.
IME_PROP_COMPLETE_ON_UNSELECT | Windows 98/Me, Windows 2000 or later: If set, the IME will complete the composition string when the IME is deactivated. If clear, the IME will cancel the composition string when the IME is deactivated (for example, from a keyboard layout change).
IME_PROP_ACCEPT_WIDE_VKEY | Windows 2000 or later: If set, the IME processes the injected Unicode that came from the SendInput function by using VK_PACKET. If clear, the IME might not process the injected Unicode, and the injected Unicode might be sent to the application directly.

If dwIndex is IGP_UI, it returns one or more of the following values.

Value | Meaning
UI_CAP_2700 | Supports text escapement values of 0 or 2700. For more information, see LOGFONT .lfEscapement.
UI_CAP_ROT90 | Supports text escapement values of 0, 900, 1800, or 2700. For more information, see LOGFONT.lfEscapement.
UI_CAP_ROTANY | Supports any text escapement value. For more information, see LOGFONT.lfEscapement.

If dwIndex is IGP_SETCOMPSTR, it returns one or more of the following values.

Value | Meaning
SCS_CAP_COMPSTR | Can create the composition string by calling the ImmSetCompositionString function with the SCS_SETSTR value.
SCS_CAP_MAKEREAD | Can create the reading string from corresponding composition string when using the ImmSetCompositionString function with SCS_SETSTR and without setting lpRead.
SCS_CAP_SETRECONVERTSTRING: | This IME can support reconversion. Use ImmSetCompositionString to do reconversion.

If dwIndex is IGP_SELECT, it returns one or more of the following values.

Value | Meaning
SELECT_CAP_CONVMODE | Inherits conversion mode when a new IME is selected.
SELECT_CAP_SENTENCE | Inherits sentence mode when a new IME is selected.

If dwIndex is IGP_GETIMEVERSION, it returns one or more of the following values.

Value | Meaning
IMEVER_0310 | The IME was created for Windows 3.1
IMEVER_0400 | The IME was created for Windows 95.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmSetCompositionString, SendInput


ImmGetRegisterWordStyle

The ImmGetRegisterWordStyle function retrieves a list of the styles support by the IME associated with the specified input locale.

UINT ImmGetRegisterWordStyle(
  HKL hKL,
  UINT nItem,
  LPSTYLEBUF lpStyleBuf
);

Parameters

hKL
[in] Input locale identifier.
nItem
[in] Specifies the maximum number of styles the buffer can hold. If zero, the function counts the number of styles available in the IME.
lpStyleBuf
[out] Pointer to a STYLEBUF structure that receives the style information.

Return Values

The function returns the number of the styles copied to the buffer, or if nItem is zero, the return value is the number of styles available i the IME.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, STYLEBUF


ImmGetStatusWindowPos

The ImmGetStatusWindowPos function retrieves the position of the status window.

BOOL ImmGetStatusWindowPos(
  HIMC hIMC,
  LPPOINT lpptPos
);

Parameters

hIMC
[in] Handle to the input context.
lpptPos
[out] Pointer to a POINT structure that receives the position coordinates. These are screen coordinates, relative to the upper-left corner of the screen.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, POINT


ImmGetVirtualKey

The ImmGetVirtualKey function retrieves the original virtual-key value associated with a key input message that has already been processed by the IME.

UINT ImmGetVirtualKey(
  HWND hWnd
);

Parameters

hWnd
[in] Handle to the window that receives the key message.

Return Values

The function returns the original virtual-key value.

Remarks

Although the IME sets the virtual-key value to VK_PROCESSKEY after processing a key input message, an application can recover the original virtual-key value with the ImmGetVirtualKey function. This function can be used only for key input messages containing the VK_PROCESSKEY value.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmInstallIME

The ImmInstallIME function installs an IME.

HKL ImmInstallIME(
  LPCTSTR lpszIMEFileName,
  LPCTSTR lpszLayoutText
);

Parameters

lpszIMEFileName
[in] Pointer to a null-terminated string that specifies the full path of the IME.
lpszLayoutText
[in] Pointer to a null-terminated string that specifies the name of the IME. This name also specifies the layout text of the IME.

Return Values

The function returns the input locale identifier for the IME.

Remarks

This function is intended to be used by IME setup programs only.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmIsIME

The ImmIsIME function determines whether the specified input locale has an IME.

BOOL ImmIsIME(
  HKL hKL
);

Parameters

hKL
[in] Input locale identifier.

Return Values

If the specified hKL has an IME, the return value is a nonzero value.

Otherwise the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmIsUIMessage

The ImmIsUIMessage function checks for messages intended for the IME window and sends those messages to the specified window.

BOOL ImmIsUIMessage(
  HWND hWndIME,
  UINT msg,
  WPARAM wParam,
  LPARAM lParam
);

Parameters

hWndIME
[in] Handle to a window belonging to the IME window class.
msg
[in] Specifies the message to be checked.
wParam
[in] Message-specific parameter.
lParam
[in] Message-specific parameter.

Return Values

If the message is processed by the IME window, the return value is a nonzero value.

If the message is not processed by the IME window, the return value is zero.

Remarks

An application typically uses this function to display any composition string or candidate list specified by IME. If hWndIME is NULL, the function checks whether the message is a user interface message.

Windows 98/Me: This function exists only in an ANSI version, but Windows 98 supports all other Unicode IME functions. To receive Unicode messages on Windows 98, use GetCompositionString to receive Unicode characters from a Unicode based IME. Note, Windows 95 does not support Unicode IMM/IME APIs.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmGetCompositionString


ImmNotifyIME

The ImmNotifyIME function notifies the IME about changes to the status of the input context.

BOOL ImmNotifyIME(
  HIMC hIMC,
  DWORD dwAction,
  DWORD dwIndex,
  DWORD dwValue
);

Parameters

hIMC
[in] Handle to the input context.
dwAction
[in] Specifies the notification code. This parameter can be one of the following values.
Value | Meaning
NI_CHANGECANDIDATELIST | An application changed the current selected candidate; dwIndex is an index of a candidate list to be selected and dwValue is not used.
NI_CLOSECANDIDATE | An application directs the IME to close a candidate list; dwIndex is the index of the list to close; dwValue is not used. The IME sends a IMN_CLOSECANDIDATE command to the application if it closes the list.
NI_COMPOSITIONSTR | An application directs the IME to carry out an action on the composition string; dwValue is not used and dwIndex can be CPS_CANCEL, CPS_COMPLETE, CPS_CONVERT, or CPS_REVERT. See dwIndex for more information.
NI_IMEMENUSELECTED | An application directs the IME to allow the application to handle the specified menu; dwIndex is the ID of the menu and dwValue is an application-defined value for that menu item.
NI_OPENCANDIDATE | An application directs the IME to open a candidate list; dwIndex is the index of the list to open; dwValue is not used. The IME sends a IMN_OPENCANDIDATE command to the application if it opens the list.
NI_SELECTCANDIDATESTR | An application selected one of candidates; dwIndex is an index of a candidate list to be selected and dwValue is an index of a candidate string in the selected candidate list.
NI_SETCANDIDATE_PAGESIZE | The application changes the page size of a candidate list. The dwIndex parameter specifies the candidate list to be changed and must have a value in the range 0 to 3. The dwValue parameter is the new page size.
NI_SETCANDIDATE_PAGESTART | The application changes the page starting index of a candidate list. The dwIndex parameter specifies the candidate list to be changed and must have a value in the range 0 to 3. The dwValue parameter is the new page start index.

dwIndex
[in] Specifies the index of a candidate list or, if dwAction is NI_COMPOSITIONSTR, this parameter can be one of the following values.
Value | Meaning
CPS_CANCEL | Clear the composition string and set the status to no composition string.
CPS_COMPLETE | Set the composition string as the result string.
CPS_CONVERT | Convert the composition string.
CPS_REVERT | Cancel the current composition string and set the composition string to be the unconverted string .

dwValue
[in] Specifies the index of a candidate string or not used, depending on the value of the dwAction parameter.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, IMN_CLOSECANDIDATE, IMN_OPENCANDIDATE


ImmRegisterWord

The ImmRegisterWord function registers a string into the dictionary of the IME associated with the specified input locale.

BOOL ImmRegisterWord(
  HKL hKL,
  LPCTSTR lpszReading,
  DWORD dwStyle,
  LPCTSTR lpszRegister
);

Parameters

hKL
[in] Input locale identifier.
lpszReading
[in] Pointer to a null-terminated string specifying the reading string associated with the string to register.
dwStyle
[in] Specifies the style of the register string. This parameter can be any of the following.
Value | Meaning
IME_REGWORD_STYLE_EUDC | The string is in the EUDC range.
any value in the range from IME_REGWORD_STYLE_USER_FIRST to IME_REGWORD_STYLE_USER_LAST | The string has a private style maintained by the specified IME. See the Remarks section.

lpszRegister
[in] Pointer to a null-terminated string specifying the string to register.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

An IME ISV can define any private styles for an IME within the IME_REGWORD_STYLE_USER_FIRST and IME_REGWORD_STYLE_USER_LAST values. For example:

#define MSIME_NOUN (IME_REGWORD_STYLE_USER_FIRST)
#define MSIME_VERB (IME_REGWORD_STYLE_USER_FIRST + 1)

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmReleaseContext

The ImmReleaseContext function releases the input context and unlocks the memory associated in the input context. An application must call this function for each call to the ImmGetContext function.

BOOL ImmReleaseContext(
  HWND hWnd,
  HIMC hIMC
);

Parameters

hWnd
[in] Handle to the window for which the input context was previously retrieved.
hIMC
[in] Handle to the input context.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, ImmGetContext


ImmSetCandidateWindow

The ImmSetCandidateWindow function sets information about the candidate list window.

BOOL ImmSetCandidateWindow(
  HIMC hIMC,
  LPCANDIDATEFORM lpCandidate
);

Parameters

hIMC
[in] Handle to the input context.
lpCandidate
[in] Pointer to a CANDIDATEFORM structure that contains information about the candidate window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

Both the IME and the application call this function.

ImmSetCandidateWindow causes an IMN_SETCANDIDATEPOS command to be sent to the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, CANDIDATEFORM, IMN_SETCANDIDATEPOS


ImmSetCompositionFont

The ImmSetCompositionFont function sets the logical font to be used to display characters in the composition window.

BOOL ImmSetCompositionFont(
  HIMC hIMC,
  LPLOGFONT lplf
);

Parameters

hIMC
[in] Handle to the input context.
lplf
[in] Pointer to a LOGFONT structure containing the font information to set.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

Even if an application never uses the composition window, it must set the appropriate font to ensure that characters are displayed properly. This is especially true for vertical writing.

This function causes a IMN_SETCOMPOSITIONFONT command to be sent to the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, IMN_SETCOMPOSITIONFONT, LOGFONT


ImmSetCompositionString

The ImmSetCompositionString function sets the characters, attributes, and clauses of the composition and reading strings.

BOOL ImmSetCompositionString(
  HIMC hIMC,
  DWORD dwIndex,
  LPVOID lpComp,
  DWORD dwCompLen,
  LPVOID lpRead,
  DWORD dwReadLen
);

Parameters

hIMC
[in] Handle to the input context.
dwIndex
[in] Specifies the type of information to set. This parameter can be one of the following values.
Value | Meaning
SCS_SETSTR | Sets the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid string. If either string is too long, the IME truncates it.
SCS_CHANGEATTR | Sets attributes for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid attribute array.
SCS_CHANGECLAUSE | Sets the clause information for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid clause information array.
SCS_SETRECONVERTSTRING | Windows 98/Me, Windows 2000 or later: Asks IME to reconvert the string by a specified RECONVERTSTRING structure.
SCS_QUERYRECONVERTSTRING | Windows 98/Me, Windows 2000 or later: Asks IME to adjust the RECONVERTSTRING structure. Then the application can pass the adjusted RECONVERTSTRING structure into this API with SCS_SETRECONVERTSTRING. IME will not generate any WM_IME_COMPOSITION messages.

lpComp
[in] Pointer to a buffer containing the information to set for the composition string. The information is as specified by the dwIndex value.
dwCompLen
[in] Specifies the size, in bytes, of the information buffer for the composition string. This is true even if SCS_SETSTR is specified and the buffer contains a Unicode string.
lpRead
[in] Pointer to a buffer containing the information to set for the reading string. The information is as specified by the dwIndex value.
dwReadLen
[in] Specifies the size, in bytes, of the information buffer for the reading string. The size is in bytes even if SCS_SETSTR is specified and the buffer contains a Unicode string.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

The application can set lpComp, lpRead or both. If the application does not specify lpComp, lpComp must be NULL and dwCompLen must be zero.

When changing attributes, all characters in a clause must have the same attribute. Converted characters must be either ATTR_CONVERTED or ATTR_TARGET_CONVERTED; unconverted characters either ATTR_INPUT or ATTR_TARGET_NOTCONVERTED.

When changing clause information, only the target clause can be changed and only one boundary of the clause can be changed at a time. The target clause has the ATTR_TARGET_CONVERTED or ATTR_TARGET_NOTCONVERTED attribute.

For more information about attributes (ATTR_* values), see Composition String.

When the IME completes the changes, it sends a WM_IME_COMPOSITION message to the application notifying it of the changes.

Windows 98 and Windows 2000 or later: The SCS_*CONVERTSTRING values are used for reconversion. They can only be used for an IME that has the SCS_CAP_SETRECONVERTSTRING property. They are used as follows: First, call ImmSetCompositionString() with SCS_QUERYRECONVERTSTRING so that IME adjusts the RECONVERTSTRING structure for the reconversion. Then, call ImmSetCompositionString() with SCS_SETRECONVERTSTRING so that IME generates a new composition string. After this, lpComp and lpRead will point to a RECONVERTSTRING structure that contains the updated composition and reading string. lpRead can be used only when the selected IME has SCS_CAP_MAKEREAD set. lpRead can be NULL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions, WM_IME_COMPOSITION, RECONVERTSTRING


ImmSetCompositionWindow

The ImmSetCompositionWindow function sets the position of the composition window.

BOOL ImmSetCompositionWindow(
  HIMC hIMC,
  LPCOMPOSITIONFORM lpCompForm
);

Parameters

hIMC
[in] Handle to the input context.
lpCompForm
[in] Pointer to a COMPOSITIONFORM structure that contains the new position and other related information about the composition window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

The ImmSetCompositionWindow function causes an IMN_SETCOMPOSITIONWINDOW command to be sent to the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, COMPOSITIONFORM, IMN_SETCOMPOSITIONWINDOW


ImmSetConversionStatus

The ImmSetConversionStatus function sets the current conversion status.

BOOL ImmSetConversionStatus(
  HIMC hIMC,
  DWORD fdwConversion,
  DWORD fdwSentence
);

Parameters

hIMC
[in] Handle to the input context.
fdwConversion
[in] Specifies the conversion-mode values. For more information, see IME Conversion Mode Values.
fdwSentence
[in] Specifies the sentence-mode values. For more information, see IME Sentence Mode Values.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

This function sends the IMN_SETCONVERSIONMODE and IMN_SETSENTENCEMODE commands to the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, IMN_SETCONVERSIONMODE, IMN_SETSENTENCEMODE


ImmSetOpenStatus

The ImmSetOpenStatus function opens or closes the IME.

BOOL ImmSetOpenStatus(
  HIMC hIMC,
  BOOL fOpen
);

Parameters

hIMC
[in] Handle to the input context.
fOpen
[in] Specifies the open state. If TRUE, the IME is opened; otherwise, it is closed.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

This function causes a IMN_SETOPENSTATUS command to be sent to the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, IMN_SETOPENSTATUS


ImmSetStatusWindowPos

The ImmSetStatusWindowPos function sets the position of the status window.

BOOL ImmSetStatusWindowPos(
  HIMC hIMC,
  LPPOINT lpptPos
);

Parameters

hIMC
[in] Handle to the input context.
lpptPos
[in] Pointer to a POINT structure that specifies the new position of the status window in screen coordinates, relative to the upper-left corner of the display screen.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

This function causes a IMN_SETSTATUSWINDOWPOS command to be sent to the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions, IMN_SETSTATUSWINDOWPOS, POINT


ImmSimulateHotKey

The ImmSimulateHotKey function simulates the specified IME hot key, causing the same response as if the user had pressed the hot key in the specified window.

BOOL ImmSimulateHotKey(
  HWND hWnd,
  DWORD dwHotKeyID
);

Parameters

hWnd
[in] Handle to the window.
dwHotKeyID
[in] Specifies the identifier of the IME hot key. For more information, see IME Hot Key Identifiers.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.

See Also

Input Method Editor Overview, Input Method Editor Functions


ImmUnregisterWord

The ImmUnregisterWord function removes a register string from the dictionary of the IME associated with the specified input locale.

BOOL ImmUnregisterWord(
  HKL hKL,
  LPCTSTR lpszReading,
  DWORD dwStyle,
  LPCTSTR lpszUnregister
);

Parameters

hKL
[in] Input locale identifier.
lpszReading
[in] Pointer to a null-terminated string specifying the reading string associated with the string to remove.
dwStyle
[in] Specifies the style of the register string. This parameter can be any of the following.
Value | Meaning
IME_REGWORD_STYLE_EUDC | The string is in the EUDC range.
any value from IME_REGWORD_STYLE_USER_FIRST to IME_REGWORD_STYLE_USER_LAST | The string is in a private style maintained by the specified IME.

lpszUnregister
[in] Pointer to a null-terminated string specifying the register string to remove.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Library: Use Imm32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000 and Windows 98.

See Also

Input Method Editor Overview, Input Method Editor Functions


Input Method Editor Messages

This section describes the input method editor messages.

WM_IME_CHAR
WM_IME_COMPOSITION
WM_IME_COMPOSITIONFULL
WM_IME_CONTROL
WM_IME_ENDCOMPOSITION
WM_IME_KEYDOWN
WM_IME_KEYUP
WM_IME_NOTIFY
WM_IME_REQUEST
WM_IME_SELECT
WM_IME_SETCONTEXT
WM_IME_STARTCOMPOSITION


WM_IME_CHAR

The WM_IME_CHAR message is sent to an application when the IME gets a character of the conversion result. Unlike the WM_CHAR message for a non-Unicode window, this message can include double-byte as well as single-byte character values. For a Unicode window, this message is the same as WM_CHAR.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_CHAR,     // message
  WPARAM wParam,   // character code
  LPARAM lParam    // key indicators
);

Parameters

wParam
DBCS: Specifies a single- or double-byte character value. For a double-byte character, (BYTE)(wParam >> 8) contains the lead byte. Note that the parentheses are necessary because the cast operator has higher precedence than the shift operator.

Unicode: Specifies a Unicode character value.

lParam
Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown following.
Bit | Meaning
0-15 | Repeat count: Since the first byte and second byte is continuous, this is always 1.
16-23 | Scan code: Scan code for a complete Asian character.
24 | Extended key
25-28 | Not used.
29 | Context code.
30 | Previous key state.
31 | Transition state.

Remarks

For a non-Unicode window, if the WM_IME_CHAR message includes a double-byte character and the application passes this message to DefWindowProc, the IME converts this message into two WM_CHAR messages, each containing one byte of the double-byte character.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, DefWindowProc, WM_CHAR


WM_IME_COMPOSITION

The WM_IME_COMPOSITION message is sent to an application when the IME changes composition status as a result of a keystroke. An application should process this message if it displays composition characters itself. Otherwise, it should send the message to the IME window.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_COMPOSITION,   // message
  WPARAM wParam,   // DBCS character
  LPARAM lParam    // change indicator
);

Parameters

wParam
DBCS character representing the latest change to the composition string.
lParam
Specifies how the composition string or character changed. This parameter can be one or more of the following values:

GCS_COMPATTR
GCS_COMPCLAUSE
GCS_COMPREADSTR
GCS_COMPREADATTR
GCS_COMPREADCLAUSE
GCS_COMPSTR
GCS_CURSORPOS
GCS_DELTASTART
GCS_RESULTCLAUSE
GCS_RESULTREADCLAUSE
GCS_RESULTREADSTR
GCS_RESULTSTR

For more information about these values, see IME Composition String Values.

The lParam parameter can also be one or more of the following values.
Value | Meaning
CS_INSERTCHAR | The wParam composition character should be inserted at the current insertion point. An application should display the composition character if it processes this message.
CS_NOMOVECARET | The application must not move the caret position as a result of processing the message. For example, if an IME specifies a combination of CS_INSERTCHAR and CS_NOMOVECARET, the application should insert the specified character at the current caret position but should not move caret to the next position. A subsequent WM_IME_COMPOSITION message with GCS_RESULTSTR will replace this character.

Return Values

This message has no return value.

Remarks

If the application has created an IME window, it should pass this message to that window. The DefWindowProc function processes this message by passing it to the default IME window. The IME window processes this message by updating its appearance based on the change flag specified. An application can call ImmGetCompositionString to retrieve the new composition status.

If none of the GCS_ values are set, the message indicates that the current composition has been canceled and applications that draw the composition string should delete the string.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, DefWindowProc, ImmGetCompositionString


WM_IME_COMPOSITIONFULL

The WM_IME_COMPOSITIONFULL message is sent to an application when the IME window finds no space to extend the area for the composition window. The application should use the IMC_SETCOMPOSITIONWINDOW command to specify how the window should be displayed.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_COMPOSITIONFULL,   // message
  WPARAM wParam,   // not used
  LPARAM lParam    // not used
);

Parameters

This message has no parameters.

Return Values

This message has no return value.

Remarks

The IME window, not the IME, sends this notification message by the SendMessage function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, IMC_SETCOMPOSITIONWINDOW, SendMessage


WM_IME_CONTROL

The WM_IME_CONTROL message directs the IME window to carry out the requested command. An application uses this message to control the IME window created by the application.

To send this message, call the SendMessage function with the following parameters.

SendMessage(
  HWND hWnd,              // handle to destination window
  WM_IME_CONTROL,         // message to send
  WPARAM wParam,          // IME command
  LPARAM lParam           // command-specific data
);

Parameters

wParam
Specifies the command. This parameter can be one of the following values:

IMC_CLOSESTATUSWINDOW
IMC_GETCANDIDATEPOS
IMC_GETCOMPOSITIONFONT
IMC_GETCOMPOSITIONWINDOW
IMC_GETSTATUSWINDOWPOS
IMC_OPENSTATUSWINDOW
IMC_SETCANDIDATEPOS
IMC_SETCOMPOSITIONFONT
IMC_SETCOMPOSITIONWINDOW
IMC_SETSTATUSWINDOWPOS

lParam
Specifies command-specific data. Its format depends on the value of the wParam parameter. For more information, refer to the documentation for each command.

Return Values

The message returns a command-specific value.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, IMC_CLOSESTATUSWINDOW, IMC_GETCANDIDATEPOS, IMC_GETCOMPOSITIONFONT, IMC_GETCOMPOSITIONWINDOW, IMC_GETSTATUSWINDOWPOS, IMC_OPENSTATUSWINDOW, IMC_SETCANDIDATEPOS, IMC_SETCOMPOSITIONFONT, IMC_SETCOMPOSITIONWINDOW, IMC_SETSTATUSWINDOWPOS


WM_IME_ENDCOMPOSITION

The WM_IME_ENDCOMPOSITION message is sent to an application when the IME ends composition. An application should process this message if it displays composition characters itself.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_ENDCOMPOSITION,    // message to send
  WPARAM wParam,   // not used
  LPARAM lParam    // not used
);

Parameters

This message has no parameters.

Return Values

This message has no return value.

Remarks

If an application has created an IME window, it should pass this message to that window. The DefWindowProc function processes this message by passing it to default IME window.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, DefWindowProc


WM_IME_KEYDOWN

The WM_IME_KEYDOWN message is sent to an application by the IME to notify the application of a key press. An application can process this message or pass it to the DefWindowProc function to generate a matching WM_KEYDOWN message. This message is usually generated by the IME to keep message order.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_KEYDOWN,   // message to send
  WPARAM wParam,   // virtual-key code
  LPARAM lParam    // key data
);

Parameters

wParam
Specifies the virtual-key code of the key.
lParam
Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Bit | Meaning
0-15 | Repeat count.
16-23 | Scan code.
24 | Extended key. This value is 1 if it is an extended key; otherwise, it is zero.
25-28 | Not used.
29 | Context code. This value is always zero.
30 | Previous key state. This value is 1 is the key is down or zero is it is up.
31 | Transition state. This value is always zero.

Return Values

An application should return zero if it processes this message.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, DefWindowProc, WM_KEYDOWN


WM_IME_KEYUP

The WM_IME_KEYUP message is sent to an application by the IME to notify the application of a key release. An application can process this message or pass it to the DefWindowProc function to generate a matching WM_KEYUP message. This message is usually generated by the IME to keep message order.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_KEYUP,    // message to send
  WPARAM wParam,   // virtual-key code
  LPARAM lParam    // key data
);

Parameters

wParam
Specifies the virtual-key code of the key.
lParam
Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown following.

Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following.
Bit | Meaning
0-15 | Repeat count. This value is always 1.
16-23 | Scan code.
24 | Extended key. This value is 1 if it is an extended key; otherwise, it is zero.
25-28 | Not used.
29 | Context code. This value is always zero.
30 | Previous key state. This value is always 1.
31 | Transition state. This value is always 1.

Return Values

An application should return zero if it processes this message.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, DefWindowProc, WM_KEYUP


WM_IME_NOTIFY

The WM_IME_NOTIFY message is sent to an application to notify it of changes to the IME window. An application processes this message if it is responsible for managing the IME window.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_NOTIFY,   // message to send
  WPARAM wParam,   // notification command
  LPARAM lParam    // command-specific data
);

Parameters

wParam
Specifies the command. This parameter can be one of the following values:

IMN_CHANGECANDIDATE
IMN_CLOSECANDIDATE
IMN_CLOSESTATUSWINDOW
IMN_GUIDELINE
IMN_OPENCANDIDATE
IMN_OPENSTATUSWINDOW
IMN_SETCANDIDATEPOS
IMN_SETCOMPOSITIONFONT
IMN_SETCOMPOSITIONWINDOW
IMN_SETCONVERSIONMODE
IMN_SETOPENSTATUS
IMN_SETSENTENCEMODE
IMN_SETSTATUSWINDOWPOS

lParam
Specifies command-specific data. Its format depends on the value of the wParam parameter. For more information, refer to the documentation for each command.

Return Values

The return value depends on the command sent.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, IMN_CHANGECANDIDATE, IMN_CLOSECANDIDATE, IMN_CLOSESTATUSWINDOW, IMN_GUIDELINE, IMN_OPENCANDIDATE, IMN_OPENSTATUSWINDOW, IMN_SETCANDIDATEPOS, IMN_SETCOMPOSITIONFONT, IMN_SETCOMPOSITIONWINDOW, IMN_SETCONVERSIONMODE, IMN_SETOPENSTATUS, IMN_SETSENTENCEMODE, IMN_SETSTATUSWINDOWPOS


WM_IME_REQUEST

The WM_IME_REQUEST message provides a group of commands to request information from an application.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_REQUEST,  // message to send
  WPARAM wParam,   // request command
  LPARAM lParam    // command-specific data
);

Parameters

wParam
Request command. This parameter can be one of the following values.

IMR_CANDIDATEWINDOW
IMR_COMPOSITIONFONT
IMR_COMPOSITIONWINDOW
IMR_CONFIRMRECONVERTSTRING
IMR_DOCUMENTFEED
IMR_QUERYCHARPOSITION
IMR_RECONVERTSTRING

lParam
Request-specific data. For more information, see the description for each command.

Return Values

Returns a request-specific value. For more information, see the description for each command.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, IMR_CANDIDATEWINDOW, IMR_COMPOSITIONFONT, IMR_COMPOSITIONWINDOW, IMR_CONFIRMRECONVERTSTRING, IMR_DOCUMENTFEED, IMR_QUERYCHARPOSITION, IMR_RECONVERTSTRING


WM_IME_SELECT

The WM_IME_SELECT message is sent to an application when the system is about to change the current IME. An application that has created an IME window should pass this message to that window so that it can retrieve the keyboard layout handle for the newly selected IME.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_SELECT,   // message to send
  WPARAM wParam,   // selection indicator
  LPARAM lParam    // input locale identifier (HANDLE)
);

Parameters

wParam
Selection indicator. If TRUE, the specified IME is selected; if FALSE, the specified IME is no longer selected.
lParam
Input locale identifier associated with the IME.

Return Values

This message has no return value.

Remarks

The DefWindowProc function processes this message by passing the information to the default IME window.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, DefWindowProc


WM_IME_SETCONTEXT

The WM_IME_SETCONTEXT message is sent to an application when a window of the application is activated. If the application has created an IME window, it should call the ImmIsUIMessage function. Otherwise, it should pass this message to the DefWindowProc function.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_SETCONTEXT,  // message to send
  WPARAM wParam,   // (BOOL) active status
  LPARAM lParam    // display options
);

Parameters

wParam
Indicates if the window is active. If this parameter is TRUE, the input context is active. Otherwise, the context is inactive.
lParam
Specifies the display options. This parameter can be one or more of the following values.
Value | Description
ISC_SHOWUICOMPOSITIONWINDOW | Shows the composition window by UI window.
ISC_SHOWUIGUIDWINDOW | Shows the guide window by UI window.
ISC_SHOWUISOFTKBD | Shows the soft keyboard by UI window.
ISC_SHOWUICANDIDATEWINDOW | Shows the candidate window of Index 0 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 1 | Shows the candidate window of Index 1 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 2 | Shows the candidate window of Index 2 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 3 | Shows the candidate window of Index 3 by UI window.

Return Values

Returns the value returned by DefWindowProc or ImmIsUIMessage.

Remarks

If the application draws the composition window, the default IME window does not need to show its composition window. In this case, the application must clear the ISC_SHOWUICOMPOSITIONWINDOW value from the lParam parameter before passing the message to the DefWindowProc or ImmIsUIMessage functions. Likewise, if an application wants to display a certain UI window, it should remove the corresponding value so IME will not display it.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, DefWindowProc, ImmIsUIMessage


WM_IME_STARTCOMPOSITION

The WM_IME_STARTCOMPOSITION message is sent immediately before the IME generates the composition string as a result of a keystroke. The message is a notification to an IME window to open its composition window. An application should process this message if it displays composition characters itself.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  WM_IME_STARTCOMPOSITION,  // message to send
  WPARAM wParam,   // not used
  LPARAM lParam    // not used
);

Parameters

This message has no parameters.

Return Values

This message has no return value.

Remarks

If an application has created an IME window, it should pass the WM_IME_STARTCOMPOSITION message to that window. The DefWindowProc function processes this message by passing it to the default IME window.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Messages, DefWindowProc


Input Method Editor Commands

This section describes the input method editor commands.

IMC_CLOSESTATUSWINDOW
IMC_GETCANDIDATEPOS
IMC_GETCOMPOSITIONFONT
IMC_GETCOMPOSITIONWINDOW
IMC_GETSTATUSWINDOWPOS
IMC_OPENSTATUSWINDOW
IMC_SETCANDIDATEPOS
IMC_SETCOMPOSITIONFONT
IMC_SETCOMPOSITIONWINDOW
IMC_SETSTATUSWINDOWPOS
IMN_CHANGECANDIDATE
IMN_CLOSECANDIDATE
IMN_CLOSESTATUSWINDOW
IMN_GUIDELINE
IMN_OPENCANDIDATE
IMN_OPENSTATUSWINDOW
IMN_SETCANDIDATEPOS
IMN_SETCOMPOSITIONFONT
IMN_SETCOMPOSITIONWINDOW
IMN_SETCONVERSIONMODE
IMN_SETOPENSTATUS
IMN_SETSENTENCEMODE
IMN_SETSTATUSWINDOWPOS
IMR_CANDIDATEWINDOW
IMR_COMPOSITIONFONT
IMR_COMPOSITIONWINDOW
IMR_CONFIRMRECONVERTSTRING
IMR_DOCUMENTFEED
IMR_QUERYCHARPOSITION
IMR_RECONVERTSTRING


IMC_CLOSESTATUSWINDOW

An application sends the IMC_CLOSESTATUSWINDOW command to the IME window to hide the status window.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_CLOSESTATUSWINDOW.
lParam
This parameter is not used.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

When the status window of IME is already hidden, this command does nothing. Although an application may send this command to the IME window, the application does not receive the corresponding IMN_CLOSESTATUSWINDOW command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands


IMC_GETCANDIDATEPOS

An application sends the IMC_GETCANDIDATEPOS command to an IME window to get the position of the candidate window. Because the IME may adjust the position of a candidate window, an application uses this command to get the actual position to decide whether to reposition the window.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_GETCANDIDATEPOS.
lParam
Pointer to the CANDIDATEFORM structure that receives the position of the candidate window.

Return Values

If the function succeeds, it returns zero. On failure it returns a nonzero value.

Remarks

The returned position is in window coordinates relative to the window having the current input focus.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, CANDIDATEFORM


IMC_GETCOMPOSITIONFONT

An application sends the IMC_GETCOMPOSITIONFONT command to an IME window to retrieve the logical font used for displaying intermediate characters in the composition window.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_GETCOMPOSITIONFONT.
lParam
Pointer to a LOGFONT structure that receives information about the logical font.

Return Values

Returns zero if successful, nonzero otherwise.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, LOGFONT


IMC_GETCOMPOSITIONWINDOW

An application sends the IMC_GETCOMPOSITIONWINDOW command to an IME window to get the position of the composition window. Because the IME may adjust the position of a composition window, an application uses this command to get the actual position to decide whether to reposition the window.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_GETCOMPOSITIONWINDOW.
lParam
Pointer to the COMPOSITIONFORM structure that receives the position of the composition window.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

The returned position is in window coordinates relative to the window having the current input focus.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, COMPOSITIONFORM


IMC_GETSTATUSWINDOWPOS

An application sends the IMC_GETSTATUSWINDOWPOS command to an IME window to get the position of the status window.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_GETSTATUSWINDOWPOS.
lParam
This parameter is not used.

Return Values

Returns a POINTS structure that contains the x- and y-coordinates of the status window position in screen coordinates, relative to the upper-left corner of the display screen.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, POINTS, WM_IME_CONTROL


IMC_OPENSTATUSWINDOW

An application sends the IMC_OPENSTATUSWINDOW command to the IME window to show the status window. This command is ignored if the system is not in the show IME status mode. The user can set or clear the show IME status mode from the task bar.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_OPENSTATUSWINDOW.
lParam
This parameter is not used.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

If the status window is already shown, this command does nothing. Although the application may send this command to the IME window, the application does not receive the corresponding IMN_OPENSTATUSWINDOW command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_CONTROL


IMC_SETCANDIDATEPOS

An application sends the IMC_SETCANDIDATEPOS command to an IME window to set the position of the candidate window. This command is intended for applications that display composition characters on their own but use the IME window to display candidates.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_SETCANDIDATEPOS.
lParam
Pointer to a CANDIDATEFORM structure that contains the x- and y-coordinates for the candidate window. The application should set the dwIndex member of this structure.

Return Values

Return zero if successful, nonzero otherwise.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, CANDIDATEFORM, WM_IME_CONTROL


IMC_SETCOMPOSITIONFONT

An application sends the IMC_SETCOMPOSITIONFONT command to an IME window to specify the logical font to use for displaying intermediate characters in the composition window.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_SETCOMPOSITIONFONT.
lParam
Pointer to a LOGFONT structure that contains information about the logical font.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

When processing this command, the IME window changes the current selected font in the input context.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, LOGFONT, WM_IME_CONTROL


IMC_SETCOMPOSITIONWINDOW

An application sends the IMC_SETCOMPOSITIONWINDOW command to an IME window to set the style of the composition window. The command sets this style in the current input context and the style is subsequently applied to each IME window that receives that input context.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_SETCOMPOSITIONWINDOW.
lParam
Pointer to a COMPOSITIONFORM structure that contains the style information.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

By default, the IME window has the CFS_POINT style. This means the IME window uses the current caret position and window client area when it opens any composition window.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, COMPOSITIONFORM, WM_IME_CONTROL


IMC_SETSTATUSWINDOWPOS

An application sends the IMC_SETSTATUSWINDOWPOS command to an IME window to set the position of the status window.

To send this command, use the WM_IME_CONTROL message with wParam and lParam set as follows.

Parameters

wParam
Set to IMC_SETSTATUSWINDOWPOS.
lParam
Pointer to a POINTS structure that contains the x- and y-coordinates of the position of the status window. The coordinates are in screen coordinates, relative to the upper-left corner of the display screen.

Return Values

Returns zero if successful, nonzero otherwise.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, POINTS, WM_IME_CONTROL


IMN_CHANGECANDIDATE

The IMN_CHANGECANDIDATE command is sent to the application when an IME is about to change the content of the candidate window. An application should process this command if it displays candidates itself.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_CHANGECANDIDATE.
lParam
Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be changed.

Return Values

This command has no return value.

Remarks

The IME window changes the appearance of the candidate window when it processes this command. An application can get information about the system window with the ImmGetCandidateListCount and ImmGetCandidateList functions.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, ImmGetCandidateList, ImmGetCandidateListCount, WM_IME_NOTIFY


IMN_CLOSECANDIDATE

The IMN_CLOSECANDIDATE command is sent to the application when an IME is about to close the candidate window. An application should process this command if it displays candidates itself.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_CLOSECANDIDATE.
lParam
Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be closed.

Return Values

This command has no return value.

Remarks

By default, the IME window destroys a candidate window when it processes this command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_NOTIFY


IMN_CLOSESTATUSWINDOW

The IMN_CLOSESTATUSWINDOW command is sent to the application when an IME is about to close the status window. An application should process this command if it displays the status window for the IME.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_CLOSESTATUSWINDOW.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The IME window closes the status window when it processes this command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_NOTIFY


IMN_GUIDELINE

The IMN_GUIDELINE command is sent when an IME is about to show an error message or other information. An application processes this command by calling the ImmGetGuideLine function to retrieve the error message or information from the IME.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_GUIDELINE.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The IME window displays the error message or information string in an information window.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, ImmGetGuideLine, WM_IME_NOTIFY


IMN_OPENCANDIDATE

The IMN_OPENCANDIDATE command is sent to the application when an IME is about to open the candidate window. An application should process this command if it displays candidates itself. The application can retrieve a list of candidates to display by using the ImmGetCandidateList function.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_OPENCANDIDATE.
lParam
Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be opened.

Return Values

This command has no return value.

Remarks

By default, the IME window creates a candidate window when it processes this command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, ImmGetCandidateList, WM_IME_NOTIFY


IMN_OPENSTATUSWINDOW

The IMN_OPENSTATUSWINDOW command is sent when an IME is about to create the status window. An application processes this command to display the status window for the IME by itself.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_OPENSTATUSWINDOW.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The IME window creates a status window when it processes this command and sets the strings to display in the window into the input context. Applications can get information about the status window by using the ImmGetConversionStatus function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETCANDIDATEPOS

The IMN_SETCANDIDATEPOS command is sent when candidate processing has finished and the IME is about to move the candidate window. An application should process this command if it displays the candidate window itself.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_SETCANDIDATEPOS.
lParam
Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be moved.

Return Values

This command has no return value.

Remarks

The IME window moves the candidate window when it processes this command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_NOTIFY


IMN_SETCOMPOSITIONFONT

The IMN_SETCOMPOSITIONFONT command is sent when the font of the input context is updated.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_SETCOMPOSITIONFONT.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The application can get information about the font by using the ImmGetCompositionFont function. The IME window subsequently uses the font to draw the composition string.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, ImmGetCompositionFont, WM_IME_NOTIFY


IMN_SETCOMPOSITIONWINDOW

The IMN_SETCOMPOSITIONWINDOW command is sent when the style or position of the composition window is updated.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_SETCOMPOSITIONWINDOW.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The application can get information about the composition form by using the IMC_GETCOMPOSITIONWINDOW command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, IMC_GETCOMPOSITIONWINDOW, WM_IME_NOTIFY


IMN_SETCONVERSIONMODE

The IMN_SETCONVERSIONMODE command is sent when the conversion mode of the input context is updated.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_SETCONVERSIONMODE.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The application can get information about the conversion mode by using the ImmGetConversionStatus function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETOPENSTATUS

The IMN_SETOPENSTATUS command is sent when the open status of the input context is updated.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_SETOPENSTATUS.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The application can get information about the open status by using the ImmGetOpenStatus function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, ImmGetOpenStatus, WM_IME_NOTIFY


IMN_SETSENTENCEMODE

The IMN_SETSENTENCEMODE command is sent when the sentence mode of the input context is updated.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_SETSENTENCEMODE.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The application can get information about the sentence mode by using the ImmGetConversionStatus function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETSTATUSWINDOWPOS

The IMN_SETSTATUSWINDOWPOS command is sent when the status window position in the input context is updated.

The application receives this command through the WM_IME_NOTIFY message with wParam and lParam set as follows.

Parameters

wParam
Set to IMN_SETSTATUSWINDOWPOS.
lParam
This parameter is not used.

Return Values

This command has no return value.

Remarks

The application can get information about the status window position by using the IMC_GETSTATUSWINDOWPOS command.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, IMC_GETSTATUSWINDOWPOS, WM_IME_NOTIFY


IMR_CANDIDATEWINDOW

The IMR_CANDIDATEWINDOW command is sent when a selected IME needs information about the candidate window.

The application receives this command through the WM_IME_REQUEST message with wParam and lParam set as follows.

Parameters

wParam
Set to IMR_CANDIDATEWINDOW.
lParam
Pointer to a buffer containing a CANDIDATEFORM structure. Its dwIndex member contains the index to the candidate window referenced.

Return Values

Returns a nonzero value if the application filled in the CANDIDATEFORM structure in lParam. Otherwise, returns zero.

Remarks

This notification may be sent by the IME to a window that cleared the ISC_SHOWUICANDIDATEWINDOW flag in the WM_IME_SETCONTEXT message handler.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_REQUEST, CANDIDATEFORM


IMR_COMPOSITIONFONT

The IMR_COMPOSITIONFONT command is sent when a selected IME needs information about the font used by the composition window.

The application receives this command through the WM_IME_REQUEST message with wParam and lParam set as follows.

Parameters

wParam
Set to IMR_COMPOSITIONFONT.
lParam
Pointer to a buffer containing a LOGFONT structure. The application fills in the values for the current composition window.

Return Values

Returns a nonzero value if the application filled in the LOGFONT structure specified by lParam. Otherwise, returns zero.

Remarks

This notification may be sent by the IME to a window that cleared the ISC_SHOWUICOMPOSITIONWINDOW flag in the WM_IME_SETCONTEXT message handler.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_REQUEST, WM_IME_SETCONTEXT, LOGFONT


IMR_COMPOSITIONWINDOW

The IMR_COMPOSITIONWINDOW command is sent when a selected IME needs information about the composition window.

The application receives this command through the WM_IME_REQUEST message with wParam and lParam set as follows.

Parameters

wParam
Set to IMR_COMPOSITIONWINDOW.
lParam
Pointer to a buffer containing a COMPOSITIONFORM structure.

Return Values

Returns a nonzero value if the application filled in the COMPOSITIONFORM structure in lParam. Otherwise, returns zero.

Remarks

This notification may be sent by the IME to a window that cleared the ISC_SHOWUICOMPOSITIONWINDOW flag in the WM_IME_SETCONTEXT message handler.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_REQUEST, COMPOSITIONFORM


IMR_CONFIRMRECONVERTSTRING

The IMR_CONFIRMRECONVERTSTRING command is sent when the IME needs to change the RECONVERTSTRING structure (previously filled in by the application upon receiving the IMR_RECONVERTSTRING command).

The application receives this command through the WM_IME_REQUEST message with wParam and lParam set as follows.

Parameters

wParam
Set to IMR_CONFIRMRECONVERTSTRING.
lParam
Pointer to a RECONVERTSTRING structure from the IME. For more information, see the Remarks.

Return Values

Returns a nonzero value if the application accepts the changed RECONVERTSTRING structure. Otherwise, returns zero and the IME will use the original RECONVERTSTRING.

Remarks

After the application has handled IMR_RECONVERTSTRING, the IME may or may not adjust the RECONVERTSTRING structure that is specified by the application. The IME sends WM_IME_REQUEST with IMR_CONFIRMRECONVERTSTRING to confirm the changes to the RECONVERTSTRING. If the application returns TRUE for IMR_CONFIRMRECONVERTSTRING, the IME will generate a new composition string based on the RECONVERTSTRING structure in the IMR_CONFIRMRECONVERTSTRING command. If the application returns FALSE for IMR_CONFIRMRECONVERTSTRING, the IME will generate a new composition string based on the original RECONVERTSTRING structure that was specified by the application in the IMR_RECONVERTSTRING command.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, IMR_RECONVERTSTRING, RECONVERTSTRING, WM_IME_REQUEST


IMR_DOCUMENTFEED

The IMR_DOCUMENTFEED command is sent when the selected IME needs the converted string from the application.

The application receives this command through the WM_IME_REQUEST message with wParam and lParam set as follows.

Parameters

wParam
Set to IMR_DOCUMENTFEED.
lParam
Pointer to a buffer to contain the reconversion string structure.

Return Values

If lParam is NULL, the application must return the required size of the RECONVERTSTRING. If the application filled the RECONVERTSTRING structure in lParam, return the required size of the RECONVERTSTRING structure. Otherwise return zero.

Remarks

The IME caches converted strings for higher conversion accuracy. There are, however, some limitations to caching converted strings because the IME loses the corrected converted string under the following circumstances:

  • When the application's caret position is moved by a key such as the cursor keys.
  • When the application's caret position is moved by the mouse.
  • When a new document is opened.

With the IMR_DOCUMENTFEED command, the IME can refresh its cached strings any time. This improves conversion accuracy.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_REQUEST, RECONVERTSTRING


IMR_QUERYCHARPOSITION

The IMR_QUERYCHARPOSITION command is sent when the selected IME needs information about the coordinates of a character in the composition string.

The application receives this command through the WM_IME_REQUEST message with wParam and lParam set as follows.

Parameters

wParam
Set to IMR_QUERYCHARPOSITION.
lParam
Pointer to an IMECHARPOSITION structure that contains the position of the character in the composition window.

Return Values

If the application filled the IMECHARPOSITION structure in lParam, return non-zero. Otherwise, return zero.

Remarks

Applications that draw the composition string themselves, rather than relying on the IME, are responsible for filling all the fields defined in the IMECHARPOSITION structure. Otherwise, this command should be passed on to DefWindowProc or ImmIsUIMessage if the application has its own IME UI window.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, WM_IME_REQUEST, DefWindowProc, ImmIsUIMessage, IMECHARPOSITION


IMR_RECONVERTSTRING

The IMR_RECONVERTSTRING command is sent when a selected IME needs a string for reconversion.

The application receives this command through the WM_IME_REQUEST message with wParam and lParam set as follows.

Parameters

wParam
Set to IMR_RECONVERTSTRING.
lParam
Pointer to a buffer containing the RECONVERTSTRING structure and strings.

Return Values

Returns the required size of the RECONVERTSTRING if the application filled the RECONVERTSTRING structure in lParam. Otherwise, returns zero. However, if lParam is NULL, the application must return the required size of the RECONVERTSTRING.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Commands, RECONVERTSTRING, WM_IME_REQUEST


Input Method Editor Structures

This section describes the structures used with input method editor functions and messages.

CANDIDATEFORM
CANDIDATELIST
COMPOSITIONFORM
IMECHARPOSITION
IMEMENUITEMINFO
RECONVERTSTRING
REGISTERWORD
STYLEBUF


CANDIDATEFORM

The CANDIDATEFORM structure contains position information for the candidate window.

typedef struct tagCANDIDATEFORM {
  DWORD  dwIndex;
  DWORD  dwStyle;
  POINT  ptCurrentPos;
  RECT   rcArea;
} CANDIDATEFORM, *PCANDIDATEFORM;

Members

dwIndex
Candidate list identifier. It is 0 for the first list, 1 for the second, and so on. The maximum index is 3.
dwStyle
Position style. This member can be one of the following values.
Value | Meaning
CFS_CANDIDATEPOS | Displays the upper-left corner of the candidate list window at the position specified by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the list window, and are subject to adjustment by the system.
CFS_EXCLUDE | Excludes the candidate window from the area specified by rcArea. The ptCurrentPos member specifies the coordinates of the current point of interest, typically the caret position.

ptCurrentPos
A POINT structure containing the coordinates of the upper-left corner of the candidate window or the caret position, depending on the value of dwStyle.
rcArea
A RECT structure containing the coordinates of the upper-left and lower-right corners of the exclusion area.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Structures, POINT, RECT


CANDIDATELIST

The CANDIDATELIST structure contains information about a candidate list.

typedef struct tagCANDIDATELIST {
  DWORD  dwSize;
  DWORD  dwStyle;
  DWORD  dwCount;
  DWORD  dwSelection;
  DWORD  dwPageStart;
  DWORD  dwPageSize;
  DWORD  dwOffset[1];
} CANDIDATELIST, *PCANDIDATELIST;

Members

dwSize
Size, in bytes, of the structure, the offset array, and all candidate strings.
dwStyle
Candidate style values. This member can be one or more of the following values.
Value | Meaning
IME_CAND_UNKNOWN | Candidates are in a style other than listed here.
IME_CAND_READ | Candidates are in same reading.
IME_CAND_CODE | Candidates are in a code range.
IME_CAND_MEANING | Candidates are in same meaning.
IME_CAND_RADICAL | Candidates use same radical character.
IME_CAND_STROKES | Candidates are in same number of strokes.

For the IME_CAND_CODE style, the candidate list has a special structure depending on the value of the dwCount member. If dwCount is 1, the dwOffset member contains a single DBCS character rather than an offset, and no candidate string is provided. If the dwCount member is greater than 1, the dwOffset member contains valid offsets, and the candidate strings are text representations of individual DBCS character values in hexadecimal notation.

dwCount
Number of candidate strings.
dwSelection
Index of the selected candidate string.
dwPageStart
Index of the first candidate string in the candidate window. This varies as the user presses the PAGE UP and PAGE DOWN keys.
dwPageSize
Number of candidate strings to be shown in one page in the candidate window. The user can move to the next page by pressing IME-defined keys, such as the PAGE UP or PAGE DOWN key. If this number is zero, an application can define a proper value by itself.
dwOffset
Offset to the start of the first candidate string, relative to the start of this structure. The offsets for subsequent strings immediately follow this member, forming an array of 32-bit offsets.

Remarks

The candidate strings immediately follow the last offset in the dwOffset array.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Structures


COMPOSITIONFORM

The COMPOSITIONFORM structure contains style and position information for a composition window.

typedef struct tagCOMPOSITIONFORM {
  DWORD  dwStyle;
  POINT  ptCurrentPos;
  RECT   rcArea;
} COMPOSITIONFORM, *PCOMPOSITIONFORM;

Members

dwStyle
Position style. This member can be one of the following values.
Value | Meaning
CFS_DEFAULT | Moves the composition window to the default position. The IME window can display the composition window outside the client area, such as in a floating window.
CFS_FORCE_POSITION | Displays the upper-left corner of the composition window at exactly the position specified by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the composition window and are not subject to adjustment by the IME.
CFS_POINT | Displays the upper-left corner of the composition window at the position specified by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the composition window and are subject to adjustment by the IME.
CFS_RECT | Displays the composition window at the position specified by rcArea. The coordinates are relative to the upper-left of the window containing the composition window.

ptCurrentPos
A POINT structure containing the coordinates of the upper-left corner of the composition window.
rcArea
A RECT structure containing the coordinates of the upper-left and lower-right corners of the composition window.

Remarks

Some IME windows adjust the composition window position specified by the system or the application. The CFS_FORCE_POSITION directs the IME window to skip this adjustment.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Structures, POINT, RECT


IMECHARPOSITION

The IMECHARPOSITION structure contains information about the character position in the composition window.

typedef struct tagIMECHARPOSITION {
  DWORD  dwSize;
  DWORD  dwCharPos;
  POINT  pt;
  UNIT   cLineHeight;
  RECT   rcDocument;
} IMECHARPOSITION, *PIMECHARPOSITION;

Members

dwSize
Size of the structure in bytes.
dwCharPos
Character offset in the composition string, in TCHARs.
pt
A POINT structure containing the coordinate of the top left (based upon character baseline in any text flow) point of requested character in screen coordinates.
cLineHeight
Height of a line which contains the requested character, in pixels.
rcDocument
A RECT structure containing the application's editable area for text, in screen coordinates

Remarks

When an application uses IME to draw the composition string, the members of this structure are automatically filled. Applications that draw the composition string themselves, rather than relying on the IME, are responsible for filling all the fields defined in the IMECHARPOSITION structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Structures, IMECHARPOSITION, IMR_QUERYCHARPOSITION, POINT, RECT


IMEMENUITEMINFO

The IMEMENUITEMINFO structure contains information about IME menu items.

typedef struct tagIMEMENUITEMINFO {
  UINT        cbSize;
  UINT        fType;
  UINT        fState;
  UINT        wID;
  HBITMAP     hbmpChecked;
  HBITMAP     hbmpUnchecked;
  DWORD       dwItemData;
  TCHAR       szString[IMEMENUITEM_STRING_SIZE];
  HBITMAP     hbmpItem;
} IMEMENUITEMINFO, *PIMEMENUITEMINFO

Members

cbSize
Size, in bytes, of the structure.
fType
Menu item type. This member can be one of the following values.
Value | Meaning
IMFT_RADIOCCHECK | Displays checked menu items using a radio-button mark instead of a check mark if the hbmpChecked member is NULL.
IMFT_SEPARATOR | Specifies that the menu item is a separator. A menu item separator appears as a horizontal dividing line. The hbmpItem and szString members are ignored in this case.
IMFT_SUBMENU | Specifies that the menu item is a submenu.

fState
Menu item state. This member can have one or more of the following values.
Value | Meaning
IMFS_CHECKED | The menu item is checked. For more information, see the description of the hbmpChecked member.
IMFS_DEFAULT | The menu item is the default. A menu can contain only one default menu item, which is displayed in bold.
IMFS_DISABLED | The menu item is disabled and appears dimmed so it cannot be selected. This is equivalent to IMFS_GRAYED.
IMFS_ENABLED | The menu item is enabled. This is the default state.
IMFS_GRAYED | The menu item is disabled and appears dimmed so it cannot be selected. This is equivalent to IMFS_DISABLED.
IMFS_HILITE | The menu item is highlighted.
IMFS_UNCHECKED | The menu item is unchecked. For more information about unchecked menu items, see the description of the hbmpUnchecked member.
IMFS_UNHILITE | The menu item is not highlighted. This is the default state.

wID
Application-defined 16-bit value that identifies the menu item.
hbmpChecked
Handle to the bitmap to display next to the item if it is checked. If this member is NULL, a default bitmap is used. If the IMFT_RADIOCHECK type value is specified, the default bitmap is a bullet. Otherwise, it is a check mark.
hbmpUnchecked
Handle to the bitmap to display next to the item if it is not checked. If this member is NULL, no bitmap is used.
dwItemData
Application-defined value associated with the menu item.
szString
Content of the menu item. This is a null-terminated string.
hbmpItem
Handle to a bitmap to display.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Input Method Editor Overview, Input Method Editor Structures, ImmGetImeMenuItems


RECONVERTSTRING

The RECONVERTSTRING structure defines the strings for IME reconversion. It is the first item in a memory block that contains the strings for reconversion.

typedef struct tagRECONVERTSTRING {
  DWORD dwSize;
  DWORD dwVersion;
  DWORD dwStrLen;
  DWORD dwStrOffset;
  DWORD dwCompStrLen;
  DWORD dwCompStrOffset;
  DWORD dwTargetStrLen;
  DWORD dwTargetStrOffset;
} RECONVERTSTRING, *PRECONVERTSTRING;

Members

dwSize
Specifies the size of this structure and the memory block it heads.
dwVersion
Specifies the version number. Must be zero.
dwStrLen
Specifies the length of the string that contains the composition string.
dwStrOffset
Specifies the offset from the start position of this structure.
dwCompStrLen
Specifies the length of the string that will be the composition string.
dwCompStrOffset
Specifies the offset of the string that will be the composition string.
dwTargetStrLen
Specifies the length of the string that is related to the target clause in the composition string.
dwTargetStrOffset
Specifies the offset of the target string.

Remarks

The dwCompStrOffset and dwTargetOffset parameters are the relative positions in dwStrOffset. For a Unicode IME, dwStrLen , dwCompStrLen, and dwTargetStrLen are TCHAR -- that is, character -- counts; and dwStrOffset, dwCompStrOffset, and dwTargetStrOffset are byte counts.

If an application starts the reconversion process—by calling ImmSetCompositionString with SCS_SETRECONVERTSTRING and SCS_QUERYRECONVERTSTRING—the application must allocate the necessary memory for the RECONVERTSTRING structure as well as the composition string buffer. IME should not use this memory later. If IME starts the process, IME should allocate necessary memory for the structure and the composition string buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Imm.h; include Windows.h.

See Also

Input Method Editor Overview, Input Method Editor Structures, ImmSetCompositionString, IMR_CONFIRMRECONVERTSTRING, IMR_RECONVERTSTRING


REGISTERWORD

The REGISTERWORD structure contains reading information or a word to register. You can pass this structure to the ImmConfigureIME function to have the information or word appear as an initial value in the configuration dialog box of the input method editor.

typedef struct tagREGISTERWORD {
  LPTSTR  lpReading;
  LPTSTR  lpWord;
} REGISTERWORD, *PREGISTERWORD;

Members

lpReading
Pointer to the reading information for the word to register. If the reading information is not needed, it can be NULL.
lpWord
Pointer to the word to register. If a word is not needed, it can be NULL.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Input Method Editor Overview, Input Method Editor Structures, ImmConfigureIME


STYLEBUF

The STYLEBUF structure contains the identifier and name of a style.

typedef struct _tagSTYLEBUF {
  DWORD  dwStyle;
  TCHAR  szDescription[STYLE_DESCRIPTION_SIZE];
} STYLEBUF, *PSTYLEBUF;

Members

dwStyle
Style of the register string. Can be IME_REGWORD_STYLE_EUDC to indicate a string in the EUDC range.
szDescription
Description of the style.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Imm.h; include Windows.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Input Method Editor Overview, Input Method Editor Structures


Input Method Editor Constants

The following constants are used by the input method editor functions and messages.

  • IME Conversion Mode Values
  • IME Composition String Values
  • IME Hot Key Identifiers
  • IME Sentence Mode Values
  • IME Escapes


IME Conversion Mode Values

These values are used with the ImmGetConversionStatus and ImmSetConversionStatus functions.

Bit | Meaning
IME_CMODE_CHARCODE | Set to 1 if character code input mode; 0 if not.
IME_CMODE_EUDC | Set to 1 if EUDC conversion mode; 0 if not.
IME_CMODE_FIXED | Windows 98 and Windows 2000 or later: Set to 1 if fixed conversion mode; 0 if not.
IME_CMODE_FULLSHAPE | Set to 1 if full shape mode; 0 if half shape mode.
IME_CMODE_HANJACONVERT | Set to 1 if HANJA convert mode; 0 if not.
IME_CMODE_KATAKANA | Set to 1 if KATAKANA mode; 0 if HIRAGANA mode.
IME_CMODE_NATIVE | Set to 1 if NATIVE mode; 0 if ALPHANUMERIC mode.
IME_CMODE_NOCONVERSION | Set to 1 to prevent processing of conversions by IME; 0 if not.
IME_CMODE_ROMAN | Set to 1 if ROMAN input mode; 0 if not.
IME_CMODE_SOFTKBD | Set to 1 if Soft Keyboard mode; 0 if not.
IME_CMODE_SYMBOL | Set to 1 if SYMBOL conversion mode; 0 if not.

All other bits are reserved.


IME Composition String Values

These values are used with ImmGetCompositionString and WM_IME_COMPOSITION.

Value | Description
GCS_COMPATTR | Retrieves or updates the attribute of the composition string.
GCS_COMPCLAUSE | Retrieves or updates clause information of the composition string.
GCS_COMPREADATTR | Retrieves or updates the attributes of the reading string of the current composition.
GCS_COMPREADCLAUSE | Retrieves or updates the clause information of the reading string of the composition string.
GCS_COMPREADSTR | Retrieves or updates the reading string of the current composition.
GCS_COMPSTR | Retrieves or updates the current composition string.
GCS_CURSORPOS | Retrieves or updates the cursor position in composition string.
GCS_DELTASTART | Retrieves or updates the starting position of any changes in composition string.
GCS_RESULTCLAUSE | Retrieves or updates clause information of the result string.
GCS_RESULTREADCLAUSE | Retrieves or updates clause information of the reading string.
GCS_RESULTREADSTR | Retrieves or updates the reading string.
GCS_RESULTSTR | Retrieves or updates the string of the composition result.


IME Hot Key Identifiers

These identifiers are used with the ImmSimulateHotKey function.

Identifiers | Meaning
IME_CHOTKEY_IME_NONIME_TOGGLE | (Simplified Chinese) Toggles between IME and non-IME operation.
IME_CHOTKEY_SHAPE_TOGGLE | (Simplified Chinese) Toggles the shape conversion mode of IME.
IME_CHOTKEY_SYMBOL_TOGGLE | (Simplified Chinese) Toggles the symbol conversion mode of IME. Symbol mode indicates that the user can input Chinese punctuation and symbols by mapping to the punctuation and symbols on the keyboard.
IME_ITHOTKEY_RECONVERTSTRING | Windows 98/Me, Windows 2000 or later: (Traditional Chinese) Triggers reconversion.
IME_JHOTKEY_CLOSE_OPEN | (Japanese) Alternately opens and closes the IME.
IME_KHOTKEY_ENGLISH | (Korean) Switches to English.
IME_KHOTKEY_SHAPE_TOGGLE | (Korean) Toggles the shape conversion mode of IME.
IME_KHOTKEY_HANJACONVERT | (Korean) Switches to Hanja converision.
IME_THOTKEY_IME_NONIME_TOGGLE | (Traditional Chinese) Toggles between IME and non-IME operation.
IME_THOTKEY_SHAPE_TOGGLE | (Traditional Chinese) Toggles the shape conversion mode of IME.
IME_THOTKEY_SYMBOL_TOGGLE | (Traditional Chinese) Toggles the symbol conversion mode of IME.


IME Sentence Mode Values

These values are used with the ImmGetConversionStatus and ImmSetConversionStatus functions.

Constant | Definition
IME_SMODE_AUTOMATIC | The IME carries out conversion processing in automatic mode.
IME_SMODE_NONE | No information for sentence.
IME_SMODE_PHRASEPREDICT | The IME uses phrase information to predict the next character.
IME_SMODE_PLURALCLAUSE | The IME uses plural clause information to carry out conversion processing.
IME_SMODE_SINGLECONVERT | The IME carries out conversion processing in single-character mode.
IME_SMODE_CONVERSATION | The IME uses conversation mode. This is useful for chat applications.

Bits 16 through 31 are reserved for IME use.


IME Escapes

These escapes are used with the ImmEscape function.

Escape | Description
IME_ESC_GET_EUDC_DICTIONARY | Retrieves the path of the EUDC dictionary file. On input, the lpData parameter must be the pointer to the buffer to receive the path. This buffer must be equal to or greater than 80 * sizeof(TCHAR). On return, the buffer contains the null-terminated string specifying the full path of the dictionary. For use by the Chinese EUDC editor only; do not use in other applications.
IME_ESC_HANJA_MODE | Converts from Hangeul to Hanja. On input, lpData must point to the buffer that contains the Hangeul character to convert; on output, it receives the converted Hanja as a null-terminated string. For use by the Korean editor; do not use in other applications.
IME_ESC_IME_NAME | Retrieves the name of the IME. On input, the lpData parameter must be the pointer to the buffer to receive the name. On return, the buffer contains the null-terminated string specifying the IME name. For use by the Chinese EUDC editor only; do not use in other applications. Windows 95/98/Me: the buffer must be no less than 16*sizeof(TCHAR). Windows NT/2000 or later: the buffer must be no less than 64 characters.
IME_ESC_MAX_KEY | Return value of the function is the maximum number of key stokes for an EUDC character. For use by the Chinese EUDC editor only; do not use in other applications.
IME_ESC_QUERY_SUPPORT | Checks for implementation. On input, lpData points to the buffer that contains the IME Escape value. The function returns zero if the escape is not implemented.
IME_ESC_SEQUENCE_TO_INTERNAL | Returns the character code that matches the specified sequence code. On input, the lpData parameter is the pointer to a 32-bit variable that contains the sequence code. For use by the Chinese EUDC editor only; do not use in other applications. Normally, the Chinese IME will encode its reading character codes into sequence 1 to n.
IME_ESC_SET_EUDC_DICTIONARY | Sets the EUDC dictionary file. On input, the lpData parameter is the pointer to a null-terminated string specifying the full path. The path should be less than 80 * sizeof(TCHAR). For use by the Chinese EUDC editor only; do not use in other applications.
IME_ESC_GETHELPFILENAME | Windows 98, Windows 2000 and later: Returns the name of the IME's help file. On return the lpData parameter is the full path of the IME's help file. The path should be less than 80 * sizeof(TCHAR).

The system reserves the escapes in the range IME_ESC_RESERVED_FIRST to IME_ESC_RESERVED_LAST for its own use.

The system reserves the escapes in the range IME_ESC_PRIVATE_FIRST to IME_ESC_PRIVATE_LAST for private use by IMEs.


National Language Support

National language support functions help Win32®-based applications support the different language- and location-specific needs of users around the world. This overview describes the national language support functions and explains how to use them in Win32-based applications.

  • About National Language Support
  • National Language Support Reference


About National Language Support

The national language support functions let applications:

  • Set the locale for the user
  • Identify the language in which the user works
  • Retrieve strings—representing times, dates, and other information—formatted correctly for the specified language and location

National language support also includes support for keyboard layouts and language-specific fonts. For more information about these topics, see Keyboard Input and Fonts and Text.

The following topics are covered in this section:

  • Locales
  • Locale and Language Information
  • Time and Date
  • Date and Calendar
  • Localization and the Shell Font
  • Digit Shapes
  • Multilanguage User Interface (MUI)
  • Multilanguage Applications

There are a number of terms that are important when discussing national language support. The following table summarizes information on locales and languages. Additional comments follow the table.

 | Language group | System locale | User locale | Thread locale | Input locale | UI language
 |  |  |  |  |  | System | User
Purpose: | Provides all keyboard layouts, IMEs, TrueType fonts, font links, LPKs, bitmap fonts and code page translation tables needed by the system for a group of languages. Therefore impacts all other settings in this list. | Determines which bitmap fonts, and OEM, ANSI, and MAC code pages are defaults for the system. This only affects applications that are not fully Unicode. | Determines which settings are used for formatting dates, times, currency, and numbers as a default for each user. Also determines the sort order for sorting text. | Determines which settings are used for formatting dates, times, currency, and large numbers for a thread. Also determines the sort order for sorting text. | A pair consisting of language and a method of input. | Determines the default language of menus and dialogs, messages, INF files, and help files of Windows 2000. | Non-MUI: Same as System UI Language.
 |  |  |  |  |  |  | MUI: Determines the language of menus and dialogs, messages, and help files of Windows 2000.
FIRST SET: | Installation | Installation | Installation | Default to user locale | Installation | Installation | Non-MUI: Installation
 |  |  |  |  |  |  | MUI: Installation
How to Change: | Regional Options (CP) (only administrators) | Regional Options (CP) (only administrator) | Regional Options (CP) | SetThreadLocale | Regional Options (CP) | No | Non-MUI: No
 |  |  |  |  |  |  | MUI:Regional Options (CP)
Default: | Western Europe and United States and language group required to display language of a localized version. | Locale matching language of localized version. | Locale matching language of localized system. | User Locale | Language of localized version with default input method. | Language of localized Version. | Language of localized Version.
API: | EnumSystemLanguageGroups | GetSystemDefaultLangID | GetUserDefaultLangID | GetThreadLocale | GetKeyboardLayout | GetSystemDefaultUILanguage | GetUseDefaultUILanguage

Language Group

The language group controls which system locale, user locales, input locales, and user interface (UI) languages can be selected. For example, Windows 2000 installs the Western Europe and United States language group by default. This default cannot be removed. For each localized version, the specified language group is the default and cannot be removed. Thus, if the English version of Windows 2000 is installed in a non-English country, the user will typically install another language group.

When adding a language group, Windows 2000 copies (but does not activate) the necessary keyboard files, Input Method Editors (IMEs), TrueType Font files, bitmap font files, and National Language Support (.nls) files. Adding a language group also adds registry values for font linking and installs scripting engines for complex script languages (Arabic, Hebrew, Indic, and Thai).

In addition to the Western Europe and United States language group there are 16 other language groups:

Arabic
Armenian
Baltic
Central Europe
Cyrillic
Georgian
Greek
Hebrew 		Indic
Japanese
Korean
Simplified Chinese
Traditional Chinese
Thai
Turkish
Vietnamese

Any number and combination of language groups can be installed on any Windows 2000 version. For example, a Spanish user would install the Cyrillic language group to work on Russian texts. In this case, the word processing application needs to support the Cyrillic language group also.

Note Adding the appropriate language group will not automatically enable an application to accept text. Testing is recommended. For example, applications that are not completely Unicode-compliant might require the system locale to be changed.

Locale

A locale is either a language or a language in combination with a country. Windows 2000 supports more than 150 locales.

System Locale

The system locale determines which code pages (ANSI, DOS, Macintosh) are used on the system by default. To select a system locale, the appropriate language group must be installed; that is, you need the script support to select a system locale. The system locale setting affects only applications that are not fully Unicode-compliant. This is because setting the system locale to a certain language instructs Windows 2000 to emulate a non-Unicode-based operating system (for example, DOS, Windows 3.1, Windows 95/98) localized to this language. Changing the system locale installs the necessary bitmap font files to support non-Unicode applications in the specified language. The system locale is a per-system setting and requires a restart to be implemented.

Sometimes there is no noticeable difference between two system locales. For example, this is the case with the German-Standard and German-Austria system locales. In general, system locales of one language group are very similar and may only differ in the OEM or MAC code page.

An ANSI application should check the system locale during installation. The following are some examples of system locale settings:

  1. A German user who wants to run a Japanese application that was designed for Japanese Windows 95 must select Japanese as the system locale. After this selection, German applications that are not fully Unicode-compliant will have problems. For example, German umlauts (ö) will not be displayed correctly.
  2. A German user who wants to type Japanese text in a German application that is not fully Unicode-compliant must select Japanese as the system locale. As in the first example, this will cause problems in entering German text in applications that are not fully Unicode-compliant.
  3. An Arabic user who wants to type Arabic, French, and English in an Arabic application that is not fully Unicode-compliant should select Arabic as a system locale, because the Arabic ANSI code page contains most French characters and all English characters.

User Locale

The user locale determines default sort order and the default settings for formatting dates, times, currency, and numbers. Although it is presented as a language (some in combination with a country or region), it is not a language setting. For example, setting the user locale to Hebrew means that the user wants to use the formatting conventions of Hebrew, not necessarily the Hebrew language. In addition, the user locale determines the string that is used for the names of the days and months. For example, if a user displays 'November 25, 1998,' the 'November' string could change based on the user locale. Changing the user locale automatically adds an input locale with the default settings for the language.

An application should typically use the user locale settings to display data. However, in some cases an application may want to use a fixed locale to display data. This can be done by setting the thread locale to a fixed value during initialization of the application. For example, an English user using English Windows 2000 working in Rome could select Italian (Italy) as the user locale to get formatting conventions for Italy.

Thread Locale

The thread locale defaults to the user locale and determines the formatting of dates, times, currency, and large numbers for the thread. It can be changed programmatically using the API SetThreadLocale. In most cases the thread locale should not be overwritten. For example, a financial stock trading application for the New York Stock Exchange, which is used in banks worldwide, has to display the time, date, and stock prices in US formats. This application uses SetThreadLocale to set the thread locale to English (United States) and can use the NLS APIs to format dates, times, and stock prices.

Input Locale

The input locale describes a language the user wants to enter (not limited to typing) and the method of input. There can be multiple input locales installed and the user can switch between them.

The default input locale is the localized language of the OS, and it is the setting that is active when a new application is started (or in some applications when a new window is opened). Switching to a different input locale is done on a per-application basis; that is, you can have two different input locales in two different applications. For example, a user can type German using the international US keyboard layout, English using voice input (with third party software), and Spanish using an Input Method Editor (IME ) in three different applications.

Language

A language is identified by a LANGID, which is composed of a primary language (for example, Swiss) and a sublanguage (for example, Swiss German).

System UI Language

The system UI language is the language of the localized version that was used to set up Windows 2000 (that is, the install language). All menus, dialog boxes, error messages, and help files are in this language, except on Windows 2000 multilanguage user interface (MUI), where the user can select a different language.

User UI Language

The user UI language determines the UI language that the system displays. In most cases, this is the same as the system UI language. However, for the Windows 2000 MUI, it can be different.

Windows 2000 MUI allows a user to change the language of the user interface. A user using MUI can change the UI language through the Regional Options in Control Panel. If a user changes the user UI language, the user will have to log off and then log back on to see the effect .For example, a multinational corporation wants to deploy Windows 2000 on all of its subsidiaries. The company creates a global install job, which installs the English language version of Windows 2000 on all clients, regardless of location. At the same time, it installs specific language modules depending on the organizational unit of which the computer is a member. When the user logs on the first time to his newly installed system, Windows 2000 will appear like a localized version.

Code Page

A code page is an ordered set of characters in which a numeric index (also known as a code point value) is associated with each character. The first 128 characters of each code page are functionally the same and include all characters needed to type English text. The upper 128 characters of OEM and ANSI code pages contain characters used in a language or group of languages.


Locales

A locale is a collection of language-related, user-preference information represented as a list of values. Each system has at least one installed locale and often has many locales from which the user may choose.

The system assigns a locale to each thread. Initially, the system assigns the system default locale to the thread. This default locale is set by the user when the system is installed or through Regional Options in Control Panel. If a thread is run in a process belonging to a user, the system assigns the user-default locale to the thread. An application can override either default by using the SetThreadLocale function to explicitly set the locale for a thread.


Locale Identifiers

Each locale has a unique identifier (LCID), a 32-bit value that consists of a language identifier and a sort identifier. The identifier supplied in an LCID is a standard international numeric abbreviation. This LCID has the components necessary to uniquely identify one of the installed system-defined locales. The LCID is constructed using the MAKELCID macro. The following illustration shows the format of the bits in an LCID.

+-------------+---------+-------------------------+
|   Reserved  | Sort ID |      Language ID        |
+-------------+---------+-------------------------+
31         20 19     16 15                      0   bit

The predefined locale identifiers are:

  • LOCALE_SYSTEM_DEFAULT, which identifies the system default locale.
  • LOCALE_USER_DEFAULT, which identifies the locale of the current user.

An application can retrieve the current locale identifiers by using the GetSystemDefaultLCID and GetUserDefaultLCID functions.


Language Identifiers

A language identifier is a standard international numeric abbreviation for a country or geographical region. Each language has a unique language identifier (LANGID), a 16-bit value that consists of a primary language identifier and a sublanguage identifier. The LANGID is constructed using the MAKELANGID macro. The following illustration shows the format of the bits in a LANGID.

+-------------------------+-------------------------+
|  SubLanguage ID  |   Primary Language ID   |
+-------------------------+-------------------------+
15                    10  9                         0   bit

There are predefined language identifiers:

  • LANG_SYSTEM_DEFAULT, which identifies the system default language.
  • LANG_USER_DEFAULT, which identifies the language of the current user.

An application can retrieve the current language identifiers by using the GetSystemDefaultLangID and GetUserDefaultLangID functions.


Locale and Language Information

It is often necessary to get specific information on available languages and locales in order to handle strings appropriately. Each element of locale information has a corresponding LCTYPE constant. To get the locale information, call GetLocaleInfo with the constant that corresponds to the information that is needed.

Most LCTYPE constants are mutually-exclusive, so usually only one type of information can be retrieved at a time. The exceptions to this are LOCALE_NOUSEROVERRIDE, LOCALE_USE_CP_ACP, and LOCALE_RETURN_NUMBER, which can be combined with other LCTYPE constants by using the binary-OR. For more information, see Locale Information.

Locale information is always stored and manipulated as a null-terminated string. No binary data is allowed; any numeric values must be specified as text. Each type of information has a particular format. Also, several of types are linked together, such that changing one changes the value of the other as well.

Although a locale identifier may be supported, it is not available for use by an application unless it is also installed. For more information about LCTYPE constants, see Locale Information.


Time and Date

You can retrieve strings for any time or date in a format that is appropriate for the current locale by using the GetTimeFormat and GetDateFormat functions.

For GetTimeFormat, the time values in the SYSTEMTIME structure pointed to by lpTime must be valid. The function checks each of the time values to determine that it is within the appropriate range of values. If any of the time values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the date portions of the SYSTEMTIME structure pointed to by lpTime: wYear, wMonth, wDayOfWeek, and wDay.

If a time marker exists and the TIME_NOTIMEMARKER flag is not set, the function localizes the time marker based on the specified locale identifier. Examples of time markers are "AM" and "PM" for US English, "de." and "du." for Mexican Spanish.

If TIME_NOMINUTESORSECONDS or TIME_NOSECONDS is specified, the function removes the separator(s) preceding the minutes and/or seconds element(s).

If TIME_NOTIMEMARKER is specified, the function removes the separator(s) preceding and following the time marker.

If TIME_FORCE24HOURFORMAT is specified, the function displays any existing time marker, unless the TIME_NOTIMEMARKER flag is also set.

The function does not include milliseconds as part of the formatted time string.

To use the LOCALE_NOUSEROVERRIDE flag, lpFormat must be NULL.

No errors are returned for a bad format string. The function simply forms the best time string that it can. If more than two hour, minute, second, or time marker format pictures are passed in, then the function defaults to two. For example, the only time marker pictures that are valid are L"t" and L"tt" (the 'L' indicates a Unicode (16-bit characters) string). If L"ttt" is passed in, the function assumes L"tt".

For GetDateFormat, the date values in the SYSTEMTIME structure pointed to by lpDate must be valid. The function checks each of the date values: year, month, day, and day of week. If the day of the week is incorrect, the function uses the correct value, and returns no error. If any of the other date values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the locale identifier. The function ignores the time portions of the SYSTEMTIME structure pointed to by lpDate: wHour, wMinute, wSecond, and wMilliseconds.

The flag DATE_USE_ALT_CALENDAR will always use the format defined as the default format for that alternate calendar, rather than using any user overrides. The user overrides will only be used in the event that there is no default format for the alternate calendar specified.

The DATE_SHORTDATE and DATE_LONGDATE flag options are mutually exclusive. If neither one is specified and lpFormat is NULL, then DATE_SHORTDATE is the default.

If the lpFormat parameter is not NULL, the dwFlags parameter must be zero. None of the flags make sense when the format string is specified.

No errors are returned for a bad format string. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L"yyyy" and L"yy" (the 'L' indicates a Unicode (16-bit characters) string). If L"y" is passed in, the function assumes L"yy". If L"yyy" is passed in, the function assumes L"yyyy". If more than 4 date (L"dddd") or 4 month (L"MMMM") pictures are passed in, then the function defaults to L"dddd" or L"MMMM".

Any text that should remain in its exact form in the date string should be enclosed within single quotes in the date format picture. The single quote may also be used as an escape character to allow the single quote itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotes. For example, to display the date as "May '93", the format string would be: L"MMMM ''''yy " The first and last single quotes are the enclosing quotes. The second and third single quotes are the escape sequence to allow the single quote to be displayed before the century.

To obtain the short and long date format for the default locale calendar, use the GetLocaleInfo function with the LOCALE_SSHORTDATE or LOCALE_SLONGDATE parameter. To get the date format for an alternate calendar, use GetLocaleInfo with the LOCALE_IOPTIONALCALENDAR parameter. To get the date format for a particular calendar, use GetCalendarInfo. Also, to return all of the date formats for a particular calendar, use EnumCalendarInfo or EnumDateFormatsEx.

To obtain the time format without performing any actual formatting, use the GetLocaleInfo function with the LOCALE_STIMEFORMAT.


Date and Calendar

Most locales use the standard Gregorian calendar and a set number of date formats. These "default choices" for date formats are available for display by using the EnumDateFormats function. There are other locales which require special considerations when creating a complete list of format choices. Some of these require text strings to be inserted within the date format string, others require a completely different method of computation of the values. These special requirements are addressed by the addition of certain LCTYPE and CALTYPE values. For more information on LCTYPE values, see Locale Information. For more information on CALTYPE values, see Calendar Type Information.

Each locale identifier (LCID) has a default calendar type associated with it. A locale identifier can also have an alternate calendar type. To have an alternate calendar type for an LCID, you must set LOCALE_IOPTIONALCALENDAR to the alternate calendar type for this locale.


Localization and the Shell Font

Microsoft® Windows NT® /Windows® 2000 is available in localized editions for many languages. However, the U.S. English edition can also be used to run applications written in languages other than English. This is true even when the base character sets are different, such as when applications are written in the Central and Eastern European languages, or in Greek. These applications require a user interface (UI) with dialog boxes, icons, and utilities that provide information in the application's language, which may be different than the language being used in the current Windows NT/Windows 2000 UI.

The problem in selecting the font is obvious. For example, the shell font (also known as the system or default font—see Font Creation and Selection) for U.S. English Windows NT is MS Sans Serif while the shell font for Greek Windows 3.1 is MS Sans Serif Greek. These character sets cannot be directly mapped to each other; simply replacing MS Sans Serif with MS Sans Serif Greek when the locale is set to Greek does not allow existing applications to run adequately (or to display Greek characters in system menus, dialog boxes and edit controls).

To resolve this problem, Microsoft has defined a new face name, MS Shell Dlg. It is mapped by an entry in the registry to the appropriate shell font for the currently active locale. When this is used, at run time Windows NT/Windows 2000 switches to the font for the currently selected locale. This allows the correct display of the U.S. English Windows NT/Windows 2000 user interface as well as characters not in code page 1252 (that is, the Windows character set for the US and Western Europe). Thus, currently shipping localized applications can run on the U.S. English version of Windows NT/Windows 2000 without modification.


MS Shell Dlg

MS Shell Dlg is a mapping mechanism that enables U.S. English Windows NT/Windows 2000 to support locales that have characters that are not contained in code page 1252. It is not a font but a face name for a nonexistent font. It can be specified in either the Windows NT/Windows 2000 Setup file during the installation process or when customizing a local system by double-clicking Control Panel's Regional Options icon. When you double-click the icon, click the Set default ... button in the General sheet of the Regional Options dialog box. Select the appropriate locale in the Select System Locale dialog box and click OK, then restart the system. The appropriate change occurs in the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\Current Version\FontSubstitutes

A benefit of font mapping in the registry is that you can change the font for the entire shell by simply changing one .inf file entry. For example, localization for Asia is much easier because you can change the .inf file entry, instead of changing every instance of MS Sans Serif in every .rc and .dlg file, and the change is complete without rebuilding any binaries. Win32-based applications that contain multiple language resources that cross character-set boundaries can also take advantage of this feature. It is also useful when you have an English application in which supporting multiple languages and character sets is important.

MS Shell Dlg is not intended for use when you are working with a static, non-English UI application that you want to run when the user has chosen a locale with a different Windows base character set. This is because the application's UI language may not be supported with the font that is substituted for MS Shell Dlg. For example, if you are using a German localized version of Windows NT/Windows 2000 and want to install a non-Unicode, Greek application, you can use Control Panel's Regional Options applet to change the locale to Greek. This will reset MS Shell Dlg to be a Greek font but this font does not contain all of the glyphs necessary to display German. Therefore, any non-ASCII characters in your German UI will not be displayed properly. To support this scenario, you would have to set MS Shell Dlg to a font that contains both the Western European and the Greek glyphs.

Windows 95/98/Me: You cannot switch Windows character sets, so the role of MS Shell Dlg is more limited. It does, however, facilitate localization in that the system is equipped with a static entry to replace the standard system font. For example, the system font, MS Sans Serif, is easily replaced with MS San Serif Greek or another language. This also ensures compatibility with the applets provided with Windows NT/Windows 2000.

Windows 2000 or later: There is a new interface font called MS Shell Dlg 2. This maps to Tahoma, which is the default font used throughout Windows 2000. For an application that runs only on Windows 2000, you can specify DS_SHELLFONT with MS Shell Dlg 2 to map to Tahoma. However, for an application that runs on Windows 95/98 or Windows NT 4.0 as well as Windows 2000, you should specify DS_SHELLFONT with MS Shell Dlg (that is, do not use MS Shell Dlg 2). This maps to Tahoma on Windows 2000 and to MS Sans Serif on both Windows 95/98 and Windows NT 4.0. MS Shell Dlg2 has no mapping on Windows 95/98 or Windows NT 4.0, so applications that specify MS Shell Dlg 2 in the dialog template for these platforms display a font that shows poorly.

Note Because the font generated using MS Shell Dlg is different on Windows 2000 from that on Windows 95/98 and Windows NT 4.0, you should check that the dialog box looks good on all platforms.


Digit Shapes

Arabic, Thai, and Indic languages have classical shapes for numbers that are different from the conventional western digits most often used on computers. To avoid ambiguity in naming these shapes, this document uses the following names from the Unicode standard.

Countries | Unicode name
Europe, America, and many others | European digits
Arabic countries (although many use European digits) | Arabic-Indic digits
Thailand (although many use European digits) | Thai digits

Unicode provides separate code points for each digit shape. Thus, to access special language–digit shapes, you can use the relevant Unicode character codes for the digits above U+0030 through U+0039. These are always displayed with the appropriate shape (subject to the available fonts).

The Unicode digits U+0030 through U+0039 are nominally the European digits of 0 through 9, but their digit shape can be altered. The system displays the digits U+0030 through U+0039 in the following ways:

  • If the national digits control code (NADS) precedes the output, the system uses digit shapes based on the user's selected locale.
  • If the nominal digits control code (NODS) precedes the output, the system uses European digits.
  • If neither NADS nor NODS precedes the output, the system uses the value of LOCALE_IDIGITSUBSTITUTION to determine digit shapes.

Native Digits

Native digits are the digit shapes chosen by the user in the Regional Settings program on the Number property sheet. To find the user's preferred digit presentation, use the GetLocaleInfo function with the LOCALE_SNATIVEDIGITS flag. Typically, Unicode digit codes are generated in run-time system routines such as _itoa, so common run-time systems must be upgraded for the application to inspect this variable appropriately.

Digit Substitution

Digit substitution tells the system how to print digits U+0030 through U+0039 in the absence of the NADS or NODS control codes. The LOCALE_IDIGITSUBSTITUTION constant, which controls this operation, can have one of the following values.

Value | Meaning
0 | Context-based substitution. Digits are displayed based on the previous text in the same output—that is, European digits follow Latin scripts, Arabic-Indic digits follow Arabic text, and Thai digits follow Thai text. When there is no preceding text, the locale and the displayed reading order determine digit substitution, as shown in the following.
 | Locale | Reading order | Digits used
 | Arabic | Right-to-left | Arabic-Indic
 | Thai | Left-to-right | Thai
 | All others | Any | No substitution is used.
1 | No substitution is used. This gives full Unicode compatibility.
2 | Native digit substitution. Digits are displayed according to LOCALE_SNATIVEDIGITS.

Digit Shaping for a Single API

The ExtTextOut, GetCharacterPlacement, and GCP_RESULTS APIs have flags that govern the substitution of Unicode characters U+0030 through U+0039 for the duration of the function call. That is, these flags override regional settings in Control Panel, but do not reset the settings. Also, they do not override the Unicode control characters NADS and NODS. The following flags are available.

Flags | Digits used
ETO_NUMERICSLATIN | European digits.
ETO_NUMERICSLOCAL | Digits appropriate to the locale.
GCP_NUMERICSLATIN | European digits.
GCP_NUMERICSLOCAL | Digits appropriate to the locale.
GCPCLASS_LATINNUMBER | European digits.
GCPCLASS_LOCALNUMBER | Digits appropriate to the locale.


Multilanguage User Interface (MUI)

All versions of Windows 2000 are enabled for all supported languages. This means that regardless of the operating system user interface (UI) language, users can edit and process text in all languages, and also run applications that have UI in any or all languages. Single UI language versions (also known as localized versions) of Windows 2000 are released in all supported UI languages. These single UI language versions basically differ only in the language in the resource sections of each binary file.

There is also a Windows 2000 Multi-language User Interface (MUI) version which includes resources for each supported UI language separated from their binaries and provided in separate language directories. The MUI allows users to set the user-interface language according to their preferences, provided the required language was added to the system. This allows large corporations to rollout the operating system worldwide, while allowing their local users or groups to select the UI language. It also allows users of different languages to share the same workstation: one user might choose to see system menus, dialog boxes, and other text in Japanese, while another user might choose to see the corresponding text in French.

MUI is a separate release version and does not replace localized versions of Windows 2000. Also, since each corporation can choose which languages to support, the MUI can be different from one corporation to another. An MUI system that is set to a particular language looks similar to a localized version, except that the following items are not localized: all 16-bit code, bitmaps, registry keys and values, folders and file names, and INF files.

As for all Windows 2000 versions, to determine the installed languages call EnumUILanguages. To determine the default user language, call GetUserDefaultUILanguage.


Multilanguage Applications

If you want your application to change the UI language, you should consider using satellite resource DLLs. In this method, each supported language has its resources in a separate DLL. Each DLL uses the same resource identifiers, but also contains strings (and possibly other language or locale-dependent resources) in the appropriate language. The name of each DLL indicates the language of its resources. On Windows 2000, your application can call EnumSystemLanguageGroups to determine which languages are supported, and thus decide which of the resource DLLs to install.

To load and get a handle to the DLL of a language, call LoadLibraryEx. Thereafter, this handle is used in all calls to load resources. However, when implementing multilanguage UI on both Windows 95/98 and Windows NT, be aware of platform differences in some Win32 API functions. For example, it is desirable to load the resource-only DLLs as data files without referencing any executable code. But on Windows 95/98, LoadLibraryEx requires the module handle returned with the lower level resource functions such as FindResource and LoadResource. Since the resource DLLs cannot be loaded as data files, each DLL must have a dummy DLLMain.

Also, you must decide on a default language for your application to use during application initialization. This requires a fallback in case the requested language is not available. To detect which UI languages are installed on Windows 2000, call EnumUILanguages. To determine the user default and system default UI languages, use GetUserDefaultUILanguage and GetSystemDefaultUILanguage, respectively. For earlier platforms, check the registry to determine the interface language of the system: on Windows 95/98, use the language of the resource locale (HKEY_CURRENT_USER\Control Panel\desktop\ResourceLocale) and on Windows NT use the locale of the default user (HKEY_USERS\.DEFAULT\Control Panel\International\Locale).

Typically, the user can change the UI language of the application. Thus you must also implement a method to find all resource DLLs that match the naming convention (because you may not have installed all of them). Another issue is whether to add, remove, or modify UI elements when changing the UI language. For example, you must decide whether to have only one accelerator table for all languages or a separate accelerator table for each one. Having only one table simplifies development and helps users who use the application with more than one UI language. However, it can lead to accelerator keys that are not clearly related in all languages to the functionality that is initiated.


National Language Support Reference

The following elements are used with national language support:

  • National Language Support Functions
  • National Language Support Macros
  • National Language Support Constants


National Language Support Functions

The following functions are used with national language support.

Function | Description
ConvertDefaultLocale | Converts a default locale value to an actual locale identifier.
EnumCalendarInfo | Enumerates calendar information for a specified locale.
EnumCalendarInfoEx | Enumerates calendar information for a specified locale.
EnumCalendarInfoProc | An application-defined function used with the EnumCalendarInfo function.
EnumCalendarInfoProcEx | An application-defined function used with the EnumCalendarInfoEx function.
EnumCodePagesProc | An application-defined function used with the EnumSystemCodePages function.
EnumDateFormats | Enumerates the long or short date formats that are available for a specified locale.
EnumDateFormatsEx | Enumerates the long or short date formats that are available for a specified locale, including date formats for any alternate calendars.
EnumDateFormatsProc | An application-defined function used with the EnumDateFormats function.
EnumDateFormatsProcEx | An application-defined function used with the EnumDateFormatsEx function.
EnumGeoInfoProc | Callback function used with EnumSystemGeoID.
EnumLanguageGroupLocales | Enumerates the locales in a specified language group.
EnumLanguageGroupLocalesProc | An application-defined function used with the EnumLanguageGroupLocales function.
EnumLanguageGroupsProc | An application-defined function used with the EnumSystemLanguageGroups function.
EnumLocalesProc | An application-defined function used with the EnumSystemLocales function.
EnumSystemCodePages | Enumerates the code pages that are either installed on or supported by a system.
EnumSystemGeoID | Enumerates all GeoIDs on the system.
EnumSystemLanguageGroups | Enumerates the language groups that are either installed on or supported by a system.
EnumSystemLocales | Enumerates the locales that are either installed on or supported by a system.
EnumTimeFormats | Enumerates the time formats that are available for a specified locale.
EnumTimeFormatsProc | An application-defined function used with the EnumTimeFormats function.
EnumUILanguages | Enumerates the UI languages that are available on the system.
EnumUILanguagesProc | An application-defined function used with the EnumUILanguages function.
GetACP | Retrieves the current ANSI code-page identifier for the system.
GetCalendarInfo | Retrieves information about a calendar.
GetCPInfo | Retrieves information about any valid installed or available code page.
GetCPInfoEx | Retrieves information about any valid installed or available code page.
GetCurrencyFormat | Formats a number string as a currency string for a specified locale.
GetDateFormat | Formats a date as a date string for a specified locale.
GetGeoInfo | Gets information about a specified location.
GetLocaleInfo | Retrieves information about a locale.
GetNumberFormat | Formats a number string as a number string customized for a specified locale.
GetOEMCP | Retrieves the current original equipment manufacturer (OEM) code-page identifier for the system.
GetSystemDefaultLangID | Retrieves the language identifier of the system locale.
GetSystemDefaultLCID | Retrieves the system default locale identifier.
GetSystemDefaultUILanguage | Retrieves the language identifier for the default language of the system.
GetThreadLocale | Retrieves the calling thread's current locale.
GetTimeFormat | Formats time as a time string for a specified locale.
GetUserDefaultLangID | Retrieves the language identifier of the current user locale.
GetUserDefaultLCID | Retrieves the user default–locale identifier.
GetUserDefaultUILanguage | Retrieves the language identifier for the current user language.
GetUserGeoID | Gets information about the user's location.
IsValidCodePage | Determines whether a specified code page is valid.
IsValidLanguageGroup | Determines whether a specified language-group identifier is valid.
IsValidLocale | Determines whether a specified locale identifier is valid.
LCMapString | Maps one character string to another, performing a specified locale-dependent transformation.
SetCalendarInfo | Sets an item of locale information for a calendar.
SetLocaleInfo | Sets an item of locale information.
SetThreadLocale | Sets the calling thread's current locale.
SetUserGeoID | Sets the user's geographical location.


ConvertDefaultLocale

The ConvertDefaultLocale function converts a default locale value to an actual locale identifier.

LCID ConvertDefaultLocale(
  LCID Locale   // default locale
);

Parameters

Locale
[in/out] Default locale value that the function converts to a locale identifier (LCID). The following are the default locale values.
Value | Description
LOCALE_SYSTEM_DEFAULT | The system's default locale.
LOCALE_USER_DEFAULT | The current user's default locale.
A sublanguage-neutral locale | A locale identifier constructed by calling MAKELCID with a primary language identifier, such as LANG_ENGLISH, and the SUBLANG_NEUTRAL sublanguage identifier.

Return Values

If the function succeeds, the return value is the appropriate LCID.

If the function fails, the return value is the Locale parameter. The function fails when Locale is not one of the default locale values listed above.

Remarks

A call to ConvertDefaultLocale(LOCALE_SYSTEM_DEFAULT) is equivalent to a call to GetSystemDefaultLCID. A call to ConvertDefaultLocale(LOCALE_USER_DEFAULT) is equivalent to a call to GetUserDefaultLCID.

For more information, see Locales and Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetSystemDefaultLCID, GetUserDefaultLCID


EnumCalendarInfo

The EnumCalendarInfo function enumerates calendar information for a specified locale. The CalType parameter specifies the type of calendar information to enumerate. The function returns the specified calendar information for all applicable calendars for the locale or, for a single requested calendar, depending on the value of the Calendar parameter.

The EnumCalendarInfo function enumerates the calendar information by calling an application defined–callback function. It passes the callback function a pointer to a buffer containing the requested calendar information. This continues until either the last applicable calendar is found or the callback function returns FALSE.

To receive a calendar identifier in addition to the calendar information provided by EnumCalendarInfo, use the EnumCalendarInfoEx function.

BOOL EnumCalendarInfo(
  CALINFO_ENUMPROC pCalInfoEnumProc, // callback function
  LCID Locale,                       // locale
  CALID Calendar,                    // calendar
  CALTYPE CalType                    // calendar information type
);

Parameters

pCalInfoEnumProc
[in] Pointer to an application defined–callback function. For more information, see the EnumCalendarInfoProc callback function.
Locale
[in] Specifies the locale for which to retrieve calendar information. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

Calendar
[in] Specifies the calendar for which information is requested. The following values are defined.
Value | Meaning
ENUM_ALL_CALENDARS | All applicable calendars for the specified locale.
CAL_GREGORIAN | Gregorian (localized).
CAL_GREGORIAN_US | Gregorian (English strings always).
CAL_JAPAN | Japanese Emperor Era.
CAL_TAIWAN | Taiwan Calendar
CAL_KOREA | Korean Tangun Era.
CAL_HIJRI | Hijri (Arabic Lunar).
CAL_THAI | Thai.
CAL_HEBREW | Hebrew (Lunar).
CAL_GREGORIAN_ME_FRENCH | Gregorian Middle East French.
CAL_GREGORIAN_ARABIC | Gregorian Arabic.
CAL_GREGORIAN_XLIT_ENGLISH | Gregorian transliterated English.
CAL_GREGORIAN_XLIT_FRENCH | Gregorian transliterated French.

CalType
[in] Specifies the type of calendar information to be returned. See the listing of constant values in Calendar Type Information. Note that only one CALTYPE value can be specified per call of this function, except where noted.

Windows 98/Me: EnumCalendarInfo does not support CAL_ITWODIGITYEARMAX.

Windows Me: EnumCalendarInfo supports CAL_ITWODIGITYEARMAX.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_BADDB
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, EnumCalendarInfoEx, EnumCalendarInfoProc, EnumDateFormats, MAKELCID


EnumCalendarInfoEx

The EnumCalendarInfoEx function enumerates calendar information for a specified locale. The CalType parameter specifies the type of calendar information to enumerate. The function returns the specified calendar information for all applicable calendars for the locale or, for a single requested calendar, depending on the value of the Calendar parameter.

The EnumCalendarInfoEx function enumerates the calendar information by calling an application defined–callback function. It passes the callback function a pointer to a buffer containing the requested calendar information and a calendar identifier (CALID). This continues until either the last applicable calendar is found or the callback function returns FALSE.

BOOL EnumCalendarInfoEx(
  CALINFO_ENUMPROCEX pCalInfoEnumProcEx, // callback function
  LCID Locale,                           // locale
  CALID Calendar,                        // calendar
  CALTYPE CalType                        // information type
);

Parameters

pCalInfoEnumProcEx
[in] Pointer to an application defined–callback function. For more information, see the EnumCalendarInfoProcEx callback function.
Locale
[in] Specifies the locale for which to retrieve calendar information. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

Calendar
[in] Specifies the calendar for which information is requested. The following values are defined.
Value | Meaning
ENUM_ALL_CALENDARS | All applicable calendars for the specified locale.
CAL_GREGORIAN | Gregorian (localized)
CAL_GREGORIAN_US | Gregorian (English strings always)
CAL_JAPAN | Japanese Emperor Era
CAL_TAIWAN | Taiwan Calendar
CAL_KOREA | Korean Tangun Era
CAL_HIJRI | Hijri (Arabic Lunar)
CAL_THAI | Thai
CAL_HEBREW | Hebrew (Lunar)
CAL_GREGORIAN_ME_FRENCH | Gregorian Middle East French
CAL_GREGORIAN_ARABIC | Gregorian Arabic
CAL_GREGORIAN_XLIT_ENGLISH | Gregorian transliterated English
CAL_GREGORIAN_XLIT_FRENCH | Gregorian transliterated French

CalType
[in] Specifies the type of calendar information to be returned. See the listing of constant values in Calendar Type Information. Note that only one CALTYPE value can be specified per call of this function, except where noted.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_BADDB
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

National Language Support Overview, National Language Support Functions, EnumCalendarInfoEx, EnumCalendarInfoProc, EnumDateFormats


EnumCalendarInfoProc

The EnumCalendarInfoProc function is an application-defined function used with the EnumCalendarInfo function. It receives a pointer to a buffer containing a calendar information string. The CALINFO_ENUMPROC type defines a pointer to this callback function. EnumCalendarInfoProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumCalendarInfoProc(
  LPTSTR lpCalendarInfoString   // calendar information string
);

Parameters

lpCalendarInfoString
[in] Pointer to a buffer containing a null-terminated calendar information string. This string is formatted according to the CALTYPE value passed to EnumCalendarInfo.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

An EnumCalendarInfoProc function can carry out any desired task.

An application registers an EnumCalendarInfoProc function by passing its address to the EnumCalendarInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumCalendarInfo


EnumCalendarInfoProcEx

The EnumCalendarInfoProcEx function is an application-defined function used with the EnumCalendarInfoEx function. It receives a pointer to a buffer containing a calendar information string and a calendar identifier (CALID). The CALINFO_ENUMPROCEX type defines a pointer to this callback function. EnumCalendarInfoProcEx is a placeholder for the application defined–function name.

BOOL CALLBACK EnumCalendarInfoProcEx (
  LPTSTR lpCalendarInfoString,  // calendar information string
  CALID Calendar                // calendar identifier
);

Parameters

lpCalendarInfoString
[in] Pointer to a buffer containing a null-terminated calendar information string. This string is formatted according to the CALTYPE value passed to EnumCalendarInfoEx.
Calendar
[in] Calendar identifier associated with the associated calendar information retrieved.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

An EnumCalendarInfoProcEx function can carry out any desired task.

An application registers an EnumCalendarInfoProcEx function by passing its address to the EnumCalendarInfoEx function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.
Unicode: Declared as Unicode and ANSI prototypes.

See Also

National Language Support Overview, National Language Support Functions, EnumCalendarInfoEx


EnumCodePagesProc

The EnumCodePagesProc function is an application-defined function used with the EnumSystemCodePages function. It receives a pointer to a buffer containing a code page identifier. The CODEPAGE_ENUMPROC type defines a pointer to this callback function. EnumCodePagesProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumCodePagesProc(
  LPTSTR lpCodePageString   // code page identifier string
);

Parameters

lpCodePageString
[in] Pointer to a buffer containing a null-terminated code page identifier string.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

An EnumCodePagesProc function can carry out any desired task.

An application registers an EnumCodePagesProc function by passing its address to the EnumSystemCodePages function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumSystemCodePages


EnumDateFormats

The EnumDateFormats function enumerates the long or short date formats that are available for a specified locale. The value of the dwFlags parameter determines whether the long or short date formats are enumerated. The function enumerates the date formats by passing date format string pointers, one at a time, to the specified application–defined callback function. This continues until the last date format is found or the callback function returns FALSE.

To receive a calendar identifier in addition to the date format information provided by EnumDateFormats, use the EnumDateFormatsEx function.

BOOL EnumDateFormats(
  DATEFMT_ENUMPROC lpDateFmtEnumProc, // callback function
  LCID Locale,                        // locale
  DWORD dwFlags                       // date formats
);

Parameters

lpDateFmtEnumProc
[in] Pointer to an application–defined callback function. The EnumDateFormats function enumerates date formats by making repeated calls to this callback function. For more information, see the EnumDateFormatsProc callback function.
Locale
[in] Specifies the locale for which to retrieve date format information. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

dwFlags
[in] Specifies the date formats of interest. Use one of the following values.
Value | Meaning
LOCALE_USE_CP_ACP | Uses the system ANSI code page for string translation instead of the locale's code page.
DATE_SHORTDATE | Return short date formats. This value cannot be used with DATE_LONGDATE.
DATE_LONGDATE | Return long date formats. This value cannot be used with DATE_SHORTDATE.
DATE_YEARMONTH | Return year/month formats.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INVALID_PARAM
  • ETERERROR_BADDB
  • ERROR_INVALID FLAGS

Remarks

This function will return all date formats for the specified locale, including alternate calendars, if any. However, the calendar identifier is not returned along with the date format in the callback function, so formats for locales with alternate calendars are difficult to use. To get the date formats for locales with alternate calendars, use EnumDateFormatsEx.

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, EnumDateFormatsEx, EnumDateFormatsProc, EnumCalendarInfo, EnumTimeFormats


EnumDateFormatsEx

The EnumDateFormatsEx function enumerates the long or short date formats that are available for a specified locale, including date formats for any alternate calendars. The value of the dwFlags parameter determines whether the long date, short date, or year/month formats are enumerated. The function enumerates the date formats by passing date format string pointers, one at a time, to the specified application–defined callback function. This continues until the last date format is found or the callback function returns FALSE.

BOOL EnumDateFormatsEx (
  DATEFMT_ENUMPROCEX lpDateFmtEnumProcEx, // callback function
  LCID Locale,                            // locale
  DWORD dwFlags                           // date formats
);

Parameters

lpDateFmtEnumProcEx
[in] Pointer to an application–defined callback function. The EnumDateFormatsEx function enumerates date formats by making repeated calls to this callback function. For more information, see the EnumDateFormatsProcEx callback function.
Locale
[in] Specifies the locale for which to retrieve date format information. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

dwFlags
[in] Specifies the date formats that are of interest. Use one of the following values.
Value | Meaning
LOCALE_USE_CP_ACP | Uses the system ANSI code page for string translation instead of the locale's code page.
DATE_SHORTDATE | Return short date formats. This value cannot be used with DATE_LONGDATE.
DATE_LONGDATE | Return long date formats. This value cannot be used with DATE_SHORTDATE.
DATE_YEARMONTH | Return year/month formats.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INVALID_PARAM
  • ETERERROR_BADDB
  • ERROR_INVALID FLAGS

Remarks

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, EnumDateFormatsProcEx, EnumCalendarInfo, EnumTimeFormats


EnumDateFormatsProc

The EnumDateFormatsProc function is an application-defined function used with the EnumDateFormats function. It receives a pointer to a buffer containing a date format string. The DATEFMT_ENUMPROC type defines a pointer to this callback function. EnumDateFormatsProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumDateFormatsProc(
  LPTSTR lpDateFormatString   // date format string
);

Parameters

lpDateFormatString
[in] Pointer to a buffer containing a null-terminated date format string. This string is a long or short date format, depending on the value of the dwFlags parameter passed to EnumDateFormats.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

An EnumDateFormatsProc function can carry out any desired task. An application registers an EnumDateFormatsProc function by passing its address to the EnumDateFormats function.

The date format strings are translated from Unicode to ANSI, for the ANSI version of this function, based on the default ANSI code page for the LCID. However, if LOCALE_USE_CP_ACP is specified, the translation is done using the system default ANSI code page.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumDateFormats


EnumDateFormatsProcEx

The EnumDateFormatsProcEx function is an application-defined function used with the EnumDateFormatsEx function. It receives a pointer to a buffer containing a date format string and a calendar identifier (CALID). The DATEFMT_ENUMPROCEX type defines a pointer to this callback function. EnumDateFormatsProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumDateFormatsProcEx (
  LPTSTR lpDateFormatString,  // date format string
  CALID  CalendarID           // calendar identifier
);

Parameters

lpDateFormatString
[in] Pointer to a buffer containing a null-terminated date format string. This string is a long or short date format, depending on the value of the dwFlags parameter passed to EnumDateFormatsEx.
CalendarID
[in] Calendar identifier associated with the date format string in lpDateFormatString. This parameter can be one of the following values.
Value | Meaning
1 | Gregorian (localized)
2 | Gregorian (English strings always)
3 | Year of the Emperor (Japan)
4 | Taiwan Calendar
5 | Tangun Era (Korea)
6 | Hijri (Arabic lunar)
7 | Thai
8 | Hebrew (Lunar)
9 | Gregorian Middle East French calendar
10 | Gregorian Arabic calendar
11 | Gregorian Transliterated English calendar
12 | Gregorian Transliterated French calendar

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

An EnumDateFormatsProcEx function can carry out any desired task. An application registers an EnumDateFormatsProcEx function by passing its address to the EnumDateFormatsEx function.

The date format strings are translated from Unicode to ANSI, for the ANSI version of this function, based on the default ANSI code page for the LCID. However, if LOCALE_USE_CP_ACP is specified, the translation is done using the system default ANSI code page.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumDateFormatsEx


EnumGeoInfoProc

The EnumGeoInfoProc function is an application-defined callback function used with EnumSystemGeoID. It receives a pointer to a buffer that contains a GeoID. EnumGeoInfoProc is a placeholder for the application-defined function name.

BOOL Callback EnumGeoInfoProc(
  GEOID  GeoId         // location identifier
);

Parameters

GeoId
[in] GeoID to be checked.

Return Values

To continue enumeration, the callback function should return TRUE. To stop enumeration, the callback function should return FALSE.

Remarks

An application registers the EnumGeoInfoProc function by passing its address to the EnumSystemGeoID function.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumSystemGeoID


EnumLanguageGroupLocales

The EnumLanguageGroupLocales function enumerates the locales in a specified language group.

BOOL EnumLanguageGroupLocales (
  LANGGROUPLOCALE_ENUMPROC pLangGroupLocaleEnumProc, // callback function
  LGRPID LanguageGroup,                              // language-group identifier
  DWORD dwFlags,                                     // reserved
  LONG_PTR lParam                                    // callback parameter
 );

Parameters

pLangGroupLocaleEnumProc
[in] Pointer to an application defined–callback function. For more information, see the EnumLanguageGroupLocalesProc callback function.
LanguageGroup
[in] Specifies the identifier of the language group to enumerate. This can be one of the following values:
LGRPID_WESTERN_EUROPE
LGRPID_CENTRAL_EUROPE
LGRPID_ARABIC
LGRPID_ARMENIAN
LGRPID_BALTIC
LGRPID_CYRILLIC
LGRPID_GEORGIAN
LGRPID_GREEK
LGRPID_HEBREW 		LGRPID_INDIC
LGRPID_JAPANESE
LGRPID_KOREAN
LGRPID_SIMPLIFIED_CHINESE
LGRPID_TRADITIONAL_CHINESE
LGRPID_THAI
LGRPID_TURKISH
LGRPID_VIETNAMESE

dwFlags
Reserved. Must be zero.
lParam
[in] Specifies a value to be passed to the callback function. This value can be used for error checking.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_BADDB
  • ERROR_INVALID_PARAMETER
  • ERROR_INVALID_FLAGS

Remarks

The EnumLanguageGroupLocales function enumerates locale identifiers in the specified language group by passing locale identifiers, one at a time, to an application defined–callback function. This continues until the last locale identifier is found or the callback function returns FALSE. For more information, see the EnumLanguageGroupLocalesProc callback function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, EnumLanguageGroupLocalesProc, IsValidLanguageGroup, EnumSystemLanguageGroups


EnumLanguageGroupLocalesProc

The EnumLanguageGroupLocalesProc function is an application-defined function used with the EnumLanguageGroupLocales function.

The LANGGROUPLOCALE_ENUMPROC type defines a pointer to this callback function. EnumLanguagesGroupLocalesProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumLanguageGroupLocalesProc(
  LGRPID LanguageGroup,     // language-group identifier
  LCID Locale,              // locale identifier
  LPTSTR lpLocaleString,    // locale identifier string
  LONG_PTR lParam           // callback parameter
);

Parameters

LanguageGroup
[in] Identifier of the language group to be enumerated. This parameter can be one of the following values:
LGRPID_WESTERN_EUROPE
LGRPID_CENTRAL_EUROPE
LGRPID_ARABIC
LGRPID_ARMENIAN
LGRPID_BALTIC
LGRPID_CYRILLIC
LGRPID_GEORGIAN
LGRPID_GREEK
LGRPID_HEBREW 		LGRPID_INDIC
LGRPID_JAPANESE
LGRPID_KOREAN
LGRPID_SIMPLIFIED_CHINESE
LGRPID_TRADITIONAL_CHINESE
LGRPID_THAI
LGRPID_TURKISH
LGRPID_VIETNAMESE
Locale
[in] Locale identifier.
lpLocaleString
[in] Pointer to a buffer containing a null-terminated locale identifier string.
lParam
[in] Application-defined value passed to the EnumLanguageGroupLocales function. This parameter can be used for error checking.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

An EnumLanguageGroupLocalesProc function can carry out any desired task. An application registers an EnumLanguageGroupLocalesProc function by passing its address to the EnumLanguageGroupLocales function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumLanguageGroupLocales, EnumSystemLanguageGroups


EnumLanguageGroupsProc

An EnumLanguageGroupsProc function is an application-defined function used with the EnumSystemLanguageGroups function.

The LANGUAGEGROUP_ENUMPROC type defines a pointer to this callback function. EnumLanguagesGroupsProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumLanguageGroupsProc(
  LGRPID LanguageGroup,             // language-group identifier
  LPTSTR lpLanguageGroupString,     // language-group identifier string
  LPTSTR lpLanguageGroupNameString, // language-group name string
  DWORD dwFlags,                    // options
  LONG_PTR  lParam                  // callback parameter
);

Parameters

LanguageGroup
[in] Language-group identifier. This parameter can be one of the following values.
LGRPID_WESTERN_EUROPE
LGRPID_CENTRAL_EUROPE
LGRPID_ARABIC
LGRPID_ARMENIAN
LGRPID_BALTIC
LGRPID_CYRILLIC
LGRPID_GEORGIAN
LGRPID_GREEK
LGRPID_HEBREW 		LGRPID_INDIC
LGRPID_JAPANESE
LGRPID_KOREAN
LGRPID_SIMPLIFIED_CHINESE
LGRPID_TRADITIONAL_CHINESE
LGRPID_THAI
LGRPID_TURKISH
LGRPID_VIETNAMESE
lpLanguageGroupString
[in] Pointer to a buffer containing a null-terminated language group identifier string.
lpLanguageGroupNameString
[in] Pointer to a buffer containing a null-terminated language group name string.
dwFlags
[in] Specifies whether the language group identifier is supported or installed. This parameter can be one of the following values.
Value | Meaning
LGRPIC_INSTALLED | Language group identifier is installed.
LGRPIC_SUPPORTED | Language group identifier is both supported and installed.

lParam
[in] Application-defined parameter passed to the EnumSystemLanguageGroups function. This parameter can be used for error checking.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

This function can carry out any desired task. An application registers an EnumLanguageGroupsProc function by passing its address to the EnumSystemLanguageGroups function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumSystemLanguageGroups, EnumLanguageGroupLocales


EnumLocalesProc

The EnumLocalesProc function is an application-defined function used with the EnumSystemLocales function. It receives a pointer to a buffer containing a locale identifier. The LOCALE_ENUMPROC type defines a pointer to this callback function. EnumLocalesProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumLocalesProc(
  LPTSTR lpLocaleString   // locale identifier string
);

Parameters

lpLocaleString
[in] Pointer to a buffer containing a null-terminated locale identifier string.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

An application registers an EnumLocalesProc function by passing its address to the EnumSystemLocales function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumSystemLocales


EnumSystemCodePages

The EnumSystemCodePages function enumerates the code pages that are either installed on or supported by a system. The dwFlags parameter determines whether the function enumerates installed or supported code pages. The function enumerates the code pages by passing code page identifiers, one at a time, to the specified application defined–callback function. This continues until all of the installed or supported code page identifiers have been passed to the callback function, or the callback function returns FALSE.

BOOL EnumSystemCodePages(
  CODEPAGE_ENUMPROC lpCodePageEnumProc, // callback function
  DWORD dwFlags                         // code pages
);

Parameters

lpCodePageEnumProc
[in] Pointer to an application defined–callback function. The EnumSystemCodePages function enumerates code pages by making repeated calls to this callback function. For more information, see the EnumCodePagesProc callback function.
dwFlags
[in] Specifies the code pages to enumerate. This parameter can be one of the following values.
Value | Meaning
CP_INSTALLED | Enumerate only installed code pages.
CP_SUPPORTED | Enumerate all supported code pages.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INVALID_PARAMETER
  • ERROR_BADDB
  • ERROR_INVALID FLAGS

Remarks

The CP_INSTALLED and CP_SUPPORTED flags are mutually exclusive.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, EnumCodePagesProc


EnumSystemGeoID

The EnumSystemGeoID function enumerates the GeoIDs that are available on the system.

BOOL EnumSystemGeoID(
  GEOCLASS GeoClass,       // geographical type to enumerate
  GEOID  ParentGeoId,         // parent GeoID
  GEO_ENUMPROC lpGeoEnumProc  // callback function
);

Parameters

GeoClass
[in] Specifies the geographical type identifier to enumerate. At present, only GEOCLASS_NATION is allowed, which enumerates all the GeoIDs of nations on the system.
ParentGeoId
Reserved. This must be zero.
lpGeoEnumProc
[in] Pointer to the application-defined callback function EnumGeoInfoProc. The EnumSystemGeoID function makes repeated calls to this callback function until it returns FALSE.

Return Values

If the function succeeds, it returns a nonzero value.

If the function fails, it returns zero. To get extended error information, call GetLastError, which can return one of the following error codes.

Error code | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was used.
ERROR_BADDB | A bad internal database was found.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, EnumGeoInfoProc


EnumSystemLanguageGroups

The EnumSystemLanguageGroups function enumerates the language groups that are either installed on or supported by a system.

BOOL EnumSystemLanguageGroups(
  LANGUAGEGROUP_ENUMPROC pLangGroupEnumProc, // callback function
  DWORD dwFlags,                             // language groups
  LONG_PTR  lParam                           // callback parameter
);

Parameters

pLangGroupEnumProc
[in] Pointer to an application defined–callback function. For more information, see the EnumLanguageGroupsProc callback function.
dwFlags
[in] Language group identifiers to enumerate. This parameter can be one of the following values.
Value | Meaning
LGRPID_INSTALLED | Enumerate only installed language group identifiers.
LGRPID_SUPPORTED | Enumerate all supported language group identifiers.

lParam
[in] Application-defined value passed to the callback function. This parameter may be used in error checking.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError. The GetLastError function may return one of the following error codes:

  • ERROR_BADDB
  • ERROR_INVALID_PARAMETER
  • ERROR_INVALID FLAGS

Remarks

The function enumerates language groups by passing language group identifiers, one at a time, to the specified application defined–callback function. This continues until the last language group identifier is found or the callback function returns FALSE. For more information, see the EnumLanguageGroupsProc callback function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, EnumLanguageGroupsProc, IsValidLanguageGroup, EnumLanguageGroupLocales


EnumSystemLocales

The EnumSystemLocales function enumerates the locales that are either installed on or supported by a system. The dwFlags parameter determines whether the function enumerates installed or supported system locales. The function enumerates locales by passing locale identifiers, one at a time, to the specified application defined–callback function. This continues until all of the installed or supported locale identifiers have been passed to the callback function or the callback function returns FALSE.

BOOL EnumSystemLocales(
  LOCALE_ENUMPROC lpLocaleEnumProc, // callback function
  DWORD dwFlags                     // locales
);

Parameters

lpLocaleEnumProc
[in] Pointer to an application defined–callback function. The EnumSystemLocales function enumerates locales by making repeated calls to this callback function. For more information, see the EnumLocalesProc callback function.
dwFlags
[in] Locale identifiers to enumerate. This parameter can be one or more of the following values.
Value | Meaning
LCID_INSTALLED | Enumerate only installed locale identifiers. This value cannot be used with LCID_SUPPORTED.
LCID_SUPPORTED | Enumerate all supported locale identifiers. This value cannot be used with LCID_INSTALLED.
LCID_ALTERNATE_SORTS | Enumerate only the alternate sorts. If this value is used with either LCID_INSTALLED or LCID_SUPPORTED, then the installed or supported locales will be returned as well as the alternate sort locale IDs.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INVALID_PARAMETER
  • ERROR_BADDB
  • ERROR_INVALID FLAGS

Remarks

The LCID_INSTALLED and LCID_SUPPORTED flags are mutually exclusive.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, EnumLocalesProc


EnumTimeFormats

The EnumTimeFormats function enumerates the time formats that are available for a specified locale. The function enumerates the time formats by passing a pointer to a buffer containing a time format to an application defined–callback function. It continues to do so until the last time format is found or the callback function returns FALSE.

BOOL EnumTimeFormats(
  TIMEFMT_ENUMPROC lpTimeFmtEnumProc, // callback function
  LCID Locale,                        // locale
  DWORD dwFlags                       // unused
);

Parameters

lpTimeFmtEnumProc
[in] Pointer to an application defined–callback function. For more information, see EnumTimeFormatsProc.
Locale
[in] Specifies the locale to retrieve time format information for. This parameter can be a locale identifier created by the MAKELCID macro, or by one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

dwFlags
[in] Currently, only the following value is defined.
Value | Meaning
LOCALE_USE_CP_ACP | Use the system ANSI code page for string translation instead of the locale's code page.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INVALID_PARAMETER
  • ERROR_BADDB
  • ERROR_INVALID FLAGS

Remarks

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, EnumTimeFormatsProc, EnumCalendarInfo, EnumDateFormats


EnumTimeFormatsProc

The EnumTimeFormatsProc function is an application-defined function used with the EnumTimeFormats function. The TIMEFMT_ENUMPROC type defines a pointer to this callback function. EnumTimeFormatsProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumTimeFormatsProc(
  LPTSTR lpTimeFormatString   // time format string
);

Parameters

lpTimeFormatString
[in] Pointer to a buffer containing a null-terminated time format string.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

This function can carry out any desired task. An application registers this function by passing its address to the EnumTimeFormats function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumTimeFormats


EnumUILanguages

The EnumUILanguages function enumerates the UI languages that are available on the system.

BOOL EnumUILanguages(
  UILANGUAGE_ENUMPROC pUILangEnumProc, // callback function
  DWORD dwFlags,                       // reserved
  LONG_PTR lParam                      // callback parameter
);

Parameters

pUILangEnumProc
[in] Pointer to an application defined–callback function. The EnumUILanguages function enumerates language identifiers by making repeated calls to this callback function. For more information, see EnumUILanguagesProc.
dwFlags
[in] Reserved. Must be zero.
lParam
[in] Application-defined value passed to the callback function. This parameter can be used for error checking.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_BADDB
  • ERROR_INVALID_PARAMETER
  • ERROR_INVALID FLAGS

Remarks

The function enumerates the UI languages by passing language identifiers, one at a time, to an application defined–callback function. The EnumUILanguages function continues to pass language identifiers to the callback function until the last language identifier is found or the callback function returns FALSE. For more information, see the EnumUILanguagesProc callback function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, EnumUILanguagesProc, GetSystemDefaultUILanguage, GetUserDefaultUILanguage


EnumUILanguagesProc

The EnumUILanguagesProc function is an application-defined function used with the EnumUILanguages function.

The UILANGUAGE_ENUMPROC type defines a pointer to this callback function. EnumUILanguagesProc is a placeholder for the application defined–function name.

BOOL CALLBACK EnumUILanguagesProc(
  LPTSTR lpUILanguageString, // language string
  LONG_PTR lParam            // callback parameter
);

Parameters

lpUILanguageString
[in] Pointer to a buffer containing a null-terminated UI language–identifier string.
lParam
[in] Application-defined parameter passed to the EnumUILanguages function. This parameter can be used for error checking.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

An EnumUILanguagesProc function can carry out any desired task. An application registers this function by passing its address to the EnumUILanguages function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Functions, EnumUILanguages


GetACP

The GetACP function retrieves the current ANSI code-page identifier for the system.

UINT GetACP(VOID);

Parameters

This function has no parameters.

Return Values

The return value is the current ANSI code-page identifier for the system, or a default identifier if no code page is current.

Remarks

The following are the ANSI code-page identifiers.

Identifier | Meaning
874 | Thai
932 | Japan
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan; Hong Kong SAR, PRC)
1200 | Unicode (BMP of ISO 10646)
1250 | Windows 3.1 Eastern European
1251 | Windows 3.1 Cyrillic
1252 | Windows 3.1 Latin 1 (U.S., Western Europe)
1253 | Windows 3.1 Greek
1254 | Windows 3.1 Turkish
1255 | Hebrew
1256 | Arabic
1257 | Baltic

MAPI: For more information, see Syntax and Limitations for Win32 Functions Useful in MAPI Development.

Windows 2000 or later: The return value for the Indic languages is 0, because they are Unicode only.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetCPInfo, GetOEMCP


GetCalendarInfo

The GetCalendarInfo function retrieves information about a calendar.

int GetCalendarInfo(
  LCID Locale,       // locale
  CALID Calendar,    // calendar identifier
  CALTYPE CalType,   // calendar type
  LPTSTR lpCalData,  // information buffer
  int cchData,       // information buffer size
  LPDWORD lpValue    // data
);

Parameters

Locale
[in] Locale identifier (LCID). This can be created by the MAKELCID macro, or it can be one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default-system locale.
LOCALE_USER_DEFAULT | Default-user locale.

Calendar
[in] Calendar identifier.
CalType
[in] Specifies the type of information to retrieve. For more information, see Calendar Type Information.
lpCalData
[out] Pointer to a buffer that receives the requested data as a string. If CAL_RETURN_NUMBER is specified in CalType, then lpCalData must be NULL.
cchData
[in] Specifies the size, in TCHARs, of the lpCalData buffer. If cchData is zero, the function returns the number of bytes or characters required to hold the information, and the buffer pointed to by lpCalData is not used. If CAL_RETURN_NUMBER is specified in CalType, then cchData must be 0.
lpValue
[out] Pointer to a variable that receives the requested data as a number. If CAL_RETURN_NUMBER is not specified in CalType, then lpValue must be NULL.

Return Values

If the function succeeds and cchData is nonzero, the return value is the number of TCHARs written to the lpCalData buffer. If the function succeeds and cchData is zero and CAL_RETURN_NUMBER is not specified, the return value is the number of bytes or characters required to hold the locale information. If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

Windows 98/Me: The only CAL_* types supported are:

  • CAL_ITWODIGITYEARMAX (only supported for Gregorian calendars)
  • CAL_RETURN_NUMBER
  • CAL_NO_USEROVERRIDE
  • CAL_USE_CP_ACP

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, SetCalendarInfo


GetCPInfo

The GetCPInfo function retrieves information about any valid installed or available code page.

To obtain additional information, use the GetCPInfoEx function.

BOOL GetCPInfo(
  UINT CodePage,      // code page identifier
  LPCPINFO lpCPInfo   // information buffer
);

Parameters

CodePage
[in] Specifies the code page about which information is to be retrieved. You can specify the code page identifier for any installed or available code page, or you can specify one of the following predefined values.
Value | Meaning
CP_ACP | Use the system default–ANSI code page.
CP_MACCP | Windows NT/2000 or later: Use the system default–Macintosh code page.
CP_OEMCP | Use the system default–OEM code page.

lpCPInfo
[out] Pointer to a CPINFO structure that receives information about the code page.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the specified code page is not installed or not available, GetCPInfo sets the last-error value to ERROR_INVALID_PARAMETER.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetACP, GetCPInfoEx, GetOEMCP, CPINFO


GetCPInfoEx

The GetCPInfoEx function retrieves information about any valid installed or available code page.

BOOL GetCPInfoEx (
  UINT CodePage,         // code-page identifier
  DWORD dwFlags,         // flags (must be zero)
  LPCPINFOEX lpCPInfoEx  // structure for information
);

Parameters

CodePage
[in] Specifies the code page about which information is to be retrieved. You can specify the code-page identifier for any installed or available code page, or you can specify one of the following predefined values.
Value | Meaning
CP_ACP | Use the system default–ANSI code page.
CP_MACCP | Windows NT/2000 or later: Use the system default–Macintosh code page.
CP_OEMCP | Use the system default–OEM code page.

dwFlags
Reserved. Must be zero.
lpCPInfoEx
[out] Pointer to a CPINFOEX structure that receives information about the code page.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the specified code page is not installed or not available, the GetCPInfoEx function sets the last-error value to ERROR_INVALID_PARAMETER.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

National Language Support Overview, National Language Support Functions, GetACP, GetOEMCP, CPINFOEX


GetCurrencyFormat

The GetCurrencyFormat function formats a number string as a currency string for a specified locale.

int GetCurrencyFormat(
  LCID Locale,                  // locale
  DWORD dwFlags,                // operation option
  LPCTSTR lpValue,              // input number string
  CONST CURRENCYFMT *lpFormat,  // formatting information
  LPTSTR lpCurrencyStr,         // output buffer
  int cchCurrency               // size of output buffer
);

Parameters

Locale
[in] Specifies the locale for which the currency string is to be formatted. If lpFormat is NULL, the function formats the string according to the currency format for this locale. If lpFormat is not NULL, the function uses the locale only for formatting information not specified in the CURRENCYFMT structure (for example, the locale's string value for the negative sign).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

dwFlags
[in] Controls the operation of the function. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify the LOCALE_NOUSEROVERRIDE flag to format the string using the system default currency format for the specified locale; or you can specify zero to format the string using any user overrides to the locale's default currency format.

lpValue
[in] Pointer to a null-terminated string containing the number string to format.

This string can contain only the following characters:

  • Characters '0' through '9'.
  • One decimal point (dot) if the number is a floating-point value.
  • A minus sign in the first character position if the number is a negative value.

All other characters are invalid. The function returns an error if the string pointed to by lpValue deviates from these rules.

lpFormat
[in] Pointer to a CURRENCYFMT structure that contains currency formatting information. All members in the structure pointed to by lpFormat must contain appropriate values.

If lpFormat is NULL, the function uses the currency format of the specified locale.

lpCurrencyStr
[out] Pointer to a buffer that receives the formatted currency string.
cchCurrency
[in] Specifies the size, in TCHARs, of the lpCurrencyStr buffer. If cchCurrency is zero, the function returns the number of TCHARs required to hold the formatted currency string, and the buffer pointed to by lpCurrencyStr is not used.

Return Values

If the function succeeds, the return value is the number of TCHARs written to the buffer pointed to by lpCurrencyStr, or if the cchCurrency parameter is zero, the number of bytes or characters required to hold the formatted currency string. The count includes the terminating null.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, GetNumberFormat, CURRENCYFMT


GetDateFormat

The GetDateFormat function formats a date as a date string for a specified locale. The function formats either a specified date or the local system date.

int GetDateFormat(
  LCID Locale,               // locale
  DWORD dwFlags,             // options
  CONST SYSTEMTIME *lpDate,  // date
  LPCTSTR lpFormat,          // date format
  LPTSTR lpDateStr,          // formatted string buffer
  int cchDate                // size of buffer
);

Parameters

Locale
[in] Specifies the locale for which the date string is to be formatted. If lpFormat is NULL, the function formats the string according to the date format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale's day and month names).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

dwFlags
[in] Specifies various function options. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify a combination of the following values.
Value | Meaning
LOCALE_NOUSEROVERRIDE | If set, the function formats the string using the system default–date format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default–date format.
LOCALE_USE_CP_ACP | Uses the system ANSI code page for string translation instead of the locale's code page.
DATE_SHORTDATE | Uses the short date format. This is the default. This value cannot be used with DATE_LONGDATE or DATE_YEARMONTH.
DATE_LONGDATE | Uses the long date format. This value cannot be used with DATE_SHORTDATE or DATE_YEARMONTH.
DATE_YEARMONTH | Uses the year/month format. This value cannot be used with DATE_SHORTDATE or DATE_LONGDATE.
DATE_USE_ALT_CALENDAR | Uses the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides will be used only in the event that there is no default format for the specified alternate calendar.
DATE_LTRREADING | Adds marks for left-to-right reading layout. This value cannot be used with DATE_RTLREADING.
DATE_RTLREADING | Adds marks for right-to-left reading layout. This value cannot be used with DATE_LTRREADING

If you do not specify either DATE_YEARMONTH, DATE_SHORTDATE, or DATE_LONGDATE, and lpFormat is NULL, then DATE_SHORTDATE is the default.

lpDate
[in] Pointer to a SYSTEMTIME structure that contains the date information to be formatted. If this pointer is NULL, the function uses the current local system date.
lpFormat
[in] Pointer to a format picture string that is used to form the date string. The format picture string must be zero terminated. If lpFormat is NULL, the function uses the date format of the specified locale.

Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown in the table (for example, "MM" not "mm"). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.
Picture | Meaning
d | Day of month as digits with no leading zero for single-digit days.
dd | Day of month as digits with leading zero for single-digit days.
ddd | Day of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd | Day of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M | Month as digits with no leading zero for single-digit months.
MM | Month as digits with leading zero for single-digit months.
MMM | Month as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM | Month as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y | Year as last two digits, but with no leading zero for years less than 10.
yy | Year as last two digits, but with leading zero for years less than 10.
yyyy | Year represented by full four digits.
gg | Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.

For example, to get the date string

"Wed, Aug 31 94"

use the following picture string:

"ddd',' MMM dd yy"
lpDateStr
[out] Pointer to a buffer that receives the formatted date string.
cchDate
[in] Specifies the size, in TCHARs, of the lpDateStr buffer. If cchDate is zero, the function returns the number of bytes or characters required to hold the formatted date string, and the buffer pointed to by lpDateStr is not used.

Return Values

If the function succeeds, the return value is the number of TCHARs written to the lpDateStr buffer, or if the cchDate parameter is zero, the number of bytes or characters required to hold the formatted date string. The count includes the terminating null.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The earliest date supported by this function is January 1, 1601.

The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the locale identifier.

The date values in the SYSTEMTIME structure pointed to by lpDate must be valid. The function checks each of the date values: year, month, day, and day of week. If the day of the week is incorrect, the function uses the correct value, and returns no error. If any of the other date values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the time portions of the SYSTEMTIME structure pointed to by lpDate: wHour, wMinute, wSecond, and wMilliseconds.

If the lpFormat parameter is a bad format string, no errors are returned. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L"yyyy" and L"yy" (the 'L' indicates a Unicode (16-bit characters) string). If L"y" is passed in, the function assumes L"yy". If L"yyy" is passed in, the function assumes L"yyyy". If more than 4 date (L"dddd") or 4 month (L"MMMM") pictures are passed in, then the function defaults to L"dddd" or L"MMMM".

Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as "May '93", the format string would be: L"MMMM ''''yy" The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

When the date picture contains a numeric form of the day (either d or dd) followed by the full month name (MMMM), the genitive form of the month name is returned in the date string.

To obtain the default short and long date format without performing any actual formatting, use the GetLocaleInfo function with the LOCALE_SSHORTDATE or LOCALE_SLONGDATE parameter. To get the date format for an alternate calendar, use GetLocaleInfo with the LOCALE_IOPTIONALCALENDAR parameter. To get the date format for a particular calendar, use GetCalendarInfo. Also, to return all of the date formats for a particular calendar, you can use EnumCalendarInfo or EnumDateFormatsEx.

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, EnumCalendarInfo, EnumDateFormatsEx, GetCalendarInfo, GetLocaleInfo, GetTimeFormat, SYSTEMTIME


GetGeoInfo

The GetGeoInfo function gets information about a specified location.

int GetGeoInfo(
  GEOID GeoId,         // location identifier
  GEOTYPE GeoType,     // type of information requested
  LPTSTR lpGeoData,    // buffer for results
  int cchData,         // size of buffer
  LANGID language      // language id
);

Parameters

GeoId
[in] Specifies the geographical location for which to get information.
GeoType
[in] Specifies the type of information requested. This is one of the values of the SYSGEOTYPE enumeration type.
lpGeoData
[out] Pointer to the buffer that stores the information.
cchData
[in] Size of the buffer pointed to by lpGeoData. This is the number of bytes if using the ANSI version of the function, or the number of WORDS if using the Unicode version. If this parameter is 0, then the return value of the function is the size of the buffer required to hold the information. See SYSGEOTYPE.
language
[in] Language in which the information is to be returned. The parameter can be NULL, which indicates the returned information is in the system default UI language. The language of the returned information is determined in the following priority:
  • If NULL, information is returned in the system default UI language.
  • If language is not NULL, use the language of the given LCID.
  • If the language of the given LCID is not available, use the language of the first entry with the same primary language as language.
  • If there is no entry with the same primary language as language, use the user default UI language.
  • If the user default UI language is not available, use the user default locale.
  • If the user default locale is not available, use the system default locale.
  • If all else fails, use English.

Return Values

If cchData is 0, the function returns the required size for the buffer pointed to by lpGeoData. Otherwise, if the function succeeds, it returns the number of bytes (ANSI) or WORDS (Unicode) copied to the buffer.

If the function fails, it returns zero.

Remarks

When GeoType is GEO_LCID, the return string is an 8-digit hexadecimal value.

Windows Me: When GeoType is GEO_LCID, the return string is the decimal equivalent of the LCID hexadecimal value.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, SYSGEOTYPE


GetLocaleInfo

The GetLocaleInfo function retrieves information about a locale.

int GetLocaleInfo(
  LCID Locale,      // locale identifier
  LCTYPE LCType,    // information type
  LPTSTR lpLCData,  // information buffer
  int cchData       // size of buffer
);

Parameters

Locale
[in] Specifies the locale to retrieve information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

LCType
[in] Specifies the type of locale information to be retrieved, by using an LCTYPE constant. For a list of LCTYPE constants, see Locale Information.

Note that only one LCTYPE constant may be specified per call, except that an application may use the binary-OR operator to combine LOCALE_NOUSEROVERRIDE or LOCALE_USE_CP_ACP with any other LCTYPE value.

If LOCALE_NOUSEROVERRIDE is combined with another value, the function bypasses user overrides, and returns the system default value for the requested LCID. The information is retrieved from the locale database, even if the LCID is the current one and the user has changed some of the values in Control Panel. If this flag is not specified, the values in Win.ini take precedence over the database settings when getting values for the current system default locale.

lpLCData
[out] Pointer to a buffer that receives the requested data.This pointer is not used if cchData is zero.
cchData
[in] Specifies the size, in TCHARs, of the lpLCData buffer. If cchData is zero, the function returns the number of bytes or characters required to hold the information, including the terminating null character, and the buffer pointed to by lpLCData is not used.

Return Values

If the function succeeds, the return value is the number of TCHARs written to the destination buffer. If the cchData parameter is zero, the return value is the number of bytes or characters required to hold the locale information.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The GetLocaleInfo function always retrieves information in text format. If the information is a numeric value, the function converts the number to text using decimal notation.

The LOCALE_FONTSIGNATURE parameter will return a non-NULL terminated string. In all other cases, the string is NULL terminated.

The ANSI string returned by the ANSI version of this function is translated from Unicode to ANSI based on the default ANSI code page for the LCID. However, if LOCALE_USE_CP_ACP is specified, the translation is based on the system default–ANSI code page.

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, GetStringTypeA, GetStringTypeEx, GetStringTypeW, GetSystemDefaultLCID, GetUserDefaultLCID, LCTYPE Constants, SetLocaleInfo, MAKELCID


GetNumberFormat

The GetNumberFormat function formats a number string as a number string customized for a specified locale.

int GetNumberFormat(
  LCID Locale,                // locale
  DWORD dwFlags,              // options
  LPCTSTR lpValue,            // input number string
  CONST NUMBERFMT *lpFormat,  // formatting information
  LPTSTR lpNumberStr,         // output buffer
  int cchNumber               // size of output buffer
);

Parameters

Locale
[in] Specifies the locale for which the number string is to be formatted. If lpFormat is NULL, the function formats the string according to the number format for this locale. If lpFormat is not NULL, the function uses the locale only for formatting information not specified in the NUMBERFMT structure (for example, the locale's string value for the negative sign).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

dwFlags
[in] Controls the operation of the function. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify LOCALE_NOUSEROVERRIDE to format the string using the system default number format for the specified locale; or you can specify zero to format the string using any user overrides to the locale's default number format.

lpValue
[in] Pointer to a null-terminated string containing the number string to format.

This string can only contain the following characters:

  • Characters '0' through '9'.
  • One decimal point (dot) if the number is a floating-point value.
  • A minus sign in the first character position if the number is a negative value.

All other characters are invalid. The function returns an error if the string pointed to by lpValue deviates from these rules.

lpFormat
[in] Pointer to a NUMBERFMT structure that contains number formatting information. All members in the structure pointed to by lpFormat must contain appropriate values.

If lpFormat is NULL, the function uses the number format of the specified locale.

lpNumberStr
[out] Pointer to a buffer that receives the formatted number string.
cchNumber
[in] Specifies the size, in TCHARs, of the lpNumberStr buffer. If cchNumber is zero, the function returns the number of bytes or characters required to hold the formatted number string, and the buffer pointed to by lpNumberStr is not used.

Return Values

If the function succeeds, the return value is the number of TCHARs written to the buffer pointed to by lpNumberStr, or if the cchNumber parameter is zero, the number of bytes or characters required to hold the formatted number string. The count includes the terminating null.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only locale. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, GetCurrencyFormat, NUMBERFMT


GetOEMCP

The GetOEMCP function retrieves the current original equipment manufacturer (OEM) code-page identifier for the system.

UINT GetOEMCP(void);

Parameters

This function has no parameters.

Return Values

The return value is the current OEM code-page identifier for the system or a default identifier if no code page is current.

Remarks

The following are the OEM code-page identifiers.

Identifier | Meaning
437 | MS-DOS United States
708 | Arabic (ASMO 708)
709 | Arabic (ASMO 449+, BCON V4)
710 | Arabic (Transparent Arabic)
720 | Arabic (Transparent ASMO)
737 | Greek (formerly 437G)
775 | Baltic
850 | MS-DOS Multilingual (Latin I)
852 | MS-DOS Slavic (Latin II)
855 | IBM Cyrillic (primarily Russian)
857 | IBM Turkish
860 | MS-DOS Portuguese
861 | MS-DOS Icelandic
862 | Hebrew
863 | MS-DOS Canadian-French
864 | Arabic
865 | MS-DOS Nordic
866 | MS-DOS Russian
869 | IBM Modern Greek
874 | Thai
932 | Japan
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan; Hong Kong SAR, PRC)
1361 | Korean (Johab)

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetACP


GetSystemDefaultLangID

The GetSystemDefaultLangID function retrieves the language identifier of the system locale.

LANGID GetSystemDefaultLangID(void);

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the language identifier of the system locale. If the function fails, the return value is zero.

Remarks

For more information about language identifiers, see Language Identifiers and Locale Information.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetSystemDefaultLCID , GetUserDefaultLangID, MAKELANGID


GetSystemDefaultLCID

The GetSystemDefaultLCID function retrieves the system default locale identifier.

LCID GetSystemDefaultLCID(void);

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the system default locale identifier. If the function fails, the return value is zero.

Remarks

For more information about locale identifiers, see Locales.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, ConvertDefaultLocale, GetLocaleInfo, GetUserDefaultLCID, MAKELCID


GetSystemDefaultUILanguage

The GetSystemDefaultUILanguage function retrieves the language identifier (LANGID) for the default language of the system.

LANGID GetSystemDefaultUILanguage(void);

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the LANGID for the system default UI language.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetUserDefaultUILanguage, EnumUILanguages


GetThreadLocale

The GetThreadLocale function retrieves the calling thread's current locale.

LCID GetThreadLocale(void);

Parameters

This function has no parameters.

Return Values

The function returns the system's default user locale.

Remarks

When a thread is created, it uses the system default user locale. The system reads the system default user locale from the registry when the system boots. This system default can be modified for future process and thread creation using Control Panel's International application.

For more information about locale identifiers, see Locales.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, SetThreadLocale, GetSystemDefaultLCID, GetUserDefaultLCID


GetTimeFormat

The GetTimeFormat function formats time as a time string for a specified locale. The function formats either a specified time or the local system time.

int GetTimeFormat(
  LCID Locale,              // locale
  DWORD dwFlags,            // options
  CONST SYSTEMTIME *lpTime, // time
  LPCTSTR lpFormat,         // time format string
  LPTSTR lpTimeStr,         // formatted string buffer
  int cchTime               // size of string buffer
);

Parameters

Locale
[in] Specifies the locale for which the time string is to be formatted. If lpFormat is NULL, the function formats the string according to the time format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale's time markers).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

dwFlags
[in] Specifies various function options. You can specify a combination of the following values.
Value | Meaning
LOCALE_NOUSEROVERRIDE | If set, the function formats the string using the system default time format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default time format. This flag cannot be set if lpFormat is non-NULL.
LOCALE_USE_CP_ACP | Uses the system ANSI code page for string translation instead of the locale code page.
TIME_NOMINUTESORSECONDS | Does not use minutes or seconds.
TIME_NOSECONDS | Does not use seconds.
TIME_NOTIMEMARKER | Does not use a time marker.
TIME_FORCE24HOURFORMAT | Always uses a 24-hour time format.

lpTime
[in] Pointer to a SYSTEMTIME structure that contains the time information to be formatted. If this pointer is NULL, the function uses the current local system time.
lpFormat
[in] Pointer to a format picture to use to form the time string. If lpFormat is NULL, the function uses the time format of the specified locale.

Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown (for example, "ss", not "SS"). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.
Picture | Meaning
h | Hours with no leading zero for single-digit hours; 12-hour clock.
hh | Hours with leading zero for single-digit hours; 12-hour clock.
H | Hours with no leading zero for single-digit hours; 24-hour clock.
HH | Hours with leading zero for single-digit hours; 24-hour clock.
m | Minutes with no leading zero for single-digit minutes.
mm | Minutes with leading zero for single-digit minutes.
s | Seconds with no leading zero for single-digit seconds.
ss | Seconds with leading zero for single-digit seconds.
t | One character time-marker string, such as A or P.
tt | Multicharacter time-marker string, such as AM or PM.

For example, to get the time string

"11:29:40 PM"

use the following picture string:

"hh':'mm':'ss tt"
lpTimeStr
[out] Pointer to a buffer that receives the formatted time string.
cchTime
[in] Specifies the size, in TCHARs, of the lpTimeStr buffer. If cchTime is zero, the function returns the number of bytes or characters required to hold the formatted time string, and the buffer pointed to by lpTimeStr is not used.

Return Values

If the function succeeds, the return value is the number of TCHARs written to the buffer pointed to by lpTimeStr. If the cchTime parameter is zero, the return value is the number of bytes or characters required to hold the formatted time string. The count includes the terminating null.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

If a time marker exists and the TIME_NOTIMEMARKER flag is not set, the function localizes the time marker based on the specified locale identifier. Examples of time markers are "AM" and "PM" for US English.

The time values in the SYSTEMTIME structure pointed to by lpTime must be valid. The function checks each of the time values to determine that it is within the appropriate range of values. If any of the time values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the date portions of the SYSTEMTIME structure pointed to by lpTime: wYear, wMonth, wDayOfWeek, and wDay.

If TIME_NOMINUTESORSECONDS or TIME_NOSECONDS is specified, the function removes the separator(s) preceding the minutes and/or seconds element(s).

If TIME_NOTIMEMARKER is specified, the function removes the separator(s) preceding and following the time marker.

If TIME_FORCE24HOURFORMAT is specified, the function displays any existing time marker, unless the TIME_NOTIMEMARKER flag is also set.

The function does not include milliseconds as part of the formatted time string.

To use LOCALE_NOUSEROVERRIDE, lpFormat must be NULL.

No errors are returned for a bad format string. The function simply forms the best time string that it can. If more than two hour, minute, second, or time marker format pictures are passed in, then the function defaults to two. For example, the only time marker pictures that are valid are L"t" and L"tt" (the 'L' indicates a Unicode (16-bit characters) string). If L"ttt" is passed in, the function assumes L"tt".

To obtain the time format without performing any actual formatting, use the GetLocaleInfo function with the LOCALE_STIMEFORMAT parameter.

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only locale. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, GetDateFormat, GetLocaleInfo, SYSTEMTIME


GetUserDefaultLangID

The GetUserDefaultLangID function retrieves the language identifier of the current user locale.

LANGID GetUserDefaultLangID(void);

Parameters

This function has no parameters.

Return Values

If the function is successful, the return value is the language identifier of the current user locale. If the function fails, the return value is zero.

Remarks

The return value is not necessarily the same as that returned by GetSystemDefaultLangID, even if the computer is a single-user system.

For more information about language identifiers, see Language Identifiers and Locale Information.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetSystemDefaultLangID, MAKELANGID


GetUserDefaultLCID

The GetUserDefaultLCID function retrieves the user default–locale identifier.

LCID GetUserDefaultLCID(void);

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the user default–locale identifier. If the function fails, the return value is zero.

Remarks

On single-user systems, the return value is the same as that returned by GetSystemDefaultLCID.

For more information about locale identifiers, see Locales.

MAPI: For more information, see Syntax and Limitations for Win32 Functions Useful in MAPI Development.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, ConvertDefaultLocale, GetLocaleInfo, GetSystemDefaultLCID, MAKELCID


GetUserDefaultUILanguage

The GetUserDefaultUILanguage function retrieves the language identifier (LANGID) for the current user language.

LANGID GetUserDefaultUILanguage(void);

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the LANGID for the current user's UI language.

If the function fails, the return value is zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetSystemDefaultUILanguage, EnumUILanguages


GetUserGeoID

The GetUserGeoID function gets information about the geographical location of the user.

GEOID GetUserGeoID(
  GEOCLASS  GeoClass         // location class
);

Parameters

GeoClass
[in] Specifies the geographical location class to return. Currently, this must be GEOCLASS_NATION.

Return Values

If SetUserGeoID has been called before, this function returns the GeoID of the user.

If there is no GeoID for the user and GeoClass has been set, the function returns GEOID_NOT_AVAILABLE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, SetUserGeoID


IsValidCodePage

The IsValidCodePage determines whether a specified code page is valid.

BOOL IsValidCodePage(
  UINT CodePage   // code page
);

Parameters

CodePage
[in] Specifies the code page to check. Each code page is identified by a unique number.

Return Values

If the code page is valid, the return values is a nonzero value.

If the code page is not valid, the return value is zero.

Remarks

A code page is considered valid only if it is installed in the system.

The following are the code-page identifiers.

Identifier | Meaning
037 | EBCDIC
437 | MS-DOS United States
500 | EBCDIC "500V1"
708 | Arabic (ASMO 708)
709 | Arabic (ASMO 449+, BCON V4)
710 | Arabic (Transparent Arabic)
720 | Arabic (Transparent ASMO)
737 | Greek (formerly 437G)
775 | Baltic
850 | MS-DOS Multilingual (Latin I)
852 | MS-DOS Slavic (Latin II)
855 | IBM Cyrillic (primarily Russian)
857 | IBM Turkish
860 | MS-DOS Portuguese
861 | MS-DOS Icelandic
862 | Hebrew
863 | MS-DOS Canadian-French
864 | Arabic
865 | MS-DOS Nordic
866 | MS-DOS Russian
869 | IBM Modern Greek
874 | Thai
875 | EBCDIC
932 | Japan
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan; Hong Kong SAR, PRC)
1026 | EBCDIC
1250 | Windows 3.1 Eastern European
1251 | Windows 3.1 Cyrillic
1252 | Windows 3.1 US (ANSI)
1253 | Windows 3.1 Greek
1254 | Windows 3.1 Turkish
1255 | Hebrew
1256 | Arabic
1257 | Baltic
1361 | Korean (Johab)
10000 | Macintosh Roman
10001 | Macintosh Japanese
10006 | Macintosh Greek I
10007 | Macintosh Cyrillic
10029 | Macintosh Latin 2
10079 | Macintosh Icelandic
10081 | Macintosh Turkish

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetACP, GetCPInfo, GetOEMCP


IsValidLanguageGroup

The IsValidLanguageGroup function determines whether a specified language-group identifier is valid. Currently, the function tests whether a language group identifier is installed or supported on the calling system.

BOOL IsValidLanguageGroup(
  LGRPID LanguageGroup,     // language-group identifier
  DWORD dwFlags             // validity test
);

Parameters

LanguageGroup
[in] Language-group identifier to be validated. This can be one of the following values.
LGRPID_WESTERN_EUROPE
LGRPID_CENTRAL_EUROPE
LGRPID_ARABIC
LGRPID_ARMENIAN
LGRPID_BALTIC
LGRPID_CYRILLIC
LGRPID_GEORGIAN
LGRPID_GREEK
LGRPID_HEBREW 		LGRPID_INDIC
LGRPID_JAPANESE
LGRPID_KOREAN
LGRPID_SIMPLIFIED_CHINESE
LGRPID_TRADITIONAL_CHINESE
LGRPID_THAI
LGRPID_TURKISH
LGRPID_VIETNAMESE
dwFlags
[in] Specifies the validity test to apply to the language-group identifier. This can be one of the following values.
Value | Meaning
LGRPID_INSTALLED | Tests whether the language-group identifier is both supported and installed.
LGRPID_SUPPORTED | Tests whether the language-group identifier is supported.

Return Value

If the language-group identifier passes the specified validity test, the return value is TRUE.

If the language-group identifier does not pass the specified validity test, the return value is FALSE.

Remarks

If the LGRPID_INSTALLED flag is specified and this function returns TRUE, the language-group identifier is both supported and installed on the system.

If the LGRPID_SUPPORTED flag is specified and this function returns TRUE, the language-group identifier is supported in the release, but not necessarily installed on the system.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, EnumSystemLanguageGroups, EnumLanguageGroupLocales


IsValidLocale

The IsValidLocale function determines whether a specified locale identifier is valid. Currently, the function tests whether a locale identifier is installed or supported on the calling system, based on the specified validity test.

BOOL IsValidLocale(
  LCID Locale,    // locale identifier
  DWORD dwFlags   // validity test
);

Parameters

Locale
[in] Specifies the locale identifier to be validated. You can use the MAKELCID macro to create a locale identifier.
dwFlags
[in] Specifies the validity test to apply to the locale identifier. This parameter can be one of the following values.
Value | Meaning
LCID_INSTALLED | Test whether the locale identifier is both supported and installed.
LCID_SUPPORTED | Test whether the locale identifier is supported.

Return Values

If the locale identifier passes the specified validity test, the return values is a nonzero value.

If the locale identifier does not pass the specified validity test, the return value is zero.

Remarks

If the LCID_INSTALLED flag is specified and this function returns a nonzero value, the locale identifier is both supported and installed on the system. Having an LCID installed implies that the full level of language support is available for this locale. This includes code page translation tables, keyboard layouts, fonts, sorting and locale data.

If LCID_SUPPORTED is specified and this function returns zero, the locale identifier is supported in the release, but not necessarily installed on the system.

For more information, see Locales.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetLocaleInfo


LCMapString

The LCMapString function either maps an input character string to another using a specified transformation or generates a sort key for the input string.

int LCMapString(
  LCID Locale,       // locale identifier
  DWORD dwMapFlags,  // mapping transformation type
  LPCTSTR lpSrcStr,  // source string
  int cchSrc,        // number of characters in source string
  LPTSTR lpDestStr,  // destination buffer
  int cchDest        // size of destination buffer
);

Parameters

Locale
[in] Specifies a locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the MAKELCID macro to create a locale identifier.
dwMapFlags
[in] Specifies the type of transformation used during string mapping or the type of sort key generated. An application can specify one or more of the following options. Restrictions are noted following the table.
Option | Meaning
LCMAP_BYTEREV | Windows NT/2000 or later: Use byte reversal. For example, if you pass in 0x3450 0x4822 the result is 0x5034 0x2248.
LCMAP_FULLWIDTH | Uses wide characters (where applicable).
LCMAP_HALFWIDTH | Uses narrow characters (where applicable).
LCMAP_HIRAGANA | Hiragana.
LCMAP_KATAKANA | Katakana.
LCMAP_LINGUISTIC_CASING | Uses linguistic rules for casing, rather than file system rules (the default). Valid with LCMAP_LOWERCASE or LCMAP_UPPERCASE only.
LCMAP_LOWERCASE | Uses lowercase.
LCMAP_SIMPLIFIED_CHINESE | Windows NT 4.0 and later: Maps traditional Chinese characters to simplified Chinese characters.
LCMAP_SORTKEY | Produces a normalized wide character–sort key. For more information, see lpDestStr and Remarks.
LCMAP_TRADITIONAL_CHINESE | Windows NT 4.0 and later: Maps simplified Chinese characters to traditional Chinese characters.
LCMAP_UPPERCASE | Uses uppercase.

The following flags are used only with the LCMAP_SORTKEY flag.
Flag | Meaning
NORM_IGNORECASE | Ignores case.
NORM_IGNOREKANATYPE | Does not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana will compare as equal.
NORM_IGNORENONSPACE | Ignores nonspacing. This flag also removes Japanese accent characters.
NORM_IGNORESYMBOLS | Ignores symbols.
NORM_IGNOREWIDTH | Does not differentiate between a single-byte character and the same character as a double-byte character.
SORT_STRINGSORT | Treats punctuation the same as symbols.

If the LCMAP_SORTKEY flag is not specified, the LCMapString function performs string mapping. In this case the following restrictions apply:

  • LCMAP_LOWERCASE and LCMAP_UPPERCASE are mutually exclusive.
  • LCMAP_HIRAGANA and LCMAP_KATAKANA are mutually exclusive.
  • LCMAP_HALFWIDTH and LCMAP_FULLWIDTH are mutually exclusive.
  • LCMAP_TRADITIONAL_CHINESE and LCMAP_SIMPLIFIED_CHINESE are mutually exclusive.
  • LCMAP_LOWERCASE and LCMAP_UPPERCASE are not valid in combination with any of these flags: LCMAP_HIRAGANA, LCMAP_KATAKANA, LCMAP_HALFWIDTH, LCMAP_FULLWIDTH.

When the LCMAP_SORTKEY flag is specified, the LCMapString function generates a sort key. In this case the following restriction applies:

  • LCMAP_SORTKEY is mutually exclusive with all other LCMAP_* flags, with the sole exception of LCMAP_BYTEREV.
lpSrcStr
[in] Pointer to a source string that the function maps or uses for sort key generation.
cchSrc
[in] Specifies the number of TCHARs in the string pointed to by the lpSrcStr parameter.

This count can include the NULL terminator, or not include it. If the NULL terminator is included in the character count, it does not greatly affect the mapping behavior. That is because NULL is considered to be unsortable, and always maps to itself.

A cchSrc value of –1 specifies that the string pointed to by lpSrcStr is null-terminated. If this is the case, and LCMapString is being used in its string-mapping mode, the function calculates the string's length itself, and null-terminates the mapped string stored into *lpDestStr.

lpDestStr
[out] Pointer to a buffer that receives the mapped string or sort key.

If LCMAP_SORTKEY is specified, LCMapString stores a sort key into the buffer. The sort key is stored as an array of byte values in the following format:

[all Unicode sort weights] 0x01 [all Diacritic weights] 0x01 [all Case weights] 0x01 [all Special weights] 0x00

Note that the sort key is null-terminated. This is true regardless of the value of cchSrc. Also note that, even if some of the sort weights are absent from the sort key, due to the presence of one or more ignore flags in dwMapFlags, the 0x01 separators and the 0x00 terminator are still present.

cchDest
[in] Specifies the size, in TCHARs, of the buffer pointed to by lpDestStr.

If the function is being used for string mapping, the size is a character count. If space for a NULL terminator is included in cchSrc, then cchDest must also include space for a NULL terminator.

If the function is being used to generate a sort key, the size is a byte count. This byte count must include space for the sort key 0x00 terminator.

If cchDest is zero, the function's return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, required to hold the mapped string or sort key. In this case, the buffer pointed to by lpDestStr is not used.

Return Values

If the function succeeds, and the value of cchDest is nonzero, the return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, written to the buffer. This count includes room for a NULL terminator.

If the function succeeds, and the value of cchDest is zero, the return value is the size of the buffer in characters, or bytes if LCMAP_SORTKEY is specified, required to receive the translated string or sort key. This size includes room for a NULL terminator.

If the function fails, the return value is 0. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The mapped string is null terminated if the source string is null terminated.

The ANSI version of this function maps strings to and from Unicode based on the specified LCID's default ANSI code page.

For the ANSI version of this function, the LCMAP_UPPERCASE flag produces the same result as CharUpper in the locale. Likewise, the LCMAP_LOWERCASE flag produces the same result as CharLower. This function always maps a single character to a single character.

If LCMAP_UPPERCASE or LCMAP_LOWERCASE is set and if LCMAP_SORTKEY is not set, the lpSrcStr and lpDestStr pointers can be the same. Otherwise, the lpSrcStr and lpDestStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

If the LCMAP_HIRAGANA flag is specified to map Katakana characters to Hiragana characters, and LCMAP_FULLWIDTH is not specified, the function only maps full-width characters to Hiragana. In this case, any half-width Katakana characters are placed as-is in the output string, with no mapping to Hiragana. An application must specify LCMAP_FULLWIDTH if it wants half-width Katakana characters mapped to Hiragana.

Even if the Unicode version of this function is called, the output string is only in WCHAR or CHAR format if the string mapping mode of LCMapString is used. If the sort key generation mode is used, specified by LCMAP_SORTKEY, the output is an array of byte values. To compare sort keys, use a byte-by-byte comparison.

An application can call the function with the NORM_IGNORENONSPACE and NORM_IGNORESYMBOLS flags set, and all other options flags cleared, in order to simply strip characters from the input string. If this is done with an input string that is not null-terminated, it is possible for LCMapString to return an empty string and not return an error.

The LCMapString function ignores the Arabic Kashida. If an application calls the function to create a sort key for a string containing an Arabic Kashida, there will be no sort key value for the Kashida.

The function treats the hyphen and apostrophe a bit differently than other punctuation symbols, so that words like coop and co-op stay together in a list. All punctuation symbols other than the hyphen and apostrophe sort before the alphanumeric characters. An application can change this behavior by setting the SORT_STRINGSORT flag. See CompareString for a more detailed discussion of this issue.

When LCMapString is used to generate a sort key, by setting the LCMAP_SORTKEY flag, the sort key stored into *lpDestStr may contain an odd number of bytes. The LCMAP_BYTEREV option only reverses an even number of bytes. If both options are chosen, the last (odd-positioned) byte in the sort key is not reversed. If the terminating 0x00 byte is an odd-positioned byte, then it remains the last byte in the sort key. If the terminating 0x00 byte is an even-positioned byte, it exchanges positions with the byte that precedes it.

When LCMAP_SORTKEY flag is specified, the function generates a sort key that, when used in strcmp, produces the same order as when the original string is used in CompareString. When LCMAP_SORTKEY flag is specified, the output string is a string, but the character values are not meaningful display values.

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only locale. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, CharLower, CharUpper, CompareString, FoldString, MAKELCID


SetCalendarInfo

The SetCalendarInfo function sets an item of locale information for a calendar.

int SetCalendarInfo(
  LCID Locale,       // locale
  CALID Calendar,    // calendar
  CALTYPE CalType,   // calendar information type
  LPCTSTR lpCalData  // calendar data
);

Parameters

Locale
[in] Locale identifier (LCID). The LCID can be created by the MAKELCID macro, or it can be one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

Calendar
[in] Identifier for the calendar whose information will be set.
CalType
[in] Type of calendar information to be set. Only one CALTYPE may be specified per call, except that an application may use the binary OR operator to combine CAL_USE_CP_ACP with any valid CALTYPE value. The CAL_USE_CP_ACP value is only used with the ANSI version of SetCalendarInfo

Windows 98/Me: The following CALTYPE values are valid for this function:

CAL_NOUSEROVERRIDE
CAL_USE_CP_ACP
CAL_RETURN_NUMBER
CAL_ITWODIGITYEARMAX

For more information on CALTYPE values, see Calendar Type Information.

lpCalData
[in] Pointer to a null-terminated string that contains the calendar information. The information must be in the format of the specified CalType.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INVALID_ACCESS
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

This function only affects the user override portion of the calendar settings; it does not set the system defaults.

The calendar information is always passed in as a null-terminated Unicode string in the Unicode version of the function, and as a null-terminated ANSI string in the ANSI version. No integers are allowed by this function; any numeric values must be specified as either Unicode or ANSI text.

Windows 98/Me: CAL_ITWODIGITYEARMAX is only supported for Gregorian calendars.

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only locale. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetCalendarInfo


SetLocaleInfo

The SetLocaleInfo function sets an item of locale information. This setting only affects the user override portion of the locale settings; it does not set the system defaults.

BOOL SetLocaleInfo(
  LCID Locale,       // locale identifier
  LCTYPE LCType,     // information type
  LPCTSTR lpLCData   // information buffer
);

Parameters

Locale
[in] Specifies the locale whose information the function will set. The locale provides a context for the string mapping or sort key generation. An application can use the MAKELCID macro to create a locale identifier.
LCType
[in] Specifies the type of locale information to be set by the function. Note that only one LCTYPE may be specified per call. Not all LCTYPE values are valid; see the list of valid LCTYPE values in the following Remarks section.
lpLCData
[in] Pointer to a null-terminated string containing the locale information the function will set. The information must be in the specified LCTYPE's particular format.

Return Values

If the function succeeds, the return values is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

  • ERROR_INVALID_ACCESS
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The locale information is always passed in as a null-terminated Unicode string in the Unicode version of the function, and as a null-terminated ANSI string in the ANSI version. No integers are allowed by this function; any numeric values must be specified as Unicode or ANSI text. Each LCTYPE has a particular format, as noted in Locales. Note that several of the LCTYPE values are linked together, so that changing one changes another value as well. For more information, see Locale Information.

Only the following LCTYPE values are valid for this function:

LOCALE_ICALENDARTYPE
LOCALE_ICURRDIGITS
LOCALE_ICURRENCY
LOCALE_IDIGITS
LOCALE_IFIRSTDAYOFWEEK
LOCALE_IFIRSTWEEKOFYEAR
LOCALE_ILZERO
LOCALE_IMEASURE
LOCALE_INEGCURR
LOCALE_INEGNUMBER
LOCALE_IPAPERSIZE
LOCALE_ITIME
LOCALE_S1159
LOCALE_S2359
LOCALE_SCURRENCY 		LOCALE_SDATE
LOCALE_SDECIMAL
LOCALE_SGROUPING
LOCALE_SLIST
LOCALE_SLONGDATE
LOCALE_SMONDECIMALSEP
LOCALE_SMONGROUPING
LOCALE_SMONTHOUSANDSEP
LOCALE_SNEGATIVESIGN
LOCALE_SPOSITIVESIGN
LOCALE_SSHORTDATE
LOCALE_STHOUSAND
LOCALE_STIME
LOCALE_STIMEFORMAT
LOCALE_SYEARMONTH

Windows 2000 or later: The ANSI version of this function will fail if it is used with a Unicode-only locale. See Language Identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

National Language Support Overview, National Language Support Functions, GetLocaleInfo, MAKELCID


SetThreadLocale

The SetThreadLocale function sets the calling thread's current locale.

BOOL SetThreadLocale (
  LCID Locale   // locale identifier
);

Parameters

Locale
[in] Specifies the new locale for the calling thread. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value | Meaning
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.

For more information, see Locales.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

When a thread is created, it uses the system default thread locale. The system reads the system default thread locale from the registry when the system boots. This system default can be modified for future process and thread creation using Control Panel's International application.

The SetThreadLocale function affects the selection of resources that are defined with a LANGUAGE statement. This affects such functions as CreateDialog, DialogBox, LoadMenu, LoadString, and FindResource, and sets the code page implied by CP_THREAD_ACP, but does not affect FindResourceEx.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, CreateDialog, DialogBox, LoadMenu, LoadString, FindResource, GetThreadLocale, GetSystemDefaultLCID, GetUserDefaultLCID, MAKELCID


SetUserGeoID

The SetUserGeoID function sets the geographical location of the user.

BOOL SetUserGeoID(
  GEOID  GeoID         // user's geographical ID
);

Parameters

GeoID
[in] Geographical location of the user.

Return Values

If the function succeeds, it returns TRUE.

If the function fails, it returns FALSE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

National Language Support Overview, National Language Support Functions, GetUserGeoID


National Language Support Structures

The following structures are used with national language support.

CPINFO
CPINFOEX
CURRENCYFMT
NUMBERFMT


CPINFO

The CPINFO structure contains information about a code page.

struct _cpinfo {
  UINT MaxCharSize;
  BYTE DefaultChar[MAX_DEFAULTCHAR];
  BYTE LeadByte[MAX_LEADBYTES];
} CPINFO, *LPCPINFO;

Members

MaxCharSize
Specifies the maximum length, in bytes, of a character in this code page.
DefaultChar
Specifies the default character used in translations into this code page. This character is used by the WideCharToMultiByte function if an explicit default character is not specified.
LeadByte
Specifies a fixed-length array of lead-byte ranges, where the number of lead-byte ranges is variable. If there are no lead bytes in this code page, then every element of the array is NULL. If there are lead bytes in this code page, a starting value and ending value is specified for each range. Ranges are inclusive. The maximum number of lead-byte ranges for any code page is five. The array uses two bytes to describe each range, with a double-byte null terminator after the last range.

Remarks

Lead bytes are unique to double-byte character sets (DBCS). A lead byte is the first byte of a 2-byte character in a DBCS. Lead bytes occupy a specific range of byte values.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Structures, GetCPInfo, WideCharToMultiByte


CPINFOEX

The CPINFOEX structure contains information about a code page. It is used by the GetCPInfoEx function.

typedef struct _cpinfoex {
  UINT    MaxCharSize;
  BYTE    DefaultChar[MAX_DEFAULTCHAR];
  BYTE    LeadByte[MAX_LEADBYTES];
  WCHAR   UnicodeDefaultChar;
  UINT    CodePage;
  TCHAR   CodePageName[MAX_PATH];
} CPINFOEX, *LPCPINFOEX;

Members

MaxCharSize
Specifies the maximum length, in bytes, of a character in the code page.
DefaultChar
Specifies the default character used when translating character strings into this code page. This character is used by the WideCharToMultiByte function if an explicit default character is not specified.
LeadByte
Specifies a fixed-length array of lead-byte ranges, where the number of lead-byte ranges is variable. If there are no lead bytes in this code page, every element of the array is NULL. If there are lead bytes in this code page, the array contains a starting and ending value for each range. Ranges are inclusive. The maximum number of lead-byte ranges for any code page is five. The array uses 2 bytes to describe each range, with a double-byte null terminator after the last range.
UnicodeDefaultChar
Specifies the Unicode default character used in translations from this code page. This character is used by the MultiByteToWideChar function.
CodePage
Specifies the code page value.
CodePageName
Specifies the full, localized name of the code page.

Remarks

Lead bytes are unique to double-byte character sets (DBCS). A lead byte is the first byte of a 2-byte character in a DBCS. Lead bytes occupy a specific range of byte values.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winnls.h; include Windows.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

National Language Support Overview, National Language Support Structures, GetCPInfoEx, MultiByteToWideChar, WideCharToMultiByte


CURRENCYFMT

The CURRENCYFMT structure contains information that defines the format of a currency string. The GetCurrencyFormat function uses this information to customize a currency string for a specified locale.

typedef struct _currencyfmt {
  UINT      NumDigits;
  UINT      LeadingZero;
  UINT      Grouping;
  LPTSTR    lpDecimalSep;
  LPTSTR    lpThousandSep;
  UINT      NegativeOrder;
  UINT      PositiveOrder;
  LPTSTR    lpCurrencySymbol;
} CURRENCYFMT, *LPCURRENCYFMT;

Members

NumDigits
Specifies the number of fractional digits. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_IDIGITS.
LeadingZero
Specifies whether to use leading zeroes in decimal fields. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ILZERO.
Grouping
Specifies the size of each group of digits to the left of the decimal. Values in the range 0 – 9 are valid.
lpDecimalSep
Pointer to a null-terminated decimal separator string.
lpThousandSep
Pointer to a null-terminated thousand separator string.
NegativeOrder
Specifies the negative currency mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_INEGCURR.
PositiveOrder
Specifies the positive currency mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ICURRENCY.
lpCurrencySymbol
Pointer to a null-terminated currency symbol string.

Remarks

For more information about the LCTYPE constants, see Locale Information.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

National Language Support Overview, National Language Support Structures, GetCurrencyFormat


NUMBERFMT

The NUMBERFMT structure contains information that defines the format of a number string. The GetNumberFormat function uses this information to customize a number string for a specified locale.

typedef struct _numberfmt {
  UINT      NumDigits;
  UINT      LeadingZero;
  UINT      Grouping;
  LPTSTR    lpDecimalSep;
  LPTSTR    lpThousandSep;
  UINT      NegativeOrder;
} NUMBERFMT, *LPNUMBERFMT;

Members

NumDigits
Specifies the number of fractional digits. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_IDIGITS.
LeadingZero
Specifies whether to use leading zeroes in decimal fields. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ILZERO.
Grouping
Specifies the size of each group of digits to the left of the decimal. Values in the range 0 – 9 and 32 are valid. For example, grouping by thousands is indicated by 3, while the Indic grouping of the first thousand and then by hundreds is indicated by 32—that is, three digits, then two-digit groupings thereafter.
lpDecimalSep
Pointer to a null-terminated decimal separator string.
lpThousandSep
Pointer to a null-terminated thousand separator string.
NegativeOrder
Specifies the negative number mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_INEGNUMBER.

Remarks

For more information about the LCTYPE constants, see Locale Information.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

National Language Support Overview, National Language Support Structures, GetNumberFormat


National Language Support Macros

The following macros are used with national language support.

LANGIDFROMLCID
MAKELANGID
MAKELCID
MAKESORTLCID
PRIMARYLANGID
SORTIDFROMLCID
SORTVERSIONFROMLCID
SUBLANGID


LANGIDFROMLCID

The LANGIDFROMLCID macro retrieves a language identifier from a locale identifier.

WORD LANGIDFROMLCID(
  LCID lcid  // locale identifier
);

Parameters

lcid
Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Return Values

The return value is a language identifier.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Macros, MAKELANGID, MAKELCID, PRIMARYLANGID, SUBLANGID


MAKELANGID

The MAKELANGID macro creates a language identifier from a primary language identifier and a sublanguage identifier.

WORD MAKELANGID(
  USHORT usPrimaryLanguage,  // primary language identifier
  USHORT usSubLanguage       // sublanguage identifier
);

Parameters

usPrimaryLanguage
Specifies the primary language identifier. This parameter can be one in the list of primary language identifiers or a user-defined primary language.

For a user-defined language, usPrimaryLanguage is a value in the range 0x0200 to 0x03FF. All other values are reserved for system use.

usSubLanguage
Specifies the sublanguage identifier. This parameter can be a value from the list of sublanguage identifiers or a user-defined sublanguage.

For a user-defined sublanguage, usSubLanguage is a value in the range 0x20 to 0x3F. All other values are reserved for system use.

Return Values

The return value is a language identifier.

Remarks

The following three combinations of usPrimaryLanguage and usSubLanguage have special meaning.

Primary language identifier | Sublanguage identifier | Meaning
LANG_NEUTRAL | SUBLANG_NEUTRAL | Language neutral
LANG_NEUTRAL | SUBLANG_DEFAULT | User default language
LANG_NEUTRAL | SUBLANG_SYS_DEFAULT | System default language

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Macros, EnumSystemLocales, LANGIDFROMLCID, MAKELCID, PRIMARYLANGID, SUBLANGID


MAKELCID

The MAKELCID macro creates a locale identifier from a language identifier.

DWORD MAKELCID(
  WORD wLanguageID,  // language identifier
  WORD wSortID       // sorting identifier
);

Parameters

wLanguageID
Specifies the language identifier. This parameter is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.
wSortID
Specifies the sort identifier. For a list of the defined values, see the sort identifiers.

Return Values

The return value is a locale identifier.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Macros, LANGIDFROMLCID, MAKELANGID, SORTIDFROMLCID


MAKESORTLCID

The MAKESORTLCID macro constructs the locale identifier from a language identifier, a sort identifier, and the sort version.

DWORD MAKESORTLCID(
  WORD wLanguageID,  // language identifier
  WORD wSortID,      // sorting identifier
  WORD wSortVersion  // sort version
);

Parameters

wLanguageID
Specifies the language identifier. This parameter is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.
wSortID
Specifies the sort identifier. For a list of the defined values, see the sort identifiers.
wSortVersion
Reserved. Must be zero.

Return Values

The return value is a locale identifier.

Remarks

The LOCALE_INVARIANT is a special locale identifier that is locale independent. It is designed for system level functions that require consistent results (for example, sorting in the file system) regardless of the locale that the user has chosen. Typically, an application does not use LOCALE_INVARIANT because it expects the results of an action to depend on the rules governing each individual locale.

LOCALE_INVARIANT is defined as LANG_INVARIANT for the primary language, SUBLANG_NEUTRAL for the sub-language, and SORT_DEFAULT for the sort id.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Macros, National Language Support Overview, National Language Support Macros, MAKELANGID


PRIMARYLANGID

The PRIMARYLANGID macro extracts a primary language identifier from a language identifier.

WORD PRIMARYLANGID(
  WORD lgid  // language identifier
);

Parameters

lgid
Specifies the language identifier. This value is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.

Return Values

The return value is a primary language identifier. It can be one of the defined primary language identifiers or a user-defined primary language identifier.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Macros, EnumSystemLocales, LANGIDFROMLCID, MAKELANGID, SUBLANGID


SORTIDFROMLCID

The SORTIDFROMLCID macro retrieves a sort identifier from a locale identifier.

WORD SORTIDFROMLCID(
  LCID lcid  // locale identifier
);

Parameters

lcid
Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Return Values

The return value is a sort identifier. For a list of defined values, see sort identifiers.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Macros, MAKELANGID, MAKELCID, PRIMARYLANGID, SUBLANGID


SORTVERSIONFROMLCID

The SORTVERSIONFROMLCID macro retrieves the sort version from a locale identifier.

WORD SORTVERSIONFROMLCID(
  LCID lcid  // locale identifier
);

Parameters

lcid
Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Return Values

The return value is the sort version. Currently, it only returns zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Macros, National Language Support Overview, National Language Support Macros, MAKELCID


SUBLANGID

The SUBLANGID macro extracts a sublanguage identifier from a language identifier.

WORD SUBLANGID(
  WORD lgid  // language identifier
);

Parameters

lgid
Specifies the language identifier. This value is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.

Return Values

The return value is a sublanguage identifier. This can be one of the defined sublanguage identifiers or a user-defined sublanguage identifier.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

National Language Support Overview, National Language Support Macros, EnumSystemLocales, LANGIDFROMLCID, MAKELANGID, PRIMARYLANGID


National Language Support Enumeration Types

The following enumeration types are used with National Language Support.

SYSGEOCLASS
SYSGEOTYPE


SYSGEOCLASS

The SYSGEOCLASS enumeration type specifies the geographical location class.

enum SYSGEOCLASS {
  GEOCLASS_NATION  = 16,
  GEOCLASS_REGION  = 14,
};

Enumeration Values

GEOCLASS_NATION
Nation GeoIDs
GEOCLASS_REGION
Region GeoIDs

Remarks

Currently, only GEOCLASS_NATION is supported.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.


SYSGEOTYPE

The SYSGEOTYPE enumeration type defines the type of information requested in the GetGeoInfo function.

enum SYSGEOTYPE {
  GEO_NATION      =       0x0001,
  GEO_LATITUDE    =       0x0002,
  GEO_LONGITUDE   =       0x0003,
  GEO_ISO2        =       0x0004,
  GEO_ISO3        =       0x0005,
  GEO_RFC1766     =       0x0006,
  GEO_LCID        =       0x0007,
  GEO_FRIENDLYNAME=       0x0008,
  GEO_OFFICIALNAME=       0x0009,
  GEO_TIMEZONES   =       0x000A,
  GEO_OFFICIALLANGUAGES = 0x000B,
};

Enumeration Values

GEO_NATION
GEOID of a nation. This value is stored in a long integer.
GEO_LATITUDE
The latitude of the GEOID. This value is stored in a floating point number.
GEO_LONGITUDE
The longitude of the GEOID. This value is stored in a floating point number.
GEO_ISO2
The ISO 2-letter country code (for nations only). This value is stored in a string.
GEO_ISO3
The ISO 3-letter country code (for nations only). This value is stored in a string.
GEO_RFC1766
An RFC1766-style string derived from the locale and GEOID (for nations only).
GEO_LCID
A locale ID (LCID) derived from the language and the GeoID (for nations only).
GEO_FRIENDLYNAME
The friendly name of the nation. Example: Germany. This value is stored in a string.
GEO_OFFICIALNAME
The official name of the nation. Example: Federal Republic of Germany. This value is stored in a string.
GEO_TIMEZONES
The time zones associated with the GEOID. These values are stored in an array of IDs.
GEO_OFFICIALLANGUAGES
The official languages of the nation at the GEOID. These values are stored in an array of LCIDs.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Winnls.h; include Windows.h.


National Language Support Constants

The following sections describe the constants used with the national language support functions.

  • Locale Information
  • Day, Month, Year, and Era Format Pictures
  • Hour, Minute, and Second Format Pictures
  • Primary Language Identifiers
  • SubLanguage Identifiers
  • Language Identifiers
  • Sort Identifiers
  • Calendar Type Information
  • Language Code and Scripts


Locale Information

An LCTYPE constant is a constant that specifies a particular piece of locale information. The values in the following list correspond to the names of these values in the configuration registry, under both the user's preferences (as values in the registry key HKEY_CURRENT_USER\Control Panel\International) and the system's installed languages (as files pointed to by registry keys, one key per language installed, under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\NLS). All values are null-terminated Unicode strings. If no maximum length is indicated, the strings may vary in length.

The following are locale, or LCTYPE, constants.

LOCALE_FONTSIGNATURE
Windows 95 and Windows NT 4.0 and later: A bit pattern used to determine the relationship between character coverage needed to support the locale and the font contents. For more information, see FONTSIGNATURE.
LOCALE_ICALENDARTYPE
Current calendar type. The maximum number of characters allowed for this string is two. This type can be one of the following values.
Value | Meaning
1 | Gregorian (localized)
2 | Gregorian (English strings always)
3 | Year of the Emperor (Japan)
4 | Taiwan Calendar
5 | Tangun Era (Korea)
6 | Hijri (Arabic lunar)
7 | Thai
8 | Hebrew (Lunar)
9 | Gregorian Middle East French calendar
10 | Gregorian Arabic calendar
11 | Gregorian Transliterated English calendar
12 | Gregorian Transliterated French calendar

LOCALE_ICENTURY
Specifier for a 2-digit or 4-digit century for the short date only. The maximum number of characters allowed for this string is two. The specifier can be one of the following values.
Value | Meaning
0 | Abbreviated 2-digit century
1 | Full 4-digit century

LOCALE_ICOUNTRY
Country/region code, based on international phone codes, also referred to as IBM country codes. The maximum number of characters allowed for this string is six.
LOCALE_ICURRDIGITS
Number of fractional digits for the local monetary format. The maximum number of characters allowed for this string is three.
LOCALE_ICURRENCY
Position of the monetary symbol in the positive currency mode. The maximum number of characters allowed for this string is two. The mode can be one of the following values.
Value | Meaning
0 | Prefix, no separation, for example $1.1
1 | Suffix, no separation, for example 1.1$
2 | Prefix, 1-character separation, for example $ 1.1
3 | Suffix, 1-character separation, for example 1.1 $

LOCALE_IDATE
Short date format-ordering specifier. The maximum number of characters allowed for this string is two. The specifier can be one of the following values.
Value | Meaning
0 | Month-Day-Year
1 | Day-Month-Year
2 | Year-Month-Day

LOCALE_IDAYLZERO
Specifier for leading zeros in day fields for the short date only. The maximum number of characters allowed for this string is two. The specifier can be one of the following values.
Value | Meaning
0 | No leading zeros for days
1 | Leading zeros for days

LOCALE_IDEFAULTANSICODEPAGE
American National Standards Institute (ANSI) code page associated with this locale. If the locale does not use an ANSI code page, the value is 0. The maximum number of characters allowed for this string is six.
LOCALE_IDEFAULTCODEPAGE
Original equipment manufacturer (OEM) code page associated with the country/region. If the locale does not use an OEM code page, the value is 1.The maximum number of characters allowed for this string is six.
LOCALE_IDEFAULTCOUNTRY
Code for the principal country/region in this locale. This is provided so that partially specified locales can be completed with default values. The maximum number of characters allowed for this string is six.
LOCALE_IDEFAULTEBCDICCODEPAGE
Windows 2000 or later: Default EBCDIC code page associated with the locale. The maximum number of characters allowed for this string is six.
LOCALE_IDEFAULTLANGUAGE
Language identifier for the principal language spoken in this locale. This is provided so partially specified locales can be completed with default values. The maximum number of characters allowed for this string is five.
LOCALE_IDEFAULTMACCODEPAGE
Default Macintosh code page associated with the locale. If the locale does not use a Macintosh code page, the value is 2. The maximum number of characters allowed for this string is six.
LOCALE_IDIGITS
Number of fractional digits. The maximum number of characters allowed for this string is two.
LOCALE_IDIGITSUBSTITUTION
Windows 2000 or later: Determines the shape of the digits. For example, Arabic, Thai, and Indic digits have classical shapes different from western digits. The specifier can be one of these values.
Value | Meaning
0 | Context—the shape depends on the previous text in the same output.
1 | None/Arabic—gives full Unicode compatibility.
2 | Native—national shapes determined by LOCALE_SNATIVEDIGITS.

LOCALE_IFIRSTDAYOFWEEK
Specifier for the first day in a week. The maximum number of characters allowed for this string is two. The specifier can be one of these values.
Value | Meaning
0 | LOCALE_SDAYNAME1
1 | LOCALE_SDAYNAME2
2 | LOCALE_SDAYNAME3
3 | LOCALE_SDAYNAME4
4 | LOCALE_SDAYNAME5
5 | LOCALE_SDAYNAME6
6 | LOCALE_SDAYNAME7

LOCALE_IFIRSTWEEKOFYEAR
Specifier for the first week of the year. The maximum number of characters allowed for this string is two. The specifier can be one of these values.
Value | Meaning
0 | Week containing 1/1 is the first week of that year.
1 | First full week following 1/1 is the first week of that year.
2 | First week containing at least four days is the first week of that year.

LOCALE_IINTLCURRDIGITS
Number of fractional digits for the international monetary format. The maximum number of characters allowed for this string is three.
LOCALE_ILANGUAGE
Language identifier. The maximum number of characters allowed for this string is five.
LOCALE_ILDATE
Long date format-ordering specifier. The maximum number of characters allowed for this string is two. The specifier can be one of the following values.
Value | Meaning
0 | Month-Day-Year
1 | Day-Month-Year
2 | Year-Month-Day

LOCALE_ILZERO
Specifier for leading zeros in decimal fields. The maximum number of characters allowed for this string is two. The specifier can be one of the following values.
Value | Meaning
0 | No leading zeros
1 | Leading zeros

LOCALE_IMEASURE
System of measurement. This value is 0 if the metric system (Système International d'Unités, or S.I.) is used, and 1 if the U.S. system is used. The maximum number of characters allowed for this string is two.
LOCALE_IMONLZERO
Specifier for leading zeros in month fields for the short date only. The maximum number of characters allowed for this string is two. The specifier can be one of the following values.
Value | Meaning
0 | No leading zeros for months
1 | Leading zeros for months

LOCALE_INEGCURR
Negative currency mode. The maximum number of characters allowed for this string is three. The mode can be one of the following values.
Mode | Format for a negative currency
0 Left parenthesis,monetary symbol,number,right parenthesis.

Example: ($1.1)
1 | Negative sign, monetary symbol, number. Example: -$1.1
2 | Monetary symbol, negative sign, number. Example: $-1.1
3 | Monetary symbol, number, negative sign. Example: $1.1-
4 | Left parenthesis, number, monetary symbol, right parenthesis. Example: (1.1$)
5 | Negative sign, number, monetary symbol. Example: -1.1$
6 | Number, negative sign, monetary symbol. Example: 1.1-$
7 | Number, monetary symbol, negative sign. Example: 1.1$-
8 | Negative sign, number, space, monetary symbol (like #5, but with a space before the monetary symbol). Example: -1.1 $
9 | Negative sign, monetary symbol, space, number (like #1, but with a space after the monetary symbol). Example: -$ 1.1
10 | Number, space, monetary symbol, negative sign (like #7, but with a space before the monetary symbol). Example: 1.1 $-
11 | Monetary symbol, space, number, negative sign (like #3, but with a space after the monetary symbol). Example: $ 1.1-
12 | Monetary symbol, space, negative sign, number (like #2, but with a space after the monetary symbol). Example: $ -1.1
13 | Number, negative sign, space, monetary symbol (like #6, but with a space before the monetary symbol). Example: 1.1- $
14 Left parenthesis, monetary symbol, space, number, right

parenthesis (like #0, but with a space after the monetary symbol). Example: ($ 1.1)
15 | Left parenthesis, number, space, monetary symbol, right parenthesis (like #4, but with a space before the monetary symbol). Example: (1.1 $)

LOCALE_INEGNUMBER
Negative number mode, that is, the format for a negative number. The maximum number of characters allowed for this string is two. The mode can be one of these values.
Value | Format
0 | Left parenthesis, number, right parenthesis. Example: (1.1)
1 | Negative sign, number. Example: -1.1
2 | Negative sign, space, number. Example: - 1.1
3 | Number, negative sign. Example: 1.1-
4 | Number, space, negative sign. Example: 1.1 -

LOCALE_INEGSEPBYSPACE
Separation of the negative sign in a monetary value. This value is 1 if the monetary symbol is separated by a space from the negative amount, 0 if it is not. The maximum number of characters allowed for this string is two.
LOCALE_INEGSIGNPOSN
Formatting index for the negative sign in currency values. The maximum number of characters allowed for this string is two. The index can be one of the following values.
Value | Meaning
0 | Parentheses surround the amount and the monetary symbol.
1 | The sign precedes the number.
2 | The sign follows the number.
3 | The sign precedes the monetary symbol.
4 | The sign follows the monetary symbol.

LOCALE_INEGSYMPRECEDES
Position of monetary symbol in a negative monetary value. This value is 1 if the monetary symbol precedes the negative amount, 0 if it follows it. The maximum number of characters allowed for this string is two.
LOCALE_IOPTIONALCALENDAR
Additional calendar types that are available for this LCID. This can be a null-separated list of one or more of the following calendar type values. The maximum number of characters allowed for this string is two.
Value | Meaning
0 | No additional types valid
1 | Gregorian (localized)
2 | Gregorian (English strings always)
3 | Year of the Emperor (Japan)
4 | Taiwan Calendar
5 | Tangun Era (Korea)
6 | Hijri (Arabic lunar)
7 | Thai
8 | Hebrew (Lunar)
9 | Gregorian Middle East French calendar
10 | Gregorian Arabic calendar
11 | Gregorian-transliterated English calendar
12 | Gregorian-transliterated French calendar

LOCALE_IPAPERSIZE
Windows 2000 or later: Default paper size associated with the locale. The specifier can be one of the following values.
Value | Meaning
1 | US Letter
5 | US legal
8 | A3
9 | A4

LOCALE_IPOSSEPBYSPACE
Separation of monetary symbol in a positive monetary value. This value is 1 if the monetary symbol is separated by a space from a positive amount, 0 if it is not. The maximum number of characters allowed for this string is two.
LOCALE_IPOSSIGNPOSN
Formatting index for positive values. This index uses the same values as LOCALE_INEGSIGNPOSN, except that it does not use the zero index. The maximum number of characters allowed for this string is two.
LOCALE_IPOSSYMPRECEDES
Position of monetary symbol in a positive monetary value. This value is 1 if the monetary symbol precedes the positive amount, zero if it follows it. The maximum number of characters allowed for this string is two.
LOCALE_ITIME
Time format specifier. The maximum number of characters allowed for this string is two. The specifier can be one of the following values.
Value | Meaning
0 | AM / PM 12-hour format.
1 | 24-hour format.

LOCALE_ITIMEMARKPOSN
Specifier indicating whether the time marker string (AM or PM) precedes or follows the time string. The registry value is iTimePrefix for compatibility with previous Asian versions of Windows. The specifier can take one of the following values.
Value | Meaning
0 | Use as suffix.
1 | Use as prefix.

LOCALE_ITIMEMARKERUSE
Specifier indicating whether the time marker should be used for 12-hour, 24-hour, or both types of clock settings. The specifier can take one of the following values.
Value | Meaning
0 | Use with 12-hour clock.
1 | Use with 24-hour clock.
2 | Use with both 12-hour and 24-hour clocks.
3 | Never use.

LOCALE_ITLZERO
Specifier for leading zeros in time fields. The maximum number of characters allowed for this string is two. The specifier can be one of the following values.
Value | Meaning
0 | No leading zeros for hours.
1 | Leading zeros for hours.

LOCALE_NOUSEROVERRIDE
This causes the function to bypass any user override and return the system default value for the other LCTYPE specified in the function call. This flag can be combined with other LOCALE values by using the binary-OR operator.
LOCALE_RETURN_NUMBER
Windows 98, and Windows NT 4.0 and later: This causes the function to return the value as a number instead of as a string. The buffer that receives the value must be at least the length of a DWORD. This flag can be combined with any specifier beginning with LOCALE_I by using the binary-OR operator.
LOCALE_S1159
String for the AM designator. The maximum number of characters allowed for this string is nine.
LOCALE_S2359
String for the PM designator. The maximum number of characters allowed for this string is nine.
LOCALE_SABBREVCTRYNAME
Abbreviated name of the country/region, mostly based on the ISO Standard 3166.
LOCALE_SABBREVDAYNAME1
Native abbreviated name for Monday.
LOCALE_SABBREVDAYNAME2
Native abbreviated name for Tuesday.
LOCALE_SABBREVDAYNAME3
Native abbreviated name for Wednesday.
LOCALE_SABBREVDAYNAME4
Native abbreviated name for Thursday.
LOCALE_SABBREVDAYNAME5
Native abbreviated name for Friday.
LOCALE_SABBREVDAYNAME6
Native abbreviated name for Saturday.
LOCALE_SABBREVDAYNAME7
Native abbreviated name for Sunday.
LOCALE_SABBREVLANGNAME
Abbreviated name of the language. In most cases it is created by taking the two-letter language abbreviation from the ISO Standard 639 and adding a third letter, as appropriate, to indicate the sublanguage.
LOCALE_SABBREVMONTHNAME1
Native abbreviated name for January.
LOCALE_SABBREVMONTHNAME2
Native abbreviated name for February.
LOCALE_SABBREVMONTHNAME3
Native abbreviated name for March.
LOCALE_SABBREVMONTHNAME4
Native abbreviated name for April.
LOCALE_SABBREVMONTHNAME5
Native abbreviated name for May.
LOCALE_SABBREVMONTHNAME6
Native abbreviated name for June.
LOCALE_SABBREVMONTHNAME7
Native abbreviated name for July.
LOCALE_SABBREVMONTHNAME8
Native abbreviated name for August.
LOCALE_SABBREVMONTHNAME9
Native abbreviated name for September.
LOCALE_SABBREVMONTHNAME10
Native abbreviated name for October.
LOCALE_SABBREVMONTHNAME11
Native abbreviated name for November.
LOCALE_SABBREVMONTHNAME12
Native abbreviated name for December.
LOCALE_SABBREVMONTHNAME13
Native abbreviated name for 13th month, if it exists.
LOCALE_SCOUNTRY
Full localized name of the country/region. This is based on the localization of the product, thus it changes for each localized version.
LOCALE_SCURRENCY
String used as the local monetary symbol. The maximum number of characters allowed for this string is six.
LOCALE_SDATE
Character(s) for the date separator. The maximum number of characters allowed for this string is four.
LOCALE_SDAYNAME1
Native long name for Monday.
LOCALE_SDAYNAME2
Native long name for Tuesday.
LOCALE_SDAYNAME3
Native long name for Wednesday.
LOCALE_SDAYNAME4
Native long name for Thursday.
LOCALE_SDAYNAME5
Native long name for Friday.
LOCALE_SDAYNAME6
Native long name for Saturday.
LOCALE_SDAYNAME7
Native long name for Sunday.
LOCALE_SDECIMAL
Character(s) used as the decimal separator. The maximum number of characters allowed for this string is 4.
LOCALE_SENGCOUNTRY
Full English name of the country/region. This is always restricted to characters that can be mapped into the ASCII 127-character subset.
LOCALE_SENGCURRNAME
Windows 98 and Windows 2000 and later: The full English name of the currency associated with the locale.
LOCALE_SENGLANGUAGE
Full English name of the language from the International Organization for Standardization (ISO) Standard 639. This is always restricted to characters that can be mapped into the ASCII 127-character subset. This is not always equivalent to the English version of LOCALE_SLANGUAGE.
LOCALE_SGROUPING
Sizes for each group of digits to the left of the decimal. An explicit size is needed for each group, and sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. For example, to group thousands, specify 3;0. Indic locales group the first thousand and then group by hundreds—for example 12,34,56,789, which is represented by 3;2;0.
LOCALE_SINTLSYMBOL
Three characters of the international monetary symbol specified in ISO 4217 followed by the character separating this string from the amount.
LOCALE_SISO3166CTRYNAME
Windows 98 and Windows NT 4.0 and later: Country/region name, based on ISO Standard 3166.
LOCALE_SISO639LANGNAME
Windows 98 and Windows NT 4.0 and later: The abbreviated name of the language based entirely on the ISO Standard 639 values.
LOCALE_SLANGUAGE
Full localized name of the language. This name is based on the localization of the product, thus the value changes for each localized version.
LOCALE_SLIST
Character(s) used to separate list items. For example, a comma is used in many locales. The maximum number of characters allowed for this string is 4.
LOCALE_SLONGDATE
Long date formatting string for this locale. The string can consist of a combination of day, month, and year format pictures defined in the Day, Month, Year, and Era Format Pictures table in National Language Support Constants and any string of characters enclosed in single quotes. Characters in single quotes remain as specified. The maximum number of characters allowed for this string is 80.
LOCALE_SMONDECIMALSEP
Character(s) used as the monetary decimal separator. The maximum number of characters allowed for this string is four.
LOCALE_SMONGROUPING
Sizes for each group of monetary digits to the left of the decimal. An explicit size is needed for each group, and sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. For example, to group thousands, specify 3;0. Indic languages group the first thousand and then group by hundreds—for example, 12,34,56,789, which is represented by 3;2;0. The maximum number of characters allowed for this string is four.
LOCALE_SMONTHNAME1
Native long name for January. See note following this list.
LOCALE_SMONTHNAME2
Native long name for February. See note following this list.
LOCALE_SMONTHNAME3
Native long name for March. See note following this list.
LOCALE_SMONTHNAME4
Native long name for April. See note following this list.
LOCALE_SMONTHNAME5
Native long name for May. See note following this list.
LOCALE_SMONTHNAME6
Native long name for June. See note following this list.
LOCALE_SMONTHNAME7
Native long name for July. See note following this list.
LOCALE_SMONTHNAME8
Native long name for August. See note following this list.
LOCALE_SMONTHNAME9
Native long name for September. See note following this list.
LOCALE_SMONTHNAME10
Native long name for October. See note following this list.
LOCALE_SMONTHNAME11
Native long name for November. See note following this list.
LOCALE_SMONTHNAME12
Native long name for December. See note following this list.
LOCALE_SMONTHNAME13
Native name for 13th month, if it exists. See note following this list.
LOCALE_SMONTHOUSANDSEP
Character(s) used as the monetary separator between groups of digits to the left of the decimal. The maximum number of characters allowed for this string is four.
LOCALE_SNATIVECTRYNAME
Native name of the country/region.
LOCALE_SNATIVECURRNAME
Windows 98 and Windows 2000 and later: The native name of the currency associated with the locale.
LOCALE_SNATIVEDIGITS
Native equivalents to ASCII zero through 9.
LOCALE_SNATIVELANGNAME
Native name of the language.
LOCALE_SNEGATIVESIGN
String value for the negative sign. The maximum number of characters allowed for this string is five.
LOCALE_SPOSITIVESIGN
String value for the positive sign. The maximum number of characters allowed for this string is five.
LOCALE_SSHORTDATE
Short date formatting string for this locale. The string can consist of a combination of day, month, and year format pictures defined in Day, Month, Year, and Era Format Pictures table in National Language Support Constants. The maximum number of characters allowed for this string is 80.
LOCALE_SSORTNAME
Windows 98 and Windows 2000 and later: The full localized name of the sort for the specified locale identifier, dependent on the language of the shell.
LOCALE_STHOUSAND
Character(s) used to separate groups of digits to the left of the decimal. The maximum number of characters allowed for this string is four.
LOCALE_STIME
Character(s) for the time separator. The maximum number of characters allowed for this string is four.
LOCALE_STIMEFORMAT
Time formatting strings for this locale. The string can consist of a combination of the hour, minute, and second format pictures defined in the Hour, Minute, and Second Format Pictures table in National Language Support Constants. The maximum number of characters allowed for this string is 80.
LOCALE_SYEARMONTH
Windows 98 and Windows 2000 and later: The Year/Month formatting string for the locale. This string shows the proper format for a date string that contains only the year and the month.
LOCALE_USE_CP_ACP
Uses the system ANSI code page (ACP) for string translation instead of the locale's code page. This is used in the GetLocaleInfo function. This flag can be combined with any other LCTYPE by using the binary-OR operator.

Note Calling the GetLocaleInfo function with a LOCALE_SMONTHNAMExx flag returns the stand-alone, or nominative, form of the month name. To get the genitive form of the month name, call GetDateFormat with a date picture of ddMMMM and remove the two digits from the beginning of the returned string.

Many of the locale types previously listed are closely related, such that changing one affects the value of the others. The following table shows the relationships between these types.

Constant | Affects
LOCALE_ICURRENCY | LOCALE_IPOSSEPBYSPACE, LOCALE_IPOSSYMPRECEDES
LOCALE_INEGCURR | LOCALE_SNEGATIVE, LOCALE_SPOSITIVE, LOCALE_INEGSEPBYSPACE, LOCALE_INEGSYMPRECEDES, LOCALE_INEGSIGNPOSN, LOCALE_IPOSSIGNPOSN
LOCALE_SSHORTDATE | LOCALE_SDATE, LOCALE_IDATE
LOCALE_SLONGDATE | LOCALE_ILDATE
LOCALE_STIMEFORMAT | LOCALE_STIME, LOCALE_ITIME, LOCALE_ITLZERO, LOCALE_ITIMEMARKPOSN


Day, Month, Year, and Era Format Pictures

The format picture for a date string consists of a combination of null-terminated strings.

Day | Meaning
d | Day of the month as digits without leading zeros for single digit days.
dd | Day of the month as digits with leading zeros for single digit days
ddd | Day of the week as a 3-letter abbreviation as specified by a LOCALE_SABBREVDAYNAME value.
dddd | Day of the week as specified by a LOCALE_SDAYNAME value.
Month |
M | Month as digits without leading zeros for single digit months.
MM | Month as digits with leading zeros for single digit months
MMM | Month as a three letter abbreviation as specified by a LOCALE_SABBREVMONTHNAME value.
MMMM | Month as specified by a LOCALE_SMONTHNAME value.
Year |
y | Year represented only be the last digit.
yy | Year represented only be the last two digits.
yyyy | Year represented by the full 4 digits.
Period/Era |
gg | Period/era string as specified by the CAL_SERASTRING value. The gg format picture in a date string is ignored if there is no associated era string.

Note In the preceding formats, the letters d, g, and y must be lowercase and the letter M must be uppercase.


Hour, Minute, and Second Format Pictures

The format picture for a time string consists of a combination of one string from each of these format types.

Hours | Meaning
h | Hours without leading zeros for single-digit hours (12-hour clock).
hh | Hours with leading zeros for single-digit hours (12-hour clock).
H | Hours without leading zeros for single-digit hours (24-hour clock).
HH | Hours with leading zeros for single-digit hours (24-hour clock).
Minutes |
m | Minutes without leading zeros for single-digit minutes.
mm | Minutes with leading zeros for single-digit minutes.
Seconds |
s | Seconds without leading zeros for single-digit seconds.
ss | Seconds with leading zeros for single-digit seconds.
Time marker |
t | One character–time marker string.
tt | Multicharacter–time marker string.

Note In the preceding formats, the letters m, s, and t must be lowercase, and the letter h must be lowercase to denote the 12-hour clock or uppercase to denote the 24-hour clock.


Primary Language Identifiers

A primary language identifier indicates the language that is used. However, to identify the language that is used in a country or region you must combine the primary language with a sublanguage identifier to form language identifiers.

A user-defined primary language ID is a value in the range 0x0200 to 0x03ff. All other values are reserved for system use.

The following table shows the defined primary language identifiers.

Identifier | Prefined symbol | Language
0x00 | LANG_NEUTRAL | Neutral
0x01 | LANG_ARABIC | Arabic
0x02 | LANG_BULGARIAN | Bulgarian
0x03 | LANG_CATALAN | Catalan
0x04 | LANG_CHINESE | Chinese
0x05 | LANG_CZECH | Czech
0x06 | LANG_DANISH | Danish
0x07 | LANG_GERMAN | German
0x08 | LANG_GREEK | Greek
0x09 | LANG_ENGLISH | English
0x0a | LANG_SPANISH | Spanish
0x0b | LANG_FINNISH | Finnish
0x0c | LANG_FRENCH | French
0x0d | LANG_HEBREW | Hebrew
0x0e | LANG_HUNGARIAN | Hungarian
0x0f | LANG_ICELANDIC | Icelandic
0x10 | LANG_ITALIAN | Italian
0x11 | LANG_JAPANESE | Japanese
0x12 | LANG_KOREAN | Korean
0x13 | LANG_DUTCH | Dutch
0x14 | LANG_NORWEGIAN | Norwegian
0x15 | LANG_POLISH | Polish
0x16 | LANG_PORTUGUESE | Portuguese
0x18 | LANG_ROMANIAN | Romanian
0x19 | LANG_RUSSIAN | Russian
0x1a | LANG_CROATIAN | Croatian
0x1a | LANG_SERBIAN | Serbian
0x1b | LANG_SLOVAK | Slovak
0x1c | LANG_ALBANIAN | Albanian
0x1d | LANG_SWEDISH | Swedish
0x1e | LANG_THAI | Thai
0x1f | LANG_TURKISH | Turkish
0x20 | LANG_URDU | Urdu
0x21 | LANG_INDONESIAN | Indonesian
0x22 | LANG_UKRANIAN | Ukrainian
0x23 | LANG_BELARUSIAN | Belarusian
0x24 | LANG_SLOVENIAN | Slovenian
0x25 | LANG_ESTONIAN | Estonian
0x26 | LANG_LATVIAN | Latvian
0x27 | LANG_LITHUANIAN | Lithuanian
0x29 | LANG_FARSI | Farsi
0x2a | LANG_VIETNAMESE | Vietnamese
0x2b | LANG_ARMENIAN | Armenian
0x2c | LANG_AZERI | Azeri
0x2d | LANG_BASQUE | Basque
0x2f | LANG_MACEDONIAN | Macedonian
0x36 | LANG_AFRIKAANS | Afrikaans
0x37 | LANG_GEORGIAN | Georgian
0x38 | LANG_FAEROESE | Faeroese
0x39 | LANG_HINDI | Hindi
0x3e | LANG_MALAY | Malay
0x3f | LANG_KAZAK | Kazak
0x40 | LANG_KYRGYZ | Kyrgyz
0x41 | LANG_SWAHILI | Swahili
0x43 | LANG_UZBEK | Uzbek
0x44 | LANG_TATAR | Tatar
0x45 | LANG_BENGALI | Bengali
0x46 | LANG_PUNJABI | Punjabi
0x47 | LANG_GUJARATI | Gujarati
0x48 | LANG_ORIYA | Oriya
0x49 | LANG_TAMIL | Tamil
0x4a | LANG_TELUGU | Telugu
0x4b | LANG_KANNADA | Kannada
0x4c | LANG_MALAYALAM | Malayalam
0x4d | LANG_ASSAMESE | Assamese
0x4e | LANG_MARATHI | Marathi
0x4f | LANG_SANSKRIT | Sanskrit
0x50 | LANG_MONGOLIAN | Mongolian
0x56 | LANG_GALICIAN | Galician
0x57 | LANG_KONKANI | Konkani
0x58 | LANG_MANIPURI | Manipuri
0x59 | LANG_SINDHI | Sindhi
0x5a | LANG_SYRIAC | Syriac
0x60 | LANG_KASHMIRI | Kashmiri
0x61 | LANG_NEPALI | Nepali
0x65 | LANG_DIVEHI | Divehi
0x7f | LANG_INVARIANT |


SubLanguage Identifiers

The MAKELCID macro generates a language identifier from a sublanguage identifier and a primary language identifier. The name immediately following SUBLANG_ indicates the primary language ID that is used with the sublanguage ID to form a valid language ID.

If there is no sublanguage ID for a primary language ID, use SUBLANG_DEFAULT. You can use SUBLANG_NEUTRAL for resources that may be the same for all sublanguages of a primary language.

A user-defined sublanguage identifier is a value in the range 0x20 to 0x3f. All other values are reserved for system use.

The following table shows the defined sublanguage identifiers.

Identifier | Predefined symbol | Language
0x00 | SUBLANG_NEUTRAL | Language neutral
0x01 | SUBLANG_DEFAULT | User Default
0x02 | SUBLANG_SYS_DEFAULT | System Default
0x01 | SUBLANG_ARABIC_SAUDI_ARABIA | Arabic (Saudi Arabia)
0x02 | SUBLANG_ARABIC_IRAQ | Arabic (Iraq)
0x03 | SUBLANG_ARABIC_EGYPT | Arabic (Egypt)
0x04 | SUBLANG_ARABIC_LIBYA | Arabic (Libya)
0x05 | SUBLANG_ARABIC_ALGERIA | Arabic (Algeria)
0x06 | SUBLANG_ARABIC_MOROCCO | Arabic (Morocco)
0x07 | SUBLANG_ARABIC_TUNISIA | Arabic (Tunisia)
0x08 | SUBLANG_ARABIC_OMAN | Arabic (Oman)
0x09 | SUBLANG_ARABIC_YEMEN | Arabic (Yemen)
0x0a | SUBLANG_ARABIC_SYRIA | Arabic (Syria)
0x0b | SUBLANG_ARABIC_JORDAN | Arabic (Jordan)
0x0c | SUBLANG_ARABIC_LEBANON | Arabic (Lebanon)
0x0d | SUBLANG_ARABIC_KUWAIT | Arabic (Kuwait)
0x0e | SUBLANG_ARABIC_UAE | Arabic (U.A.E.)
0x0f | SUBLANG_ARABIC_BAHRAIN | Arabic (Bahrain)
0x10 | SUBLANG_ARABIC_QATAR | Arabic (Qatar)
0x01 | SUBLANG_AZERI_LATIN | Azeri (Latin)
0x02 | SUBLANG_AZERI_CYRILLIC | Azeri (Cyrillic)
0x01 | SUBLANG_CHINESE_TRADITIONAL | Chinese (Traditional)
0x02 | SUBLANG_CHINESE_SIMPLIFIED | Chinese (Simplified)
0x03 | SUBLANG_CHINESE_HONGKONG | Chinese (Hong Kong SAR, PRC)
0x04 | SUBLANG_CHINESE_SINGAPORE | Chinese (Singapore)
0x05 | SUBLANG_CHINESE_MACAU | Chinese (Macau SAR)
0x01 | SUBLANG_DUTCH | Dutch
0x02 | SUBLANG_DUTCH_BELGIAN | Dutch (Belgian)
0x01 | SUBLANG_ENGLISH_US | English (US)
0x02 | SUBLANG_ENGLISH_UK | English (UK)
0x03 | SUBLANG_ENGLISH_AUS | English (Australian)
0x04 | SUBLANG_ENGLISH_CAN | English (Canadian)
0x05 | SUBLANG_ENGLISH_NZ | English (New Zealand)
0x06 | SUBLANG_ENGLISH_EIRE | English (Ireland)
0x07 | SUBLANG_ENGLISH_SOUTH_AFRICA | English (South Africa)
0x08 | SUBLANG_ENGLISH_JAMAICA | English (Jamaica)
0x09 | SUBLANG_ENGLISH_CARIBBEAN | English (Caribbean)
0x0a | SUBLANG_ENGLISH_BELIZE | English (Belize)
0x0b | SUBLANG_ENGLISH_TRINIDAD | English (Trinidad)
0x0c | SUBLANG_ENGLISH_ZIMBABWE | English (Zimbabwe)
0x0d | SUBLANG_ENGLISH_PHILIPPINES | English (Philippines)
0x01 | SUBLANG_FRENCH | French
0x02 | SUBLANG_FRENCH_BELGIAN | French (Belgian)
0x03 | SUBLANG_FRENCH_CANADIAN | French (Canadian)
0x04 | SUBLANG_FRENCH_SWISS | French (Swiss)
0x05 | SUBLANG_FRENCH_LUXEMBOURG | French (Luxembourg)
0x06 | SUBLANG_FRENCH_MONACO | French (Monaco)
0x01 | SUBLANG_GERMAN | German
0x02 | SUBLANG_GERMAN_SWISS | German (Swiss)
0x03 | SUBLANG_GERMAN_AUSTRIAN | German (Austrian)
0x04 | SUBLANG_GERMAN_LUXEMBOURG | German (Luxembourg)
0x05 | SUBLANG_GERMAN_LIECHTENSTEIN | German (Liechtenstein)
0x01 | SUBLANG_ITALIAN | Italian
0x02 | SUBLANG_ITALIAN_SWISS | Italian (Swiss)
0x02 | SUBLANG_KASHMIRI_INDIA | Kashmiri (India)
0x01 | SUBLANG_KOREAN | Korean
0x01 | SUBLANG_LITHUANIAN | Lithuanian
0x01 | SUBLANG_MALAY_MALAYSIA | Malay (Malaysia)
0x02 | SUBLANG_MALAY_BRUNEI_DARUSSALAM | Malay (Brunei Darassalam)
0x02 | SUBLANG_NEPALI_INDIA | Nepali (India)
0x01 | SUBLANG_NORWEGIAN_BOKMAL | Norwegian (Bokmal)
0x02 | SUBLANG_NORWEGIAN_NYNORSK | Norwegian (Nynorsk)
0x01 | SUBLANG_PORTUGUESE_BRAZILIAN | Portuguese (Brazilian)
0x02 | SUBLANG_PORTUGUESE | Portuguese
0x02 | SUBLANG_SERBIAN_LATIN | Serbian (Latin)
0x03 | SUBLANG_SERBIAN_CYRILLIC | Serbian (Cyrillic)
0x01 | SUBLANG_SPANISH | Spanish (Castilian)
0x02 | SUBLANG_SPANISH_MEXICAN | Spanish (Mexican)
0x03 | SUBLANG_SPANISH_MODERN | Spanish (Modern)
0x04 | SUBLANG_SPANISH_GUATEMALA | Spanish (Guatemala)
0x05 | SUBLANG_SPANISH_COSTA_RICA | Spanish (Costa Rica)
0x06 | SUBLANG_SPANISH_PANAMA | Spanish (Panama)
0x07 | SUBLANG_SPANISH_DOMINICAN_REPUBLIC | Spanish (Dominican Republic)
0x08 | SUBLANG_SPANISH_VENEZUELA | Spanish (Venezuela)
0x09 | SUBLANG_SPANISH_COLOMBIA | Spanish (Colombia)
0x0a | SUBLANG_SPANISH_PERU | Spanish (Peru)
0x0b | SUBLANG_SPANISH_ARGENTINA | Spanish (Argentina)
0x0c | SUBLANG_SPANISH_ECUADOR | Spanish (Ecuador)
0x0d | SUBLANG_SPANISH_CHILE | Spanish (Chile)
0x0e | SUBLANG_SPANISH_URUGUAY | Spanish (Uruguay)
0x0f | SUBLANG_SPANISH_PARAGUAY | Spanish (Paraguay)
0x10 | SUBLANG_SPANISH_BOLIVIA | Spanish (Bolivia)
0x11 | SUBLANG_SPANISH_EL_SALVADOR | Spanish (El Salvador)
0x12 | SUBLANG_SPANISH_HONDURAS | Spanish (Honduras)
0x13 | SUBLANG_SPANISH_NICARAGUA | Spanish (Nicaragua)
0x14 | SUBLANG_SPANISH_PUERTO_RICO | Spanish (Puerto Rico)
0x01 | SUBLANG_SWEDISH | Swedish
0x02 | SUBLANG_SWEDISH_FINLAND | Swedish (Finland)
0x01 | SUBLANG_URDU_PAKISTAN | Urdu (Pakistan)
0x02 | SUBLANG_URDU_INDIA | Urdu (India)
0x01 | SUBLANG_UZBEK_LATIN | Uzbek (Latin)
0x02 | SUBLANG_UZBEK_CYRILLIC | Uzbek (Cyrillic)


Language Identifiers

The following are language identifiers. They are composed of a primary language identifier and a sublanguage identifier.

The following identifiers were composed using the MAKELANGID macro.

Identifier | Language
0x0000 | Language Neutral
0x007f | The language for the invariant locale (LOCALE_INVARIANT). See MAKELCID.
0x0400 | Process or User Default Language
0x0800 | System Default Language
0x0436 | Afrikaans
0x041c | Albanian
0x0401 | Arabic (Saudi Arabia)
0x0801 | Arabic (Iraq)
0x0c01 | Arabic (Egypt)
0x1001 | Arabic (Libya)
0x1401 | Arabic (Algeria)
0x1801 | Arabic (Morocco)
0x1c01 | Arabic (Tunisia)
0x2001 | Arabic (Oman)
0x2401 | Arabic (Yemen)
0x2801 | Arabic (Syria)
0x2c01 | Arabic (Jordan)
0x3001 | Arabic (Lebanon)
0x3401 | Arabic (Kuwait)
0x3801 | Arabic (U.A.E.)
0x3c01 | Arabic (Bahrain)
0x4001 | Arabic (Qatar)
0x042b | Windows 2000 or later: Armenian. This is Unicode only.
0x042c | Azeri (Latin)
0x082c | Azeri (Cyrillic)
0x042d | Basque
0x0423 | Belarussian
0x0402 | Bulgarian
0x0455 | Burmese
0x0403 | Catalan
0x0404 | Chinese (Taiwan)
0x0804 | Chinese (PRC)
0x0c04 | Chinese (Hong Kong SAR, PRC)
0x1004 | Chinese (Singapore)
0x1404 | Windows 98/Me, Windows 2000 or later: Chinese (Macau SAR)
0x041a | Croatian
0x0405 | Czech
0x0406 | Danish
0x0465 | Whistler or later: Divehi. This is Unicode only.
0x0413 | Dutch (Netherlands)
0x0813 | Dutch (Belgium)
0x0409 | English (United States)
0x0809 | English (United Kingdom)
0x0c09 | English (Australian)
0x1009 | English (Canadian)
0x1409 | English (New Zealand)
0x1809 | English (Ireland)
0x1c09 | English (South Africa)
0x2009 | English (Jamaica)
0x2409 | English (Caribbean)
0x2809 | English (Belize)
0x2c09 | English (Trinidad)
0x3009 | Windows 98/Me, Windows 2000 or later: English (Zimbabwe)
0x3409 | Windows 98/Me, Windows 2000 or later: English (Philippines)
0x0425 | Estonian
0x0438 | Faeroese
0x0429 | Farsi
0x040b | Finnish
0x040c | French (Standard)
0x080c | French (Belgian)
0x0c0c | French (Canadian)
0x100c | French (Switzerland)
0x140c | French (Luxembourg)
0x180c | Windows 98/Me, Windows 2000 or later: French (Monaco)
0x0456 | Whistler and later: Galician
0x0437 | Windows 2000 and later: Georgian. This is Unicode only.
0x0407 | German (Standard)
0x0807 | German (Switzerland)
0x0c07 | German (Austria)
0x1007 | German (Luxembourg)
0x1407 | German (Liechtenstein)
0x0408 | Greek
0x0447 | Whistler and later: Gujarati. This is Unicode only.
0x040d | Hebrew
0x0439 | Windows 2000 and later: Hindi. This is Unicode only.
0x040e | Hungarian
0x040f | Icelandic
0x0421 | Indonesian
0x0410 | Italian (Standard)
0x0810 | Italian (Switzerland)
0x0411 | Japanese
0x044b | Whistler and later: Kannada. This is Unicode only.
0x0860 | Kashmiri (India)
0x043f | Kazakh
0x0457 | Windows 2000 and later: Konkani. This is Unicode only.
0x0412 | Korean
0x0812 | Windows 95 and Windows NT 4.0 only: Korean (Johab)
0x0440 | Whistler and later: Kyrgyz.
0x0426 | Latvian
0x0427 | Lithuanian
0x0827 | Windows 98 only: Lithuanian (Classic)
0x042f | Macedonian
0x043e | Malay (Malaysian)
0x083e | Malay (Brunei Darussalam)
0x0458 | Manipuri
0x044e | Windows 2000 and later: Marathi. This is Unicode only.
0x0450 | Whistler and later: Mongolian
0x0414 | Norwegian (Bokmal)
0x0814 | Norwegian (Nynorsk)
0x0415 | Polish
0x0416 | Portuguese (Brazil)
0x0816 | Portuguese (Standard)
0x0446 | Whistler and later: Punjabi. This is Unicode only.
0x0418 | Romanian
0x0419 | Russian
0x044f | Windows 2000 and later: Sanskrit. This is Unicode only.
0x0c1a | Serbian (Cyrillic)
0x081a | Serbian (Latin)
0x0459 | Sindhi
0x041b | Slovak
0x0424 | Slovenian
0x040a | Spanish (Traditional Sort)
0x080a | Spanish (Mexican)
0x0c0a | Spanish (Modern Sort)
0x100a | Spanish (Guatemala)
0x140a | Spanish (Costa Rica)
0x180a | Spanish (Panama)
0x1c0a | Spanish (Dominican Republic)
0x200a | Spanish (Venezuela)
0x240a | Spanish (Colombia)
0x280a | Spanish (Peru)
0x2c0a | Spanish (Argentina)
0x300a | Spanish (Ecuador)
0x340a | Spanish (Chile)
0x380a | Spanish (Uruguay)
0x3c0a | Spanish (Paraguay)
0x400a | Spanish (Bolivia)
0x440a | Spanish (El Salvador)
0x480a | Spanish (Honduras)
0x4c0a | Spanish (Nicaragua)
0x500a | Spanish (Puerto Rico)
0x0430 | Sutu
0x0441 | Swahili (Kenya)
0x041d | Swedish
0x081d | Swedish (Finland)
0x045a | Whistler and later: Syriac. This is Unicode only.
0x0449 | Windows 2000 and later: Tamil. This is Unicode only.
0x0444 | Tatar (Tatarstan)
0x044a | Whistler and later: Telugu. This is Unicode only.
0x041e | Thai
0x041f | Turkish
0x0422 | Ukrainian
0x0420 | Windows 98/Me, Windows 2000 or later: Urdu (Pakistan)
0x0820 | Urdu (India)
0x0443 | Uzbek (Latin)
0x0843 | Uzbek (Cyrillic)
0x042a | Windows 98, Windows NT 4.0 and later: Vietnamese

The following three combinations of usPrimaryLanguage and usSubLanguage have special meaning.

Primary language identifier | Sublanguage identifier | Meaning
LANG_NEUTRAL | SUBLANG_NEUTRAL | Language neutral
LANG_NEUTRAL | SUBLANG_DEFAULT | User default language
LANG_NEUTRAL | SUBLANG_SYS_DEFAULT | System default language


Sort Identifiers

The defined sort orders are SORT_DEFAULT and the following values.

Value | Meaning
SORT_CHINESE_BIG5 | Chinese BIG5 order.
SORT_CHINESE_BOPOMOFO | Traditional Chinese Bopomofo order.
SORT_CHINESE_PRC | PRC Chinese Stroke Count order.
SORT_CHINESE_PRCP | PRC Chinese Phonetic order.
SORT_CHINESE_UNICODE | Chinese Unicode order.
SORT_DEFAULT | Default sort.
SORT_GEORGIAN_MODERN | Georgian Modern order.
SORT_GEORGIAN_TRADITIONAL | Georgian Traditional order.
SORT_GERMAN_PHONE_BOOK | German Phone Book order.
SORT_HUNGARIAN_DEFAULT | Hungarian Default order.
SORT_HUNGARIAN_TECHNICAL | Hungarian Technical order.
SORT_JAPANESE_UNICODE | Japanese Unicode order.
SORT_JAPANESE_XJIS | Japanese XJIS order.
SORT_KOREAN_KSC | Korean KSC order.
SORT_KOREAN_UNICODE | Korean Unicode order.


Calendar Type Information

The CALTYPE constants are used in the EnumCalendarInfo and GetCalendarInfo functions to define particular pieces of calendar information. Some of these types are also used for the SetCalendarInfo function.

The following CALTYPE constants may be used in combination with any other CALTYPE constants.

Type | Description
CAL_NOUSEROVERRIDE | Windows 98/Me, Windows 2000 or later: Uses the system default instead of the user's choice.
CAL_RETURN_NUMBER | Windows 98/Me, Windows 2000 or later: Returns the result from GetCalendarInfo as a number instead of a string. This is only valid for CALTYPES beginning with CAL_I.
CAL_USE_CP_ACP | Windows 98/Me, Windows 2000 or later: Uses the system ANSI code page (ACP) for string translation instead of the locale's code page.

The following CALTYPE constants are mutually exclusive—that is, they may not be used in combination with each other in a function call.

Type | Description
CAL_ICALINTVALUE | An integer value indicating the calendar type of the alternate calendar.
CAL_ITWODIGITYEARMAX | Windows 98/Me, Windows 2000 or later: An integer value indicating the upper boundary of the two-digit year range.
CAL_IYEAROFFSETRANGE | One or more null-terminated strings that specify the year offsets for each of the era ranges. The last string has an extra terminating null character.
CAL_SABBREVDAYNAME1 | Abbreviated native name of the first day of the week.
CAL_SABBREVDAYNAME2 | Abbreviated native name of the second day of the week.
CAL_SABBREVDAYNAME3 | Abbreviated native name of the third day of the week.
CAL_SABBREVDAYNAME4 | Abbreviated native name of the fourth day of the week.
CAL_SABBREVDAYNAME5 | Abbreviated native name of the fifth day of the week.
CAL_SABBREVDAYNAME6 | Abbreviated native name of the sixth day of the week.
CAL_SABBREVDAYNAME7 | Abbreviated native name of the seventh day of the week.
CAL_SABBREVMONTHNAME1 | Abbreviated native name of the first month of the year.
CAL_SABBREVMONTHNAME2 | Abbreviated native name of the second month of the year.
CAL_SABBREVMONTHNAME3 | Abbreviated native name of the third month of the year.
CAL_SABBREVMONTHNAME4 | Abbreviated native name of the fourth month of the year.
CAL_SABBREVMONTHNAME5 | Abbreviated native name of the fifth month of the year.
CAL_SABBREVMONTHNAME6 | Abbreviated native name of the sixth month of the year.
CAL_SABBREVMONTHNAME7 | Abbreviated native name of the seventh month of the year.
CAL_SABBREVMONTHNAME8 | Abbreviated native name of the eighth month of the year.
CAL_SABBREVMONTHNAME9 | Abbreviated native name of the ninth month of the year.
CAL_SABBREVMONTHNAME10 | Abbreviated native name of the tenth month of the year.
CAL_SABBREVMONTHNAME11 | Abbreviated native name of the eleventh month of the year.
CAL_SABBREVMONTHNAME12 | Abbreviated native name of the twelfth month of the year.
CAL_SABBREVMONTHNAME13 | Abbreviated native name of the thirteenth month of the year, if it exists.
CAL_SCALNAME | Native name of the alternate calendar.
CAL_SDAYNAME1 | Native name of the first day of the week.
CAL_SDAYNAME2 | Native name of the second day of the week.
CAL_SDAYNAME3 | Native name of the third day of the week.
CAL_SDAYNAME4 | Native name of the fourth day of the week.
CAL_SDAYNAME5 | Native name of the fifth day of the week.
CAL_SDAYNAME6 | Native name of the sixth day of the week.
CAL_SDAYNAME7 | Native name of the seventh day of the week.
CAL_SERASTRING | One or more null-terminated strings that specify each of the Unicode code points specifying the era associated with CAL_IYEAROFFSETRANGE. The last string has an extra terminating null character. See example below.
CAL_SLONGDATE | Long date formats for this calendar type.
CAL_SMONTHNAME1 | Native name of the first month of the year.
CAL_SMONTHNAME2 | Native name of the second month of the year.
CAL_SMONTHNAME3 | Native name of the fifth month of the year.
CAL_SMONTHNAME4 | Native name of the fourth month of the year.
CAL_SMONTHNAME5 | Native name of the fifth month of the year.
CAL_SMONTHNAME6 | Native name of the sixth month of the year.
CAL_SMONTHNAME7 | Native name of the seventh month of the year.
CAL_SMONTHNAME8 | Native name of the eighth month of the year.
CAL_SMONTHNAME9 | Native name of the ninth month of the year.
CAL_SMONTHNAME10 | Native name of the tenth month of the year.
CAL_SMONTHNAME11 | Native name of the eleventh month of the year.
CAL_SMONTHNAME12 | Native name of the twelfth month of the year.
CAL_SMONTHNAME13 | Native name of the thirteenth month of the year, if it exists.
CAL_SSHORTDATE | Short date formats for this calendar type.
CAL_SYEARMONTH | Windows 98/Me, Windows 2000 or later: Enumerates the year/month formats for the specified calendars.

If the native name for the day of the week or for a month is an empty string, that name is identical to the name specified in the corresponding locale information and therefore is not duplicated here.

The CAL_IYEAROFFSETRANGE and CAL_SERASTRING values vary in format depending on the type of optional calendar. The following example shows the values for these types (for each supported alternate calendar type) along with the formula for how to use the CAL_IYEAROFFSETRANGE value to compute the correct year given the Gregorian current year value Y:

CAL_ICALINTVALUE = "1"
CAL_IYEAROFFSETRANGE = ""
CAL_SERASTRING = ""

CAL_ICALINTVALUE = "2"
CAL_IYEAROFFSETRANGE = ""
CAL_SERASTRING = ""

CAL_ICALINTVALUE = "3"
CAL_IYEAROFFSETRANGE = "1989\01926\01912\01868\0"
CAL_SERASTRING = "Ux337B\0Ux337C\0Ux337D\0Ux337E\0"
if (Y>=1989) { Y = (Y-1989)+1; }
if (Y>=1926 && Y<1989) { Y = (Y-1926)+1; }
if (Y>=1912 && Y<1926) { Y = (Y-1912)+1; }
if (Y>=1868 && Y<1912) { Y = (Y-1868)+1; }
if (Y<1868) { Y = Y; }

CAL_ICALINTVALUE = "4"
CAL_IYEAROFFSETRANGE = "1912\0"
CAL_SERASTRING = "Ux4E2D\0Ux83EF\0Ux6C11\0Ux570B\0"
if (Y>=1912) { Y = (Y-1912)+1; }
if (Y<1912) { Y = Y; }

CAL_ICALINTVALUE = "5"
CAL_IYEAROFFSETRANGE = "2333\0"
CAL_SERASTRING = ""
Y = Y+2333;


Language Code and Scripts

The following table shows language codes and scripts.

Language | Code | Script
Greek | ELL | Other
Russian | RUS | Cyrillic
Czech | CSY | Latin 2
Hungarian | HUN | Latin 2
Polish | PLK | Latin 2
Slovak | SKY | Latin 2
Turkish | TRK | Latin 2
Danish | DAN | Latin 1
Dutch (Standard) | NLD | Latin 1
Belgian (Flemish) | NLB | Latin 1
English (US) | ENU | Latin 1
English (British) | ENG | Latin 1
English (Australian) | ENA | Latin 1
English (Canadian) | ENC | Latin 1
English (New Zealand) | ENZ | Latin 1
English (Ireland) | ENI | Latin 1
Finnish | FIN | Latin 1
French (Standard) | FRA | Latin 1
French (Belgian) | FRB | Latin 1
French (Canadian) | FRC | Latin 1
French (Swiss) | FRS | Latin 1
German (Standard) | DEU | Latin 1
German (Swiss) | DES | Latin 1
German (Austrian) | DEA | Latin 1
Icelandic | ISL | Latin 1
Italian (Standard) | ITA | Latin 1
Italian (Swiss) | ITS | Latin 1
Norwegian (Bokmal) | NOR | Latin 1
Norwegian (Nynorsk) | NON | Latin 1
Portuguese (Brazilian) | PTB | Latin 1
Portuguese (Standard) | PTG | Latin 1
Swedish | SVE | Latin 1
Spanish (Standard/Traditional) | ESP | Latin 1
Spanish (Mexican) | ESM | Latin 1
Spanish (Modern) | ESN | Latin 1


Unicode and Character Sets

The Microsoft® Win32® API provides support for the many different written languages of the international marketplace through Unicode and traditional character sets. Unicode is a worldwide character-encoding standard that uses 16-bit code values to represent all the characters used in modern computing, including technical symbols and special characters used in publishing. Traditional character sets are the previous character-encoding standards—such as the Windows ANSI character set—that use 8-bit code values or combinations of 8-bit values to represent the characters used in a specific language or geographical region.

This overview describes the character set functions and explains how to use them in your Win32-based applications.

  • About Unicode and Character Sets
  • Using Strings and Unicode
  • Unicode and Character Set Reference

For a list of functions that support Unicode under Windows 95/98, see Windows 95/98 Me General Limitations.


About Unicode and Character Sets

The world's character-based data was developed using both Unicode and traditional character sets. Because of this, the Microsoft® Win32® API provides character-set functions that help Win32-based applications convert the character-based data from its original character set to Unicode or another traditional character set. These character-set functions also help Win32-based applications create character-based data that can be transferred to and used on any operating system, including those that do not support Unicode.

For details about Unicode beyond the scope of this overview, see The Unicode Standard: Worldwide Character Encoding, version 2.0, Addison-Wesley Publishing Company.

This section provides detailed reference information for the character set functions, structures, and messages.

This section covers the following topics.

  • Character Sets
  • Unicode in the Win32 API


Character Sets

A character set is a mapping of characters to their identifying code values. Most of the character sets commonly used in computers are single-byte character sets in which each character is identified by a value one byte wide. The large number of characters in Asian languages led to the development of multibyte character sets, in particular the double-byte character set (DBCS). Microsoft® Windows NT® /Windows® 2000 incorporates a new global standard for character encoding: Unicode.

For more information, see the following topics:

  • Single-byte Character Sets
  • Double-byte Character Sets
  • Unicode


Single-byte Character Sets

A single-byte character set is a mapping of 256 individual characters to their identifying code values. The code values 0x20 through 0x7E represent standardized displayable characters, but the characters represented by the remaining codes vary among character sets. The ASCII character set covers the range 0x00 through 0x7F.

The ANSI character set is used in the window manager (User) and graphics device interface (GDI), but the Microsoft® MS-DOS® file allocation table (FAT) file system uses the original equipment manufacturer (OEM) character set. Variations on the character sets, called code pages, include different special characters, typically customized for a language or group of languages. The OEM code page 437 is generally used in the United States.

Win32-based applications can use Unicode to avoid the inconsistencies of varied code pages and as an aid in developing easily localized applications.

An application can use the GetACP function to retrieve the ANSI code-page identifier for the system or use the GetOEMCP function to retrieve the OEM code-page identifier.

The OemToChar and OemToCharBuff functions allow an application to convert a character or string from the OEM code page to either the ANSI code page or Unicode. To convert in the other direction, you can use either the CharToOem or CharToOemBuff function. In addition, an application can use the MultiByteToWideChar and WideCharToMultiByte functions to map single-byte character set (SBCS) strings to Unicode and map Unicode strings to SBCS strings.

The GetCPInfo function fills a CPINFO structure with information that includes the size, in bytes, of the largest character in the code page and the default character used when a character code is entered that has no corresponding entry in the code page.


Double-byte Character Sets

The double-byte character set (DBCS) is called an expanded 8-bit character set because its smallest unit is a byte. Some characters in a DBCS have a single byte code value and some have a double byte code value. A DBCS can be thought of as the ANSI character set for some Asian versions of Microsoft® Windows NT®/Windows® 2000, Windows® 95, and Windows® 98 (particularly the Japanese versions). Win32 functions for the Japanese versions of Windows NT/Windows 2000, Windows 95, and Windows 98 accept DBCS strings for the ANSI versions of the functions. However, unlike the handling of Unicode, DBCS character handling requires detailed changes in the character-processing algorithms throughout an application's source code.

To help identify double-byte character sets, an application can use the IsDBCSLeadByte function to determine whether a given character is the first byte in a 2-byte character. In addition, an application can use the MultiByteToWideChar and WideCharToMultiByte functions to map DBCS strings to Unicode and map Unicode strings to DBCS strings.


Unicode

Unicode is a worldwide character-encoding standard. Windows NT/Windows 2000 uses it exclusively at the system level for character and string manipulation. Unicode simplifies localization of software and improves multilingual text processing. By implementing it in your applications, you can enable the application with universal data exchange capabilities for global marketing, using a single binary file for every possible character code.

Unicode defines semantics for each character, standardizes script behavior, provides a standard algorithm for bidirectional text, and defines cross-mappings to other standards. Among the scripts supported by Unicode are Latin, Greek, Han, Hiragana, and Katakana. Supported languages include, but are not limited to, German, French, English, Greek, Chinese, and Japanese.

Unicode can represent all of the world's characters in modern computer use, including technical symbols and special characters used in publishing. Because each Unicode code value is 16 bits wide, it is possible to have separate values for up to 65,536 characters. Unicode-enabled functions are often referred to as "wide-character" functions. Note that the implementation of Unicode in 16-bit values is referred to as UTF-16. For compatibility with 8- and 7-bit environments, UTF-8 and UTF-7 are two lossless transformations of 16-bit Unicode values. For more information, see The Unicode Standard, Version 2.0.

Win32 functions support applications that use either Unicode or the regular ANSI character set. Mixed use in the same application is also possible. Adding Unicode support to an application is easy, and you can even maintain a single set of sources from which to compile an application that supports either Unicode or the Windows ANSI character set.

Win32 functions support Unicode by assigning its strings a specific data type and providing a separate set of entry points and messages to support this new data type. A series of macros and naming conventions make transparent migration to Unicode, or even compiling both non-Unicode and Unicode versions of an application from the same set of sources, a straightforward matter.

Implementing Unicode as a separate data type also enables the compiler's type checking to ensure that only Unicode parameters are used with functions expecting Unicode strings.

For a list of functions that support Unicode under Windows 95/98, see Windows 95/98 Me General Limitations.


Surrogates

There is a need to support more characters than the 65,536 that fit in the 16-bit Unicode codespace. For example, the Chinese speaking community alone uses over 55,000 characters. To answer this need, the Unicode Standard defines surrogates. A surrogate or surrogate pair is a pair of 16-bit Unicode code values that represent a single character. The first (high) surrogate is a 16-bit code value in the range U+D800 to U+DBFF. The second (low) surrogate is a 16-bit code value in the range U+DC00 to U+DFFF. Using surrogates, Unicode can support over one million characters. For more details about surrogates, refer to The Unicode Standard, version 2.0.

Windows 2000 provides support for basic input, output, and simple sorting of surrogates. However, not all Windows 2000 system components are surrogate compatible. Also, surrogates are not supported in Windows 95/98 or in Windows NT 4.0.

Windows 2000 supports surrogates in the following ways:

  • The cmap 12 OpenType font format is introduced, which directly supports the 4-byte character code. Refer to the OpenType font specification for more detail.
  • Windows USER supports surrogate-enabled IMEs.
  • Windows GDI APIs support cmap 12 so surrogates can be displayed correctly.
  • Uniscribe APIs support surrogates.
  • Windows controls, including Edit and Rich Edit, support surrogates.
  • HTML engine supports HTML page that includes surrogates for display, editing (through Outlook Express), and forms submission.
  • System sorting table supports surrogates.
  • Planes two and three (defined in ISO/IEC 10646) are reserved for ideographic characters.These planes fall in the high surrogate range of U+D840 to U+D8BF.

General Guidelines for Software Development

Windows 2000 handles surrogates as pairs of 16-bit code values. The system processes surrogate pairs in a way similar to the way it processes nonspacing marks. At display time, the surrogate pair display as one glyph by means of Uniscribe. (This conforms to the requirements in the Unicode Standard, version 2.0)

Applications automatically support surrogates if they support Unicode and use system controls and standard APIs, such as ExtTextOut and DrawText. Thus, if your code uses standard system controls or uses general ExtTextOut-type calls to display, surrogate pairs should work without any changes necessary.

Applications implementing their own editing support by working out glyph positions for themselves may use Uniscribe for all text processing. Uniscribe has separate APIs to deal with complex script processing (such as line service, hit testing, and cursor movement). The application must call the Uniscribe APIs specifically to get these advanced features. Applications written to the Uniscribe API are fully multilingual. However, this does impose a performance penalty, so some applications may want to do their own surrogate processing.

Because surrogates are well defined, you can also write your own code to handle surrogate text processing. When a program encounters a separated Unicode value from either the lower reserved range or the upper reserved range, it must be one half of a surrogate pair. Thus, you can detect a surrogate pair by doing simple range checking. If you encounter a Unicode value in the lower or upper range, then you need to track backward or forward one 16-bit width to get the rest of the character. Keep in mind that CharNext and CharPrev move by 16-bit code points, not by surrogates.

For sorting, all surrogate pairs are treated as two Unicode code points. Surrogates are sorted after other Unicode code points, but before the PUA (private user area). Sorting for a standalone surrogate character (that is, either the high or low character is missing) is not supported.

If you are a font or IME provider, note that Windows 2000 disables surrogate support by default. If you provide a font and IME package that requires surrogate support, you must set the following registry values:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\LanguagePack]
SURROGATE=(REG_DWORD)0x00000002

[HKEY_CURRENT_USER\Software\Microsoft\Internet Explorer\International\Scripts\42]
IEFixedFontName=[Surrogate Font Face Name]
IEPropFontName=[Surrogate Font Face Name]


Unicode in the Win32 API

Win32 API elements that use characters are generally implemented in one of three formats:

  • A generic version that can be compiled for either ANSI or Unicode
  • An ANSI version
  • A Unicode version

The following topics discuss Unicode data types and how they are used in functions and messages; the use of resources, file names, and command-line arguments; and methods of translating between different types of strings.

  • Win32 Data Types
  • Win32 Function Prototypes
  • Automatic Message Translation
  • String Function Differences
  • Standard C Functions
  • Character Sets Used in Filenames
  • Translation Between String Types
  • Command-line Arguments

For a list of functions that support Unicode under Windows 95/98, see Windows 95/98 Me General Limitations.


Win32 Data Types

Most string operations for Unicode can be written by using the same logic used for handling the Windows ANSI character set, except that the basic unit of operation is a 16-bit character instead of an 8-bit byte character. The Platform SDK header files provide several type definitions that make it easy to create sources that can be compiled for Unicode or the ANSI character set.

The following example shows the method used in the Platform SDK header files to define three sets of data types: a set of generic type definitions that can compile for either ANSI or Unicode, and two sets of specific type definitions. The first set of specific type definitions is for use with the existing Windows (ANSI) character set, and the other is for use with Unicode (or wide) characters.

// Generic types

#ifdef UNICODE
    typedef wchar_t TCHAR;
#else
    typedef unsigned char TCHAR;
#endif

typedef TCHAR * LPTSTR, *LPTCH;

// 8-bit character specific

typedef unsigned char CHAR;
typedef CHAR *LPSTR, *LPCH;

// Unicode specific (wide characters)

typedef unsigned wchar_t WCHAR;
typedef WCHAR *LPWSTR, *LPWCH;

The letter T in a type definition designates a generic type that can be compiled for either ANSI or Unicode. The letter W in a type definition designates a wide-character (Unicode) type. For the actual implementation of this method, see the WinNT.h header file.

An application using generic data types can be compiled for Unicode simply by defining UNICODE before the include statements for the header files, or during compilation. To compile the code for ANSI, omit the UNICODE definition. It is best to use the generic data types, but the specific types exist for applications that require mixed types.


Win32 Function Prototypes

Win32 function prototypes are provided in generic, ANSI, and Unicode versions. The documentation provides generic function prototypes, which can be compiled to produce either ANSI or Unicode prototypes. As an example, all three prototypes are shown in the following code sample for the SetWindowText function.

Generic Prototype:

BOOL SetWindowText(
  HWND hwnd,
  LPCTSTR lpText
);

The header file provides the generic function name implemented as a macro:

#ifdef UNICODE
#define SetWindowText SetWindowTextW
#else
#define SetWindowText SetWindowTextA
#endif // !UNICODE

The preprocessor expands the macro into either the ANSI or Unicode function names, depending on whether UNICODE is defined. The letter A (ANSI) or W (wide) is added at the end of the generic function name, as appropriate. The header file then provides ANSI and Unicode function prototypes, as shown in the following examples.

ANSI Prototype:

BOOL
WINAPI
SetWindowTextA(
    HWND hwnd,
    LPCSTR lpText );

Unicode Prototype:

BOOL
WINAPI
SetWindowTextW(
    HWND hwnd,
    LPCWSTR lpText );

Note that the generic function prototype uses the generic LPCTSTR for the text parameter, but the ANSI prototype uses LPCSTR, and the Unicode prototype uses LPCWSTR.

You can call the generic function in your application, then define UNICODE when you compile the code to use the Unicode function. To default to the ANSI function, do not define UNICODE. You can mix function calls by using the explicit function names ending with A and W.

This approach applies to all functions with text arguments. Always use a generic function prototype with the generic string and character types. All function names that end with an uppercase W take wide-character arguments. Some functions exist only in wide-character versions and can be used only with the appropriate data types.

The Requirements section in the documentation for each function provides information on the function versions implemented by the system. If there is a line that begins with Unicode, either the function has separate Unicode and ANSI versions, or the function accepts only Unicode strings. Otherwise, the function does not accept strings, or accepts only ANSI strings.

Note Whenever a function has a length parameter for a character string, the length should be documented as a count of TCHAR values in the string. This refers to bytes for ANSI versions of the function or characters for Unicode versions. However, functions that require or return pointers to untyped memory blocks, such as the GlobalAlloc function, are exceptions.


Automatic Message Translation

Although applications generally use the same window class, messages between windows of different classes are transparently translated by the system.

Even though a window function is implemented to receive messages in Unicode or ANSI format, the window procedure can still send messages or call functions of either type.

The following messages have text arguments and are subject to automatic text translation. (For information about automatic translation, see Subclassing and Automatic Message Translation.)

CB_ADDSTRING
CB_DIR
CB_FINDSTRING
CB_GETLBTEXT
CB_INSERTSTRING
CB_SELECTSTRING
EM_GETLINE
EM_REPLACESEL
EM_SETPASSWORDCHAR
LB_ADDFILE
LB_ADDSTRING
LB_DIR
LB_FINDSTRING
LB_GETTEXT
LB_INSERTSTRING
LB_SELECTSTRING
WM_ASKCBFORMATNAME
WM_CHAR
WM_CHARTOITEM
WM_CREATE
WM_DEADCHAR
WM_DEVMODECHANGE
WM_GETTEXT
WM_MDICREATE
WM_MENUCHAR
WM_NCCREATE
WM_SETTEXT
WM_SYSCHAR
WM_SYSDEADCHAR
WM_WININICHANGE


String Function Differences

All string functions listed in this section exist in ANSI and Unicode implementations to support ANSI and Unicode arguments. There are, however, subtle differences among some of them.

The following string functions do not require special comment; their ANSI and Unicode implementations work identically.

CharNext
CharPrev
lstrcat
lstrcpy
lstrlen

The value returned by the lstrlen function is always the number of characters, regardless of whether the ANSI or Unicode form is used.

The following string functions are sensitive to the locale of the current thread (as derived from the locale the user selects in Control Panel). The lstrcmp and lstrcmpi functions do not perform byte comparisons like their ANSI C namesakes; they compare strings according to the rules of the selected locale.

CharLower
CharLowerBuff
CharUpper
CharUpperBuff
lstrcmp
lstrcmpi

The following functions convert between the OEM character set and either ANSI or Unicode, depending on which version is used.

CharToOem
CharToOemBuff
OemToChar
OemToCharBuff

The print function wsprintf supports Unicode by providing the following new and changed data types in its format specifications. These format specifications affect the way the wsprintf function interprets the corresponding passed-in parameter.

Format specification | ANSI version | Unicode version
c | CHAR | WCHAR
C | WCHAR | CHAR
hc, hC | CHAR | CHAR
hs, hS | LPSTR | LPSTR
lc, lC | WCHAR | WCHAR
ls, lS | LPWSTR | LPWSTR
s | LPSTR | LPWSTR
S | LPWSTR | LPSTR

The data type for the output text always depends on the version of the function. Where the data type of the passed-in parameter and of the output text do not agree, wsprintf will perform a conversion from Unicode to ANSI, or vice versa, as required.

For the Unicode version of wsprintf, the format string is Unicode, as is the output text.


Standard C Functions

The standard C run-time libraries contain wide-character versions of the ANSI string functions that begin with the letters str. The wide-character versions of the functions start with the letters wcs (or sometimes _wcs). The Unicode data type is compatible with the wide-character data type wchar_t in ANSI C; this allows access to the wide-character string functions.

Generic functions exist for all standard C string functions. They start with the letters _tcs and are listed in the Tchar.h header file. These functions use the generic data types TCHAR and TCHAR*

An application must add the following lines to its program in order to use the generic functions and compile for Unicode:

     #define _UNICODE

     #include <tchar.h>
     #include <wchar.h>

Note that both the Tchar.h and Wchar.h are required, and that the leading underscore on the _UNICODE variable is also required.

The wcstombs and mbstowcs functions can convert from the character set supported by the standard C library to Unicode and back, with some limitations. For more information about translating strings to and from Unicode, see Translation Between String Types.

The printf function defined in Tchar.h supports the same format specifications as wsprintf; for details, see String Functions. Similarly, Tchar.h contains a wprintf function, in which the format string itself is a Unicode string.


Character Sets Used in Filenames

Window manager (User) and graphics device interface (GDI) use the ANSI character set; the MS-DOS FAT file system uses the OEM character set. Applications that create MS-DOS files sometimes have to use the CharToOem and OemToChar functions to translate between these character sets. However, NTFS is capable of storing file names in Unicode; no translation is necessary with NTFS.

With Unicode implementations of the file-system functions, it is not necessary to perform translations to and from ANSI and OEM character sets. Instead, you can use a single source file to compile non-Unicode versions of an application by providing macros for functions that are not invoked when compiling for Unicode, such as CharToOem and OemToChar.

The special file name characters in MS-DOS are unchanged in Unicode file names:

"\," "/," ".," "?," "*."

These special characters are in the ASCII range of characters (0x00 through 0x7F) and their Unicode equivalents are simply the same values in a 2-byte form: 0x0000 through 0x007F.


Translation Between String Types

The following Win32 functions translate character strings from one string type to another.

Function | Description
FoldString | Translates one character string to another.
LCMapString | Maps a character string by locale.
ToUnicode | Translates a virtual-key code into a Unicode character.
MultiByteToWideChar | Maps a multibyte string into a wide-character string.
WideCharToMultiByte | Maps a wide-character string into a multibyte string.

The WideCharToMultiByte and MultiByteToWideChar functions are particularly useful for applications that support several string types. ANSI C also defines the conversion functions wcstombs and mbstowcs, but they can only convert to and from the character set supported by the standard C library.


Command-line Arguments

An application can use the GetCommandLine function to retrieve Unicode command-line arguments by calling it as a Unicode function.


Using Strings and Unicode

This section covers the following topics.

  • Using generic data types
  • Registering window classes
  • Subclassing and automatic message translation
  • Using special characters in Unicode
  • Using functions that have no Unicode equivalents


Using Generic Data Types

If you use generic data types in your code, it can be compiled for Unicode simply by defining UNICODE before the include statements for the header files. To compile the code for ANSI, omit the UNICODE definition.

To convert code to be compiled for either ANSI or Unicode

  1. Change all character and string types used for text to TCHAR, LPTSTR, or LPTCH.
  2. Be sure that pointers to nontext data buffers or binary byte arrays are coded with the LPBYTE type and not mistakenly with the LPTSTR or LPTCH type. Declare pointers of indeterminate type explicitly as void pointers by using LPVOID, as appropriate.
  3. Make pointer arithmetic type-independent. Using units of TCHAR size yields variables that are 2 bytes if UNICODE is defined, and 1 byte if UNICODE is not defined. Using pointer arithmetic always returns the number of elements indicated by the pointer, whether the elements are 1 or 2 bytes in size. The following expression always returns the number of elements, regardless of whether UNICODE is defined:
    cCount = lpEnd - lpStart;

    The following expression determines the number of bytes used:

    cByteCount = (lpEnd - lpStart) * sizeof(TCHAR);

    There is no need to change a statement like the following one, because the pointer increment points to the next character element.

    chNext = *++lpText;
  4. Replace literal strings and manifest character constants with macros. Change expressions like the following one.
        while(*lpFileName++ != '\\')
    {
    // ...
    }

    Use the TEXT macro as follows in this expression.

        while(*lpFileName++ != TEXT('\\'))
    {
    // ...
    }

    The TEXT macro causes strings to be evaluated as L"string" when UNICODE is defined, and as "string" otherwise. For easier management, move literal strings into resources, especially if they contain characters outside the ASCII range (that is, 0x00 through 0x7F).

  5. Call only the Unicode versions of the standard C–library string functions, as listed in Standard C Functions.
  6. Change any code that relies on 255 as the largest value for a character.

When you compile code that you have changed as outlined above, the compiler creates the same binary file as it did before you made the changes. When you define UNICODE during compilation, however, it is compiled as a Unicode application.


Registering Window Classes

A window class is supported by a window procedure. You can register a window class by using either the RegisterClassA or RegisterClassW function. If you register the window class by using RegisterClassA, the application tells the system that the windows of the created class expect messages with text or character parameters to use the ANSI character set; if you register it by using RegisterClassW, the application requests that the system pass text parameters of messages as Unicode. The IsWindowUnicode function enables applications to query the nature of each window.

The following example shows how to register an ANSI window class and a Unicode window class and how to write the window procedures for both cases. For the purposes of this example, all functions and structures are shown with the specific A or W data types. Using the techniques explained in Using Generic Data Types, you could alternatively write this example by using generic data types, so that it could be compiled as either ANSI or Unicode, depending on whether UNICODE is defined.

// Register an ANSI window class.

WNDCLASSA AnsiWndCls;

AnsiWndCls.style         = CS_DBLCLKS | CS_PARENTDC;
AnsiWndCls.lpfnWndProc   = (WNDPROC)AnsiWndProc;
AnsiWndCls.cbClsExtra    = 0;
AnsiWndCls.cbWndExtra    = 0;
AnsiWndCls.hInstance     = hmodUser;
AnsiWndCls.hIcon         = NULL;
AnsiWndCls.hCursor       = LoadCursor(NULL, (LPTSTR)IDC_IBEAM);
AnsiWndCls.hbrBackground = NULL;
AnsiWndCls.lpszMenuName  = NULL;
AnsiWndCls.lpszClassName = "TestAnsi";

RegisterClassA(&AnsiWndCls);

// Register a Unicode window class.

WNDCLASSW UnicodeWndCls;

UnicodeWndCls.style         = CS_DBLCLKS | CS_PARENTDC;
UnicodeWndCls.lpfnWndProc   = (WNDPROC)UniWndProc;
UnicodeWndCls.cbClsExtra    = 0;
UnicodeWndCls.cbWndExtra    = 0;
UnicodeWndCls.hInstance     = hmodUser;
UnicodeWndCls.hIcon         = NULL;
UnicodeWndCls.hCursor       = LoadCursor(NULL,(LPTSTR)IDC_IBEAM);
UnicodeWndCls.hbrBackground = NULL;
UnicodeWndCls.lpszMenuName  = NULL;
UnicodeWndCls.lpszClassName = L"TestUnicode";

RegisterClassW(&UnicodeWndCls);

The following example shows the difference between handling the WM_CHAR message in an ANSI window procedure and a Unicode window procedure.

// ANSI Window Procedure

LONG AnsiWndProc(HWND hwnd, UINT message,
                 WPARAM wParam, LPARAM lParam)
{

    // Dispatch the messages that can be received.

    switch (message)
    {
        case WM_CHAR:

            // wParam - the value of the key
            // lParam - (not used in this example)

            if (lstrcmpA("Q", (LPCSTR) wParam))
            {
                // ...
            }
            else
            {
                // ...
            }
            break;
        // Process other messages.
    }
}

// Unicode Window Procedure

LONG UniWndProc(HWND hwnd, UINT message,
    WPARAM wParam, LPARAM lParam)
{

    // Dispatch the messages that can be received.

    switch (message)
    {
        case WM_CHAR:

            // wParam - the value of the key
            // lParam - (not used in this example)

            if (lstrcmpW(L"Q", (LPCWSTR) wParam))
            {
                // ...
            }
            else
            {
                // ...
            }
            break;
        // Process other messages.
    }
}

All text in messages received by AnsiWndProc will be composed of ANSI characters, and all text in messages received by UniWndProc will be composed of Unicode characters.


Subclassing and Automatic Message Translation

Subclassing is a technique that allows an application to intercept and process messages sent or posted to a particular window before the window has a chance to process them. The system automatically translates messages into ANSI or Unicode form, depending on the form of the function that subclassed the window procedure.

The following call to the SetWindowLongA function subclasses the current window procedure associated with the window identified by the hwnd parameter. The new window procedure, NewWndProc, will receive messages with text in ANSI format.

OldWndProc = (WNDPROC) SetWindowLongA(hwnd,
    GWL_WNDPROC, (LONG)NewWndProc);

When NewWndProc has finished processing a message, it uses the CallWindowProc function as follows to pass the message to OldWndProc.

CallWindowProc(OldWndProc, hwnd, uMessage, wParam, lParam);

If OldWndProc was created with a class style of UNICODE, messages will be translated from the ANSI form received by NewWndProc into Unicode.

Similarly, a call to the SetWindowLongW function would subclass the current window procedure with a window procedure that expects Unicode text messages. Message translation, if necessary, is performed during the processing of the CallWindowProc function.

For more information about subclassing, see Window Procedures.


Using Special Characters in Unicode

Unicode has a few special characters and characters that have unusual meanings in text strings. To avoid unexpected problems with these characters, use the rules provided in the following topics.

  • Null-terminated strings
  • Byte-order mark
  • Escape sequences and control characters
  • Line and paragraph separators
  • ASCII control codes 0x000D and 0x000A
  • Nonspacing characters and diacritics


Null-terminated Strings

Always cast zero to TCHAR when using null-terminated strings. The code 0x0000 is the Unicode string terminator for null-terminated strings. A single null byte is not sufficient for this code, because many Unicode characters contain null bytes as either the high or the low byte. An example is the letter A, for which the character code is 0x0041.


Byte-order Mark

Always prefix a Unicode plain text file with a byte-order mark. Because Unicode plain text is a sequence of 16-bit code values, it is sensitive to the byte ordering used when the text was written.

A byte-order mark is not a control character that selects the byte order of the text; it simply informs an application receiving the file that the file is byte ordered.

Ideally, all Unicode text would follow only one set of byte-ordering rules. This is not possible, however, because microprocessors differ in the placement of the least significant byte: Intel® and MIPS® processors position the least significant byte first, whereas Motorola processors (and all byte-reversed Unicode files) position it last. With only a single set of byte-ordering rules, users of one type of microprocessor would be forced to swap the byte order every time a plain text file is read from or written to, even if the file is never transferred to another system based on a different microprocessor.

The preferred place to specify byte order is in a file header, but text files do not have headers. Therefore, Unicode has defined a character (0xFEFF) and a noncharacter (0xFFFE) as byte-order marks. They are mirror byte-images of each other.

Since the sequence 0xFEFF is exceedingly rare at the outset of regular non-Unicode text files, it can serve as an implicit marker or signature to identify the file as a Unicode file. Applications that read both Unicode and non-Unicode text files should use the presence of this sequence as an indicator that the file is most likely a Unicode file. (Compare this technique to using the MS-DOS EOF marker to terminate text files.)

When an application finds 0xFEFF at the beginning of a text file, it typically processes the file as though it were a Unicode file, although it may also perform further heuristic checks to verify that this is true. Such a check could be as simple as testing whether the variation in the low-order bytes is much higher than the variation in the high-order bytes. For example, if ASCII text is converted to Unicode text, every second byte is zero. Also, checking both for the linefeed and carriage-return characters (0x000A and 0x000D) and for even or odd file size can provide a strong indicator of the nature of the file.

When an application finds 0xFFFE at the beginning of a text file, it interprets it to mean the file is a byte-reversed Unicode file. The application can either swap the order of the bytes or alert the user that an error has occurred.

The Unicode byte-order mark character is not found in any code page, so it disappears if data is converted to ANSI. Unlike other Unicode characters, it is not replaced by a default character when it is converted. If a byte-order mark is found in the middle of a file, it is not interpreted as a Unicode character and has no effect on text output.

The Unicode value 0xFFFF is illegal in plain text files and cannot be passed between Win32 functions. The value 0xFFFF is reserved for an application's private use.


Escape Sequences and Control Characters

You should translate escape sequences character by character into Unicode. When an ASCII plain text file is converted to Unicode, there is a chance that it will subsequently be converted back to ASCII. Converting escape sequences into Unicode on a character-by-character basis, rather than as a single 2-byte characters makes it possible to perform the reverse conversion without needing to recognize and parse the escape sequences as such. For example, ESC+A should become 0x001B (ESC), 0x0041 (A), rather than 0x411B.

The first 32 16-bit code values in Unicode are intended for the 32 control characters. This approach supports the existing use of control characters for formatting purposes—that is, Unicode applications can treat these control characters in exactly the same way as they treat their ASCII equivalents.


ASCII Control Codes 0x000D and 0x000A

The Unicode standard does not prescribe a specific meaning for the control codes 0x000D (carriage return) and 0x000A (linefeed). There is no requirement that these codes be used in combination, and if used individually, either code may represent either itself only or both codes together. It is entirely up to the application to determine what these codes represent. (Applications have always had to interpret these control codes in ASCII; the Unicode policy is not a change in their use.)


Line and Paragraph Separators

Use the line-separator character (0x2028) and the paragraph-separator character (0x2029) to divide plain text. A new line is begun after each line separator. A new paragraph is begun after each paragraph separator.

Because these are separator codes, it is not necessary to start the first line or paragraph in the file with them, or to end the last line or paragraph with them. (Doing so would indicate that there is an empty line or paragraph in that location.)

The line separator can be used to indicate an unconditional end of line. However, line separators do not correspond to the carriage-return and linefeed characters, or to the carriage-return–linefeed character combination; they must be processed separately from carriage return and linefeed characters.

The paragraph separator can be inserted between paragraphs of text. This allows plain text files to be created that can be formatted with different line widths on different systems. The receiving system can ignore any line breaks and break paragraphs only at the paragraph separators.


Nonspacing Characters and Diacritics

When breaking lines or otherwise separating text, be sure to keep nonspacing characters with their base characters. Many scripts contain characters that visually combine with other characters on output—for example, the diacritical marks (or "floating accents"). In Unicode, nonspacing characters follow their base character.


Using Functions That Have No Unicode Equivalents

Win32 functions that have not been exported in a Unicode version have typically been replaced by more powerful or extended functions that do support Unicode. If you are porting code that calls the OpenFile function, for example, you can support Unicode by using the CreateFile function instead.

If a function has no Unicode equivalent, you can map characters to and from 8-bit character sets before and after the function call. For example, the number-formatting functions atoi and itoa use only the digits 0 through 9. Normally, mapping Unicode to 8-bit characters could cause loss of data, but this can be avoided by making the code type-independent and conditionalizing the expressions. For example, the following statements are type-dependent and should be changed to support Unicode.

    char str[4];

    num = atoi(str);

These statements could be rewritten as follows to make them type independent.

    TCHAR tstr[4];

    CHAR strTmp[SIZE];

    #ifdef UNICODE

    wcstombs(strTmp, (const wchar_t *) tstr, sizeof(strTmp));

    num = atoi(strTmp);

    #else

    num = atoi(tstr);

    #endif

In this example, the wcstombs function is the standard C function that translates Unicode to ASCII. The example relies on the fact that the digits 0 through 9 can always be translated from Unicode to ASCII, even if some of the surrounding text cannot. The atoi function stops at any character that is not a digit. You can use the LCMapString function if you need to process text that includes the native digits provided for some of the scripts in Unicode.


Unicode and Character Set Reference

The following elements are used with character sets:

  • Unicode and Character Set Functions
  • Unicode and Character Set Structures
  • Unicode and Character Set Macros
  • Unicode and Character Set Constants
  • Unicode Subset Bitfields


Unicode and Character Set Functions

The following functions are used with character sets.

Function | Description
GetTextCharset | Retrieves a character-set identifier for the font that is currently selected into a specified device context.
GetTextCharsetInfo | Retrieves information about the character set of the font that is currently selected into a specified device context.
IsDBCSLeadByte | Determines whether a character is a lead byte.
IsDBCSLeadByteEx | Determines whether a character is a lead byte.
IsTextUnicode | Determines whether a buffer is likely to contain a form of Unicode text.
MultiByteToWideChar | Maps a character string to a wide-character (Unicode) string.
TranslateCharsetInfo | Translates based on the specified character set, code page, or font signature value.
WideCharToMultiByte | Maps a wide-character string to a new character string.


GetTextCharset

The GetTextCharset function retrieves a character-set identifier for the font that is currently selected into a specified device context.

The function call GetTextCharset(hdc) is equivalent to the function call GetTextCharsetInfo(hdc, NULL, 0).

int GetTextCharset(
  HDC hdc,  // handle to DC
);

Parameters

hdc
[in] Handle to a device context. The function obtains a character-set identifier for the font that is selected into this device context.

Return Values

If the function succeeds, the return value identifies the character set of the font that is currently selected into the specified device context. The following character-set identifiers are defined:

ANSI_CHARSET
BALTIC_CHARSET
CHINESEBIG5_CHARSET
DEFAULT_CHARSET
EASTEUROPE_CHARSET
GB2312_CHARSET
GREEK_CHARSET 		HANGUL_CHARSET
MAC_CHARSET
OEM_CHARSET
RUSSIAN_CHARSET
SHIFTJIS_CHARSET
SYMBOL_CHARSET
TURKISH_CHARSET

Korean language edition of Windows:
JOHAB_CHARSET
Middle East language edition of Windows:
HEBREW_CHARSET
ARABIC_CHARSET
Thai language edition of Windows:
THAI_CHARSET

If the function fails, the return value is DEFAULT_CHARSET.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Wingdi.h; include Windows.h.
Library: Use Gdi32.lib.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Functions, GetTextCharsetInfo


GetTextCharsetInfo

The GetTextCharsetInfo function retrieves information about the character set of the font that is currently selected into a specified device context.

int GetTextCharsetInfo(
  HDC hdc,                // handle to DC
  LPFONTSIGNATURE lpSig,  // data buffer
  DWORD dwFlags           // reserved; must be zero
);

Parameters

hdc
[in] Handle to a device context. The function obtains information about the font that is selected into this device context.
lpSig
[out] Pointer to a FONTSIGNATURE data structure that receives font-signature information.

If a TrueType font is currently selected into the device context, the FONTSIGNATURE structure receives information that identifies the code page and Unicode subranges for which the font provides glyphs.

If a font other than TrueType is currently selected into the device context, the FONTSIGNATURE structure receives zeroes. In this case, use the TranslateCharsetInfo function to obtain generic font-signature information for the character set.

The lpSig parameter can be NULL if you do not need the FONTSIGNATURE information. In this case, you can also call the GetTextCharset function, which is equivalent to calling GetTextCharsetInfo with lpSig set to NULL.

dwFlags
This parameter is reserved for future use. It must be set to zero.

Return Values

If the function succeeds, the return value identifies the character set of the font currently selected into the specified device context. The following character-set identifiers are defined:

ANSI_CHARSET
BALTIC_CHARSET
CHINESEBIG5_CHARSET
DEFAULT_CHARSET
EASTEUROPE_CHARSET
GB2312_CHARSET
GREEK_CHARSET 		HANGUL_CHARSET
MAC_CHARSET
OEM_CHARSET
RUSSIAN_CHARSET
SHIFTJIS_CHARSET
SYMBOL_CHARSET
TURKISH_CHARSET

Korean language edition of Windows:
JOHAB_CHARSET
Middle-Eastern language edition of Windows:
HEBREW_CHARSET
ARABIC_CHARSET
Thai language edition of Windows:
THAI_CHARSET

If the function fails, the return value is DEFAULT_CHARSET.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Wingdi.h; include Windows.h.
Library: Use Gdi32.lib.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Functions, FONTSIGNATURE, GetTextCharset, TranslateCharsetInfo


IsDBCSLeadByte

The IsDBCSLeadByte function determines whether a specified byte is potentially a lead byte—that is, the first byte of a character in a double-byte character set (DBCS).

BOOL IsDBCSLeadByte(
  BYTE TestChar   // character to test
);

Parameters

TestChar
[in] Specifies the byte to be tested.

Return Values

If the byte is potentially a lead byte, it returns a nonzero value.

If the byte is not a lead byte, the return value is zero. To get extended error information, call GetLastError.

Remarks

Some byte values can appear in both the leading and trailing byte of a DBCS character. Thus, IsDBCSLeadByte can only indicate a potential lead byte value.

Lead bytes are unique to double-byte character sets. A lead byte introduces a double-byte character. Lead bytes occupy a specific range of byte values. The IsDBCSLeadByte function uses the ANSI code page to check lead-byte ranges. To specify a different code page, use the IsDBCSLeadByteEx function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Functions, IsDBCSLeadByteEx, MultiByteToWideChar


IsDBCSLeadByteEx

The IsDBCSLeadByteEx function determines whether a specified byte is a lead byte that is, the first byte of a character in a double-byte character set (DBCS).

BOOL IsDBCSLeadByteEx(
  UINT CodePage,   // identifier of code page
  BYTE TestChar    // byte to test
);

Parameters

CodePage
[in] Identifier of the code page to use to check lead-byte ranges. Can be one of the values given in the "Code-Page Identifiers" table in Unicode and Character Set Constants or one of the following predefined values.
Value | Meaning
0 | Use system default ANSI code page.
CP_ACP | Use system default ANSI code page.
CP_OEMCP | Use system default OEM code page.

TestChar
[in] Byte to test.

Return Values

If the byte is a lead byte, it returns a nonzero value.

If the byte is not a lead byte, the return value is zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Functions


IsTextUnicode

The IsTextUnicode function determines whether a buffer is likely to contain a form of Unicode text. The function uses various statistical and deterministic methods to make its determination, under the control of flags passed via lpi. When the function returns, the results of such tests are reported via lpi.

BOOL IsTextUnicode(
  CONST VOID *lpBuffer, // input buffer to be examined
  int cb,                // size of input buffer
  LPINT lpi              // options
);

Parameters

lpBuffer
[in] Pointer to the input buffer to be examined.
cb
[in] Specifies the size, in bytes, of the input buffer pointed to by lpBuffer.
lpi
[in/out] On input, specifies the tests to be applied to the input buffer text. On output, receives the results of the specified tests: 1 if the contents of the buffer pass a test, zero for failure. Only flags that are set upon input to the function are significant upon output.

If lpi is NULL, the function uses all available tests to determine whether the data in the buffer is likely to be Unicode text.

This parameter can be one or more of the following values.
Value | Meaning
IS_TEXT_UNICODE_ASCII16 | The text is Unicode, and contains onlyzero-extended ASCII values/characters.
IS_TEXT_UNICODE_REVERSE_ASCII16 | Same as the preceding, except that the Unicode text is byte-reversed.
IS_TEXT_UNICODE_STATISTICS | The text is probably Unicode, with the determination made by applying statistical analysis. Absolute certainty is not guaranteed. See the following Remarks section.
IS_TEXT_UNICODE_REVERSE_STATISTICS | Same as the preceding, except that the probably-Unicode text is byte-reversed.
IS_TEXT_UNICODE_CONTROLS | The text contains Unicode representations of one or more of these nonprinting characters: RETURN, LINEFEED, SPACE, CJK_SPACE, TAB.
IS_TEXT_UNICODE_REVERSE_CONTROLS | Same as the preceding, except that the Unicode characters are byte-reversed.
IS_TEXT_UNICODE_BUFFER_TOO_SMALL | There are too few characters in the buffer for meaningful analysis (fewer than two bytes).
IS_TEXT_UNICODE_SIGNATURE | The text contains the Unicode byte-order mark (BOM) 0xFEFF as its first character.
IS_TEXT_UNICODE_REVERSE_SIGNATURE | The text contains the Unicode byte-reversed byte-order mark (Reverse BOM) 0xFFFE as its first character.
IS_TEXT_UNICODE_ILLEGAL_CHARS | The text contains one of these Unicode-illegal characters: embedded Reverse BOM, UNICODE_NUL, CRLF (packed into one WORD), or 0xFFFF.
IS_TEXT_UNICODE_ODD_LENGTH | The number of characters in the string is odd. A string of odd length cannot (by definition) be Unicode text.
IS_TEXT_UNICODE_NULL_BYTES | The text contains null bytes, which indicate non-ASCII text.
IS_TEXT_UNICODE_UNICODE_MASK | This flag constant is a combination of IS_TEXT_UNICODE_ASCII16, IS_TEXT_UNICODE_STATISTICS, IS_TEXT_UNICODE_CONTROLS, IS_TEXT_UNICODE_SIGNATURE.
IS_TEXT_UNICODE_REVERSE_MASK | This flag constant is a combination of IS_TEXT_UNICODE_REVERSE_ASCII16, IS_TEXT_UNICODE_REVERSE_STATISTICS, IS_TEXT_UNICODE_REVERSE_CONTROLS, IS_TEXT_UNICODE_REVERSE_SIGNATURE.
IS_TEXT_UNICODE_NOT_UNICODE_MASK | This flag constant is a combination of IS_TEXT_UNICODE_ILLEGAL_CHARS, IS_TEXT_UNICODE_ODD_LENGTH, and two currently unused bit flags.
IS_TEXT_UNICODE_NOT_ASCII_MASK | This flag constant is a combination of IS_TEXT_UNICODE_NULL_BYTES and three currently unused bit flags.

Return Values

The function returns a nonzero value if the data in the buffer passes the specified tests.

The function returns zero if the data in the buffer does not pass the specified tests.

Remarks

As noted in the preceding table of flag constants, the IS_TEXT_UNICODE_STATISTICS and IS_TEXT_UNICODE_REVERSE_STATISTICS tests use statistical analysis. These tests are not foolproof. The statistical tests assume certain amounts of variation between low and high bytes in a string, and some ASCII strings can slip through. For example, if lpBuffer points to the ASCII string 0x41, 0x0A, 0x0D, 0x1D (A\n\r^Z), the string passes the IS_TEXT_UNICODE_STATISTICS test, though failure would be preferable.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Advapi32.lib.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Functions


MultiByteToWideChar

The MultiByteToWideChar function maps a character string to a wide-character (Unicode) string. The character string mapped by this function is not necessarily from a multibyte character set.

int MultiByteToWideChar(
  UINT CodePage,         // code page
  DWORD dwFlags,         // character-type options
  LPCSTR lpMultiByteStr, // string to map
  int cbMultiByte,       // number of bytes in string
  LPWSTR lpWideCharStr,  // wide-character buffer
  int cchWideChar        // size of buffer
);

Parameters

CodePage
[in] Specifies the code page to be used to perform the conversion. This parameter can be given the value of any code page that is installed or available in the system. You can also specify one of the values shown in the following table.
Value | Meaning
CP_ACP | ANSI code page
CP_MACCP | Macintosh code page
CP_OEMCP | OEM code page
CP_SYMBOL | Windows 2000 or later: Symbol code page (42)
CP_THREAD_ACP | Windows 2000 or later: The current thread's ANSI code page
CP_UTF7 | Windows 98 and Windows NT 4.0 and later: Translate using UTF-7
CP_UTF8 | Windows 98 and Windows NT 4.0 and later: Translate using UTF-8. When this is set, dwFlags must be zero.

dwFlags
[in] Indicates whether to translate to precomposed or composite-wide characters (if a composite form exists), whether to use glyph characters in place of control characters, and how to deal with invalid characters. You can specify a combination of the following flag constants.
Value | Meaning
MB_PRECOMPOSED | Always use precomposed characters—that is, characters in which a base character and a nonspacing character have a single character value. This is the default translation option. Cannot be used with MB_COMPOSITE.
MB_COMPOSITE | Always use composite characters—that is, characters in which a base character and a nonspacing character have different character values. Cannot be used with MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS | If the function encounters an invalid input character, it fails and GetLastError returns ERROR_NO_UNICODE_TRANSLATION.
MB_USEGLYPHCHARS | Use glyph characters instead of control characters.

A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/nonspacing character combination. In the character è, the e is the base character and the accent grave mark is the nonspacing character.

The function's default behavior is to translate to the precomposed form. If a precomposed form does not exist, the function attempts to translate to a composite form.

The flags MB_PRECOMPOSED and MB_COMPOSITE are mutually exclusive. The MB_USEGLYPHCHARS flag and the MB_ERR_INVALID_CHARS can be set regardless of the state of the other flags.

lpMultiByteStr
[in] Points to the character string to be converted.
cbMultiByte
[in] Specifies the size in bytes of the string pointed to by the lpMultiByteStr parameter, or it can be -1 if the string is null terminated.

If this parameter is -1, the function processes the entire input string including the null terminator. The resulting wide character string therefore has a null terminator, and the returned length includes the null terminator.

If this parameter is a positive integer, the function processes exactly the specified number of bytes. If the given length does not include a null terminator then the resulting wide character string will not be null terminated, and the returned length does not include a null terminator.

lpWideCharStr
[out] Points to a buffer that receives the translated string.
cchWideChar
[in] Specifies the size, in wide characters, of the buffer pointed to by the lpWideCharStr parameter. If this value is zero, the function returns the required buffer size, in wide characters, and makes no use of the lpWideCharStr buffer.

Return Values

If the function succeeds, and cchWideChar is nonzero, the return value is the number of wide characters written to the buffer pointed to by lpWideCharStr.

If the function succeeds, and cchWideChar is zero, the return value is the required size, in wide characters, for a buffer that can receive the translated string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER
ERROR_NO_UNICODE_TRANSLATION

Remarks

The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns the value ERROR_INVALID_PARAMETER.

The function fails if MB_ERR_INVALID_CHARS is set and encounters an invalid character in the source string. An invalid character is either, a) a character that is not the default character in the source string but translates to the default character when MB_ERR_INVALID_CHARS is not set, or b) for DBCS strings, a character which has a lead byte but no valid trailing byte. When an invalid character is found, and MB_ERR_INVALID_CHARS is set, the function returns 0 and sets GetLastError with the error ERROR_NO_UNICODE_TRANSLATION.

MAPI: For more information, see Syntax and Limitations for Win32 Functions Useful in MAPI Development.

For an example, see Looking Up a User's Full Name.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Functions, WideCharToMultiByte


TranslateCharsetInfo

The TranslateCharsetInfo function translates based on the specified character set, code page, or font signature value, setting all members of the destination structure to appropriate values.

BOOL TranslateCharsetInfo(
  DWORD *lpSrc,        // information
  LPCHARSETINFO lpCs,  // character set information
  DWORD dwFlags        // translation option
);

Parameters

lpSrc
[in/out] If dwFlags is TCI_SRCFONTSIG, this parameter is the address of the fsCsb member of a FONTSIGNATURE structure. Otherwise, this parameter is a DWORD value.
lpCs
[out] Pointer to a CHARSETINFO structure that receives the translated character set information.
dwFlags
[in] Specifies how to perform the translation. This parameter can be one of the following values.
Value | Meaning
TCI_SRCCHARSET | Source contains the character set value in the low word, and zero in the high word.
TCI_SRCCODEPAGE | Source is a code-page identifier in the low word and zero in the high word.
TCI_SRCFONTSIG Source is the code-page bitfield portion of a FONTSIGNATURE structure. On input this should have only one Windows code-page bit set, either for an ANSI code-page value or for a common ANSI and OEM value (for OEM values, bits 32-63 must be clear.). On output this will have only one bit set.

If the TCI_SRCFONTSIG value is given, the lpSrc parameter must be the address of the code-page bitfield. If any other TCI_ value is given, the lpSrc parameter must be a value not an address.

Return Values

If the function succeeds, it returns a nonzero value.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Wingdi.h; include Windows.h.
Library: Use Gdi32.lib.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Functions, CHARSETINFO, FONTSIGNATURE


WideCharToMultiByte

The WideCharToMultiByte function maps a wide-character string to a new character string. The new character string is not necessarily from a multibyte character set.

int WideCharToMultiByte(
  UINT CodePage,            // code page
  DWORD dwFlags,            // performance and mapping flags
  LPCWSTR lpWideCharStr,    // wide-character string
  int cchWideChar,          // number of chars in string
  LPSTR lpMultiByteStr,     // buffer for new string
  int cbMultiByte,          // size of buffer
  LPCSTR lpDefaultChar,     // default for unmappable chars
  LPBOOL lpUsedDefaultChar  // set when default char used
);

Parameters

CodePage
[in] Specifies the code page used to perform the conversion. This parameter can be given the value of any code page that is installed or available in the system. You can also specify one of the following values.
Value | Meaning
CP_ACP | ANSI code page
CP_MACCP | Macintosh code page
CP_OEMCP | OEM code page
CP_SYMBOL | Windows 2000 or later: Symbol code page (42)
CP_THREAD_ACP | Windows 2000 or later: Current thread's ANSI code page
CP_UTF7 | Windows 98, Windows Me, Windows NT 4.0 and Windows 2000 or later: Translate using UTF-7. When this is set, lpDefaultChar and lpUsedDefaultChar must be NULL
CP_UTF8 | Windows 98, Windows Me, Windows NT 4.0 and Windows 2000 or later: Translate using UTF-8. When this is set, dwFlags must be zero and both lpDefaultChar and lpUsedDefaultChar must be NULL.

dwFlags
[in] Specifies the handling of unmapped characters. The function performs more quickly when none of these flags is set. The following flag constants are defined.
Value | Meaning
WC_NO_BEST_FIT_CHARS Windows 2000 or later: Any Unicode characters that do not translate directly to multibyte equivalents will be translated to the default character (see lpDefaultChar parameter). In other words, if translating from Unicode to multibyte and back to Unicode again does not yield the exact same Unicode character, the default character is used.

This flag may be used by itself or in combination with the other dwFlag options.
WC_COMPOSITECHECK | Convert composite characters to precomposed characters.
WC_DISCARDNS | Discard nonspacing characters during conversion.
WC_SEPCHARS | Generate separate characters during conversion. This is the default conversion behavior.
WC_DEFAULTCHAR | Replace exceptions with the default character during conversion.

When WC_COMPOSITECHECK is specified, the function converts composite characters to precomposed characters. A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/nonspacing character combination. In the character è, the e is the base character, and the accent grave mark is the nonspacing character.

When an application specifies WC_COMPOSITECHECK, it can use the last three flags in this list (WC_DISCARDNS, WC_SEPCHARS, and WC_DEFAULTCHAR) to customize the conversion to precomposed characters. These flags determine the function's behavior when there is no precomposed mapping for a base/nonspace character combination in a wide-character string. These last three flags can only be used if the WC_COMPOSITECHECK flag is set.

The function's default behavior is to generate separate characters (WC_SEPCHARS) for unmapped composite characters.

lpWideCharStr
[in] Points to the wide-character string to be converted.
cchWideChar
[in] Specifies the number of wide characters in the string pointed to by the lpWideCharStr parameter. If this value is –1, the string is assumed to be null-terminated and the length is calculated automatically. The length will include the null-terminator.
lpMultiByteStr
[out] Points to the buffer to receive the translated string.
cbMultiByte
[in] Specifies the size, in bytes, of the buffer pointed to by the lpMultiByteStr parameter. If this value is zero, the function returns the number of bytes required for the buffer. (In this case, the lpMultiByteStr buffer is not used.)
lpDefaultChar
[in] Points to the character used if a wide character cannot be represented in the specified code page. If this parameter is NULL, a system default value is used. The function is faster when both lpDefaultChar and lpUsedDefaultChar are NULL.

If CodePage is either CP_UTF7 or CP_UTF8, this parameter must be NULL.

lpUsedDefaultChar
[in] Points to a flag that indicates whether a default character was used. The flag is set to TRUE if one or more wide characters in the source string cannot be represented in the specified code page. Otherwise, the flag is set to FALSE. This parameter may be NULL. The function is faster when both lpDefaultChar and lpUsedDefaultChar are NULL.

If CodePage is either CP_UTF7 or CP_UTF8, this parameter must be NULL.

Return Values

If the function succeeds, and cbMultiByte is nonzero, the return value is the number of bytes written to the buffer pointed to by lpMultiByteStr. The number includes the byte for the null terminator.

If the function succeeds, and cbMultiByte is zero, the return value is the required size, in bytes, for a buffer that can receive the translated string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

If CodePage is CP_SYMBOL and cbMultiByte is less than cchWideChar, no characters are written to lpMultiByte. Otherwise, if cbMultiByte is less than cchWideChar, cbMultiByte characters are copied to the buffer pointed to by lpMultiByte.

An application can use the lpDefaultChar parameter to change the default character used for the conversion.

As noted earlier, the WideCharToMultiByte function operates most efficiently when both lpDefaultChar and lpUsedDefaultChar are NULL. The following table shows the behavior of WideCharToMultiByte for the four combinations of lpDefaultChar and lpUsedDefaultChar.

lpDefaultChar | lpUsedDefaultChar | Result
NULL | NULL | No default checking. This is the most efficient way to use this function.
non-NULL | NULL | Uses the specified default character, but does not set lpUsedDefaultChar.
NULL | non-NULL | Uses the system default character and sets lpUsedDefaultChar if necessary.
non-NULL | non-NULL | Uses the specified default character and sets lpUsedDefaultChar if necessary.

MAPI: For more information, see Syntax and Limitations for Win32 Functions Useful in MAPI Development.

For an example, see Looking Up a User's Full Name.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Functions, MultiByteToWideChar


Unicode and Character Set Structures

The following structures are used by the character set functions.

  • CHARSETINFO
  • FONTSIGNATURE
  • LOCALESIGNATURE


CHARSETINFO

The CHARSETINFO structure contains information about a character set.

typedef struct {
  UINT ciCharset;
  UINT ciACP;
  FONTSIGNATURE fs;
} CHARSETINFO, *PCHARSETINFO;

Members

ciCharset
Character set value.
ciACP
ANSI code-page identifier.
fs
A FONTSIGNATURE structure that identifies the Unicode and code page–font signature values. Only one code page will be set when this structure is set by the function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Wingdi.h; include Windows.h.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Structures, FONTSIGNATURE, TranslateCharsetInfo


FONTSIGNATURE

The FONTSIGNATURE structure contains information identifying the code pages and Unicode subranges for which a given font provides glyphs.

typedef struct tagFONTSIGNATURE {
  DWORD  fsUsb[4];
  DWORD  fsCsb[2];
} FONTSIGNATURE, *PFONTSIGNATURE;

Members

fsUsb
A 128-bit Unicode subset bitfield (USB) identifying up to 126 Unicode subranges. Each bit, except the two most significant bits, represents a single subrange. The most significant bit is always 1 and identifies the bitfield as a font signature; the second most significant bit is reserved and must be 0. Unicode subranges are numbered in accordance with the ISO 10646 standard. For more information, see Unicode Subset Bitfields.
fsCsb
A 64-bit, code-page bitfield (CPB) that identifies a specific character set or code page. Code pages are in the lower 32 bits of this bitfield. The high 32 are used for non-Windows code pages. For more information, see Code-Page Bitfields.

Remarks

GDI relies on Windows code pages fitting within a 32-bit value. Furthermore, the highest 2 bits within this value are reserved for GDI internal use and may not be assigned to code pages.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Wingdi.h; include Windows.h.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Structures, LOCALESIGNATURE


LOCALESIGNATURE

The LOCALESIGNATURE structure contains extended font-signature information, including two code-page bitfields (CPBs) that define the default and supported character sets and code pages. This structure is typically used to represent the relationships between font coverage and locales.

typedef struct tagLOCALESIGNATURE {
  DWORD  lsUsb[4];
  DWORD  lsCsbDefault[2];
  DWORD  lsCsbSupported[2];
} LOCALESIGNATURE, *PLOCALESIGNATURE;

Members

lsUsb
A 128-bit Unicode subset bitfield (USB) identifying up to 126 Unicode subranges. Each bit, except the two most significant bits, represents a single subrange. The most significant bit is always 1 and identifies the bitfield as a font signature; the second most significant is reserved and must be 0. Unicode subranges are numbered in accordance with the ISO 10646 standard. For a list of possible bitfield values, see Unicode Subset Bitfields.
lsCsbDefault
A code-page bitfield that indicates the default OEM and ANSI code pages for a locale. The code pages may be identified by separate bits or a single bit representing a common ANSI and OEM code page. For a list of possible bitfield values, see Code-Page Bitfields.
lsCsbSupported
A code-page bitfield that indicates all the code pages in which the locale can be supported. For a list of possible bitfield values, see Code-Page Bitfields.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Wingdi.h; include Windows.h.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Structures, FONTSIGNATURE


Unicode and Character Set Macros

The following macro is used in Unicode applications.

TEXT


TEXT

The TEXT macro identifies a string as Unicode when the UNICODE is defined during compilation. Otherwise, it identifies a string as an ANSI string.

TEXT(
  LPTSTR string  // ANSI or Unicode string
);

Parameters

string
Pointer to the string to be interpreted as either Unicode or ANSI.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Unicode and Character Sets Overview, Unicode and Character Set Macros


Unicode and Character Set Constants

The following groups of constants are used with the character set functions.

  • ANSI Code-Page Identifiers
  • OEM Code-Page Identifiers
  • Code-Page Identifiers
  • Code-Page Bitfields
  • Unicode Subset Bitfields


ANSI Code Page Identifiers

Platform SDK: International Features

ANSI Code-Page Identifiers

Identifier | Meaning
874 | Thai
932 | Japanese
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan; Hong Kong SAR, PRC)
1200 | Unicode (BMP of ISO 10646)
1250 | Windows 3.1 Eastern European
1251 | Windows 3.1 Cyrillic
1252 | Windows 3.1 Latin 1 (US, Western Europe)
1253 | Windows 3.1 Greek
1254 | Windows 3.1 Turkish
1255 | Hebrew
1256 | Arabic
1257 | Baltic


OEM Code Page Identifiers

Platform SDK: International Features

OEM Code-Page Identifiers

Identifier | Meaning
437 | MS-DOS United States
708 | Arabic (ASMO 708)
709 | Arabic (ASMO 449+, BCON V4)
710 | Arabic (Transparent Arabic)
720 | Arabic (Transparent ASMO)
737 | Greek (formerly 437G)
775 | Baltic
850 | MS-DOS Multilingual (Latin I)
852 | MS-DOS Slavic (Latin II)
855 | IBM Cyrillic (primarily Russian)
857 | IBM Turkish
860 | MS-DOS Portuguese
861 | MS-DOS Icelandic
862 | Hebrew
863 | MS-DOS Canadian-French
864 | Arabic
865 | MS-DOS Nordic
866 | MS-DOS Russian
869 | IBM Modern Greek
874 | Thai
932 | Japanese
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan; Hong Kong SAR, PRC)
1361 | Korean (Johab)


Code Page Identifiers

Platform SDK: International Features

Code-Page Identifiers

Identifier | Meaning
037 | EBCDIC
437 | MS-DOS United States
500 | EBCDIC "500V1"
708 | Arabic (ASMO 708)
709 | Arabic (ASMO 449+, BCON V4)
710 | Arabic (Transparent Arabic)
720 | Arabic (Transparent ASMO)
737 | Greek (formerly 437G)
775 | Baltic
850 | MS-DOS Multilingual (Latin I)
852 | MS-DOS Slavic (Latin II)
855 | IBM Cyrillic (primarily Russian)
857 | IBM Turkish
860 | MS-DOS Portuguese
861 | MS-DOS Icelandic
862 | Hebrew
863 | MS-DOS Canadian-French
864 | Arabic
865 | MS-DOS Nordic
866 | MS-DOS Russian
869 | IBM Modern Greek
874 | Thai
875 | EBCDIC
932 | Japanese
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan; Hong Kong SAR, PRC)
1026 | EBCDIC
1200 | Unicode (BMP of ISO 10646)
1250 | Windows 3.1 Eastern European
1251 | Windows 3.1 Cyrillic
1252 | Windows 3.1 US (ANSI)
1253 | Windows 3.1 Greek
1254 | Windows 3.1 Turkish
1255 | Hebrew
1256 | Arabic
1257 | Baltic
1361 | Korean (Johab)
10000 | Macintosh Roman
10001 | Macintosh Japanese
10006 | Macintosh Greek I
10007 | Macintosh Cyrillic
10029 | Macintosh Latin 2
10079 | Macintosh Icelandic
10081 | Macintosh Turkish


Code Page Bitfields

Platform SDK: International Features

Code-Page Bitfields

The Code-Page Bitfields are used in the FONTSIGNATURE and LOCALESIGNATURE structures.

Bit | Code page | Description
ANSI |  |
0 | 1252 | Latin 1
1 | 1250 | Latin 2: Eastern Europe
2 | 1251 | Cyrillic
3 | 1253 | Greek
4 | 1254 | Turkish
5 | 1255 | Hebrew
6 | 1256 | Arabic
7 | 1257 | Baltic
8 | 1258 | VietNam
9 - 15 |  | Reserved for ANSI
ANSI and OEM |  |
16 | 874 | Thai
17 | 932 | Japanese, Shift-JIS
18 | 936 | Chinese: Simplified chars—PRC and Singapore
19 | 949 | Korean Unified Hangeul Code (Hangeul TongHabHyung Code)
20 | 950 | Chinese: Traditional chars—Hong Kong SAR, PRC and Taiwan
21 | 1361 | Korean (Johab)
22 - 29 |  | Reserved for alternate ANSI and OEM
30 - 31 |  | Reserved by system.
OEM |  |
32 - 46 |  | Reserved for OEM
47 | 1258 | VietNam
48 | 869 | IBM Greek
49 | 866 | MS-DOS Russian
50 | 865 | MS-DOS Nordic
51 | 864 | Arabic
52 | 863 | MS-DOS Canadian French
53 | 862 | Hebrew
54 | 861 | MS-DOS Icelandic
55 | 860 | MS-DOS Portuguese
56 | 857 | IBM Turkish
57 | 855 | IBM Cyrillic; primarily Russian
58 | 852 | Latin 2
59 | 775 | Baltic
60 | 737 | Greek; former 437 G
61 | 708 | Arabic; ASMO 708
62 | 850 | Western European/Latin 1
63 | 437 | US


Unicode Subset Bitfields

The Unicode Subset Bitfields (USB) are used in the FONTSIGNATURE and LOCALESIGNATURE structures.

Bit | Unicode subrange | Description
0 | 0020 - 007e | Basic Latin
1 | 00a0 - 00ff | Latin-1 Supplement
2 | 0100 - 017f | Latin Extended-A
3 | 0180 - 024f | Latin Extended-B
4 | 0250 - 02af | IPA Extensions
5 | 02b0 - 02ff | Spacing Modifier Letters
6 | 0300 - 036f | Combining Diacritical Marks
7 | 0370 - 03ff | Basic Greek
8 |  | Reserved
9 | 0400 - 04ff | Cyrillic
10 | 0530 - 058f | Armenian
11 | 0590 - 05ff | Basic Hebrew
12 |  | Reserved
13 | 0600 - 06ff | Basic Arabic
14 |  | Reserved
15 | 0900 - 097f | Devanagari
16 | 0980 - 09ff | Bengali
17 | 0a00 - 0a7f | Gurmukhi
18 | 0a80 - 0aff | Gujarati
19 | 0b00 - 0b7f | Oriya
20 | 0b80 - 0bff | Tamil
21 | 0c00 - 0c7f | Telugu
22 | 0c80 - 0cff | Kannada
23 | 0d00 - 0d7f | Malayalam
24 | 0e00 - 0e7f | Thai
25 | 0e80 - 0eff | Lao
26 | 10a0 - 10ff | Basic Georgian
27 |  | Reserved
28 | 1100 - 11ff | Hangul Jamo
29 | 1e00 - 1eff | Latin Extended Additional
30 | 1f00 - 1fff | Greek Extended
31 | 2000 - 206f | General Punctuation
32 | 2070 - 209f | Subscripts and Superscripts
33 | 20a0 - 20cf | Currency Symbols
34 | 20d0 - 20ff | Combining Diacritical Marks for Symbols
35 | 2100 - 214f | Letter-like Symbols
36 | 2150 - 218f | Number Forms
37 | 2190 - 21ff | Arrows
38 | 2200 - 22ff | Mathematical Operators
39 | 2300 - 23ff | Miscellaneous Technical
40 | 2400 - 243f | Control Pictures
41 | 2440 - 245f | Optical Character Recognition
42 | 2460 - 24ff | Enclosed Alphanumerics
43 | 2500 - 257f | Box Drawing
44 | 2580 - 259f | Block Elements
45 | 25a0 - 25ff | Geometric Shapes
46 | 2600 - 26ff | Miscellaneous Symbols
47 | 2700 - 27bf | Dingbats
48 | 3000 - 303f | Chinese, Japanese, and Korean (CJK) Symbols and Punctuation
49 | 3040 - 309f | Hiragana
50 | 30a0 - 30ff | Katakana
51 | 3100 - 312f 31a0 - 31bf | Bopomofo Extended Bopomofo
52 | 3130 - 318f | Hangul Compatibility Jamo
53 | 3190 - 319f | CJK Miscellaneous
54 | 3200 - 32ff | Enclosed CJK Letters and Months
55 | 3300 - 33ff | CJK Compatibility
56 | ac00 - d7a3 | Hangul
57 | d800 - dfff | Surrogates. Note that setting this bit implies that there is at least one codepoint beyond the Basic Multilingual Plane that is supported by this font.
58 |  | Reserved
59 | 4e00 - 9fff 2e80 - 2eff 2f00 - 2fdf 2ff0 - 2fff 3400 - 4dbf | CJK Unified Ideographs CJK Radicals Supplement Kangxi Radicals Ideographic Description CJK Unified Ideograph Extension A
60 | e000 - f8ff | Private Use Area
61 | f900 - faff | CJK Compatibility Ideographs
62 | fb00 - fb4f | Alphabetic Presentation Forms
63 | fb50 - fdff | Arabic Presentation Forms-A
64 | fe20 - fe2f | Combining Half Marks
65 | fe30 - fe4f | CJK Compatibility Forms
66 | fe50 - fe6f | Small Form Variants
67 | fe70 - fefe | Arabic Presentation Forms-B
68 | ff00 - ffef | Halfwidth and Fullwidth Forms
69 | fff0 - fffd | Specials
70 | 0f00 - 0fcf | Tibetan
71 | 0700 - 074f | Syriac
72 | 0780 - 07bf | Thaana
73 | 0d80 - 0dff | Sinhala
74 | 1000 - 109f | Myanmar
75 | 1200 - 12bf | Ethiopic
76 | 13a0 - 13ff | Cherokee
77 | 1400 - 14df | Canadian Aboriginal Syllabics
78 | 1680 - 169f | Ogham
79 | 16a0 - 16ff | Runic
80 | 1780 - 17ff | Khmer
81 | 1800 - 18af | Mongolian
82 | 2800 - 28ff | Braille
83 | a000 - a48c | Yi Yi Radicals
84-122 |  | Reserved
123 |  | Windows 2000 or later: Layout progress: horizontal from right to left
124 |  | Windows 2000 or later: Layout progress: vertical before horizontal
125 |  | Windows 2000 or later: Layout progress: vertical bottom to top
126 |  | Reserved; must be 0
127 |  | Reserved; must be 1


Uniscribe

Uniscribe is a set of APIs that allow a fine degree of control for processing complex scripts. A complex script requires special processing to display and edit because the characters, or glyphs, are not laid out in a simple way. The rules governing the shaping and positioning of glyphs are specified and catalogued in The Unicode Standard: Worldwide Character Encoding, Version 2.0, Addison-Wesley Publishing Company.

This topic discusses various aspects of processing complex scripts, and is presented as follows:

  • About Uniscribe
  • Using Uniscribe
  • Uniscribe Reference


About Uniscribe

Uniscribe is one of several ways to process complex scripts. To put it in context, we start with a brief description of complex scripts and their special problems, and then discuss the other standard ways to deal with complex scripts:

  • About Complex Scripts
  • Processing Complex Scripts
  • OpenType Font Format


About Complex Scripts

A complex script has at least one of the following attributes:

  • Allows bidirectional rendering.
  • Has contextual shaping.
  • Has combining characters.
  • Has specialized word-breaking and justification rules.
  • Filters out illegal character combinations.

Bidirectional rendering refers to the script's ability to handle text that reads both left-to-right and right-to-left. For example, in the bidirectional rendering of Arabic, the default reading direction for text is right-to-left, but for some numbers, it is left-to-right. Processing a complex script must account for the difference between the logical (keystroke) order and the visual order of the glyphs. In addition, processing must properly deal with caret movement and hit testing. The mapping between screen position and a character index for, say, selection of text or caret display requires knowledge of the layout algorithms.

Contextual shaping occurs when a script's characters change shape depending on the characters that surround them. This occurs in English cursive writing when a lowercase "l" changes shape depending on the character that precedes it such as an "a" (connects low to the "l") or an "o" (connects high). Arabic is a script that exhibits contextual shaping.

Combining characters or ligatures are characters that join into one character when placed together. One example is the "ae" combination in English; it is sometimes represented by a single character. Arabic is a script that has many combining characters.

Specialized word break and justification refers to scripts that have complex rules for dividing words between lines or justifying text on a line. Thai is such a script.

Filtering out illegal character combinations occurs when a language does not allow certain character combinations. Thai is such a script.


Processing Complex Scripts

The following are options for processing complex scripts:

  • Text functions
  • Edit controls
  • Rich edit controls
  • Uniscribe

The options you choose will depend on the following factors:

  • The type of text or scripts.
  • The choice of implementation model that is used, for example, the text layout and whether the application handles line breaking.
  • Whether the application exists or is created from scratch.

In general, an application that does relatively simple script processing can choose any option. However, for the most complete control of complex script processing, Uniscribe is recommended.

Text Functions

Applications that work mostly in plain text--that is, text that uses the same typeface, weight, color, and so on--have traditionally written text and measured line lengths using standard Microsoft® Win32® text functions, such as TextOut, ExtTextOut, TabbedTextOut, DrawText, and GetTextExtentExPoint. Starting with Microsoft® Windows® 2000, these functions have been extended to support complex scripts. In general, this support is transparent to the application. However, applications should save characters in a buffer and display the whole line of text at one time rather than, for example, calling ExtTextOut on each character as it is typed in by the user. This allows the complex script shaping modules to use context to reorder and generate glyphs correctly. Also, applications should use GetTextExtentExPoint to determine line length rather than computing line lengths from cached character widths. This is because the width of a glyph may vary by context. In addition, complex script-aware applications should consider adding support for right-to-left reading order and right alignment to their applications.

For more information, see Fonts and Text.

Edit Controls

The standard edit controls have been extended to support multilingual text and complex scripts. This includes not only input and display, but also correct cursor movement over character clusters (in Thai and Devanagari script, for example).

For more information, see Edit Controls.

Rich Edit Controls

Rich Edit 3.0 is a higher-level collection of interfaces that takes advantage of Uniscribe to further insulate text layout clients from the complexities of certain scripts. Rich Edit is designed for clients whose primary purpose is not necessarily text layout, but who nonetheless need to display complex scripts.

Rich Edit provides fast, versatile editing of rich Unicode multilingual text and simple plain text. It includes extensive message and COM interfaces, text editing, formatting, line breaking, simple table layout, vertical text layout, bidirectional text layout, Indic and Thai support, an editing UI much like Microsoft Word, and Text Object Model interfaces. Rich Edit is the simplest way for a client to support features of complex scripts. Clients use its TextOut function to automatically parse, shape, position, and break lines.

For more information, see Rich Edit Controls.

Uniscribe

Uniscribe enables extremely fine processing of complex scripts. It supports the complex rules found in scripts such as Arabic, Indian, and Thai. It also handles scripts written from right to left, such as Arabic and Hebrew, and supports the mixing of scripts. The rest of this section deals with Uniscribe.


OpenType Font Format

The Unicode-based Microsoft® OpenType® font format extends the TrueType font file format. OpenType fonts allow mapping between characters and glyphs, enabling support for ligatures, positional forms, alternates, and other substitutions. OpenType fonts may also include information that supports two-dimensional glyph positioning and glyph attachment, and may contain either TrueType or PostScript outlines.

Layout features within OpenType fonts are organized by scripts and languages, allowing a single font to support multiple writing systems, even within the same script. To ensure consistency in text layout operations and to avoid unnecessary overhead in font files or applications, many of the text layout and language semantic algorithms are included in Uniscribe. This relieves the font developer from having to define generalized script rules within a font.

Applications may introduce their own knowledge or preferences regarding script layout. OpenType layout fonts may even contain layout rules that duplicate or supersede those applied by OS services. The layered structure of OS services supporting text layout allows a client to choose which layout information to use, and how to apply it.


Processing Complex Scripts with Uniscribe

Uniscribe provides APIs to support the display and editing of international text, including the complex rules of Middle Eastern and Asian scripts. Uniscribe provides low level routines for handling fully formatted text, and an easier ScriptString API set for unformatted text.

Using Uniscribe, applications need only manage a backing store of Unicode character codes. Text layout applications do not need to maintain any other buffer or mapping table to track character order. An application only needs to store and manage the order in which the characters were entered by the user, which is the same logical order as defined by Unicode. The application's backing store never changes as a result of layout operations. Uniscribe maintains an index from the reordered clusters to the original character boundaries passed by the application. The following topics are covered in this section.

  • Shaping Engines
  • Caching
  • Displaying Text with Uniscribe
  • The ScriptString Functions
  • Related Processing for Complex Scripts
  • Caret Placement and Hit Testing
  • Word Break Points
  • Character Clusters
  • Relationship Between Caret Positions, Justification Points, and Clusters
  • Notes on ScriptXtoCP and ScriptCPtoX


Shaping Engines

Uniscribe uses multiple shaping engines that contain the layout knowledge for particular scripts. It also takes advantage of the Microsoft® OpenType® layout shaping engine for handling font-specific script features such as glyph generation, extent measurement, and word-breaking support. Uniscribe manages bidirectional character reordering using the Unicode bidirectional algorithm, and understands non-OpenType layout font formats for Arabic, Hebrew, and Thai shaping.

The exact codepoint ranges assigned to each shaping engine may vary, so with the exception of SCRIPT_ UNDEFINED, script numbers are not published. However, you can test the attributes of scripts by calling the ScriptGetProperties function, which accesses the global script properties table. Applications may use the global script properties to help combine their own layout rules with the required shaping engine divisions.

All the complex script shaping engines, the digit shaping engines, and the ASCII shaping engines validate the font in the hdc before shaping, and will return USP_E_SCRIPT_NOT_IN_FONT if the font does not contain sufficient glyphs or shaping tables. Only scripts that have the property fComplex should be shaped with the script returned by the ScriptItemize function. All other runs may be merged and shaped with SCRIPT_UNDEFINED specified in the SCRIPT_ANALYSIS structure. Note that if there are characters not supported by the font, SCRIPT_UNDEFINED does not fail with USP_E_SCRIPT_ NOT_IN_FONT. Instead, missing glyphs will usually be displayed as an empty rectangle. An application can determine if a codepoint is supported by a font by calling the ScriptGetFontProperties function to obtain the default glyph index, and the ScriptGetCMap function to look up font glyphs for Unicode code points. However, some codepoints can be rendered by a combination of glyphs -- for example, 00C9; LATIN CAPITAL LETTER E WITH ACUTE. In this example, if a font supports the capital E glyph and the acute glyph but not a single glyph for 00C9, ScriptGetCMap would indicate that 00C9 is unsupported. To reliably determine the font support for a string that contains these kinds of codepoints, call ScriptShape. If it returns S_OK, check the output for missing glyphs.


Caching

Uniscribe saves Unicode to glyph mappings (CMAP), glyph widths, and OpenType script shaping tables. A handle to the tables for a particular font of a particular size is called a script cache. Many Uniscribe functions call for both an HDC and a SCRIPT_CACHE parameter. These functions look first for information through the script cache, using the device context only when required tables are not already cached. When calling the ScriptShape, ScriptPlace, or ScriptTextOut function, you must provide a pointer to a SCRIPT_CACHE structure, which you must initially set to NULL.

An application may free a script cache at any time. Uniscribe maintains reference counts in its font and shaper caches, and frees font data only when all sizes of the font are free, and Uniscribe frees shaper data only when all fonts the shaper supports are freed. When you are done with a style -- that is, a certain set of attributes that typically includes font, size, and color -- call the ScriptFreeCache function to free the script cache for the file.

For ScriptShape and ScriptPlace, it is valid to pass a NULL device context. Most often the call will be successful as required tables will already be cached. If the shaping or placement requires access to a device context, ScriptShape or ScriptPlace will return immediately with the E_PENDING error code. Then the application must select the font into the device context. This eliminates most calls to the SelectObject function.


Displaying Text with Uniscribe

An application that uses complex scripts has problems with a simple approach to formatting and display. First, the width of a complex script character depends on its context. It is not possible to save the widths in simple tables. Second, breaking between words in scripts like Thai requires dictionary support since there is no separator character between Thai words. Third, Arabic, Hebrew, Farsi, Urdu and other bidirectional text requires reordering before display. And finally, some form of font association is often required to easily use complex scripts.

To deal adequately with these issues, Uniscribe uses the paragraph as the unit for display. Note, this means that Uniscribe must be used for the entire paragraph, even if sections of the paragraph are not complex scripts.

Before using Uniscribe, an application divides the paragraph into runs, that is, a string of characters with the same style. The style depends on what the application has implemented, but typically includes such attributes as font, size, and color. Uniscribe divides the paragraph into items -- strings that have the same script and direction. The application applies the item information to produce runs that are unique in script and direction.

Uniscribe identifies the clusters in each run and determines the size of each cluster. A cluster is a script-defined, indivisible character grouping. For European languages, a cluster is a single character, but, in languages such as Thai, it is a grouping of glyphs. Uniscribe sums the clusters to determine the size of a run. Then the application sums the lengths of the runs until they overflow a line (or reach the margin), and divides the run that overflows the line between the current line and the next line. For each line, a map is built from visual position to a run. For each run, the code points are shaped into glyphs, which are then positioned and rendered.

With this overview in mind, we can look at the process in detail and how Uniscribe fits in. An application does text layout, or formatting, one time. Then it either saves the glyphs and positions for display purposes or it generates them each time it displays the text. The trade-off is speed vs. memory. Typically, an application will generate the glyphs and positions each time for display, so the process is presented as a layout procedure and a display procedure.

To Lay out Text Using Uniscribe

This procedure assumes that the application has already divided the paragraph into runs.

  1. Call ScriptRecordDigitSubstitution only when the application starts, or when receiving a WM_SETTINGCHANGE message.
  2. (optional) Call ScriptIsComplex to determine if the paragraph requires complex processing.
  3. For automatic digit substitution, call ScriptApplyDigitSubstitution to prepare the SCRIPT_CONTROL and SCRIPT_STATE structures in ScriptItemize. If the application does its own reordering and layout, it must substitute the proper digits for Unicode U+0030 through U+0039 (the Western digits).
  4. Call ScriptItemize to divide the paragraph into items. If an application already knows the bidirectional order -- for example, because of the keyboard layout used to enter the character -- it can call ScriptItemize with NULL for the SCRIPT_CONTROL and SCRIPT_STATE parameters. This generates items only by shaping engine. The application can then reorder the items using its information.
  5. Merge the item information with the run information to produce runs with a single style, script, and direction.
  6. Call ScriptGetCMap to assign a font to a run and get glyphs. If some glyphs are not supported by the font, either substitute another font or set the eScript member to SCRIPT_UNDEFINED. Note that if a font renders a code point by a combination of glyphs instead of a single glyph, this method may indicate that the code point is unsupported. In this case, call ScriptShape, check for an S_OK return code, and then check the output for missing glyphs.
  7. Call ScriptShape to identify clusters and generate glyphs.
  8. Call ScriptPlace to generate advance widths and x and y positions for the run width.
  9. Sum the run widths until the line overflows.
  10. Break the run on a word boundary by using the fSoftBreak and fWhiteSpace members in the logical attributes. To break a single character cluster off the run, use the information returned by calling ScriptBreak.

This completes layout of the line. Repeat steps 6 through 10 for each line in the paragraph. However, if the application needed to break the last run on the line, call ScriptShape to reshape the remaining part of the run as the first run on the next line.

To Display Text Using Uniscribe

This procedure is done for each line. It assumes that the text has already been laid out using Uniscribe, and that the glyphs and positions from the layout process were not saved. If speed is a concern, an application can save the glyphs and positions from the layout procedure and start at #2.

  1. For each run, in logical order.
    1. If the style has changed since the last run, update the hdc.
    2. Call ScriptShape to generate glyphs for the run.
    3. Call ScriptPlace to generate an advance width and an x,y offset for each glyph.
  2. Establish the correct visual order for the runs in this line:
    1. Extract an array of bidi embedding levels, one per run, from the merged item and run information. The embedding level is given by (SCRIPT_ITEM) si.(SCRIPT_ANALYSIS) a. (SCRIPT_STATE) s.uBidiLevel.
    2. Pass this array to ScriptLayout to generate a map of visual to logical positions.
  3. (optional) To justify the text, either call ScriptJustify or use specialized knowledge of the text. For more information, see Related Processing by Uniscribe.
  4. Use the visual to logical map to display the runs in visual order. Starting at the left end of the line, call ScriptTextOut to display the run given by the first entry in the visual to logical map. For each subsequent entry in the visual to logical map, call ScriptTextOut to display the indicated run to the right of the previously displayed run.

Note that step 2 may be omitted if the text contains no characters from right-to-left scripts, contains no bidi control characters, and the base embedding level is left-to-right. In this case, step 4 becomes: start at the left end of the line and call ScriptTextOut to display the first logical run and then to display each logical run to the right of the previous run.


The ScriptString Functions

For an application dealing with unformatted text, Uniscribe provides the ScriptString functions. These functions are similar to ExtTextOut, DrawText, and GetTextExtent, but they provide full complex script support including caret placement. The ScriptString functions are similar to the other Uniscribe functions, but are tailored to the simpler requirements of plain text processing.

The following table details the ScriptString functions and any counterparts in the other Uniscribe functions.

Function | Description
ScriptStringAnalyse | Analyses plain text. It corresponds to the following functions: ScriptItemize ScriptShape ScriptPlace ScriptBreak ScriptGetCMap ScriptJustify ScriptLayout
ScriptStringCPtoX | Returns the x coordinate for a character position. It corresponds to ScriptCPtoX.
ScriptStringFree | Frees a SCRIPT_STRING_ANALYSIS structure.
ScriptStringGetLogicalWidths | Converts visual widths to logical widths. It corresponds to ScriptGetLogicalWidths.
ScriptStringGetOrder | Maps character glyph positions in a similar way to GetCharacterPlacement, for legacy use only. Does not work well with scripts that generate more than one glyph per codepoint.
ScriptStringOut | Displays plain text. It corresponds to ScriptTextOut.
ScriptString_pcOutChars | Returns a pointer to the length of a clipped plain text string.
ScriptString_pLogAttr | Returns a pointer to the logical attributes buffer for an analyzed plain text string.
ScriptString_pSize | Returns a pointer to the size (width and height) for an analyzed plain text string.
ScriptStringValidate | Identifies codepoint sequences not valid in the given script. This is different from ScriptGetCMap, which identifies code points not present in a font.
ScriptStringXtoCP | Converts an x coordinate to a character position. It corresponds to ScriptXtoCP.

To simply display plain text without any modifications, call ScriptStringAnalyse, ScriptStringOut, and then ScriptStringFree. The other functions are used to modify the plain text before display.


Related Processing for Complex Scripts

To provide text justification, an application can use one of two methods. For a simple implementation of multilingual justification, call ScriptJustify . It generates the delta dx array by considering kashida, then interword spacing, and then intercharacter spacing. For more sophisticated justification, an application would generate an updated delta dx array using its own language knowledge and the information returned by ScriptShape in the SCRIPT_VISATTR array.

Justification space or kashida should be inserted where identified by the uJustificaion member of the SCRIPT_VISATTR. When performing inter-character justification, insert extra space only after glyphs marked with SCRIPT_JUSTIFY_CHARACTER.

The application does caret placement and hit testing by using ScriptXtoCP and ScriptCPtoX. For more information, see Caret Placement and Hit Testing.

To get widths in a font independent manner, call ScriptGetLogicalWidths. By passing the logical widths to ScriptApplyLogicalWidth, a block of text can be redisplayed in the same boundaries with acceptable loss of quality even when the original font is not available. It generates an array of glyph widths suitable for passing to ScriptTextOut. Such recording and reapplying of advance width information in a font independent manner can be useful in situations such as metafiling in an application defined format. Note that metafiles do not support glyph indices. To write to a Microsoft® Windows® enhanced metafile, use ExtTextOut to write the logical characters directly, so that glyph generation and placement does not occur until the text is played back.

To retrieve the specific glyphs that are used for the default, blanks, kashida, and so forth, for the current font, call ScriptGetFontProperties. To determine which characters in a run are supported by the selected font, call ScriptGetCMap. Characters that are not available have the default glyph in the glyph buffer. Note that this method fails if a font renders a character using a combination of glyphs instead of a single glyph -- for example, 00C9; LATIN CAPITAL LETTER E WITH ACUTE could be rendered using a capital E glyph and an acute glyph. To determine the font support for a string that contains these kinds of code points, call ScriptShape. If it returns S_OK, check the output for missing glyphs.

The ScriptCacheGetHeight function returns the height of the font from the font cache. ScriptGetProperties provides information on the special processing required for all the scripts, indexed by script. For example, it includes the primary language associated with the script, whether the script is numeric, and whether the script is a complex script.

ScriptGetGlyphABCWidth returns the ABC width of a given glyph, which may be useful for drawing glyph charts. However, it should not be used for normal complex script text formatting.


Caret Placement and Hit Testing

Complex script languages are broken into clusters by ScriptShape. Character reordering always occurs within cluster boundaries. The clusters themselves are guaranteed to advance monotonically in the reading order.

Conventions for caret placement within clusters depend on the script. For the Arabic script, if the caret position is set between a base character and its combining mark, then the caret is displayed halfway through the base character. For the Thai script, the caret may not be positioned within a cluster. Thus, when the user advances the caret, the application must advance past all the glyphs that make up the cluster.

The ScriptXtoCP and ScriptCPtoX functions translate between caret positions (in codepoint offsets) and x positions (in pixels). Both functions require that the following parameters come from earlier Uniscribe calls, as shown in the following table:

Parameter | Source
const SCRIPT_ANALYSIS *psa | As returned by ScriptItemize.
int cGlyphs const WORD *pwLogClust const SCRIPT_VISATTR *psva | As returned by ScriptShape.
const int *piAdvance | As returned by ScriptPlace.

If you do not save the width information, you may want to do hit testing and caret placement after you display each run. As an alternative, you could cache enough information to do hit testing and caret placement on the current line without requiring reprocessing of the paragraph.

ScriptXtoCP returns a trailing edge valueso the caller knows which side of the character or cluster the user has clicked on. The value is either zero or the width of the character or cluster in code points. The returned character position is the position of the character on which the user clicked. Most editors set the caret closest to the cluster whose leading edge the user clicked. To achieve this, add the trailing edge value to the returned character position.

For languages such as Thai where the user conventionally does not want to place the caret into a cluster, ScriptXtoCP sets the trailing side flag to zero or the cluster width. For languages such as Arabic, where the user expects to be able to edit within a cluster, ScriptXtoCP sets the trailing side flag to zero or one.

To help the client establish valid locations for the caret when handling the arrow keys, Uniscribe provides information on valid caret positions in the fCharStop member in the logical attributes returned by ScriptBreak: TRUE is returned for most characters and FALSE for intercluster characters in scripts such as Thai. Check the fNeedsCaretInfo flag in the SCRIPT_PROPERTIES for an item to see if it is necessary to call ScriptBreak to check for valid caret positions. If the fNeedsCaretInfo member is FALSE, all code points are valid caret positions.


Word Break Points

Valid positions for the caret, when dealing with whole words, are marked by the fWordStop flag returned by ScriptBreak.

Valid positions for breaking lines between words are marked by the fSoftBreak flag returned by ScriptBreak.


Character Clusters

Character clusters are glyph sequences that cannot be split between lines. Some languages, for example Thai and Indic, restrict caret placement to points between clusters. This applies to caret movement initiated with keyboard or mouse actions(hit testing).

Uniscribe provides cluster information in both the visual and logical attributes. After calling ScriptShape, the cluster information is represented both by sequences of the same value in the pwLogClust array, and by the fClusterStart member in the psva SCRIPT_VISATTR array.

ScriptBreak also returns the fCharStop member in the SCRIPT_LOGATTR array to identify cluster positions.


Relationship Between Caret Positions, Justification Points, and Clusters

The following table shows the various methods to handle the caret, justification, and clusters.

Job | Uniscribe support
Caret move by character cluster | The pwLogClust parameter of the ScriptShape function The fClusterStart member of the SCRIPT_VISATTR structure The fCharStop member of the SCRIPT_LOGATTR structure
Line breaking between characters | The pwLogClust parameter of the ScriptShape function The fClusterStart member of the SCRIPT_VISATTR structure The fCharStop member of the SCRIPT_LOGATTR structure
Caret move by word | The fWordStop member of the SCRIPT_LOGATTR structure
Line breaking between words | The fWordStop member of the SCRIPT_LOGATTR structure
Justification | The uJustification member of the SCRIPT_VISATTR structure


Notes on ScriptXtoCP and ScriptCPtoX

Both ScriptCPtoX and ScriptXtoCP functions work only within runs and require the results of a previous ScriptShape call.

The client must establish which run a given caret offset or x position is within before passing it to ScriptCPtoX or ScriptXtoCP.

Cluster information in the logical cluster array is used to share the width of a cluster of glyphs equally among the logical characters they represent.

For example, the lam alef glyph is divided into four areas:

  • The leading half of the lam.
  • The trailing half of the lam.
  • The leading half of the alef.
  • The trailing half of the alef.

The ScriptXtoCP function has knowledge of the caret position conventions of each script:

  • For Indian and Thai, caret positions are snapped to cluster boundaries.
  • For Arabic and Hebrew, caret positions are interpolated with clusters.


Using Uniscribe

The following sections show code samples for dealing with Uniscribe.

  • Determining if a script requires glyph shaping
  • Translating Mouse Hit 'x' Offset to Caret Position
  • Displaying the Caret in Bidirectional Strings


Determining if a script requires glyph shaping

The following code sample calls ScriptGetProperties to check if the script requires glyph shaping.

const SCRIPT_PROPERTIES **g_ppScriptProperties;
 int g_iMaxScript;

 ScriptGetProperties(&g_ppScriptProperties,
                     &g_iMaxScript);

 hResult = ScriptItemize( … , pItems, &cItems);
 for (i=0; i<cItems; i++) {
     if (g_ppScriptProperties[pItems[i].a.eScript]
         >fComplex) {

         // Item [i] is complex script text
         // requiring glyph shaping
   }
 }


Translating Mouse Hit 'x' Offset to Caret Position

Conventionally, caret position (cp) may be selected by clicking either the trailing half of character "cp-1" or the leading half of character "cp". This may be implemented as follows:

int iCharPos;
int iCaretPos
int fTrailing;
ScriptXtoCP(iMouseX, ..., &iCharPos, &fTrailing);
iCaretPos = iCharPos + fTrailing;

For scripts that snap the caret to cluster boundaries, ScriptXtoCP returns ftrailing set to either 0 or the width of the cluster in code points.


Displaying the Caret in Bidirectional Strings

In unidirectional text, there is no ambiguity in the caret position because the leading edge of a character is at the same place as the trailing edge of the previous character. However, in bidirectional text, the caret position between runs of opposing direction is ambiguous. For example, in the LTR paragraph "helloMAALAS", the last letter of "hello" immediately precedes the first letter of "salaam". The best position in which to display the caret depends on whether it is considered to follow the "o" of "hello" or to precede the "s" of "salaam".

Uniscribe uses the following caret positioning conventions.

Situation | Visual caret placement
Typing | Trailing edge of last character typed.
Pasting | Trailing edge of last character pasted.
Caret advancing | Trailing edge of last character passed over.
Caret retiring | Leading edge of last character passed over.
Home | Leading edge of line.
End | Trailing edge of line.

The caret may be positioned as follows:

if (advancing) {
    ScriptCPtoX(iCharPos-1, TRUE, ..., &iCaretX);
} else {
    ScriptCPtoX(iCharPos, FALSE, ..., &iCaretX);
}

Or, more simply, given an fAdvancing BOOL restricted to TRUE or FALSE:

ScriptCPtoX(iCharPos-fAdvancing, fAdvancing, ..., &iCaretX);

ScriptCPtoX handles out-of-range positions logically: It returns the leading edge of the run for iCharPos <0, and the trailing edge of the run for iCharPos =length.


Uniscribe Reference

The following elements are associated with complex script processing:

  • Uniscribe Functions
  • Uniscribe Structures
  • Uniscribe Enumeration Types


Uniscribe Functions

This section describes complex script processing functions.

Function | Description
ScriptApplyDigitSubstitution | Applies digit substitution settings.
ScriptApplyLogicalWidth | Takes an array of advance widths for a run and generates an array of glyph widths.
ScriptBreak | Returns information for determining line breaks.
ScriptCacheGetHeight | Returns information about the currently cached font.
ScriptCPtoX | Returns the x offset of a run to either the leading or the trailing edge of a logical character cluster.
ScriptFreeCache | Frees a SCRIPT_CACHE structure.
ScriptGetCMap | Returns the glyph indices of the characters of a string according to the cmap table.
ScriptGetFontProperties | Returns information from the font cache.
ScriptGetGlyphABCWidth | Returns the ABC width of a glyph.
ScriptGetLogicalWidths | Converts the glyph advance widths into logical widths.
ScriptGetProperties | Returns information about the current scripts.
ScriptIsComplex | Determines whether a string requires complex script processing.
ScriptItemize | Breaks a string into individually shapeable items.
ScriptJustify | Creates an advance widths table to allow text justification.
ScriptLayout | Converts an array of run-embedding levels into a map of visual-to-logical position, and/or logical-to-visual position.
ScriptPlace | Takes the glyphs and visual attributes of a run and generates glyph-advance width and two-dimensional offset information.
ScriptRecordDigitSubstitution | Reads the National Language Support (NLS) native-digit and digit-substitution settings and then records them in the SCRIPT_DIGITSUBSTITUTE structure.
ScriptShape | Takes a run and generates its glyphs and visual attributes.
ScriptStringAnalyse | Analyzes a plain text string.
ScriptStringCPtoX | Returns the x-coordinate for the leading or trailing edge of a character position.
ScriptStringFree | Frees a SCRIPT_STRING_ANALYSIS structure.
ScriptStringGetLogicalWidths | Converts visual widths into logical widths.
ScriptStringGetOrder | Creates an array that maps an original character position to a glyph position.
ScriptStringOut | Displays a string generated by a prior call to ScriptStringAnalyse and optionally adds highlighting.
ScriptString_pcOutChars | Returns a pointer to the length of a string after clipping.
ScriptString_pLogAttr | Returns a pointer to a logical attributes buffer for an analyzed string.
ScriptString_pSize | Returns a pointer to a SIZE structure for an analyzed string.
ScriptStringValidate | Checks the SCRIPT_STRING_ANALYSIS structure for invalid sequences.
ScriptStringXtoCP | Converts an x-coordinate to a character position.
ScriptTextOut | Takes the output of both the ScriptShape and ScriptPlace calls and then calls the operating system ExtTextOut function appropriately.
ScriptXtoCP | Converts the x offset of a run to a logical character position and a flag to indicate whether the x position fell in the leading or trailing half of the character.


ScriptApplyDigitSubstitution

The ScriptApplyDigitSubstitution function applies the digit substitution settings recorded in a SCRIPT_DIGITSUBSTITUTE structure to the SCRIPT_CONTROL and SCRIPT_STATE structures.

HRESULT WINAPI ScriptApplyDigitSubstitution(
  const SCRIPT_DIGITSUBSTITUTE* psds,
  SCRIPT_CONTROL* psc,
  SCRIPT_STATE* pss
);

Parameters

psds
[in] Pointer to a SCRIPT_DIGITSUBSTITUTE structure. If NULL, ScriptApplyDigitSubstitution calls ScriptRecordDigitSubstitution with LOCALE_USER_DEFAULT.
psc
[out] Pointer to a SCRIPT_CONTROL structure. When this function returns, the fContextDigits and uDefaultLanguage members are updated.
pss
[out] Pointer to a SCRIPT_STATE structure. When this function returns, the fDigitSubstitute member will be updated.

Return Values

If the function succeeds, it returns S_OK.

If the DigitSubstitute member of SCRIPT_DIGITSUBSTITUTE structure is unrecognized, the function returns E_INVALIDARG. And if any other unrecoverable error is encountered, it is also returned as an HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The DigitSubstitute member of SCRIPT_DIGITSUBSTITUTE structure is normally set by ScriptRecordDigitSubstitution. However, it may be replaced by any one of the following values:

  • SCRIPT_DIGITSUBSTITUTE_CONTEXT - Digits U+0030 to U+0039 are substituted using the language of the prior letters. If there are no prior letters, digits are substituted using the TraditionalDigitLanguage member of the SCRIPT_DIGITSUBSTITUTE structure. This member is normally set to the primary language of the locale passed to ScriptRecordDigitSubstitution.
  • SCRIPT_DIGITSUBSTITUTE_NATIONAL - Digits U+0030 to U+0039 are substituted using the NationalDigitLanguage member of the SCRIPT_DIGITSUBSTITUTE structure. This member is normally set to the national digits returned for the NLS LCTYPE LOCALE_SNATIVEDIGITS by ScriptRecordDigitSubstitution.
  • SCRIPT_DIGITSUBSTITUTE_NONE - Digits are not substituted. Unicode values U+0030 to U+0039 are displayed with Arabic, that is Western, numerals.
  • SCRIPT_DIGITSUBSTITUTE_TRADITIONAL - Digits U+0030 to U+0039 are substituted using the TraditionalDigitLanguage member of the SCRIPT_DIGITSUBSTITUTE structure. This member is normally set to the primary language of the locale passed to ScriptRecordDigitSubstitution.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptRecordDigitSubstitution, SCRIPT_CONTROL, SCRIPT_DIGITSUBSTITUTE, SCRIPT_STATE


ScriptApplyLogicalWidth

The ScriptApplyLogicalWidth function takes an array of advance widths for a run and generates an array of glyph widths that are suitable for passing to the piJustify parameter of ScriptTextOut.

HESULT WINAPI ScriptApplyLogicalWidth(
  const int *piDx,
  int cChars,
  int cGlyphs,
  const WORD *pwLogClust,
  const SCRIPT_VISATTR *psva,
  const int *piAdvance,
  const SCRIPT_ANALYSIS *psa,
  ABC *pABC,
  int *piJustify,
);

Parameters

piDx
[in] Pointer to an array of dx widths in logical order, one per code point.
cChars
[in] Count of the logical code points in the run.
cGlyphs
[in] Glyph count.
pwLogClust
[in] Pointer to an array of logical clusters from ScriptShape.
psva
[in] Pointer to a SCRIPT_VISATTR structure from ScriptShape and updated by ScriptPlace.
piAdvance
[in] Pointer to an array of glyph advance widths from ScriptPlace.
psa
[in] Pointer to a SCRIPT_ANALYSIS structure from ScriptItemize and updated by ScriptShape and ScriptPlace.
pABC
[in/out] Pointer to the overall ABC width of a run. It is optional. If present, when the function is called, it should contain the run ABC widths returned by ScriptPlace; when the function returns, the ABC width has been updated to match the new widths.
piJustify
[out] Pointer to an array that receives the resulting glyph advance widths. This is suitable for passing to the piJustify parameter of ScriptTextOut.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

ScriptApplyLogicalWidth may be used to reapply logical widths obtained with ScriptGetLogicalWidths. It may be useful in situations such as metafiling, where it is necessary to record and reapply advance width information in a font-independent manner, independent of glyph substitutions such as ligaturisation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptGetLogicalWidths, ScriptItemize, ScriptPlace, ScriptShape, ScriptTextOut, SCRIPT_ANALYSIS, SCRIPT_VISATTR


ScriptBreak

The ScriptBreak function returns information for determining line breaks.

HRESULT WINAPI ScriptBreak(
  const WCHAR *pwcChars,
  int cChars,
  const SCRIPT_ANALYSIS *psa,
  SCRIPT_LOGATTR *psla
);

Parameters

pwcChars
[in] Unicode characters to be processed.
cChars
[in] Number of Unicode characters to be processed.
psa
[in] Pointer to the SCRIPT_ANALYSIS structure obtained from an earlier call to the ScriptItemize function.
psla
[out] Pointer to a buffer that receives the character attributes as a SCRIPT_LOGATTR structure.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The ScriptBreak function returns cursor movement and formatting break positions for an item in an array of SCRIPT_LOGATTR structures. To support mixed formatting within a single word correctly, ScriptBreak should be passed whole items as returned by ScriptItemize and not the finer formatting runs.

ScriptBreak does not require an hdc and does not perform shaping.

The SCRIPT_LOGATTR structure, pointed to by psla, identifies valid caret positions and line breaks. The SCRIPT_LOGATTR.fCharStop flag marks cluster boundaries for those scripts where it is conventional to restrict from moving inside clusters. The same boundaries could also be inferred by inspecting the pwLogCLust array returned by ScriptShape, however ScriptBreak is considerably faster in implementation and does not require an hdc to be prepared. The fWordStop, fSoftBreak, and fWhiteSpace flags in SCRIPT_LOGATTR are only available through ScriptBreak.

Most shaping engines that identify invalid sequences do so by setting the fInvalid flag in ScriptBreak. The fInvalidLogAttr flag in SCRIPT_PROPERTIES identifies which scripts do this.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptItemize, ScriptShape, SCRIPT_ANALYSIS, SCRIPT_LOGATTR


ScriptCacheGetHeight

The ScriptCacheGetHeight function returns the height of the currently cached font.

HRESULT WINAPI ScriptCacheGetHeight(
  HDC hdc,
  SCRIPT_CACHE *psc,
  long *tmHeight
);

Parameters

hdc
[in] Handle to the device context. This parameter is optional.
psc
[in/out] Pointer to a SCRIPT_CACHE structure.
tmHeight
[out] Pointer to a variable that receives the height of the font.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_CACHE


ScriptCPtoX

The ScriptCPtoX function generates the x offset from the left end (!fLogicalOrder) or leading edge (fLogicalOrder) of a run to either the leading or trailing edge of a logical character cluster.

HRESULT WINAPI ScriptCPtoX(
  int iCP,
  BOOL fTrailing,
  int cChars,
  int cGlyphs,
  const WORD *pwLogClust,
  const SCRIPT_VISATTR *psva,
  const int *piAdvance,
  const SCRIPT_ANALYSIS *psa,
  int *piX
);

Parameters

iCP
[in] Logical character position in the run.
fTrailing
[in] Indicates the edge of the logical character cluster from which to compute the offset. If TRUE, the trailing edge is used; otherwise, the leading edge is used.
cChars
[in] Number of characters in the run.
cGlyphs
[in] Number of glyphs in the run.
pwLogClust
[in] Logical clusters.
psva
[in] Pointer to a SCRIPT_VISATTR array.
piAdvance
[in] Pointer to advance widths value.
psa
[in] Pointer to a SCRIPT_ANALYSIS structure. SCRIPT_ANALYSIS.fLogicalOrder specifies the end of the run: if it is set, the leading edge of the run is used; otherwise, the left end of the run is used.
piX
[out] Pointer to a variable that receives the resulting x position of the caret.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The leading or trailing edge of the character and the leading edge of a run depend on the direction of text in the run.

The iCP parameter is the offset of any logical character in the cluster.

For scripts in which the caret may conventionally be placed in the middle of clusters (for example, Arabic and Hebrew), the returned x may be an interpolated position for any code point in the line.

For scripts in which the caret is conventionally snapped to the boundaries of clusters, (for example, Thai and Indian), the resulting x position will be snapped to the requested edge of the cluster containing iCP.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptXtoCP, SCRIPT_ANALYSIS, SCRIPT_VISATTR


ScriptFreeCache

The ScriptFreeCache function frees a SCRIPT_CACHE item.

HRESULT WINAPI ScriptFreeCache(
  SCRIPT_CACHE *psc
);

Parameters

psc
[in/out] Pointer to a SCRIPT_CACHE item to be freed.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The client may free a SCRIPT_CACHE at any time. Uniscribe maintains reference counts in its font and shaper caches and frees font data only when all sizes of the font are free, and shaper data only when all fonts it supports are freed.

The client should free the SCRIPT_CACHE for a style when it discards that style.

ScriptFreeCache always sets its parameter to NULL to help avoid misreferencing.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_CACHE


ScriptGetCMap

The ScriptGetCMap function takes a string and returns the glyph indices of the Unicode characters according to the TrueType cmap table or the standard cmap table implemented for old style fonts.

HRESULT WINAPI ScriptGetCMap(
  HDC hdc,
  SCRIPT_CACHE *psc,
  const WCHAR *pwcInChars,
  int cChars,
  DWORD dwFlags,
  WORD *pwOutGlyphs
);

Parameters

hdc
[in] Handle to the device context. This parameter is optional.
psc
[in/out] Pointer to a SCRIPT_CACHE structure.
pwcInChars
[in] Pointer to a string of Unicode characters.
cChars
[in] Number of Unicode characters in pwcInChars.
dwFlags
[in] Flag that specifies any special handling of the glyphs. By default, the glyphs of the buffer are given in logical order with no special handling. This parameter can be the following value.
Value | Meaning
SGCM_RTL | Indicates the glyph array pwOutGlyps should contain mirrored glyphs for those glyphs that have a mirrored equivalent.

pwOutGlyphs
[out] Pointer to an array that receives the glyph indexes.

Return Values

If all Unicode code points are present in the font, the return value is S_OK.

If the function fails, it may return one of the following nonzero values.

Return value | Meaning
E_HANDLE | The font or the system does not support glyph indices.
S_FALSE | Some of the Unicode code points were mapped to the default glyph.

If any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

ScriptGetCMap may be used to determine which characters in a run are supported by the selected font. The caller may scan the returned glyph buffer looking for the default glyph to determine which characters are not available. The default glyph index for the selected font should be determined by calling ScriptGetFontProperties.

The return value indicates the presence of any missing glyphs.

Note that some code points can be rendered by a combination of glyphs as well as by a single glyph -- for example, 00C9; LATIN CAPITAL LETTER E WITH ACUTE. In this case, if the font supports the capital E glyph and the acute glyph but not a single glyph for 00C9, ScriptGetCMap will show 00C9 is unsupported. To determine the font support for a string that contains these kinds of code points, call ScriptShape. If it returns S_OK, check the output for missing glyphs.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptGetFontProperties, ScriptShape, SCRIPT_CACHE


ScriptGetFontProperties

The ScriptGetFontProperties returns information from the font cache on the special glyphs used by a font .

HRESULT WINAPI ScriptGetFontProperties(
  HDC hdc,
  SCRIPT_CACHE *psc,
  SCRIPT_FONTPROPERTIES *sfp
);

Parameters

hdc
[in] Handle to a device context. This parameter is optional.
psc
[in/out] Pointer to a SCRIPT_CACHE structure.
sfp
[out] Pointer to a SCRIPT_FONTPROPERTIES structure to receive the information from the font cache.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

ScriptGetFontProperties gets a SCRIPT_FONTPROPERTIES structure that tells what glyphs are used for blanks, missing glyphs, invalid combinations, and the smallest kashida.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_CACHE, SCRIPT_FONTPROPERTIES


ScriptGetGlyphABCWidth

The ScriptGetGlyphABCWidth function returns the ABC width of a given glyph.

HRESULT WINAPI ScriptGetGlyphABCWidth(
  HDC hdc,
  SCRIPT_CACHE *psc,
  WORD wGlyph,
  ABC *pABC,
);

Parameters

hdc
[in] Handle to the device context. It is optional depending on psc.
psc
[in/out] Pointer to a SCRIPT_CACHE structure.
wGlyph
[in] Glyph to be analyzed.
pABC
[out] ABC width of wGlyph.

Return Values

If the ABC width of the glyph is returned, the function returns S_OK.

If the font or system does not support glyph indices, the function returns E_HANDLE. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The ScriptGetGlyphABCWidth function may be useful for drawing glyph charts. It should not be used for ordinary complex script text formatting.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_CACHE


ScriptGetLogicalWidths

The ScriptGetLogicalWidths function converts the glyph advance widths for a specific font into logical widths.

HRESULT WINAPI ScriptGetLogicalWidths(
  const SCRIPT_ANALYSIS *psa,
  int cChars,
  int cGlyphs,
  const int *piGlyphWidth,
  const WORD *pwLogClust,
  const SCRIPT_VISATTR *psva,
  int *piDx,
);

Parameters

psa
[in] Pointer to a SCRIPT_ANALYSIS structure.
cChars
[in] Count of the logical code points in the run.
cGlyphs
[in] Count of the glyphs in a run.
piGlyphWidth
[in] Pointer to an array of glyph advance widths.
pwLogClust
[in] Pointer to an array of logical clusters.
psva
[in] Pointer to a SCRIPT_VISATTR structure.
piDx
[out] Pointer to an array of logical widths.

Return Values

Currently, ScriptGetLogicalWidths always returns S_OK.

Remarks

ScriptGetLogicalWidths is useful for recording widths in a font-independent manner. ScriptGetLogicalWidths converts the glyph advance widths calculated for a specific font into logical widths, one per code point, in the same order as the code points. If the same string is then displayed on a different device using a different font, the logical widths may be applied, by using ScriptApplyLogicalWidth, to approximate the original placement. This would be useful when implementing print preview—on the preview screen it is important to match the layout and placement of the final printed result.

Ligature glyph widths are divided evenly among the characters they represent.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptApplyLogicalWidth, SCRIPT_ANALYSIS, SCRIPT_VISATTR


ScriptGetProperties

The ScriptGetProperties function returns information about the current scripts.

HRESULT WINAPI ScriptGetProperties(
  const SCRIPT_PROPERTIES ***ppSp,
  int *piNumScripts
);

Parameters

ppSp
[out] Receives a pointer to an array of pointers to SCRIPT_PROPERTIES structures indexed by script.
piNumScripts
[out] Receives the number of scripts. The valid range for this value is zero through NumScripts –1.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_PROPERTIES


ScriptIsComplex

The ScriptIsComplex function determines whether a Unicode string requires complex script processing.

HRESULT WINAPI ScriptIsComplex(
  const WCHAR *pwcInChars,
  int cInChars,
  DWORD dwFlags
);

Parameters

pwcInChars
[in] Pointer to the string to be tested.
cInChars
[in] Length of the string, in characters.
dwFlags
[in] This parameter can be one of the following values.
Value | Meaning
SIC_ASCIIDIGIT | Treats digits U+0030 to U+0039 as complex. Set this flag if the string would be displayed with digit substitution enabled. If you are following the user's NLS settings using the ScriptRecordDigitSubstitution API, you can pass SCRIPT_DIGITSUBSTITUTE .DigitSubstitute != SCRIPT_DIGITSUBSTITUTE_NONE.
SIC_COMPLEX | Treats complex script letters as complex. This should normally be set.
SIC_NEUTRAL | Treats neutrals as complex. Set this flag if you might be displaying the string with RTL reading order.

Return Values

The function returns S_OK if the string requires complex script processing. The function returns S_FALSE if the string can be handled by standard API calls, that is, the string contains only characters laid out side-by-side and left-to-right. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptRecordDigitSubstitution, SCRIPT_DIGITSUBSTITUTE


ScriptItemize

The ScriptItemize function breaks a Unicode string into individually shapeable items.

HRESULT WINAPI ScriptItemize(
  const WCHAR *pwcInChars,
  int cInChars,
  int cMaxItems,
  const SCRIPT_CONTROL *psControl,
  const SCRIPT_STATE *psState,
  SCRIPT_ITEM *pItems,
  int *pcItems
);

Parameters

pwcInChars
[in] Pointer to a Unicode string to be itemized.
cInChars
[in] Number of characters in pwcInChars to be itemized.
cMaxItems
[in] Maximum number of SCRIPT_ITEM structures to process.
psControl
[in] Pointer to a SCRIPT_CONTROL structure containing flags indicating the type of itemization to be performed. Use NULL if this is not needed.
psState
[in] Pointer to a SCRIPT_STATE structure indicating the initial bidirectional algorithm state. Use NULL if this is not needed.
pItems
[out] Pointer to a buffer to receive the SCRIPT_ITEM structures processed. The buffer pointed to by pItems should be cMaxItems * sizeof(SCRIPT_ITEM) bytes in length.
pcItems
[out] Pointer to a variable to receive the number of SCRIPT_ITEM structures processed.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. The function returns E_INVALIDARG if pwcInChars is NULL or cInChars is 0 or pItems is NULL or cMaxItems < 2.

The function returns E_OUTOFMEMORY if the output buffer length (cMaxItems) is insufficient. Note that in this case, as in all error cases, no items have been fully processed—so no part of the output array contains defined values.

If any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

Items are delimited by either a change of shaping engine or a change of direction.

The client may create multiple runs from each SCRIPT_ITEM returned by ScriptItemize, but should not combine multiple items into a single run. The reason for this is that later the client will call ScriptShape for each run (when measuring or rendering), and must pass the SCRIPT_ANALYSIS structure that ScriptItemize returned. Each SCRIPT_ITEM contains a SCRIPT_ANALYSIS structure.

If psControl and psState are NULL on entry, ScriptItemize breaks the Unicode string purely by character code. If the parameters are all non-NULL, ScriptItemize performs a full Unicode bidirectional analysis.

The ScriptItemize function always adds a terminal item to the item analysis array (pItems) such that the length of an item at pItem is always available as (in the case of one item):

pItem[1].iCharPos - pItem[0].iCharPos

For this reason, it is invalid to call ScriptItemize with a buffer of less than two SCRIPT_ITEM structures.

To perform a correct Unicode bidirectional analysis, the SCRIPT_STATE structure should be initialized according to the reading order at paragraph start, and ScriptItemize should be passed the whole paragraph.

The bidirectional stack is not large, just 16 bytes. It should be shared between calls.

The fRTL member of SCRIPT_ANALYSIS (referenced in SCRIPT_ITEM) and the fNumeric member of SCRIPT_PROPERTIES (which is returned by ScriptGetProperties) together provide the same classification as the lpClass member of GCP_RESULTS that is referenced by lpResults in GetCharacterPlacement.

If shaping is disabled (fDisableGlyphShape in SCRIPT_STATE), complex scripts are substituted by SCRIPT_UNDEFINED, causing shaping to be performed with contextual substitution following the one-to-one code point to glyph mapping provided by the fonts cmap table. The rendering direction is still set appropriately.

European digits U+0030 through U+0039 may be rendered as national digits as shown in the following table.

fDigitSubstitute | FContextDigits | Digit shapes displayed for Unicode U+0030 through U+0039
False | Any | Western (European / North American) digits
True | False | As specified in SCRIPT_CONTROL.uDefaultLanguage.
True | True | As prior strong text, defaulting to SCRIPT_CONTROL.uDefaultLanguage.

Note that in context digit mode, any digits encountered before the first letters are rendered in SCRIPT_CONTROL.uDefaultLanguage if that script is in the same direction as the output, and in Arabic-Indic, that is, Western, digits if the direction is opposite. For example if SCRIPT_CONTROL.uDefaultLanguage is LANG_ARABIC, initial digits will be in Arabic-Indic in a RTL embedding, but in Western, which is also known as Arabic, in a LTR embedding.

Effect of Unicode control characters on SCRIPT_STATE.

SCRIPT_STATE flag | Set by | Cleared by
fDigitSubstitute | NADS | NODS
fInhibitSymSwap | ISS | ASS
fCharShape | AAFS | IAFS

The Unicode control characters are defined in the following table. For more information, see the Unicode Standard.

Unicode control characters | Meaning
NADS | Overrides Western digits (NODS) with national digit shapes.
NODS | Nominal digit shapes, otherwise known as Western digits. See NADS.
ASS | Activates swapping of symmetric pairs (for example, parentheses). For these characters, left and right are interpreted as opening and closing. This is the default. See ISS.
ISS | Inhibits swapping of symmetric pairs. See ASS.
AAFS | Activates Arabic form shaping, that is, ligatures or cursive connections, for Arabic presentation forms. See IAFS.
IAFS | Inhibits Arabic form shaping, that is ligatures and cursive connections, for Arabic presentation forms. Nominal Arabic characters are not affected. This is the default. See AAFS.

SCRIPT_STATE.fArabicNumContext controls the Unicode EN-AN rule. At the beginning of a paragraph it should normally be initialized to TRUE for an Arabic locale, FALSE for any other. The ScriptItemize function will update it as it processes strong text.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, GetCharacterPlacement, ScriptItemize, ScriptShape, GCP_RESULTS, SCRIPT_ANALYSIS, SCRIPT_CONTROL, SCRIPT_ITEM, SCRIPT_PROPERTIES, SCRIPT_STATE


ScriptJustify

The ScriptJustify function creates an advance widths table to allow text justification when passed to the ScriptTextOut function.

HRESULT WINAPI ScriptJustify(
  const SCRIPT_VISATTR *psva,
  const int *piAdvance,
  int cGlyphs,
  int iDx,
  int iMinKashida,
  int *piJustify
);

Parameters

psva
[in] Pointer to an array of SCRIPT_VISATTR structures containing visual attributes for the entire line to be processed.
piAdvance
[in] Pointer to an advance widths array obtained from a previous call to the ScriptPlace function.
cGlyphs
[in] Count of the number of glyphs contained in all arrays.
iDx
[in] Length of the desired line in pixels.
iMinKashida
[in] Minimum length of a kashida glyph to generate.
piJustify
[out] Pointer to an updated advance widths array to pass to the ScriptTextOut function.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

ScriptJustify provides a simple implementation of multilingual justification. The ScriptJustify function establishes how much adjustment to make at each glyph position on the line. It interprets the SCRIPT_VISATTR array generated by a call to ScriptShape, and gives top priority to kashida. It uses interword spacing if there are no kashida points, and then uses intercharacter spacing if there are no interword points.

Sophisticated text formatters may prefer to generate their own delta dx array by combining their own features with the information returned by ScriptShape in the SCRIPT_VISATTR array.

The justified advance widths generated in ScriptJustify should be passed to ScriptTextOut in the piJustify paramter.

ScriptJustify creates a justify array containing updated advance widths for each glyph. Where a glyph's advance width is increased, it is expected that the extra width will be rendered to the right of the glyph, with a white space or, for Arabic text, a kashida.

Note Kashida insertion occurs to the right of the glyph, visually. Word and PPT use this concept. As a result, ScriptJustify now generates piJustify, which indicates kashida insertion to the right (visually) of the glyph to be justified. Any change in the algorithm of where to insert kashida should accompany a change in the corresponding ScriptTextOut handler for the particular script (for example, Arabic TextOut justification handler if kashida placement algorithm has changed).

If there are a series of glyphs that can't be justified (that is, SCRIPT_VISATTR.uJustification is SCRIPT_JUSTIFY_NONE for the glyphs), ScriptJustify copies the input piAdvance array to the output piJustify array and returns S_FALSE to the caller.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptPlace, ScriptShape, ScriptTextOut, SCRIPT_VISATTR


ScriptLayout

The ScriptLayout function converts an array of run-embedding levels to a map of visual-to-logical position and/or logical-to-visual position.

HRESULT WINAPI ScriptLayout(
  int cRuns,
  const BYTE *pbLevel,
  int *piVisualToLogical,
  int *piLogicalToVisual
);

Parameters

cRuns
[in] Number of runs to process.
pbLevel
[in] Pointer to an array of run-embedding levels.
piVisualToLogical
[out] Pointer to an array that receives the run levels reordered to visual order.
piLogicalToVisual
[out] Pointer to an array that receives the visual run positions.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. If any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The run-embedding levels, defined in the Unicode bidirectional algorithm, describe the direction of a run, the direction of any runs it is embedded in, and the direction of the paragraph.

Level | Meaning
0 | A left-to-right run in a left-to-right paragraph.
1 | A right-to-left run embedded in a left-to-right run in a left-to-right paragraph, or a right-to-left run (not embedded in another run) in a right-to-left paragraph.
2 | A left-to-right run embedded in a right-to-left run of type 1.
3 | A right-to-left run embedded in a left-to-right run of type 2.
etc. | The embedding levels can continue as far as necessary.

The logical position refers to the placement of a run relative to other runs. It is the position in backing store, and corresponds to the order in which you would read the text aloud. The visual position of a run is the way the run is visually displayed on the line, taking into account the possible directions of each run.

The pbLevel parameter must contain the embedding levels for all runs on the line, ordered logically.

On output, piVisualToLogical[0] is the logical index of the run to display at the far left. Subsequent entries should be displayed progressing from left-to-right.

The piLogicalToVisual[0] parameter is the relative visual position where the first logical run should be displayed, the leftmost display position being zero.

The caller may request either piLogicalToVisual or piVisualToLogicalI, or both.

Note that no other input is required because the embedding levels give all necessary information for layout.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions


ScriptPlace

The ScriptPlace function takes the output of a ScriptShape call and generates glyph advance width and two-dimensional offset information.

HRESULT WINAPI ScriptPlace(
  HDC hdc,
  SCRIPT_CACHE *psc,
  const WORD *pwGlyphs,
  int cGlyphs,
  const SCRIPT_VISATTR *psva,
  SCRIPT_ANALYSIS *psa,
  int *piAdvance,
  GOFFSET *pGoffset,
  ABC *pABC
);

Parameters

hdc
[in] Handle to the device context.
psc
[in/out] Pointer to a SCRIPT_CACHE structure.
pwGlyphs
[in] Pointer to a glyph buffer obtained from an earlier call to the ScriptShape function.
cGlyphs
[in] Count of glyphs in the glyph buffer.
psva
[in] Pointer to an array of SCRIPT_VISATTR structures.
psa
[in/out] Pointer to an array of SCRIPT_ANALYSIS structures obtained from a previous call to ScriptItemize.
piAdvance
[out] Pointer to an array that receives the advance width information.
pGoffset
[out] Pointer to a GOFFSET structure that receives the x and y offset of the combining glyph.
pABC
[out] Pointer to an ABC structure that receives the ABC widths for the entire run.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The composite ABC width for the whole item identifies how much the glyphs overhang to the left of the start position and to the right of the length implied by the sum of the advance widths. The total advance width of the line is exactly abcA+abcB+abcC. The abcA and abcC values are maintained as proportions of the cell height represented in 8 bits and are thus roughly +/-1%. The total width returned, which is the sum of the abcA+abcB+abcC values pointed to by piAdvance, is accurate to the resolution of the TrueType shaping engine.

All arrays are in visual order unless the fLogicalOrder member is set in the psa parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptItemize, ScriptShape, ABC, GOFFSET, SCRIPT_ANALYSIS, SCRIPT_CACHE, SCRIPT_VISATTR


ScriptRecordDigitSubstitution

The ScriptRecordDigitSubstitution function reads the National Language Support (NLS) native digit and digit substitution settings and records them in the SCRIPT_DIGITSUBSTITUTE structure.

HRESULT WINAPI ScriptRecordDigitSubstitution(
  LCID Locale,
  SCRIPT_DIGITSUBSTITUTE *psds
);

Parameters

Locale
[in] NLS locale to be queried. Typically, it should be set to LOCALE_USER_DEFAULT. Alternatively, it can be a locale combined with LOCALE_NOUSEROVERRIDE to obtain the default settings.

Note that context digit substitution is supported only in Arabic and Farsi locales. In other locales, context digit substitution is mapped to no substitution.

psds
[out] Pointer to a SCRIPT_DIGITSUBSTITUTE structure. This structure may be passed later to ScriptApplyDigitSubstitution.

Return Values

If successful, the function returns S_OK.

If psds is NULL, the function returns E_POINTER.

If Locale is invalid or not installed, the function returns E_INVALIDARG.

If any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The typical way to call this function is:

SCRIPT_DIGITSUBSTITUTE sds;
ScriptRecordDigitSubstitution(LOCALE_USER_DEFAULT, &sds);

At every itemization, you can use the results like this:

SCRIPT_CONTROL sc = {0};
SCRIPT_STATE   ss = {0};
ScriptApplyDigitSubstitution(&sds, &sc, &ss);

For performance reasons you should not call ScriptRecordDigitSubstitution frequently. In particular, it requires considerable overhead to call it every time you call ScriptItemize or ScriptStringAnalyse. Instead, you can save the SCRIPT_DIGITSUBSTITUTE structure and update it only when:

  • You receive a WM_SETTINGCHANGE message

    – Or –

  • A RegNotifyChangeKeyValue call in a dedicated thread indicates a change in the registry under HKCU\Control Panel\International.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptStringAnalyse, ScriptApplyDigitSubstitution, ScriptItemize, SCRIPT_DIGITSUBSTITUTE


ScriptShape

The ScriptShape function takes a Unicode run and generates glyphs and visual attributes.

HRESULT WINAPI ScriptShape(
  HDC hdc,
  SCRIPT_CACHE *psc,
  const WCHAR *pwcChars,
  int cChars,
  int cMaxGlyphs,
  SCRIPT_ANALYSIS *psa,
  WORD *pwOutGlyphs,
  WORD *pwLogClust,
  SCRIPT_VISATTR *psva,
  int *pcGlyphs
);

Parameters

hdc
[in] Handle to a device context.
psc
[in/out] Pointer to a SCRIPT_CACHE structure.
pwcChars
[in] Pointer to an array of Unicode characters containing the run.
cChars
[in] Number of characters in the Unicode run.
cMaxGlyphs
[in] Maximum number of glyphs to generate.
psa
[in/out] Pointer to theSCRIPT_ANALYSIS structure for the run, containing the results from an earlier call to ScriptItemize.
pwOutGlyphs
[out] Pointer to an array that receives the glyphs.
pwLogClust
[out] Pointer to an array that receives the logical cluster information. Each element in *pwLogClust corresponds to a character in *pwcChars. The value of each element is the offset from the first glyph in the run to the first glyph in the cluster containing the corresponding character. For an example, see Remarks. Note that when *psa.fRTL is TRUE, the elements in *pwLogClust decrease when reading the array.
psva
[out] Pointer to an array of SCRIPT_VISATTR structures that receives visual attributes information. There is one visual attribute per glyph, so *psva has cMaxGlyphs elements.
pcGlyphs
[out] Pointer to an integer that receives a count of the number of glyphs written to pwOutGlyphs.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. The function returns E_OUTOFMEMORY if the output buffer length, cMaxGlyphs, is insufficient. Note that in all error cases the content of all output parameters are undefined.

If any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

If ScriptShape returns E_OUTOFMEMORY, pcGlyphs is undefined; you may need to call ScriptShape repeatedly until a large enough buffer is found. The number of glyphs generated by a code point varies according to the script and the font. For a simple script, a Unicode code point may generate a single glyph. However, a complex script font might construct characters from components, and thus generate several times as many glyphs as characters. Also, there are special cases like invalid character representations, where extra glyphs are added to represent the invalid sequence. Therefore, a reasonable guess for the buffer pointed to by pwOutGlyphs might be 1.5 times the length of the character buffer, plus an additional 16 glyphs for rare cases like invalid sequence representation.

If ScriptShape returns E_OUTOFMEMORY it will be necessary to call ScriptShape again, and possibly more than once, until a large enough buffer is found.

Clusters are sequenced uniformly within the run, as are glyphs within the cluster. The fRTL item flag (from ScriptItemize) identifies whether sequencing is left-to-right, or right-to-left.

ScriptShape may set the fNoGlyphIndex flag in psa if the font or operating system cannot support glyph indices.

To determine if a font supports the characters in a given string, call ScriptShape. If it returns S_OK, check the output for missing glyphs.If fLogicalOrder is requested in psa, glyphs will be always be generated in the same order as the original Unicode characters. If fLogicalOrder is not set, RTL items are generated in reverse order, so ScriptTextOut does not need to reverse them before calling ExtTextOut.

If SCRIPT_ANALYSIS.eScript is set to SCRIPT_UNDEFINED, shaping is disabled and ScriptShape displays whatever glyph is in the font cmap table; if none, it displays the missing glyph.

The following example shows how ScriptShape would generate the logical cluster array (*pwLogClust) from a character array (*pwcChars) and a glyph array (*pwOutGlyphs). The run has four clusters:

  • 1st cluster: one character represented by one glyph
  • 2nd cluster: one character represented by three glyphs
  • 3rd cluster: three characters represented by one glyph
  • 4th cluster: two characters represented by three glyphs

Character array (where c<n>u<m> means cluster n, Unicode codepoint m):

  • | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |

Glyph array (where c<n>g<m> means cluster n, glyph m):

  • | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |

Cluster array (the offset, in glyphs, to the cluster containing the character):

  • | 0 | 1 | 4 4 4 | 5 5 |

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ExtTextOut, ScriptItemize, ScriptShape, ScriptTextOut, SCRIPT_ANALYSIS, SCRIPT_CACHE, SCRIPT_VISATTR


ScriptStringAnalyse

The ScriptStringAnalyse function analyzes a plain text string.

HRESULT WINAPI ScriptStringAnalyse(
  HDC hdc,
  const void *pString,
  int cString,
  int cGlyphs,
  int iCharset,
  DWORD dwFlags,
  int iReqWidth,
  SCRIPT_CONTROL *psControl,
  SCRIPT_STATE *psState,
  const int *piDx,
  SCRIPT_TABDEF *pTabdef,
  const BYTE *pbInClass,
  SCRIPT_STRING_ANALYSIS *pssa
);

Parameters

hdc
[in] Handle to the device context. If dwFlags is SSA_GLYPH, the hdc is required. If dwFlags is SSA_BREAK, the hdc is optional.

If the hdc is present, the current font in the hdc is inspected. If the current font is a symbolic font, the character string is treated as a single neutral SCRIPT_UNDEFINED item.

pString
[in] Pointer to the string to be analyzed. It must have at least one character.
cString
[in] Length of the string. This must be at least 1.
cGlyphs
[in] Glyph buffer size. This is required. The default size is cString * 3/2 + 1.
iCharset
[in] Character set descriptor. If this is an ANSI string, this is the charset. If it is a Unicode string, this is –1.
dwFlags
[in] Indicates the analysis required. This parameter can be one of the following values.
Value | Meaning
SSA_BREAK | Returns break flags, that is, character and word stops.
SSA_CLIP | Clips the string at iReqWidth.
SSA_DZWG | Provides representation glyphs for control characters.
SSA_FALLBACK | Uses fallback fonts.
SSA_FIT | Justifies string to iReqWidth.
SSA_GLYPHS | Generates glyphs, positions, and attributes.
SSA_GCP | Returns missing glyphs and pwLogClust with GetCharacterPlacement conventions.
SSA_HIDEHOTKEY | Removes the first '&' from displayed string.
SSA_HOTKEY | Replaces '&' with underline on subsequent codepoint.
SSA_HOTKEYONLY | Displays underline only.
SSA_LINK | Applies East Asian font linking and association to noncomplex text.
SSA_METAFILE | Writes items with ExtTextOutW calls, not with glyphs.
SSA_PASSWORD | Inputs string contains a single character to be duplicated iLength times.
SSA_RTL | Uses base embedding level 1.
SSA_TAB | Expands tabs.

iReqWidth
[in] Required width for fitting or clipping.
psControl
[in] Pointer to a SCRIPT_CONTROL structure. If NULL, all SCRIPT_CONTROL members are set to zero.
psState
[in] Pointer to a SCRIPT_STATE structure. If NULL, all SCRIPT_STATE members are set to zero. The uBidiLevel member of SCRIPT_STATE is ignored. The value used is derived from the SSA_RTL flag in combination with the layout of the hdc.
piDx
[in] Pointer to the requested logical dx array.
pTabdef
[in] Pointer to a SCRIPT_TABDEF structure. This is only required if dwFlags is SSA_TAB.
pbInClass
[in] Pointer to a BYTE that indicates GetCharacterPlacement character classifications.
pssa
[out] Pointer to a SCRIPT_STRING_ANALYSIS structure.

Return Values

If the function is successful, it returns S_OK.

If there is an invalid argument, it returns E_INVALIDARG.

If SSA_FALLBACK was not specified, or if a standard fallback font is missing, it returns USP_E_SCRIPT_NOT_IN_FONT. It will also return any Win32 error (converted to an HRESULT by the HRESULT_FROM_WIN32 macro), such as those from lack of memory or GDI calls using the hdc.

If any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The ScriptStringAnalyse function is the first step in handling plain text strings. Plain text is a string that has only one font, one style, one size, one color, and so forth. ScriptStringAnalyse allocates temporary buffers for item analyzes, glyphs, advance widths, and so forth. Then it automatically runs ScriptItemize, ScriptShape, ScriptPlace, and ScriptBreak. The results are then available through all the other ScriptString functions.

Although the functionality of ScriptStringAnalyse can be implemented by direct calls to other functions, ScriptStringAnalyse drastically reduces the amount of code required in the application for plain text handling.

Note that the uBidiLevel member in the initial SCRIPT_STATE value is ignored—the uBidiLevel that is used is derived from the SSA_RTL flag in combination with the layout of the hdc.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ExtTextOut, GetCharacterPlacement, ScriptBreak, ScriptItemize, ScriptPlace, ScriptShape, SCRIPT_CONTROL, SCRIPT_STATE, SCRIPT_STRING_ANALYSIS, SCRIPT_TABDEF


ScriptStringCPtoX

The ScriptStringCPtoX function returns the x-coordinate for the leading or trailing edge of a character position.

HRESULT WINAPI ScriptStringCPtoX(
  SCRIPT_STRING_ANALYSIS ssa,
  int icp,
  BOOL fTrailing,
  int *pX
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for the string.
icp
[in] Character position in the string.
fTrailing
[in] Indicates the edge of the icp that corresponds to the x coordinate. If TRUE, it indicates the trailing edge. If FALSE, it indicates the leading edge.
pX
[out] Pointer to a variable that receives the corresponding x coordinate for the icp.

Return Values

If the function succeeds, it returns S_OK.

If the function fails, it returns another HRESULT value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

The return value can be tested with the SUCCEEDED and FAILED macros.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_STRING_ANALYSIS


ScriptStringFree

The ScriptStringFree function frees a SCRIPT_STRING_ANALYSIS structure.

HRESULT WINAPI ScriptStringFree(
  SCRIPT_STRING_ANALYSIS *pssa
);

Parameters

pssa
[in/out] Pointer to a SCRIPT_STRING_ANALYSIS structure.

Return Values

If the function is successful, it returns S_OK.

If the function fails, it returns another HRESULT value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

The return value can be tested with the SUCCEEDED and FAILED macros.

Remarks

When you are finished with a SCRIPT_STRING_ANALYSIS structure, you should free its associated memory.

Note, after this function is called, the pointers returned from ScriptString_pcOutChars, ScriptString_pLogAttr, and ScriptString_pSize that are associated with the pssa are invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptString_pcOutChars, ScriptString_pLogAttr, ScriptString_pSize, SCRIPT_STRING_ANALYSIS


ScriptStringGetLogicalWidths

The ScriptStringGetLogicalWidths function converts visual widths into logical widths.

HRESULT WINAPI ScriptStringGetLogicalWidths(
  SCRIPT_STRING_ANALYSIS ssa,
  int *piDx
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for the string.
piDx
[out] Pointer to a buffer containing the logical widths that are returned. The buffer should have room for at least *ScriptString_pcOutChars(ssa) ints.

Return Values

If the function is successful, it returns S_OK.

If the function fails, it returns another HRESULT value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

The return value can be tested with the SUCCEEDED and FAILED macros.

Remarks

This function converts the visual widths that were generated by ScriptStringAnalyse into logical widths, one per original character, in logical order.

This function requires that SSA_GLYPHS was requested in the original ScriptStringAnalyse call.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptStringAnalyse, ScriptString_pcOutChars, SCRIPT_STRING_ANALYSIS


ScriptStringGetOrder

The ScriptStringGetOrder function creates an array that maps an original character position to a glyph position.

HRESULT WINAPI ScriptStringGetOrder(
  SCRIPT_STRING_ANALYSIS ssa,
  UINT *puOrder
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for the string.
puOrder
[out] Pointer to the array that receives the glyph positions, indexed by the original character position. The array should have room for at least *ScriptString_pcOutChars(ssa) ints.

Return Values

If the function is successful, it returns S_OK.

If the function fails, it returns another HRESULT value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

The return value can be tested with the SUCCEEDED and FAILED macros.

Remarks

When there are are an equal number of glyphs and characters, the function returns an array that references every glyph. This is the same treatment that occurs in GetCharacterPlacement.

This function requires that SSA_GLYPHS was requested in the original call to ScriptStringAnalyse.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, GetCharacterPlacement, ScriptStringAnalyse, ScriptString_pcOutChars, SCRIPT_STRING_ANALYSIS


ScriptStringOut

The ScriptStringOut function displays a string generated by a prior call to ScriptStringAnalyse and optionally adds highlighting.

HRESULT WINAPI ScriptStringOut(
  SCRIPT_STRING_ANALYSIS ssa,
  int iX,
  int iY,
  UINT uOptions,
  const RECT *prc,
  int iMinSel,
  int iMaxSel,
  BOOL fDisabled
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for the string.
iX
[in] Specifies the x-coordinate of the reference point used to position the string.
iY
[in] Specifies the y-coordinate of the reference point used to position the string.
uOptions
[in] Specifies how to use the application-defined rectangle. This parameter can be a combination of the following values.
Value | Meaning
ETO_CLIPPED | The text will be clipped to the rectangle.
ETO_OPAQUE | The current background color should be used to fill the rectangle.

prc
[in] Pointer to a RECT structure that defines a clipping rectangle. The puOptions parameter must be set to ETO_CLIPPED.
iMinSel
[in] Starting position in the string. For no selection, set iMinSel >= iMaxSel.
iMaxSel
[in] Ending position in the string.
fDisabled
[in] If this parameter is TRUE, the system applies disabled-text highlighting by setting the background color to COLOR_HIGHLIGHT behind all selected characters.

If this parameter is FALSE, the system applies enabled-text highlighting by setting the background color to COLOR_HIGHLIGHT and the text color to COLOR_HIGHLIGHTTEXT for each selected character.

Return Values

If the function is successful, it returns S_OK.

If the function fails, it returns another HRESULT value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

The return value can be tested with the SUCCEEDED and FAILED macros.

Remarks

This function requires that SSA_GLYPHS was requested in the original ScriptStringAnalyse call.

You should not use SetTextAlign with TA_UPDATECP when you are using ScriptStringOut because selected text will not be rendered correctly. If you must use this flag, you can unset and reset it as necessary to avoid the problem.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptStringAnalyse, RECT, SetTextAlign, SCRIPT_STRING_ANALYSIS


ScriptString_pcOutChars

The ScriptString_pcOutChars function returns a pointer to the length of a string after clipping.

const int* WINAPI ScriptString_pcOutChars(
  SCRIPT_STRING_ANALYSIS ssa
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for the string.

Return Values

If the function is successful, it returns a pointer to the length of the string after clipping. The length is the number of Unicode code points.

If the function fails, it returns NULL.

Remarks

Clipping requires that SSA_CLIP was requested in the original call to ScriptStringAnalyse.

Note, the INT pointer is valid only until the associated ssa is passed to ScriptStringFree.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptStringAnalyse, ScriptStringFree, SCRIPT_STRING_ANALYSIS


ScriptString_pLogAttr

The ScriptString_pLogAttr function returns a pointer to a logical attributes buffer for an analyzed string.

const SCRIPT_LOGATTR* WINAPI ScriptString_pLogAttr(
  SCRIPT_STRING_ANALYSIS ssa
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for the string.

Return Values

If the function is successful, it returns a pointer to the logical attributes buffer.

If the function fails, it returns NULL.

Remarks

The buffer pointer is valid only until the associated ssa is passed to ScriptStringFree.

The logical attribute buffer contains *ScriptString_pcOutChars (ssa) entries.

When scanning the SCRIPT_LOGATTR array for a wordbreak point you should look backwards for fWordStop and fWhiteSpace. This is because ScriptStringAnalyse simply calls ScriptBreak on each run, and ScriptBreak never sets fWordBreak on the first character of a run because it does not know whether the previous run ended in whitespace.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptStringFree, ScriptString_pcOutChars, SCRIPT_STRING_ANALYSIS , ScriptStringAnalyse, ScriptBreak


ScriptString_pSize

The ScriptString_pSize function returns a pointer to a SIZE structure for an analyzed string.

const SIZE* WINAPI ScriptString_pSize(
  SCRIPT_STRING_ANALYSIS ssa
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for a string.

Return Values

If the function is successful, it returns a pointer to the size (width and height) of an analyzed string.

If the function fails, it returns NULL.

Remarks

The SIZE pointer remains valid only until the associated ssa is passed to ScriptStringFree.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ScriptStringFree, SCRIPT_STRING_ANALYSIS, SIZE


ScriptStringValidate

The ScriptStringValidate function checks the SCRIPT_STRING_ANALYSIS structure for invalid sequences.

HRESULT WINAPI ScriptStringValidate(
  SCRIPT_STRING_ANALYSIS ssa
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for a string.

Return Values

If there are no invalid sequences, the function returns S_OK.

If there are one or more invalid sequences, the function returns S_FALSE. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

This function is intended for use in editors that reject the input of invalid sequences.

Invalid sequences are only checked for those scripts with the fRejectInvalid member set in SCRIPT_PROPERTIES. For example, it is conventional for Notepad to reject invalid Thai character sequences. However, invalid Indian sequences are not conventionally rejected, but instead are displayed in composition with a missing base character symbol.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_PROPERTIES, SCRIPT_STRING_ANALYSIS


ScriptStringXtoCP

The ScriptStringXtoCP function converts an x-coordinate to a character position.

HRESULT WINAPI ScriptStringXtoCP(
  SCRIPT_STRING_ANALYSIS  ssa,
  int iX,
  int *piCh,
  int *piTrailing
);

Parameters

ssa
[in] A SCRIPT_STRING_ANALYSIS structure for the string.
iX
[in] Specifies the x coordinate.
piCh
[out] Pointer to a variable that receives the character position corresponding to iX.
piTrailing
[out] Pointer to a variable that receives an indicator whether the position is the leading or trailing edge of the character.

Return Values

If the function is successful, it returns S_OK.

If the function fails, it returns another HRESULT value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

The return value can be tested with the SUCCEEDED and FAILED macros.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_STRING_ANALYSIS


ScriptTextOut

The ScriptTextOut function takes the output of both ScriptShape and ScriptPlace calls and calls the operating system ExtTextOut function appropriately.

All arrays are in display order unless the fLogicalOrder member is set in the SCRIPT_ANALYSIS structure pointed to by psa.

HRESULT WINAPI ScriptTextOut(
  const HDC hdc,
  SCRIPT_CACHE *psc,
  int x,
  int y,
  UINT fuOptions,
  const RECT *lprc,
  const SCRIPT_ANALYSIS *psa,
  const WCHAR *pwcReserved,
  int iReserved,
  const WORD *pwGlyphs,
  int cGlyphs,
  const int *piAdvance,
  const int *piJustify,
  const GOFFSET *pGoffset
);

Parameters

hdc
[in] Handle to a device context.
psc
[in/out] Pointer to a SCRIPT_CACHE structure.
x
[in] Value of the x-coordinate of the first glyph.
y
[in] Value of the y-coordinate of the first glyph.
fuOptions
[in] Options equivalent to the fuOptions parameter of ExtTextOut. It may contain ETO_CLIPPED or ETO_OPAQUE (or neither of them, or both of them).
lprc
[in] Pointer to a rectangle used to clip the display. This parameter is optional and can be NULL.
psa
[in] Pointer to a SCRIPT_ANALYSIS structure obtained from a previous call to ScriptItemize.
pwcReserved
Reserved, must be NULL.
iReserved
Reserved, must be zero.
pwGlyphs
[in] Pointer to an array of glyphs obtained from a previous call to ScriptShape.
cGlyphs
[in] Count of the glyphs in the pwGlyphs array. The maximum number of glyphs is 65,536.

Windows 95/98: The maximum number of glyphs is 8,192.

piAdvance
[in] Pointer to an array of advance widths obtained from a previous call to ScriptPlace.
piJustify
[in] Pointer to an array of justified advance widths. This parameter is optional and can be NULL.
pGoffset
[in] Pointer to a GOFFSET structure containing the x and y offsets for the combining glyph.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

For any run that is rendered right-to-left (fRTL) and was generated in logical order by forcing the fLogicalOrder flag, call SetTextAlign(hdc, TA_RIGHT) and give the right-side coordinate before calling ScriptTextOut.

The piJustify array provides requested cell widths for each glyph. When the piJustify width of a glyph differs from the unjustified width (in piAdvance), space is added to or removed from the glyph cell at its trailing edge. The glyph is always aligned with the leading edge of its cell. (This rule applies even in visual order.)

When a glyph cell is extended the extra space is usually made up by the addition of white space, however for Arabic scripts, the extra space is made up by one or more kashida glyphs, unless the extra space is insufficient for the shortest kashida glyph in the font. (The width of the shortest kashida is available by calling ScriptGetFontProperties.)

The piJustify parameter should be passed only if the string must be justified again. Normally, pass NULL to this parameter.

The pwcinChars and cChars parameters are required only if output is to a metafile DC. If hdc is not a metafile, these parameters may be passed as NULL and zero.

Do not use ScriptTextOut to write to a metafile unless you are sure that the metafile will be played back without any font substitution. ScriptTextOut records glyph numbers in the metafile, and since glyph numbers vary considerably from one font to another, such a metafile is unlikely to play back correctly when different fonts are substituted. For example, when a metafile is played back at a different scale, a CreateFont request that is recorded in the metafile may resolve to a bitmap instead of a TrueType font. Likewise, if the metafile is played back on a different machine, the requested fonts may not be installed. To write complex scripts in a metafile in a font-independent manner, use ExtTextOut to write the logical characters directly, so that glyph generation and placement do not occur until the text is played back.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ExtTextOut, ScriptGetFontProperties, ScriptItemize, ScriptPlace, ScriptShape, SetTextAlign, GOFFSET, SCRIPT_ANALYSIS, SCRIPT_CACHE


ScriptXtoCP

The ScriptXtoCP function converts an x offset from the left end (!fLogicalOrder) or leading edge (fLogicalOrder) of a run to a logical character position and a flag that indicates whether the x position fell in the leading or the trailing half of the character.

HRESULT WINAPI ScriptXtoCP(
  int iX,
  int cChars,
  int cGlyphs,
  const WORD *pwLogClust,
  const SCRIPT_VISATTR *psva,
  const int *piAdvance,
  const SCRIPT_ANALYSIS *psa,
  int *piCP,
  int *piTrailing
);

Parameters

iX
[in] Offset, in logical units, from the end of the run specified by SCRIPT_ANALYSIS.fLogicalOrder.
cChars
[in] Count of logical code points in the run.
cGlyphs
[in] Count of glyphs in the run.
pwLogClust
[in] Pointer to an array containing logical clusters.
psva
[in] Pointer to an array of SCRIPT_VISATTR structures containing the glyph's visual attributes.
piAdvance
[in] Pointer to an array of advance widths.
psa
[in] Pointer to a SCRIPT_ANALYSIS structure. SCRIPT_ANALYSIS.fLogicalOrder specifies the end of the run: if it is set, the leading edge of the run is specified; otherwise, the left end of the run is specified.
piCP
[out] Pointer to an integer to receive the character position.
piTrailing
[out] Pointer to an integer that tells the distance, in code points, from the leading edge of the logical character to the iX position. If zero, the iX position is at the leading edge of the logical character. For more information, see the Remarks.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The leading and trailing edge of the logical character is determined by the direction of text in the run (LTR or RTL).

For scripts where the caret may conventionally be placed into the middle of clusters (for example, Arabic and Hebrew), the returned character position may be for any code point in the line, and piTrailing will be either zero or one.

For scripts in which the caret is conventionally snapped to the boundaries of a cluster, the returned character position is always the position of the first code point in a cluster (considered logically), and piTrailing is either zero or the number of code points in the cluster.

Thus the appropriate caret position for a mouse hit is always the returned character position plus the value of fTrailing.

When iX is a position outside of the run, ScriptXtoCP acts as if there is an extra infinitely large character beyond each end of the run. This results in the behavior shown in the following table.

iX position (outside of the run) | Result
Before the run, that is: (if run is LTR) iX < 0, or (if run is RTL) iX >= sum of advances for the run | *piCP is returned as -1 and *piTrailing is returned as TRUE
After the run, that is: (if run is LTR) iX >= sum of the advances of the run, or (if run is RTL), iX < 0 | *piCP is returned as cChars, and *piTrailing is returned as FALSE

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.
Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, SCRIPT_ANALYSIS, SCRIPT_VISATTR


Uniscribe Structures

The following section describes complex script processing structures.

GOFFSET
SCRIPT_ANALYSIS
SCRIPT_CACHE
SCRIPT_CONTROL
SCRIPT_DIGITSUBSTITUTE
SCRIPT_FONTPROPERTIES
SCRIPT_ITEM
SCRIPT_LOGATTR
SCRIPT_PROPERTIES
SCRIPT_STATE
SCRIPT_STRING_ANALYSIS
SCRIPT_TABDEF
SCRIPT_VISATTR


GOFFSET

The GOFFSET structure contains the x and y offsets of the combining glyph.

typedef struct tagGOFFSET {
  LONG  du;
  LONG  dv;
} GOFFSET;

Members

du
x offset, in logical units, for the combining glyph.
dv
y offset, in logical units, for the combining glyph.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptPlace, ScriptTextOut


SCRIPT_ANALYSIS

The SCRIPT_ANALYSIS structure describes an item, that is, a portion of a Unicode string. This structure is filled by ScriptItemize, which breaks a Unicode string into individually shapeable items. The structure also includes a copy of the Unicode algorithm state (SCRIPT_STATE).

typedef struct tag_SCRIPT_ANALYSIS {
  WORD eScript      :10;
  WORD fRTL          :1;
  WORD fLayoutRTL    :1;
  WORD fLinkBefore   :1;
  WORD fLinkAfter    :1;
  WORD fLogicalOrder :1;
  WORD fNoGlyphIndex :1;
  SCRIPT_STATE s ;
} SCRIPT_ANALYSIS;

Members

eScript
Opaque value identifying which engine Uniscribe will use when calling the ScriptShape, ScriptPlace, and ScriptTextOut functions for this item. The value of eScript is undefined and will change in future releases, but attributes of eScript may be obtained by calling ScriptGetProperties.

To disable shaping, set this parameter to SCRIPT_UNDEFINED.

fRTL
Rendering direction. Normally identical to the parity of the Unicode embedding level, but it may differ if overridden by GetCharacterPlacement legacy support.
fLayoutRTL
Logical direction, whether left-to-right or right-to-left. Although this is usually the same as fRTL, for a number in a RTL run, fRTL is False (because digits are always displayed LTR), but fLayoutRTL is True (because the number is read as part of the RTL sequence).
fLinkBefore
If set, the shaping engine will shape the first character of this item as if it were joining with a previous character. Set by ScriptItemize, it may be overridden before calling ScriptShape.
fLinkAfter
If set, the shaping engine will shape the last character of this item as if it were joining with a subsequent character. Set by ScriptItemize, it may be overridden before calling ScriptShape.
fLogicalOrder
If set, the shaping engine will generate all glyph-related arrays in logical order. By default, glyph-related arrays are in visual order, the first array entry corresponding to the leftmost glyph. Set to FALSE by ScriptItemize, it may be overridden before calling ScriptShape.
fNoGlyphIndex
Typically FALSE. Set to TRUE for bitmap, vector, and device fonts; and for Asian scripts. It may be set to TRUE on input to ScriptShape to disable use of glyphs for this item. Additionally, ScriptShape will set it to TRUE for an hdc containing symbolic, unrecognized, and device fonts.

Disabling glyphing disables complex script shaping. When set, shaping and placing for this item is implemented directly by calls to GetTextExtentExPoint and ExtTextOut.

s
A SCRIPT_STATE structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ExtTextOut, GetCharacterPlacement, GetTextExtentExPoint, ScriptGetProperties, ScriptItemize, ScriptPlace, ScriptShape, ScriptTextOut, SCRIPT_STATE


SCRIPT_CACHE

SCRIPT_CACHE is an opaque pointer to a Uniscribe font metric cache structure.

typedef void *SCRIPT_CACHE;

Remarks

The client must allocate and retain one SCRIPT_CACHE variable for each character style used. It must be initialized by the client to NULL.

Many script functions take a combination of HDC and SCRIPT_CACHE. Uniscribe will first attempt to access font data by using the SCRIPT_CACHE and will only inspect the HDC if the required data is not already cached.

The HDC may be passed as NULL. If data required by Uniscribe is already cached, the HDC won't be accessed, and the operation continues normally.

If the HDC is passed as NULL, and Uniscribe needs to access it for any reason, Uniscribe will return E_PENDING.

E_PENDING is returned quickly, allowing the client to avoid time-consuming SelectObject calls. The following example applies to all functions that take a SCRIPT_CACHE and an optional HDC.

hr = ScriptShape(NULL, &sc, ..);
if (hr == E_PENDING) {
    ... select font into hdc ...
    hr = ScriptShape(hdc, &sc, ...);
}

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, SelectObject


SCRIPT_CONTROL

The SCRIPT_CONTROL structure provides itemization control flags to the ScriptItemize function.

typedef struct tag_SCRIPT_CONTROL {
  DWORD uDefaultLanguage :16;
  DWORD fContextDigits :1;
  DWORD fInvertPreBoundDir :1;
  DWORD fInvertPostBoundDir :1;
  DWORD fLinkStringBefore :1;
  DWORD fLinkStringAfter :1;
  DWORD fNeutralOverride :1;
  DWORD fNumericOverride :1;
  DWORD fLegacyBidiClass :1;
  DWORD fReserved :8;
} SCRIPT_CONTROL;

Members

uDefaultLanguage
Specifies the language to use when Unicode values are ambiguous. This is a LANGID, including both a primary language and a sublanguage. Used by numeric processing to select digit shape when fDigitSubstitute (see SCRIPT_STATE) is set.
fContextDigits
Specifies that national digits are chosen according to the nearest previous strong text, rather than using uDefaultLanguage.
fInvertPreBoundDir
By default, text at the start of the string is laid out as if it follows a strong LTR character if the base embedding level is 0, and as if it follows a strong RTL character if the base embedding level is 1.Set fInvertPreBoundDir to change the initial context to the opposite of the base embedding level. This member is for GetCharacterPlacement legacy support.
fInvertPostBoundDir
By default, text at the end of the string is laid out as if it precedes strong text of the same direction as the base embedding level. Set fInvertPreBoundDir to change the final context to the opposite of the base embedding level. This flag is for GetCharacterPlacement legacy support.
fLinkStringBefore
Causes the first character of the string to be shaped as if it were joined to a previous character.
fLinkStringAfter
Causes the last character of the string to be shaped as if it were joined to a following character.
fNeutralOverride
Causes all neutral characters in the string to be treated as if they were strong characters of their enclosing embedding level. This effectively locks them in place, and reordering occurs only between neutrals.
fNumericOverride
Causes all numeric characters in the string to be treated as if they were strong characters of their enclosing embedding level. This effectively locks them in place, and reordering occurs only between numeric characters.
fLegacyBidiClass
Causes the plus and minus characters to be treated as neutral characters, that is, with no implied direction, and the slash character to be treated as a common separator.
fReserved
Reserved. Always initialize to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, GetCharacterPlacement, ScriptItemize, SCRIPT_STATE


SCRIPT_DIGITSUBSTITUTE

The SCRIPT_DIGITSUBSTITUTE structure contains the native digit and digit substitution settings.

typedef struct tag_SCRIPT_DIGITSUBSTITUTE {
  DWORD NationalDigitLanguage    : 16;
  DWORD TraditionalDigitLanguage : 16;
  DWORD DigitSubstitute          :8;
  DWORD dwReserved;
} SCRIPT_DIGITSUBSTITUTE;

Members

NationalDigitLanguage
Language for native substitution.
TraditionalDigitLanguage
Language for traditional substitution.
DigitSubstitute
Substitution type.
dwReserved
Reserved. Initialize to 0.

Remarks

The DigitSubstitute member of SCRIPT_DIGITSUBSTITUTE structure is normally set by ScriptRecordDigitSubstitution. However, it may be replaced by any one of the following values:

  • SCRIPT_DIGITSUBSTITUTE_CONTEXT - Digits U+0030 to U+0039 are substituted using the language of the prior letters. If there are no prior letters, digits are substituted using the TraditionalDigitLanguage member of the SCRIPT_DIGITSUBSTITUTE structure. This member is normally set to the primary language of the locale passed to ScriptRecordDigitSubstitution.
  • SCRIPT_DIGITSUBSTITUTE_NATIONAL - Digits U+0030 to U+0039 are substituted using the NationalDigitLanguage member of the SCRIPT_DIGITSUBSTITUTE structure. This member is normally set to the national digits returned for the NLS LCTYPE LOCALE_SNATIVEDIGITS by ScriptRecordDigitSubstitution.
  • SCRIPT_DIGITSUBSTITUTE_NONE - Digits are not substituted. Unicode values U+0030 to U+0039 are displayed with Arabic, that is Western, numerals.
  • SCRIPT_DIGITSUBSTITUTE_TRADITIONAL - Digits U+0030 to U+0039 are substituted using the TraditionalDigitLanguage member of the SCRIPT_DIGITSUBSTITUTE structure. This member is normally set to the primary language of the locale passed to ScriptRecordDigitSubstitution.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptRecordDigitSubstitution


SCRIPT_FONTPROPERTIES

The SCRIPT_FONTPROPERTIES structure contains information about the current font's properties.

typedef struct {
  int   cBytes;
  WORD  wgBlank;
  WORD  wgDefault;
  WORD  wgInvalid;
  WORD  wgKashida;
  int   iKashidaWidth;
} SCRIPT_FONTPROPERTIES;

Members

cBytes
Size, in bytes, of the structure.
wgBlank
Glyph used to indicate a blank.
wgDefault
Glyph used to indicate Unicode characters not present in the font.
wgInvalid
Glyph used to indicate invalid character combinations.
wgKashida
Glyph used to indicate the shortest continuous kashida, with –1 indicating that the font contains no kashida.
iKashidaWidth
Width of the shortest continuous kashida glyph in the font, indicated by the wgKashida member.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptGetFontProperties


SCRIPT_ITEM

The SCRIPT_ITEM structure includes a SCRIPT_ANALYSIS with the string offset of the first character of the item.

typedef struct tag_SCRIPT_ITEM {
  int iCharPos;
  SCRIPT_ANALYSIS a;
} SCRIPT_ITEM;

Members

iCharPos
Specifies the offset from the beginning of the itemized string to the first character of this item, counted in Unicode code points, that is, in words.
a
Specifies a SCRIPT_ANALYSIS structure containing analysis specific to this item.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptItemize, SCRIPT_ANALYSIS


SCRIPT_LOGATTR

The SCRIPT_LOGATTR structure describes attributes of logical characters that are useful when editing and formatting text.

typedef struct tag_SCRIPT_LOGATTR {
  BYTE fSoftBreak :1;
  BYTE fWhiteSpace :1;
  BYTE fCharStop :1;
  BYTE fWordStop :1;
  BYTE fInvalid :1;
  BYTE fReserved :3;
} SCRIPT_LOGATTR;

Members

fSoftBreak
It is valid to break the line in front of this character. This member is set on the first character of Southeast Asian words.
fWhiteSpace
This character is one of the many Unicode characters that are classified as breakable white space. Breakable white space can break words—that is, it is all white space except NBSP (nonbreaking space) and ZWNBSP (zero-width nonbreaking space).
fCharStop
Valid caret position. Set on most characters, but not on code points inside Indian and Southeast Asian character clusters. May be used to implement LEFT ARROW and RIGHT ARROW operations in editors.
fWordStop
Valid caret position. It is the correct place to show the caret when you use a word movement keyboard action such as CTRL+LEFT ARROW and CTRL+RIGHT ARROW. May be used to implement the CTRL+LEFT ARROW and CTRL+RIGHT ARROW operations in editors.
fInvalid
Marks characters which form an invalid or undisplayable combination. Scripts which can set this flag have the flag fInvalidLogAttr set in their SCRIPT_PROPERTIES structure.
fReserved
Reserved.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptBreak, SCRIPT_PROPERTIES


SCRIPT_PROPERTIES

The SCRIPT_PROPERTIES structure has information about special processing for each script.

typedef struct {
  DWORD   langid              :16;
  DWORD   fNumeric            :1;
  DWORD   fComplex            :1;
  DWORD   fNeedsWordBreaking  :1;
  DWORD   fNeedsCaretInfo     :1;
  DWORD   bCharSet            :8;
  DWORD   fControl            :1;
  DWORD   fPrivateUseArea     :1;
  DWORD   fNeedsCharacterJustify :1;
  DWORD   fInvalidGlyph       :1;
  DWORD   fInvalidLogAttr     :1;
  DWORD   fCDM                :1;
  DWORD   fAmbiguousCharSet   :1;
  DWORD   fClusterSizeVaries  :1;
  DWORD   fRejectInvalid      ;1;
} SCRIPT_PROPERTIES;

Members

langid
Primary language and sublanguage associated with the script. When a script is used for many languages, langid represents a default language. For example, Western script is represented by LANG_ENGLISH although it is also used for French, German, and other European languages.
fNumeric
If set, the script contains only digits and the other characters used in writing numbers by the rules of the Unicode bidirectional algorithm. For example, currency symbols, the thousands separator, and the decimal point are classified as numeric when adjacent to or between digits.
fComplex
If set, this is a language whose script requires special shaping or layout. If fComplex is false, the script contains no combining characters and requires no contextual shaping or reordering.
fNeedsWordBreaking
If set, this is a language whose word break placement requires that the application call ScriptBreak and that word break placement include character positions marked as fWordStop in SCRIPT_LOGATTR.

If not set, word break placement is identified by scanning for characters marked as fWhiteSpace in SCRIPT_LOGATTR, or for glyphs marked as uJustify == SCRIPT_JUSTIFY_BLANK or SCRIPT_JUSTIFY_ARABIC_BLANK in SCRIPT_VISATTR.

fNeedsCaretInfo
If set, this is a language that restricts caret placement to cluster boundaries, for example, Thai and Indian. To determine valid caret positions, inspect the fCharStop flag in the logical attributes returned by ScriptBreak, or compare adjacent values in the pwLogClust array returned by ScriptShape.

Note that ScriptXtoCP and ScriptCPtoX automatically apply caret placement restictions.

bCharSet
The nominal charset associated with the script. This charset may be used in a log font when creating a font suitable for displaying this script. Note that for a new script where no charset is defined, bCharSet may be inappropriate. In this case, DEFAULT_CHARSET should be used instead. See the description of fAmbiguousCharSet.
fControl
If set, the script contains only control characters. Note, the converse is not necessarily true—not every control character ends up in a SCRIPT_CONTROL structure.
fPrivateUseArea
If set, the script uses a special set of characters that is privately defined for the Unicode range U+E000 through U+F8FF.
fNeedsCharacterJustify
If set, justification for the script is achieved by increasing the space between all letters, not just between words. When performing inter-character justification, insert extra space only after glyphs marked with SCRIPT_VISATTR.uJustify == SCRIPT_JUSTIFY_CHARACTER.
fInvalidGlyph
If set, this is a script for which ScriptShape generates an invalid glyph to represent invalid sequences. That is, it generates wgInvalid in the glyph buffer. The glyph index of the invalid glyph for a particular font may be obtained by calling ScriptGetFontProperties.
fInvalidLogAttr
If set, this is a script for which ScriptBreak marks invalid combinations by setting fInvalid in the logical attributes buffer.
fCDM
If set, the script contains an item that was analyzed by ScriptItemize as including Combining Diacritical Marks (U+0300 through U+36F).
fAmbiguousCharSet
If set, the script contains characters that are supported by more than one charset. See the Remarks section for more information. The bCharSet member should be set to DEFAULT_CHARSET.
fClusterSizeVaries
If set, this is a script, such as Arabic, in which contextual shaping may cause a string to increase in size when removing characters. An example of this is Arabic.
fRejectInvalid
If set, this is a script, such as Thai, where invalid sequences conventionally cause an editor program—such as Notepad—to beep and ignore keystrokes.

Remarks

This structure is filled by the ScriptGetProperties function.

Many Uniscribe scripts do not correspond directly to 8-bit character sets. In the case where some of their characters are supported by more than one charset, the fAmbiguousCharSet member is set. The Uniscribe client should do further processing to determine which charset to use when requesting a font suitable for the run. For example, it may determine that the run consists of multiple languages and split the run so that a different font is used for each language.

Use the following code during initialization to get a pointer to the SCRIPT_PROPERTIES array:

const SCRIPT_PROPERTIES **g_ppScriptProperties; // Array of pointers
                                                // to properties
int iMaxScript;
HRESULT hr;

hr = ScriptGetProperties(&g_ppScriptProperties, &g_iMaxScript);

Then inspect the properties of the script of an item 'iItem' as follows:

hr = ScriptItemize( ... , pItems, ... );
...
if (g_ppScriptProperties[pItems[iItem].a.eScript]->fNeedsCaretInfo)
    {
       // Use ScriptBreak to restrict the caret from entering clusters (for example).
    }

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptBreak, ScriptCPtoX, ScriptGetFontProperties, ScriptItemize, ScriptGetProperties, ScriptShape, ScriptXtoCP, SCRIPT_CONTROL, SCRIPT_LOGATTR, SCRIPT_VISATTR


SCRIPT_STATE

The SCRIPT_STATE structure is used both to initialize the Unicode algorithm state as an input parameter to ScriptItemize, and is also a component of the analysis returned by ScriptItemize.

typedef struct tag_SCRIPT_STATE {
  WORD uBidiLevel :5;
  WORD fOverrideDirection :1;
  WORD fInhibitSymSwap :1;
  WORD fCharShape :1;
  WORD fDigitSubstitute :1;
  WORD fInhibitLigate :1;
  WORD fDisplayZWG :1;
  WORD fArabicNumContext :1;
  WORD fGcpClusters :1;
  WORD fReserved :1;
  WORD fEngineReserved :2;
} SCRIPT_STATE;

Members

uBidiLevel
The embedding level associated with all characters in this run according to the Unicode bidirectional algorithm. When passed to ScriptItemize, should be initialized to zero for an LTR base embedding level, or 1 for RTL.
fOverrideDirection
TRUE if this level is an override level (LRO/RLO). In an override level, characters are laid out in one direction only, either left-to-right or right-to-left. No reordering of digits or strong characters of opposing direction takes place. Note that this initial value is reset by LRE, RLE, LRO or RLO codes in the string.
fInhibitSymSwap
TRUE if the shaping engine is to bypass mirroring of Unicode mirrored glyphs such as brackets. Set by Unicode character ISS, cleared by ASS.
fCharShape
TRUE if character codes in the Arabic Presentation Forms areas of Unicode should be shaped. (Not implemented).
fDigitSubstitute
TRUE if character codes U+0030 through U+0039 (European digits) are to be substituted by national digits. Set by Unicode NADS, cleared by NODS.
fInhibitLigate
TRUE if ligatures are not to be used in the shaping of Arabic or Hebrew characters.
fDisplayZWG
TRUE if control characters are to be shaped as representational glyphs. (Typically, control characters are shaped to the blank glyph and given a width of zero).
fArabicNumContext
TRUE indicates prior strong characters were Arabic for the purposes of rule P0 as discussed in The Unicode Standard, version 2.0. This should normally be set to TRUE before itemizing an RTL paragraph in an Arabic language, and FALSE otherwise.
fGcpClusters
For GetCharacterPlacement legacy support only. Initialize to TRUE to request ScriptShape to generate the pwLogClust array the same way as GetCharacterPlacement does in Arabic and Hebrew Windows 95. Affects only Arabic and Hebrew items.
fReserved
Reserved. Always initialize to zero.
fEngineReserved
Reserved. Always initialize to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, GetCharacterPlacement, ScriptItemize, ScriptShape


SCRIPT_STRING_ANALYSIS

SCRIPT_STRING_ANALYSIS is an opaque structure containing some or all of the character attributes, glyphs, advance widths, x- and y-positions, character-to-glyph mappings, and so forth, for a string.

typedef void *SCRIPT_STRING_ANALYSIS;

Remarks

It is allocated dynamically and returned by ScriptStringAnalyse, and is a required parameter to all other ScriptString functions.

It is important to call ScriptStringFree as soon as you have finished with the string, since the analysis can be large.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptStringAnalyse, ScriptStringFree


SCRIPT_TABDEF

The SCRIPT_TABDEF structure defines the tab positions for ScriptStringAnalyse.

typedef struct tag_SCRIPT_TABDEF {
  int cTabStops;
  int iScale;
  int *pTabStops;
  int iTabOrigin;
} SCRIPT_TABDEF;

Members

cTabStops
Number of entries in the array pointed to by pTabStops.
Value | Meaning
0 | Tab stops occur every eight average-character widths.
1 | All tab stops are the length of the first entry in the array pointed to by pTabStops.
greater than 1 | The first cTabStops tab stops are as specified in the array pointed to by pTabStops, and subsequent tab stops are every eight average characters.

iScale
Scale factor for iTabOrigin and pTabStops entries. Values are converted to device coordinates by multiplying by iScale, then dividing by four. If values are already in device units, set iScale to four. If values are in dialog units, set iScale to the average character width of the dialog font. If values are multiples of the average character width for the selected font, set iScale to 0.
pTabStops
Pointer to an array whose number of entries is cTabStops. Each entry specifies a tab stop position. Positive values give near-edge alignment, while negative values give far-edge alignment.

The units for the array elements are as selected by iScale.

iTabOrigin
Initial offset, in logical units, for tab stops. Tabs start iTabOrigin logical units before the beginning of the string. This helps with situations where there are multiple tabbed outputs on the same line.

Remarks

This structure is ignored unless the dwFlags parameter is set to SSA_TAB in the ScriptStringAnalyse function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptStringAnalyse


SCRIPT_VISATTR

The SCRIPT_VISATTR structure contains the visual (glyph) attribute buffer generated by ScriptShape that identifies clusters and justification points.

typedef struct tag_SCRIPT_VISATTR {
  WORD uJustification :4;
  WORD fClusterStart :1;
  WORD fDiacritic :1;
  WORD fZeroWidth :1;
  WORD fReserved :1;
  WORD fShapeReserved :8;
} SCRIPT_VISATTR;

Members

uJustification
Justification class for this glyph. See SCRIPT_JUSTIFY.
fClusterStart
Set for the logical first glyph in every cluster, even for clusters containing just one glyph.
fDiacritic
Set for glyphs that combine with base characters.
fZeroWidth
Set by the shaping engine for some, but not all, zero-width characters, such as ZWJ and ZWNJ.
fReserved
Reserved. Always initialize to zero.
fShapeReserved
Reserved for use by the shaping engines.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Structures, ScriptShape, SCRIPT_JUSTIFY


Uniscribe Enumeration Types

The following enumeration types are used with complex script processing:

SCRIPT
SCRIPT_JUSTIFY


SCRIPT

The SCRIPT enumeration type is an opaque type used internally to identify which shaping engine functions are used to process a given run. The only public value is SCRIPT_UNDEFINED.

Enumeration Values

SCRIPT_UNDEFINED
When forced into the eScript member of SCRIPT_ANALYSIS, shaping is disabled. When this is done, ScriptShape displays whatever glyph is defined in the font CMAP table, or, if none, the missing glyph.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Enumeration Types, ScriptShape, SCRIPT_ANALYSIS


SCRIPT_JUSTIFY

The SCRIPT_JUSTIFY enumeration type provides the client with the glyph characteristic information it needs to implement justification.

typedef enum tag_SCRIPT_JUSTIFY {
  SCRIPT_JUSTIFY_NONE = 0,
  SCRIPT_JUSTIFY_ARABIC_BLANK = 1,
  SCRIPT_JUSTIFY_CHARACTER = 2,
  SCRIPT_JUSTIFY_RESERVED1 = 3,
  SCRIPT_JUSTIFY_BLANK = 4,
  SCRIPT_JUSTIFY_RESERVED2 = 5,
  SCRIPT_JUSTIFY_RESERVED3 = 6,
  SCRIPT_JUSTIFY_ARABIC_NORMAL = 7,
  SCRIPT_JUSTIFY_ARABIC_KASHIDA = 8,
  SCRIPT_JUSTIFY_ARABIC_ALEF = 9,
  SCRIPT_JUSTIFY_ARABIC_HA = 10,
  SCRIPT_JUSTIFY_ARABIC_RA = 11,
  SCRIPT_JUSTIFY_ARABIC_BA = 12,
  SCRIPT_JUSTIFY_ARABIC_BARA = 13,
  SCRIPT_JUSTIFY_ARABIC_SEEN = 14,
  SCRIPT_JUSTIFY_RESERVED4 = 15,
} SCRIPT_JUSTIFY;

Enumeration Values

SCRIPT_JUSTIFY_NONE
Justification cannot be applied at this glyph.
SCRIPT_JUSTIFY_ARABIC_BLANK
This glyph represents a blank in an Arabic run.
SCRIPT_JUSTIFY_CHARACTER
An inter-character justification point follows this glyph.
SCRIPT_JUSTIFY_RESERVED1
Reserved.
SCRIPT_JUSTIFY_BLANK
This glyph represents a blank outside an Arabic run.
SCRIPT_JUSTIFY_RESERVED2
Reserved.
SCRIPT_JUSTIFY_RESERVED3
Reserved.
SCRIPT_JUSTIFY_ARABIC_NORMAL
Normal middle-of-word glyph that connects to the right (begin).
SCRIPT_JUSTIFY_ARABIC_KASHIDA
Kashida(U+640) in the middle of the word.
SCRIPT_JUSTIFY_ARABIC_ALEF
Final form of an alef-like (U+627, U+625, U+623, U+632).
SCRIPT_JUSTIFY_ARABIC_HA
Final form of Ha (U+647).
SCRIPT_JUSTIFY_ARABIC_RA
Final form of Ra (U+631).
SCRIPT_JUSTIFY_ARABIC_BA
Final form of Ba (U+628).
SCRIPT_JUSTIFY_ARABIC_BARA
Ligature of alike (U+628,U+631).
SCRIPT_JUSTIFY_ARABIC_SEEN
Highest priority: Initial shape of Seen(U+633) (end).
SCRIPT_JUSTIFY_RESERVED4
Reserved.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Usp10.h.

See Also

Uniscribe Overview, Uniscribe Enumeration Types, SCRIPT_VISATTR


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.