Microsoft Speech Platform

---

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