Microsoft Speech Platform

---

ISpVoice::DisplayUI

ISpVoice::DisplayUI displays the UI from the underlying text-to-speech engine's object token.

[local] HRESULT DisplayUI(
    HWND           hwndParent,
    LPCWSTR       *pszTitle,
    LPCWSTR       *pszTypeOfUI,
    void          *pvExtraData,
    ULONG          cbExtraData
);

Parameters

hwndParent

[in] Specifies the parent window handle information.

pszTitle

[in] Address of a null-terminated string containing the window title information. Set this value to NULL to indicate that the TTS engine should use its default window title for this UI type.

pszTypeOfUI

[in] Address of the null-terminated string containing the requested UI type to display.

pvExtraData

[in] Pointer to additional information needed for the object. The TTS Engine implementer dictates the format and usage of the data provided.

cbExtraData

[in] Size, in bytes, of the ExtraData. The TTS Engine implementer dictates the format and usage of the data provided.

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 or more parameters are invalid.
FAILED(hr)	Appropriate error message.

Remarks

The best practice for using ISpVoice::DisplayUI is to call ISpVoice::IsUISupported with a specific UI type before calling DisplayUI.

See the TTS Engine White Paper for further information on how a TTS Engine should implement UI.

The call to DisplayUI is synchronous, so the call will not return until the UI has been closed.

Example

The following code snippet illustrates the use of ISpVoice::DisplayUI.

// Declare local identifiers:
HRESULT	             hr = S_OK;
CComPtr<ISpVoice>    cpVoice;
HWND                 hwndParent;

// Display properties UI for the current TTS engine.
hr = cpVoice->DisplayUI(hwndParent, L"My App's Caption", SPDUI_EngineProperties, NULL, NULL);

if (SUCCEEDED (hr))
{
   // Do some more stuff.
}