TSF Aware : Applications

Where are the TSF Samples?

Eric Brown — Wed, 22 Oct 2008 23:57:41 GMT

Many people have emailed me asking about the TSF samples on MSDN. They’re supposed to be on MSDN code gallery, although they don’t appear to be there.

They are, however, part of the Windows SDK. After installation, you'll find them in %programfiles%\Microsoft SDKs\Windows\v6.1\Samples\winui\Input\tsf.

There are actually more samples in the Windows SDK than were on MSDN, including some examples of how to write a text store, as well as how to interact with TSF in UILess mode.

Things the Documentation left out, part N

Eric Brown — Sat, 22 Dec 2007 18:00:00 GMT

I recently had two people ask me the same question:

"Why can't I insert more than one character into a composition on Notepad?"

It's actually a bit more complicated than that, since this behavior only appears to happen on Windows XP with a US English text service. (Japanese text services appear to work correctly.)

I just had a chance to figure out what was going on here, and, since it doesn't seem to be documented anywhere else, I thought I'd post the answer so that the next poor sod doesn't have to spend eternity scratching his head wondering why he can't get it to work.

After a longish debugging bout, and a bunch of searching through the XP source code, I have the answer.

The answer is that there's a Text Event Sink attached to the TSF-unaware context, and when the context changes, this event sink looks to see if the changed text has the GUID_PROP_COMPOSING property attached to it. If it doesn't, it terminates the composition.

So, if you want to have your text services insert more than one character into a composition, you need to make sure that your text has the GUID_PROP_COMPOSING property set to 1.

I had previously written some code to manage this property. However, you cannot explicitly set the GUID_PROP_COMPOSING property -

ITfProperty::SetValue() will return TF_E_READONLY if you do.

What you do need to do is use the ITfComposition::ShiftStart and ITfComposition::ShiftEnd methods to move the start and ending points of your composition to cover the text. These methods will update the GUID_PROP_COMPOSING property directly.

~~The code to do that would look like this:~~

BOOL CTextService::_SetCompositionComposing(TfEditCookie ec, ITfContext *pContext)
{
    ITfRange *pRangeComposition;
    ITfProperty *pComposingProperty;
    HRESULT hr;

    // the composition requires a range and the context it lives in
    if (_pComposition->GetRange(&pRangeComposition) != S_OK)
        return FALSE;

~~hr = E_FAIL;~~

    // get our the display attribute property
    if (pContext->GetProperty(GUID_PROP_COMPOSING, &pComposingProperty) == S_OK)
    {
        VARIANT var;
        // set the value over the range
        var.vt = VT_I4;
        var.lVal = 1;

~~hr = pComposingProperty->SetValue(ec, pRangeComposition, &var);~~

pComposingProperty->Release();
}

pRangeComposition->Release();
return (hr == S_OK);
}

~~When you're ready to finalize your composition, you should clear the property over the composed text by calling ITfProperty::Clear().~~

Note that none of the sample text services do this.

Oops!

Eric Brown — Wed, 14 Nov 2007 21:01:48 GMT

If you've tried to use the modified version of Scintilla that I described in my MSDN article, you will find that the zipped sources don't actually have the changes that I made. That was my fault; when I was packaging the sources, I had two versions of ScintillaWin.cxx around, and I picked the newer one, which (sigh) was the wrong one. Anyway, here's a link to the correct version of ScintillaWin.cxx with TSF support.

Input Scopes

Eric Brown — Tue, 10 Jul 2007 17:00:00 GMT

Another useful, but underutilized, group of functions in TSF are those relating to Input Scopes. Input Scopes allow an application to define the sorts of things that are expected in this document (edit control, etc.). For example, the Internet Explorer 7 address bar has an input scope of IS_URL | IS_DEFAULT | IS_ENUMSTRING - meaning that the address bar expects the input to be either a URL, one of the entries in its enumeration, or just plain anything (IE will default to searching for the string you typed).

Input scopes were originally created for the Tablet PC, and a lot of the MSDN documentation is specifically related to the Tablet PC. However, other input handlers (for example, speech) use input scopes as well to improve recognition. For example, Windows Speech Recognition has a custom URL language model that is used when a control specifies the IS_URL input scope. This significantly improves recognitions on URLs that are part of the language model.

The functions are very easy to use, if you have an hwnd for your control. If you only want to set a single input scope (for example, IS_DIGITS for a numeric control), then SetInputScope is the function for you. If you want to set multiple input scopes, or you want to use one of the more exotic input scopes like IS_PHRASELIST or IS_REGULAREXPRESSION (which return application-defined strings), then you will want to use SetInputScopes, which allows you to pass an array of input scopes, along with other data. Finally, Windows Vista adds SetInputScopes2, which is a variant of the SetInputScopes function, but which takes a string enumerator object instead of an array of strings.

One thing to take note is that if you call SetInputScope (or one of its siblings), you need to call SetInputScope(hwnd, IS_DEFAULT) before the window is destroyed. MSDN mentions this in the remarks; I want to emphasize it.

If your control doesn't have an hwnd, or if you want to have multiple input scopes per document, the situation is a bit more complicated. MSDN isn't very clear about how to make input scopes work in TSF-aware applications. In the description of the ITfInputScope interface, MSDN says

A TSF-aware application does not call SetInputScope directly, but rather implements either ITextStoreACP or ITfContextOwner to get a pointer to ITfInputScope.

What this bit means is that TSF-aware applications need to implement input scopes via an application property. In particular, you need to implement ITextStoreACP::RequestSupportedAttrs, and ITextStoreACP::RetrieveRequestedAttrs. If you want to have multiple input scopes per document, then you also need to implement ITextStoreACP::RequestAttrsAtPosition. Note that the documentation refers to TS_ATTRIDs; these are typedefs for GUIDs! The TS_ATTRID that you need to support for input scopes is GUID_PROP_INPUTSCOPE (you may, of course, add support for other TS_ATTRIDs).

Retrieving input scopes is fairly straightforward. MSDN has a nice code snippet describing how to retrieve the ITfInputScope interface here; once you have it, use ITfInputScope::GetInputScopes to retrieve the list of input scopes, and the other methods return auxiliary data for exotic input scopes.

If you need the string enumerator (i.e., you want to support IS_ENUMSTRING), then you need to get the ITfInputScope2 interface, instead of ITfInputScope; all you need to do is QI the application property for IID_ITfInputScope2 instead of IID_ITfInputScope. The MSDN documentation for ITfInputScope2 is incorrect; ITfInputScope2 extends ITfInputScope, not IUnknown (and it's only available on Windows Vista).

The Input Scope enumerations are defined here.

How do I use RichEdit 4.1?

Eric Brown — Thu, 14 Jun 2007 21:18:56 GMT

Another thing I didn't talk about in my article was how to make sure your rich text edit controls are based on RichEdit 4.1 (which has TSF support).

You need to do two things:

1) change your window class name from RICHEDIT_CLASS to MSFTEDIT_CLASS, and

2) LoadLibrary("msftedit.dll") instead of LoadLibrary("richedit.dll").

That's it!

Easy Dictation support for Windowless RichEdit controls

Eric Brown — Tue, 12 Jun 2007 17:00:00 GMT

In my article in MSDN, I mention that there are some easy ways to enable dictation support in controls that don't normally support dictation. All the methods I described assume that the control has a window. There is a way to enable dictation support for windowless rich text edit controls, assuming that you are using the RichEdit 4.1 implementation of ITextServices.

I did not include this method in my article because I didn't want to include all the details about ITextServices, how you get an instance, and so forth. I assume that if you already have an existing windowless rich edit control that uses ITextServices, you already know all that. (If you don't, there's a quick primer available at CodeProject; note that I haven't actually used this code, and cannot vouch for it.)

Anyway, if you have an ITextServices interface pointer, then you can enable TSF support (and, by extension, dictation support), by calling ITextServices::TxSendMessage(EM_SETEDITSTYLE, SES_USECTF, SES_USECTF).

I hope that more richedit users will enable TSF support, so that users will have an easier time using dictation.

Published!

Eric Brown — Sat, 09 Jun 2007 21:01:00 GMT

You might have noticed that I haven't really talked about text stores on this blog. That's because I've been working on an article for MSDN Magazine on just that very subject. It's in the July 2007 issue, and I just got my copy in the mail, so if you're a subscriber, you can read all the gory details about how to add TSF support to your controls and applications, complete with a working example.

~~The article isn't currently available online yet - I'll add a link to the article as soon as it's available.~~

Update: The article is now online, and you can find it here.

Generating Candidates from an Application

Eric Brown — Fri, 25 May 2007 21:43:00 GMT

Kirby left a comment to my post on candidates asking when a text service should create an ITfCandidateList.

The answer is that when the text service wants to show candidates (via a preserved key or other mechanism), it should show its modal UI, and quite possibly may wish to push a new context so that the modal UI can be keyboard enabled (the sample does this).

The thing to note here is that ITfCandidateList is not involved here.

So when does the text service use ITfCandidateList? When the application wants to show candidates.

How does this work? Well, it's pretty complicated, but I'll try to outline the steps here. (Get ready, it's going to get a little wild...)

The big blocks

1) Application gets ITfFnReconversion interface.

2) Application gets target range (ITextStoreACPServices::CreateRange comes in very handy here).

3) Application calls ITfFnReconversion::QueryRange to transform the target range.

4) Application calls ITfFnReconversion::GetReconversion to get the list of candidates.

5) Application displays candidate list (e.g., in context menu, dialog, what have you).

6) Application calls ITfCandidateList::SetResult() when the selection is selected.

7) Application releases candidate list, reconversion interface, and does other cleanup.

Alternatively, if the application wants to let the text service manage the UI, it can call ITfFnReconversion::Reconvert at step 4 and step out of the way. (Note that not all text services implement this, as this function must not wait for the UI to be dismissed before returning.)

An excellent way to test this is with Microsoft Word. Word supports reconversion, and will show the candidates in the context menu when you right-click on a word.

Getting ITfFnReconversion

This is a two-step process. First, you get the system function provider, and then you get the reconversion pointer (error checking is omitted):

ITfFunctionProvider* ipProvider;

hr = ITfThreadMgr::GetFunctionProvider(GUID_SYSTEM_FUNCTIONPROVIDER, &ipProvider);

IUnknown* ipConv;

hr = ipProvider->GetFunction(GUID_NULL, IID_ITfFnReconversion, &ipConv);

ITfFnReconversion *ipConversion;

hr = ipConv->QueryInterface(IID_ITfFnReconversion, &ipConversion);

What should QueryRange do?

ITfFnReconversion::QueryRange needs to modify the range to cover the entire range of text contained by the conversion token. An example is useful here, as that last sentence didn't even make sense to me. The Speech text service does correction by words, and all words must be part of a single recognition.

Therefore, the Speech text services's implementation of QueryRange alters the range of text to contain entire words that are part of a single recognition.

If the range starts in the middle of a word with recognition data, QueryRange shifts the start of the range to the start of a word. If the range starts in text that doesn't have recognition data associated with it, it moves the start point to a point where it does have recognition data, or to the end of the initial range. If it runs off the end, it sets pfConvertable to FALSE, and returns NULL.

If it does find some recognition data for the start of the range, it adjusts the end of the range in the same manner.

But wait, you say. How can QueryRange do all that when it doesn't have an edit cookie? Well, it gets one in the usual manner - it (say it with me) schedules an edit session to do all that work. OK, you say, how can I get my data back from an asynchronous edit session? Well, you're in luck - you're guaranteed to be able to schedule a synchronous edit session from ITfFnReconversion::QueryRange.

What should GetReconversion do?

ITfFnReconversion::GetReconversion needs to compute the candidates from a target range (that should be aligned with a conversion token). Like QueryRange, most of the work will need to be done from an edit session, and also like QueryRange, you are guaranteed to be able to schedule a synchronous edit session from within GetReconversion. How you go about computing the candidates is discussed in my next post.

TSF Application interfaces

Eric Brown — Sat, 28 Apr 2007 01:36:00 GMT

The first stop on the TSF tour is the application interfaces. These are implemented by applications or text controls.

An application (or text control) must implement ITextStoreACP to be considered ‘TSF-aware'. It may choose to implement any of the other interfaces described in the table below. I also describe how TSF obtains an instance of each interface.

Interface	Optional?	How Obtained?
ITextStoreACP	No	Passed to ITfDocumentMgr::CreateContext
ITfInputScope	Yes	Returned from ITextStoreACP::RequestSupportedAttrs with GUID_PROP_INPUTSCOPE.
ITfInputScope2	Yes	QI from ITfInputScope
ITfPersistentPropertyLoaderACP	Yes	Passed to ITextStoreACPServices::Unserialize
ITfMouseTrackerACP	Yes	QI from ITextStoreACP
ITfContextOwnerCompositionSink	Yes	Passed to ITfDocumentMgr::CreateContext
ITfUIElementSink	Yes	Passed to ITfSource::AdviseSink (see below)

Note: I put ITfUIElementSink here because text services never implement this interface, even though it's an event sink (described in a future post). Full-screen applications (or games) would implement this interface if they wish to control the UI drawn by text services. (See the discussion of UILess mode in MSDN.)

Interface	When to implement
ITextStoreACP	Always implement this.
ITfInputScope	Consider implementing this. It's not hard, and some text services use it to improve recognition (e.g., Windows Speech Recognition knows about the URL input scope, and has special code for that).
ITfInputScope2	Implement this if you implemented ITfInputScope, and you need the extra functionality (string enumeration).
ITfPersistentPropertyLoaderACP	Implement this if you support asynchronous property loading. If you don't know what that means, you don't need to implement this.
ITfMouseTrackerACP	Implement this to help handwriting recognition (I believe that you must implement this to get gestures).
ITfContextOwnerCompositionSink	Implement this if you need control over compositions.
ITfUIElementSink	Only implement this if your application takes over the screen, and you still want IMEs to work inside your application. It's a fair amount of work to implement this.