ISpRecognizer::DisplayUI (Windows Embedded CE 6.0)
1/6/2010
This method displays the requested UI component from the underlying SR engine. A call to this method is synchronous. Thus the method does not return until the UI has been closed.
To best utilize ISpRecognizer::DisplayUI, the application should call ISpRecognizer::IsUISupported with a specific UI type before calling ISpRecognizer::DisplayUI.
Syntax
[local] HRESULT DisplayUI(
HWND hwndParent,
const WCHAR* pszTitle,
const WCHAR* pszTypeOfUI,
void* pvExtraData,
ULONG cbExtraData
);
Parameters
- hwndParent
[in] Handle to the parent window.
- pszTitle
[in] Pointer to a null-terminated string specifying the window title. Set this value to NULL to indicate that the SR engine should use its default window title for this UI type.
- pszTypeOfUI
[in] Pointer to a null-terminated string specifying the UI type information.
- pvExtraData
[in] Pointer to additional information for the call. The SR engine implementation dictates the format and use of the data provided.
- cbExtraData
[in] Size, in bytes, of the data indicated by pvExtraData. The SR engine implementation dictates the format and use of the data provided.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully. |
S_FALSE |
The UI is supported but not with the current run-time environment or parameters. |
FAILED(hr) |
Appropriate error message. |
Remarks
SAPI 5.0 SR engines are capable of sending UI requests to the application using the SPEI_REQUEST_UI event (SPEVENTENUM). Typical SR engine UI requests are for user training (SPDUI_UserTraining), microphone training (SPDUI_MicTraining), and lexicon updates (SPDUI_AddRemoveWord).
An application can call ISpRecognizer::DisplayUI at any time, and does not necessarily have to wait for a UI request from the SR engine. For example, if the SR engine is receiving a poor audio input signal, it can ask for microphone training. The application can receive these requests by calling ISpEventSource::SetInterest with the SPEI_REQUEST_UI event specified. When the UI request is received, the application can call ISpRecognizer::DisplayUI at an appropriate point to satisfy the SR engine requirement.
Example
The following code snippet illustrates the use of this method to request the user training UI.
HRESULT hr = S_OK;
// display user training UI for the current recognizer
hr = cpRecognizer->DisplayUI(MY_HWND, MY_APP_USER_TRAINING, SPDUI_UserTraining,
NULL, NULL);
// Check hr
Requirements
| Header | sapi.h, sapi.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |