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 );
[in] Handle to the parent window.
[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.
[in] Pointer to a null-terminated string specifying the UI type information.
[in] Pointer to additional information for the call. The SR engine implementation dictates the format and use of the data provided.
[in] Size, in bytes, of the data indicated by pvExtraData. The SR engine implementation dictates the format and use of the data provided.
The following table shows the possible return values.
|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.|
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.
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
OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.
Last updated on Saturday, April 10, 2004
© 1992-2003 Microsoft Corporation. All rights reserved.