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.

    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