ISpRecognizer::DisplayUI

Article
06/30/2006

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.

 [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 Values

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

OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.