FreezeVirtualCaretPos method

Anchors the virtual caret's position at the current position of the real caret or virtual caret.

Syntax

HRESULT retVal = object.FreezeVirtualCaretPos(fReCompute);

Parameters

fReCompute [in]

Type: BOOL

TRUE

Recompute the virtual caret position from the current real position of the insertion point.

FALSE

Anchor the virtual caret location at its current value, whether it is defined or undefined.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The virtual caret tracks the "ideal" movement of the insertion point relative to some given starting point. In horizontal text, the virtual caret position is an X-coordinate value that is used to calculate left-right placement of the insertion point during up/down line movement. In vertical text, it is a Y-coordinate value that is used to calculate up-down placement of the insertion point during left/right line movement.

For example, suppose that you have three lines of text in a IHTMLElement3::contentEditable region—a long line, a short line and another long line—with the insertion point located near the end of the first line, as shown in the following diagram.

When the user presses the DOWN ARROW key, the visible insertion point moves to the end of the short line. There is also an invisible virtual caret located under the point where the caret was positioned in the first line.

When the user presses the DOWN ARROW key again, the real insertion point moves to the third line so that it is located (as nearly as possible) under the position that was occupied by the caret when it was in the first line—the position of the virtual caret. As the real insertion point moves from line to line, its visible position is always as close to the virtual caret position as possible.

The virtual caret position might be undefined, if there is no previous up/down movement. The MSHTML Editor resets the virtual caret position under various circumstances. For example, the virtual caret position resets when the user presses the LEFT ARROW key or the RIGHT ARROW key (for horizontal text), or when the user moves the insertion point to a new location with the mouse.

When IHTMLEditServices2::FreezeVirtualCaretPos is called, the MSHTML Editor does not reset the virtual caret position (which is standard behavior) until the virtual caret position is released by a call to IHTMLEditServices2::UnFreezeVirtualCaretPos.