ISpVoice::DisplayUI (SAPI 5.3)

Microsoft Speech API 5.3

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

S_OK

S_FALSE

E_INVALIDARG

FAILED(hr)

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 using SPDUI_EngineProperties.

  
// 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.
}