SPDUI_EngineProperties
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
This variable defines the string for displaying the UI for changing TTS or SR engine's properties on a per-user basis.
It is not a SAPI 5 compliance requirement for a speech engine to implement 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, the users can settings that should affect all their recognition profiles, but be specific to each user. For example, the Microsoft Text-To-Speech Engine exposes some inverse-text-normalization (ITN) rules (for example, comma versus period number delimiter, date format) in their engine properties.
Use the Speech Control Panel to change settings for all installed SAPI 5-compliant Text-To-Speech and Speech Recognition Engines. Choose 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), then the Settings button will be unavailable.
When to Access
The application could display a button or menu item for advanced engine properties that accessed SPDUI_EngineProperties (see ISpVoice::DisplayUI). Users should be informed that 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.
HRESULT hr = S_OK;
// get the default text-to-speech engine token
hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpObjectToken);
// Check hr
// get the object token's UI
hr = cpObjectToken->QueryInterface(&cpTokenUI);
// Check hr
// check if the default text-to-speech engine has UI for its properties
hr = cpTokenUI->IsUISupported(SPDUI_EngineProperties, NULL, NULL, NULL, &fSupported);
// Check hr
// if fSupported == TRUE, then default speech text-to-speech engine has UI for its properties
The following code snippet illustrates the use of ISpVoice::DisplayUI using SPDUI_EngineProperties.
HRESULT hr = S_OK;
// display engine properties UI for the current TTS engine
hr = cpVoice->DisplayUI(MY_HWND, MY_APP_VOICE_PROPERTIES, SPDUI_EngineProperties, NULL, NULL);
// Check hr