Text Services: Candidates


If your text service supports multiple interpretations of the same input, and you wish to allow users to correct the initial interpretation (for dictation, we call this ‘correction’; IMEs tend to call it ‘reconversion’), your text service will need to implement these interfaces.  Your service will also need to implement ITfFnReconversion (so that applications can get these interfaces), and ITfFunctionProvider (so that applications can get the ITfFnReconversion interface).

















Interface


How Obtained


ITfCandidateList


Returned from ITfFnReconversion::GetReconversion


ITfCandidateString


Returned from ITfCandidateList::GetCandidate


IEnumTfCandidates


Returned from ITfCandidateList::EnumCandidates


There is a sample text service that implements candidates available on MSDN.

Comments (6)

  1. Kirby Zhou says:

    Unfortunately, The sample from MSDN does not implement ITfCandidateList nor any interface related to Candiate.

    Anyone can tell me how to implement candidate feature correctly?

  2. Eric C Brown says:

    I originally thought that the MSDN sample implemented candidate lists, but on further inspection, it doesn’t; the sample manages the UI itself.   ITfCandidateList is used when the application (or another text service) wants to manage the candidate UI.

    ITfCandidateList isn’t that hard to implement yourself; it’s just a logical array of candidate strings.  You’ll need to implement a standard COM enumerator on the array; ATL has a stock implementation that will work well.  

    The other methods are pretty straightforward, with the possible exception of SetResult – that method simply needs to replace the old text with the new text.  You’ll need to schedule an edit session to do the work, of course.

    Unfortunately, I can’t show you my implementation of ITfCandidateList for copyright reasons, but I assure you that it’s really quite straightforward.

  3. Kirby Zhou says:

    En, In my opinion, there is no difficult to implement ITfCandidateList itself, but only a litte information about how to make it works with other parts of TIP.

    For instance, If I captured "space key" in my OnKeyDown method and want to create a ITfCandidateList. How can I connect the ITfCandidateList to my TIP? The only information from MSDN is ITfFnReconversion::GetReconversion. ITfFnReconversion::GetReconversion provides an argument "range", I donot know how the range arugment should be used with my candidate list and how to notify the System my candidate list created or changed.

  4. Eric C Brown says:

    I understand your question, Kirby, and I’m going to answer it more completely in a separate post, as it needs more detail than can comfortably fit in this comment.

    The short answer is that GetReconversion should create a candidate list based on the range.  

    For example, the speech text service creates a candidate list based on the acoustic data associated with the range.  

    Where does the data come from?  It’s stored as a text property, again associated with the range.

    How can I get that data?  Well, like anything else in TSF, you create an edit session.  Luckily, GetReconversion is one of the few places you can create a synchronous edit session, so that simplifies things immensely.

  5. TSF Aware says:

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

  6. Allan asks via the Contact link: Hi, Michael; Thanks for a great blog; it’s the most insightfull (and