ITfDocumentMgr::Push method (msctf.h)

Adds a context to the top of the context stack.

Syntax

HRESULT Push(
  [in] ITfContext *pic
);

Parameters

[in] pic

Pointer to the ITfContext object to be added to the stack. This object is obtained from a previous call to ITfDocumentMgr::CreateContext.

Return value

This method can return one of these values.

Value Description
S_OK
The method was successful.
E_INVALIDARG
pic is invalid.
TF_E_STACKFULL
No space exists on the stack for the context. The context stack has a limit of two contexts.
E_UNEXPECTED
This method was called during an ITfDocumentMgr::Pop call.

Remarks

The first context added to the stack becomes the main document context.

The TSF manager and text services only interact with the context at the top of the stack. Normally, only the main document context is on the stack. Occasionally, it is necessary to add a second context to the stack. For example, when a text service must display a modal UI, such as a candidate list. During this time, the text service will add its context to the stack. When the text service UI is no longer required, the text service removes the context from the stack. The main context then returns to the top of the stack. To simplify this process and prevent multiple modal UIs from being displayed, there is a maximum of two contexts allowed on the stack.

This method causes the ITfThreadMgrEventSink::OnPushContext method of all installed thread manager event sinks to be called. If this is the first context to be added to the stack, this method causes the ITfThreadMgrEventSink::OnInitDocumentMgr method of all installed thread manager event sinks to be called.

ITfDocumentMgr::Pop must be called to remove this context from the context stack.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server Windows 2000 Server [desktop apps | UWP apps]
Target Platform Windows
Header msctf.h
DLL Msctf.dll
Redistributable TSF 1.0 on Windows 2000 Professional

See also

ITfContext

ITfDocumentMgr

ITfDocumentMgr::CreateContext

ITfDocumentMgr::Pop

ITfThreadMgrEventSink::OnInitDocumentMgr

ITfThreadMgrEventSink::OnPushContext