Edit

Text Stores

  • Article

Application Character Position (ACP)

An ACP is the location of a character, or characters, in a text stream that is expressed as the number of characters from the start of the text stream. Because the ACP model is zero-based, the first character in a text stream has an ACP of zero. For example:

Text Stream  H | e | l | l | o |   | W | o | r | l | d
ACP          0   1   2   3   4   5   6   7   8   9   10

A text store implements an object that supports the ITextStoreACP interface, which enables the text stream to be expressed in an ACP. The ITextStoreACP interface methods use the ACP range of the text stream to modify the text.

Anchor-Based Applications

The manager uses the ACP-based methods natively to manipulate text. However, an anchor-based approach is available for Microsoft Active Accessibility clients that support anchors, whereby the manager uses ITextStoreAnchor and ITextStoreAnchorSink methods to wrap the ITextStoreACP and ITextStoreACPSink methods.

Document Access Control

The text store controls access to the text stream by using document locks. To read or modify the text store, the manager must first install an advise sink that supports the ITextStoreACPSink interface by calling the ITextStoreACP::AdviseSink method and passing a pointer to an advise sink. The advise sink enables the manager to obtain a document locks on the text store and receive notifications when the text store is modified by something other than the manager, such as user input through the application. Advise sinks are discussed later in this topic.

How To Initialize the Text Store

An application initializes a text store by completing the following steps:

  1. Create a thread manager object based on the ITfThreadMgr interface by calling the CoCreateInstance function with a pointer to a thread manager object. The following is a code example of implementing a thread manager object.

    hr = CoCreateInstance (CLSID_TF_ThreadMgr, NULL, CLSCTX_INPROC_SERVER, 
                        IID_ITfThreadMgr, (void**)&pThreadMgr);

  2. Activate the thread manager object by calling the ITfThreadMgr::Activate method. This method supplies a pointer to a client identifier used to create a context object. The thread manager is used to implement a document manager object.

  3. Create a document manager object based on the ITfDocumentMgr interface by calling the ITfThreadMgr::CreateDocumentMgr method with a pointer to the document manager object. The document manager object is used to implement a context object that is the text store.

  4. Create a context object from the document manager by calling the ITfDocumentMgr::CreateContext method with the pointer to the text store object and a pointer to the client identifier from activating the thread manager. The following is an example of creating a context object:

    hr = pDocumentMgr->CreateContext(m_ClientID, 0, (ITextStoreACP*)this, 
                                &pContext, pEditCookie);

  5. Push the context object onto the stack with the ITfDocumentMgr::Push method. The following is an example of pushing the context object onto the stack:

    hr = pDocumentMgr->Push(pContext);

How To Modify the Text Store

The ITfDocumentMgr::Push method calls ITextStoreACP::AdviseSink with a pointer to the advise sink interface to install a new advise sink or modify an existing advise sink. The advise sink receives notifications when the text store is modified by something other than the manager, such as user input to the application. Applications must call the ITfThreadMgrEventSink::OnSetFocus method when the input method obtains the focus. Other notifications to the thread manager are provided by calling to the appropriate ITextStoreACPSink interface methods.

However, applications should not call the ITextStoreACPSink interface methods in response to ITextStoreACP interface methods. Applications should only call ITextStoreACPSink interface methods when the text store is modified by something other than the manager.

The contents of the text store can be modified with a temporary input state called a composition.

Anchors

Compositions

Document Locks

ITextStoreACPSink

ITextStoreACP

ITextStoreAnchor

ITextStoreAnchorSink

ITfDocumentMgr

ITfThreadMgr

ITfThreadMgrEventSink::OnSetFocus

TfClientId

Microsoft Active Accessibility