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


 

Comments (0)