ISpSREngine::SetTextSelection (SAPI 5.3)
ISpSREngine::SetTextSelection informs the engine of the displayed and selected areas of the text buffer.(See ISpSREngine::SetWordSequenceData). Once a text buffer has been supplied to the engine, this method can be used to control which parts of the buffer are active for recognition using a text-buffer transition in a CFG. This method can communicate to the engine the location of the current text insertion point for dictation.
HRESULT SetTextSelection( void *pvEngineGrammar, const SPTEXTSELECTIONINFO *pInfo );
- [in] The engine's grammar pointer for this grammar, as returned from a previous call to the OnCreateGrammar method.
- [in] Pointer to the text selection information structure.
|S_OK||Function completed successfully.|
|E_NOTIMPL||Engine does not support text-buffer functionality|
|FAILED(hr)||Other appropriate error message.|
The first two fields of the SPTEXTSELECTIONINFO structure, ulStartActiveOffset and cchActiveChars, indicate the area of the buffer that should be active for recognition when using a text-buffer transition in a CFG.
The other two fields of the SPTEXTSELECTIONINFO, ulStartSelection and cchSelection, can be used with dictation. These could indicate, for example, which area of the buffer is currently selected on the screen. If cchSelection is zero, this could display the current location of the insertion point. This can be used by the engine to get extra language model context from preceding words in the dictated text.
This text buffer feature is optional for engines, and support for it is indicated using the TextBuffer attribute. You need to check that the four fields of the SPTEXTSELECTIONINFO structure point to valid places in the current text buffer; this is not validated by SAPI. If this method is called on an engine that does not support this feature, the engine should return E_NOTIMPL.