ISpObjectToken::DisplayUI (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

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.

Syntax

[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 Value

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

Header	sapi.h, sapi.idl
Library	sapilib.lib
Windows Embedded CE	Windows CE .NET 4.1 and later

Share via