ISpObjectToken::DisplayUI (Windows CE 5.0)
This method displays the UI associated with the object. The best practice for using this method is to call ISpObjectToken::IsUISupported with a specific UI type before calling ISpObjectToken::DisplayUI. Ultimately, use of this practice is similar to creating an ISpTokenUI object and calling ISpTokenUI::DisplayUI.
A call to ISpObjectToken::DisplayUI is synchronous. Thus the method will not return until the UI has been closed.
[local] HRESULT DisplayUI( HWND hwndParent, const WCHAR* pszTitle, const WCHAR pszTypeOfUI, void* pvExtraData, ULONG cbExtraData, IUnknown* punkObject);
Parameters
- hwndParent
[in] Handle of the parent window. - pszTitle
[in] Pointer to a null-terminated string specifying the window title. Set this value to NULL to indicate that the ISpTokenUI object should use its default window title. - pszTypeOfUI
[in] Pointer to a null-terminated string specifying the UI type to query. Must be a SPDUI_xxx type. - pvExtraData
[in] Pointer to additional information needed for the object. The object implementing ISpTokenUI dictates the format and use of the data provided. - cbExtraData
[in] Size, in bytes, of cbExtraData. See Remarks section. - punkObject
[in] Pointer to the IUnknown interface. See Remarks section.
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. |
| E_INVALIDARG | One of the parameters is invalid or bad. |
| SPERR_UNINITIALIZED | Either the data key or token delegate interface is not initialized. |
| SPERR_TOKEN_DELETED | Key has been deleted. |
| FAILED(hr) | Appropriate error message. |
Remarks
When asking an ISpObjectToken to display a particular piece of UI, the UI object may require extra functionality that only it understands. Common implementation practice for accessing this functionality is to call QueryInterface on a known IUnknown interface. The caller of ISpTokenUI::DisplayUI can set the punkObject parameter with a pointer to the necessary IUnknown interface. For example, asking to display Speech Recognition Training UI (see SPDUI_UserTraining) requires use of a specific SR engine.
Example
The following code snippet illustrates the use of this method using SPGUID_EngineProperties.
HRESULT hr = S_OK;
// get the default text-to-speech engine object token
hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpObjectToken);
// Check hr
// create the engine object based on the object token
hr = SpCreateObjectFromToken(cpObjectToken, &cpVoice);
// Check hr
// create a data key for the voice's UI objects
hr = cpObjectToken->OpenKey(L"UI", &cpUIDataKey);
// Check hr
// create a data key for the specific Engine Properties UI
hr = cpUIDataKey->OpenKey(SPDUI_EngineProperties, &cpEngPropsDataKey);
// Check hr
// get the GUID for the voice's engine properties UI
hr = cpEngPropsDataKey->GetStringValue(L"CLSID", &pwszEngPropsCLSID);
// Check hr
// convert GUID string to pure GUID
hr = CLSIDFromString(pwszEngPropsCLSID, &clsidEngProps);
// Check hr
// check if the default voice object has UI for Properties
hr = cpObjectToken->DisplayUI(MY_HWND, MY_APP_VOICE_PROPERTIES, &clsidEngProps, NULL, NULL, cpVoice);
// Check hr
Requirements
OS Versions: Windows CE .NET 4.1 and later.
Header: sapi.h, sapi.idl.
Link Library: Sapilib.lib.
See Also
ISpObjectToken | SAPI Interfaces
Send Feedback on this topic to the authors