ISpObjectToken::DisplayUI (SAPI 5.4)

Article
08/26/2009

Microsoft Speech API 5.4

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. Set this value to NULL to indicate that the ISpTokenUI object should use its default 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. The ISp TokenUI object implementer dictates the format and usage of the data provided.
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

S_OK

S_FALSE

E_INVALIDARG

SPERR_UNINITIALIZED

SPERR_TOKEN_DELETED

FAILED(hr)

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

Example

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

Partager via