A Tour through TSF: Event sinks

The interfaces in this category allow you to be called back when certain events happen on another interface.  These callbacks are generally referred to as 'event sinks'.

Interface	How to Obtain
ITfSource	QI on ITfThreadMgr, ITfContext, ITfCompartment, ITfInputProcessorProfiles, ITfDocumentMgr, or ITfLangBarItem
ITfSourceSingle	QI on ITfThreadMgr or ITfContext

Event Sinks

TSF can call your application or text service back when certain events occur.  Many event sinks are installed by a two-step process:

• 1) Call QueryInterface() on a host interface (described in the table) for ITfSource;
• 2) Call ITfSource::AdviseSink() with the target interface IID and the target interface pointer.

 You will get back a cookie that you will need to pass back to ITfSource::UnadviseSink() when it's time to detach from the event source (e.g., when the host or target object is about to be destroyed, or the text service is uninitializing).

Your application or text service must implement the target interface; these interfaces are typically implemented on the main object (i.e., the object that implements either ITextStoreACP or ITfTextInputProcessor for applications or text services, respectively).

Target Interface	Hosting Interface
ITfActiveLanguageProfileNotifySink	ITfThreadMgr
ITfCompartmentEventSink	ITfCompartment
ITfContextKeyEventSink	ITfContext
ITfDisplayAttributeNotifySink	ITfThreadMgr
ITfEditTransactionSink	ITfContext
ITfKeyTraceEventSink	ITfThreadMgr
ITfLangBarItemSink	ITfLangBarItem
ITfLanguageProfileNotifySink	ITfInputProcessorProfiles
ITfPreservedKeyNotifySink	ITfThreadMgr
ITfStatusSink	ITfContext
ITfSystemLangBarItemSink	ITfLangBarItem
ITfTextEditSink	ITfContext
ITfTextLayoutSink	ITfContext
ITfThreadFocusSink	ITfThreadMgr
ITfThreadMgrEventSink	ITfThreadMgr
ITfTransitoryExtensionSink	ITfDocumentMgr
ITfUIElementSink	ITfUIElementMgr

Single sinks

Some event sources can only have a single sink attached.  Attaching an single event sink is similar to installing a regular event sink, except that you QueryInterface() for ITfSourceSingle instead of ITfSource; one then attaches the sink by calling ITfSourceSingle::AdviseSingleSink().

Interface	Hosting Interface
ITfCleanupContextSink	ITfContext
ITfCleanupContextDurationSink	ITfThreadMgr

Specialized Sinks

Some event sinks are attached by calling specific methods.  The following table describes the installation method for these sinks:

Interface	Installation Method
ITfMouseSink	ITfMouseTracker::AdviseMouseSink
ITfCompositionSink	ITfContextComposition::StartComposition
ITfLangBarEventSink	ITfLangBarMgr::AdviseEventSink
ITfKeyEventSink	ITfKeystrokeMgr::AdviseKeyEventSink