SPDUI_EngineProperties (SAPI 5.3)

Article
04/17/2012

Microsoft Speech API 5.3

SPDUI_EngineProperties (C/C++)

SpeechEngineProperties (Automation)

SPDUI_EngineProperties defines the string for displaying the UI for changing text-to-speech (TTS) or speech recognition (SR) engine properties on a per-user basis.

It is not a SAPI 5 compliance requirement for a speech engine to implement this UI for SPDUI_EngineProperties.

The Microsoft SR engine that ships in the SAPI 5 SDK does not support SPDUI_EngineProperties.

When to Implement

When writing a speech engine for the desktop or a graphical environment, users can change settings that should affect all of their recognition profiles, but be specific to each user. For example, the Microsoft TTS engine exposes some inverse-text-normalization (ITN) rules (e.g., comma versus period number delimiter, date format) in their engine properties.

Use Speech properties in Control Panel to change settings for all installed SAPI 5-compliant TTS and SR engines. Click Settings to change settings on a per-user/per-engine basis. Use Settings to directly accesses each Engine's Settings UI using SPDUI_EngineProperties. If the engine does not support the Engine Properties UI (see ISpTokenUI::IsUISupported), Settings will be unavailable.

When to Access

For advanced engine properties, the application could display a button or menu item that accessed SPDUI_EngineProperties (see ISpVoice::DisplayUI). Changes made within the engine properties UI will affect only one engine, and will not affect other users.

  
#define SPDUI_EngineProperties        L"EngineProperties"

Example

The following code snippet illustrates the use of ISpTokenUI::IsUISupported using SPDUI_EngineProperties.

  
// Declare local identifiers:
HRESULT                    hr = S_OK;
CComPtr<ISpObjectToken>    cpObjectToken;
CComPtr<ISpTokenUI>        cpTokenUI;
BOOL                       fSupported;

// Get the default text-to-speech engine token.
hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpObjectToken;);

if (SUCCEEDED(hr))
{
   // Get the object token's UI.
   hr = cpObjectToken->QueryInterface(&cpTokenUI;);
}

// Check if the default text-to-speech engine has UI for its properties.
hr = cpTokenUI->IsUISupported(SPDUI_EngineProperties, NULL, NULL, NULL, &fSupported;);

if (SUCCEEDED(hr))
{
   // If fSupported = TRUE, then default text-to-speech
   // engine has UI for its properties.
}

The following code snippet illustrates the use of ISpVoice::DisplayUI using SPDUI_EngineProperties.

  
// Declare local identifiers:
HRESULT              hr = S_OK;
CComPtr<ISpVoice>    cpVoice;
HWND                 hwndParent;

// Display engine properties UI for the current TTS engine.
hr = cpVoice->DisplayUI(hwndParent, L"My App's Caption", SPDUI_EngineProperties, NULL, NULL);

if (SUCCEEDED(hr))
{
   // Do stuff here.
}

Share via