ISpObjectToken::DisplayUI

Article
06/30/2006

This method displays the UI associated with the object. The best practice for using this method is to call ISpObjectToken::IsUISupported with a specific UI type before calling ISpObjectToken::DisplayUI. Ultimately, use of this practice is similar to creating an ISpTokenUI object and calling ISpTokenUI::DisplayUI.

A call to ISpObjectToken::DisplayUI is synchronous. Thus the method will not return until the UI has been closed.

[local] HRESULT DisplayUI(
  HWND hwndParent,
  const WCHAR* pszTitle,
  const WCHAR pszTypeOfUI,
  void* pvExtraData,
  ULONG cbExtraData,
  IUnknown* punkObject
);

Parameters

hwndParent
[in] Handle of the parent window.
pszTitle
[in] Pointer to a null-terminated string specifying the window title. Set this value to NULL to indicate that the ISpTokenUI object should use its default window title.
pszTypeOfUI
[in] Pointer to a null-terminated string specifying the UI type to query. Must be a SPDUI_xxx type.
pvExtraData
[in] Pointer to additional information needed for the object. The object implementing ISpTokenUI dictates the format and use of the data provided.
cbExtraData
[in] Size, in bytes, of cbExtraData. See Remarks section.
punkObject
[in] Pointer to the IUnknown interface. See Remarks section.

Return Values

The following table shows the possible 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

When asking an ISpObjectToken to display a particular piece of UI, the UI object may require extra functionality that only it understands. Common implementation practice for accessing this functionality is to call QueryInterface on a known IUnknown interface. The caller of ISpTokenUI::DisplayUI can set the punkObject parameter with a pointer to the necessary IUnknown interface. For example, asking to display Speech Recognition Training UI (see SPDUI_UserTraining) requires use of a specific SR engine.

Example

The following code snippet illustrates the use of this method 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

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: sapi.h, sapi.idl.
Link Library: Sapilib.lib.

Share via