ISpRecoGrammar::SetTextSelection (SAPI 5.3)

Microsoft Speech API 5.3

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

S_OK

E_INVALIDARG

FAILED(hr)

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.

  
// Declare local identifiers:
HRESULT                      hr = S_OK;
CComPtr<ISpRecoContext>      cpRecoContext;
CComPtr<ISpRecoGrammar>      cpRecoGrammar;
SPTEXTSELECTIONINFO          tsi;
DWORD                        cch = 0;
WCHAR                        *pwszCoMem = L"";
WCHAR                        *pwszCoMem2;

// Place the contents of text buffer into pwszCoMem
// and the length of the text into cch:
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);
}

if (SUCCEEDED(hr))
{
   // Set the text selection information.
   hr = cpRecoGrammar->SetTextSelection(&tsi;);
}

if (SUCCEEDED(hr))
{
   // The SR engine is now capable of recognizing
   // the contents of the text buffer.
}

// Release system resources:
CoTaskMemFree(pwszCoMem2);
CoTaskMemFree(pwszCoMem);