SetInputScopes Function

Introduction to SetInputScopes function.

The SetInputScopes function associates a window with some combination of one input scope, multiple input scopes, and/or one phrase list.

HRESULT SetInputScopes(
    [in] HWND hwnd,
    [in] const InputScope *pInputScopes,
    [in] UINT cInputScopes,
    [in] WCHAR **ppszPhraseList,
    [in] UINT cPhrases,
    [in] WCHAR *pszRegExp,
    [in] WCHAR *pszSRGS
);

Parameters

hwnd

[in] The window to set the input scope on. This call replaces whatever input scope may have been on the hwnd before the call.

pInputScopes

[in] Pointer to an array of input scopes. May be NULL. If not NULL, all of the input scopes contained within are set as the input scope of the hwnd with equal weighting. Use IS_DEFAULT in combination with another input scope to accept all other input as well (that is, to not coerce to the input scope). For a listing of these values, see the InputScope enumeration.

cInputScopes

[in] Specifies the count of the number of input scopes in pInputScopes.

ppszPhraseList

[in] Pointer to an array of pointers to NULL-terminated phrases to consider. May be NULL.

cPhrases

[in] Count of phrases passed in ppszPhraseList.

pszRegExp

[in] Pointer to NULL-terminated string containing a handwriting regular expression. See Custom Input Scopes for details.

pszSRGS

[in] Reserved. Must be NULL when used with the Tablet PC.

Return Values

S_OK if the function succeeds; otherwise an error code.

Remarks

If you wish for recognition to be restricted to just the content of a phrase list, you should only pass the phrase list for recognizer. You should not set any input scope on the field. For example, if you want recognition on a field to be restricted to two URLs (for example, www.microsoft.com and www.msn.com) you should pass in a phrase list containing these URLs but not set the IS_URL input scope.

When you pass in a regular expression or a phrase list, you should not include IS_PHRASELIST or IS_REGULAREXPRESSION in the pInputScopes parameter. These values are set internally and returned to applications, such as the Tablet PC Input Panel, that query the input scopes on a given control to indicate that a regular expression or phrase list is present.

The InputScope APIs are not thread safe. Only the thread that creates the control may call an InputScope API for the control.

Example Code

[C++]

The following code illustrates how to set an input scope.

InputScope scope = IS_EMAIL_USERNAME;
SetInputScopes(hwnd, &scope, 1, NULL, 0, NULL, NULL);

The following code illustrates how to limit the scope of the recognizer's vocabulary to a list of words or phrases by using a phrase list. This causes the recognizer to coerce to the input scope.

SetInputScopes(hwnd, NULL, 0, { "blue", "yellow", "green", "greenish blue" }, 4, NULL, NULL);

The following code illustrates how to suggest (not coerce) a phrase list as an input scope, by specifying IS_DEFAULT.

SetInputScopes(hwnd, { IS_DEFAULT }, 1, { "blue", "yellow", "green", "greenish blue" }, 4, NULL, NULL);

The following code illustrates how to coerce to an input scope.

InputScope scope = IS_TELEPHONE_FULLTELEPHONENUMBER;
SetInputScopes(hwnd, &scope, 1, NULL, 0, NULL, NULL);

The following code illustrates how to clear an input scope.

InputScope scope = IS_DEFAULT;
SetInputScopes(hwnd, &scope, 1, NULL, 0, NULL, NULL);

Windows XP: Included in Windows XP SP2.

Header: Declared in InputScope.idl and InputScope.h.

Library: Included as a resource in Msctf.dll.