ISpObjectToken::DisplayUI
ISpObjectToken::DisplayUI displays the user interface (UI) associated with the object.
[local] HRESULT DisplayUI(
HWND hwndParent,
LPCWSTR *pszTitle,
LPCWSTR pszTypeOfUI,
void *pvExtraData,
ULONG cbExtraData,
IUnknown *punkObject
);
Parameters
- hwndParent
- [in] Specifies the handle of the parent window.
- pszTitle
- [in] Address of a null-terminated string containing the window title.
- pszTypeOfUI
- [in] Address of the null-terminated string containing the UI type that is being queried. Must be a SPDUI_xxx type.
- pvExtraData
- [in] Pointer to additional information needed for the object.
- cbExtraData
- [in] Size, in bytes, of the ExtraData. See Remarks section.
- punkObject
- [in] Address of the IUnknown interface pointer. See Remarks section.
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
pvExtraData and punkObject Parameters: When requesting an ISpObjectToken to display a particular piece of UI, the UI object may require extra functionality. Common implementation practice for accessing this functionality is to QueryInterface from a known IUnknown interface. For example, asking to display Speech Recognition Training UI requires the use of a specific SR engine.
The best practice for using ISpObjectToken::DisplayUI is to call ISpObjectToken::IsUISupported with a specific UI type before calling DisplayUI.
The call to DisplayUI is synchronous and the call will not return until the UI has been closed.
Example
The following code snippet illustrates the use of ISpObjectToken::DisplayUI.
// Declare local identifiers:
HRESULT hr = S_OK;
CComPtr<ISpObjectToken> cpObjectToken;
CComPtr<ISpVoice> cpVoice;
BOOL fSupported;
HWND hwndParent;
// Get the default text-to-speech engine object token.
hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpObjectToken;);
if (SUCCEEDED(hr))
{
// Create the engine object based on the object token.
hr = SpCreateObjectFromToken(cpObjectToken, &cpVoice;);
}
if (SUCCEEDED(hr))
{
// Check if the default engine object has UI for Properties.
hr = cpObjectToken->IsUISupported(SPDUI_EngineProperties, NULL, NULL, cpVoice, &fSupported;);
}
if (SUCCEEDED(hr))
{
// If default engine object has UI for
// Engine Properties, display UI--
if (fSupported == TRUE)
{
hr = cpObjectToken->DisplayUI(hwndParent, L"My App's Caption", SPDUI_EngineProperties, NULL, NULL, cpVoice);
}
}
if (SUCCEEDED(hr))
{
// Do stuff here.
}