A Tour through TSF: Contexts and Ranges

Our next stop on our tour through TSF brings us to the two most heavily used interfaces in text services:  Contexts and Ranges.  But first, a quick diversion to discuss the relationship between threads, documents, and contexts.

The ITfThreadMgr object is the primary object implemented by TSF.  TSF ensures that no more than one ITfThreadMgr object exists in each thread.   The ITfThreadMgr object manages documents, text services, and handles focus changes between documents.

The ITfDocumentMgr object represents a logical document.  It isn't heavily used, though; its primary purpose is to be a container for edit contexts.  There is usually only one context in the document manager, although sometimes there can be two.

The ITfContext object represents a view of the document that you can interact with; it manages selections, properties, & ranges.

Contexts

A context represents a view of the document that a text service can interact with.

Interface	How to Obtain
ITfContext	Varies widely.  Common examples: ITfDocumentMgr::GetTop() ITfDocumentMgr::CreateContext()
ITfContextView	ITfContext::GetActiveView
ITfContextComposition	QI on ITfContext
ITfContextOwnerCompositionServices	QI on ITfContext
ITfContextOwnerServices	QI on ITfContext
ITfInsertAtSelection	QI on ITfContext
ITfMouseTracker	QI on ITfContext
ITfQueryEmbedded	QI on ITfContext
ITfComposition	ITfContextComposition::StartComposition
ITfCompositionView	Passed to any of: ITfContextOwnerCompositionSink::OnStartComposition ITfContextOwnerCompositionSink::OnUpdateComposition ITfContextOwnerCompositionSink::OnEndComposition

Once you have a context (and usually an edit cookie - most of the things you can do with contexts can only be done from within edit sessions), you can start to manipulate the document. 

Ranges

These interfaces deal with pieces of text within a logical document.

Interface	How to Obtain
ITfRange	Varies widely;  common instances are: ITfContext::GetSelection
ITfRangeACP	QI on ITfRange
ITfRangeBackup	ITfContext::CreateRangeBackup