ScriptRecordDigitSubstitution function (usp10.h)

Article
10/13/2021

Reads the National Language Support (NLS) native digit and digit substitution settings and records them in a SCRIPT_DIGITSUBSTITUTE structure. For more information, see Digit Shapes.

Syntax

HRESULT ScriptRecordDigitSubstitution(
  [in]  LCID                   Locale,
  [out] SCRIPT_DIGITSUBSTITUTE *psds
);

Parameters

[in] Locale

Locale identifier of the locale to query. Typically, the application should set this parameter to LOCALE_USER_DEFAULT. Alternatively, the setting can indicate a specific locale combined with LOCALE_NOUSEROVERRIDE to obtain the default settings.

[out] psds

Pointer to a SCRIPT_DIGITSUBSTITUTE structure. This structure can be passed later to ScriptApplyDigitSubstitution.

Return value

Returns S_OK if successful. The function returns a nonzero HRESULT value if it does not succeed.

Error returns include:

E_INVALIDARG. The Locale parameter indicates a locale that is invalid or not installed.
E_POINTER. The psds parameter is set to NULL.

Remarks

See Displaying Text with Uniscribe for a discussion of the context in which this function is normally called.

This function supports context digit substitution only for Arabic and Persian locales. For other locales, context digit substitution is mapped to no substitution.

The following example shows the typical way to call this function.

SCRIPT_DIGITSUBSTITUTE sds;
ScriptRecordDigitSubstitution(LOCALE_USER_DEFAULT, &sds);

At every itemization, the application can use the results as shown in the next example.

SCRIPT_CONTROL sc = {0};
SCRIPT_STATE   ss = {0};
ScriptApplyDigitSubstitution(&sds, &sc, &ss);

For performance reasons, your application should not call ScriptRecordDigitSubstitution frequently. The function requires considerable overhead to call it every time ScriptItemize or ScriptStringAnalyse is called. Instead, the application can save the SCRIPT_DIGITSUBSTITUTE structure and update it only when a WM_SETTINGCHANGE message is received. Alternatively, the application can update the structure when a RegNotifyChangeKeyValue call in a dedicated thread indicates a change in the registry under HKCU\Control Panel\International.

Important Starting with Windows 8: To maintain the ability to run on Windows 7, a module that uses Uniscribe must specify Usp10.lib before gdi32.lib in its library list.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	usp10.h
Library	Usp10.lib
DLL	Usp10.dll