Microsoft Speech SDK SAPI 5.1

---

ISpObjectToken::DisplayUI

ISpObjectToken::DisplayUI displays the user interface (UI) associated with the object.

[local] HRESULT DisplayUI(
   HWND           hwndParent,
   const WCHAR   *pszTitle,
   const WCHAR    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	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. 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 SPGUID_EngineProperties.

    HRESULT hr = S_OK;

    // get the default text-to-speech engine object token
    hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpObjectToken);
    // Check hr

    // create the engine object based on the object token
    hr = SpCreateObjectFromToken(cpObjectToken, &cpVoice);
    // Check hr

    // create a data key for the voice's UI objects
    hr = cpObjectToken->OpenKey(L"UI", &cpUIDataKey);
    // Check hr

    // create a data key for the specific Engine Properties UI
    hr = cpUIDataKey->OpenKey(SPDUI_EngineProperties, &cpEngPropsDataKey);
    // Check hr

    // get the GUID for the voice's engine properties UI
    hr = cpEngPropsDataKey->GetStringValue(L"CLSID", &pwszEngPropsCLSID);
    // Check hr

    // convert GUID string to pure GUID
    hr = CLSIDFromString(pwszEngPropsCLSID, &clsidEngProps);
    // Check hr

    // check if the default voice object has UI for Properties
    hr = cpObjectToken->DisplayUI(MY_HWND, MY_APP_VOICE_PROPERTIES, &clsidEngProps, NULL, NULL, cpVoice);
    // Check hr