Microsoft Speech SDK SAPI 5.1

---

ISpRecoGrammar::SetTextSelection

ISpRecoGrammar::SetTextSelection sets the current text selection and insertion point information.

HRESULT SetTextSelection(
   const   SPTEXTSELECTIONINFO  *pInfo
);

Parameters

pInfo

[in] Address of the SPTEXTSELECTIONINFO structure that contains the text selection and insertion point information.

Return values

Value	Description
S_OK	Function completed successfully.
E_INVALIDARG	One or more parameters are invalid.
FAILED(hr)	Appropriate error message.

Remarks

An application that has a text box could enable the user to speak commands into the text box to edit the text. One way to design this functionality would be to create a CFG which supports such commands as "cut the text *", "bold the text *", or "italicize the words *". The grammar would then use a TEXTBUFFER tag in place of the * which would enable the SR engine to recognize the text buffer information. At run time, the application would update the SR engine's view of the text buffer using ISpRecoGrammar::SetWordSequenceData. When the user highlights a selection of text and the text selection using ::SetTextSelection.

If a user had the text "hello world" in the text box and no text highlighted, the SR engine could recognize "bold the text world". If the user highlighted "hello", and the application changed the active text selection only contain "hello", "bold the text world" would fail to recognize.

The application should change the active text selection when the text highlight changes, rather than the entire word sequence data, to ensure the SR engine has a textual context to help the recognition language model.

See also ISpRecoGrammar::SetWordSequenceData for information on how to set the text data.

See also ISpSREngine::SetTextSelection for information on how SAPI passes the text selection information to the SR engine.

The SR engine must support text buffer features. Check for the presence of the TextBuffer attribute in the SR engine. Microsoft SR ASR engines support these features although there is no requirement that other manufacturers engines need to. See Recognizers in Object Tokens and Registry Settings for more information.

Example

The following code snippet illustrates how to use ISpRecoGrammar::SetTextSelection after sending a text buffer to the SR engine using ISpRecoGrammar::SetWordSequenceData.

        HRESULT hr = S_OK;

        // place the contents of text buffer into pwszCoMem and the length of the text in cch

        SPTEXTSELECTIONINFO tsi;
        tsi.ulStartActiveOffset = 0;
        tsi.cchActiveChars = cch;
        tsi.ulStartSelection = 0;
        tsi.cchSelection = cch;

        pwszCoMem2 = (WCHAR *)CoTaskMemAlloc(sizeof(WCHAR) * (cch + 2));

        if (SUCCEEDED(hr) && pwszCoMem2)
        {
            // SetWordSequenceData requires double NULL terminator.
            memcpy(pwszCoMem2, pwszCoMem, sizeof(WCHAR) * cch);
            pwszCoMem2[cch] = L'\0';
            pwszCoMem2[cch+1] = L'\0';

            // set the text buffer data
            hr = cpRecoGrammar->SetWordSequenceData(pwszCoMem2, cch + 2, NULL);
            // Check hr

            // set the text selection information
            hr = cpRecoGrammar->SetTextSelection(&tsi);
            // Check hr

            CoTaskMemFree(pwszCoMem2);
        }
        CoTaskMemFree(pwszCoMem);

        // the SR engine is now capable of recognizing the contents of the text buffer