ISpObjectToken::DisplayUI (SAPI 5.4)

Speech API 5.4
Microsoft Speech API 5.4


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


[in] Specifies the handle of the parent window.
[in] Address of a null-terminated string containing the window title. Set this value to NULL to indicate that the ISpTokenUI object should use its default window title.
[in] Address of the null-terminated string containing the UI type that is being queried. Must be a SPDUI_xxx type.
[in] Pointer to additional information needed for the object. The ISp TokenUI object implementer dictates the format and usage of the data provided.
[in] Size, in bytes, of the ExtraData. See Remarks section.
[in] Address of the IUnknown interface pointer. See Remarks section.

Return values

S_OKFunction completed successfully.
S_FALSEThe UI is supported but not with the current run-time environment or parameters.
E_INVALIDARGOne of the parameters is invalid or bad.
SPERR_UNINITIALIZEDEither the data key or token delegate interface is not initialized.
SPERR_TOKEN_DELETEDKey has been deleted.
FAILED(hr)Appropriate error message.


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. The caller of ISpTokenUI::DisplayUI can set the punkObject parameter with the necessary IUnknown interface. For example, asking to display Speech Recognition Training UI (see SPDUI_UserTraining) 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. Ultimately, ISpObjectToken::DisplayUI is similar to creating an ISpTokenUI object and calling ISpTokenUI::DisplayUI

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


The following code snippet illustrates the use of ISpObjectToken::DisplayUI using SPDUI_EngineProperties.

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