Caret Service

The Caret Service exposes the caret-related operations of the WPF HTML Editor through the ICaretService interface. The service lets you query and move the caret programmatically, hide or show it, scroll it into view, and translate between editor-local pixel coordinates and the linear character index within the document body.

Reach the service via the Caret property of the WpfHtmlEditor control. All operations work against the document currently loaded into the editor; if the document has not finished loading the caret position is undefined and the methods are no-ops.

Indices returned by GetCaretIndex are zero-based offsets into the visible text content (no HTML markup). GetCaretIndexInHtml returns the offset within the raw HTML source instead, which is useful when you need to splice markup at the cursor.

SetCaretAt(int x, int y, bool scrollToView)

Places the caret at the editor-local pixel coordinates (x, y). The point is hit-tested against the rendered document; if it falls outside any text node the caret is moved to the nearest valid insertion point.

Syntax

void SetCaretAt(int x, int y, bool scrollToView);

Parameters

Example

// Drop the caret near the top-left of the editor and bring it on-screen.

MyEditor.Caret.SetCaretAt(50, 120, scrollToView: true);

MyEditor.Focus();

GetCaretPosition()

Returns the current caret position as a System.Drawing.Point expressed in editor-local pixel coordinates. The returned point identifies the top-left corner of the caret glyph.

Syntax

System.Drawing.Point GetCaretPosition();

Returns

Point — X and Y are pixel offsets relative to the editor surface.

Example

// Show the live caret position in the WPF status bar.

var pt = MyEditor.Caret.GetCaretPosition();

StatusText.Text = $"Caret at ({pt.X}, {pt.Y})";

SetCaretPosition(int x, int y, bool scrollToView)

Moves the caret to the specified editor-local pixel coordinates. Functionally equivalent to SetCaretAt; provided as a symmetric counterpart to GetCaretPosition.

Syntax

void SetCaretPosition(int x, int y, bool scrollToView);

Parameters

Example

// Round-trip a caret position across an HTML insertion.

var saved = MyEditor.Caret.GetCaretPosition();

MyEditor.AppendHtml("<b>mark</b>");

MyEditor.Caret.SetCaretPosition(saved.X, saved.Y, scrollToView: true);

Hide()

Hides the caret glyph without changing its logical position. Typing or programmatic insertion still occur at the hidden caret position; call Show to make it visible again.

Syntax

void Hide();

Example

// Suppress caret flicker during a batch insert.

MyEditor.Caret.Hide();

foreach (var html in snippets)

    MyEditor.AppendHtml(html);

MyEditor.Caret.Show(scrollToView: true);

Show(bool scrollToView)

Restores the caret display after a prior call to Hide. When scrollToView is true the editor scrolls so the caret is on screen.

Syntax

void Show(bool scrollToView);

Parameters

Example

// Show the caret again after a long programmatic edit.

MyEditor.Caret.Show(scrollToView: true);

ScrollToCaretView()

Scrolls the editor viewport so the current caret position is visible. Useful after operations that move the caret without auto-scrolling (for example a programmatic SetCaretByIndex with no scroll flag).

Syntax

void ScrollToCaretView();

Example

// Jump to a deep offset and bring it on screen.

MyEditor.Caret.SetCaretByIndex(2048);

MyEditor.Caret.ScrollToCaretView();

GetCaretIndex()

Returns the zero-based character offset of the caret within the document's plain-text content. Markup tags do not count toward the index, so the value is suitable for use with SelectionStart/SelectionLength-style APIs.

Syntax

int GetCaretIndex();

Returns

int — the zero-based plain-text index of the caret, or -1 when no document is loaded.

Example

// Persist the caret offset in user settings.

int caret = MyEditor.Caret.GetCaretIndex();

Properties.Settings.Default.LastCaret = caret;

Properties.Settings.Default.Save();

SetCaretByIndex(int index)

Moves the caret to the given zero-based plain-text index in the document body. The editor does not auto-scroll; call ScrollToCaretView afterwards if needed.

Syntax

void SetCaretByIndex(int index);

Parameters

Example

// Restore a previously saved caret offset.

int saved = Properties.Settings.Default.LastCaret;

MyEditor.Caret.SetCaretByIndex(saved);

MyEditor.Caret.ScrollToCaretView();

SetCaretByIndex(int index, int length)

Positions the caret at index and extends a selection forward by length characters. Equivalent to calling SetCaretByIndex(index) followed by selecting length characters to the right.

Syntax

void SetCaretByIndex(int index, int length);

Parameters

Example

// Select the 12 characters starting at offset 100, then italicise them.

MyEditor.Caret.SetCaretByIndex(100, 12);

MyEditor.Formatting.SetItalic();

GetCaretIndexInHtml()

Returns the offset of the caret within the raw HTML source of the document, including all markup tags. Use this when you need to splice raw HTML at the cursor position.

Syntax

int GetCaretIndexInHtml();

Returns

int — offset of the caret within the editor's HTML source string, or -1 when no document is loaded.

Remarks

The HTML index changes whenever the source markup changes (for example after applying a style that introduces a new <span>); do not cache it across edits.

Example

// Splice a custom marker into the raw HTML at the caret.

int idx = MyEditor.Caret.GetCaretIndexInHtml();

string html = MyEditor.Html;

MyEditor.Html = html.Insert(idx, "<!-- mark -->");

SetCaretAtHome()

Moves the caret to the very beginning of the document body, before the first character of the first block element.

Syntax

void SetCaretAtHome();

Example

// Scroll to the top of the document on a button click.

private void GoToTop_Click(object sender, RoutedEventArgs e)

{

    MyEditor.Caret.SetCaretAtHome();

    MyEditor.Caret.ScrollToCaretView();

}

SetCaretAtLineBeginning()

Moves the caret to the beginning of the current line, mirroring the behaviour of the Home key.

Syntax

void SetCaretAtLineBeginning();

Example

// Indent the current line at its beginning.

MyEditor.Caret.SetCaretAtLineBeginning();

MyEditor.Editor.ExecCommand("InsertHTML", false, " ");

SetCaretAtLineEnd()

Moves the caret to the end of the current line, mirroring the behaviour of the End key.

Syntax

void SetCaretAtLineEnd();

Example

// Append a footnote marker to the current line.

MyEditor.Caret.SetCaretAtLineEnd();

MyEditor.Editor.ExecCommand("InsertHTML", false, "<sup>[1]</sup>");

SetCaretAtEnd()

Moves the caret to the very end of the document body, after the last character of the last block element. Common pattern after appending content programmatically and giving focus back to the user.

Syntax

void SetCaretAtEnd();

Example

// Append a paragraph and place the caret after it.

MyEditor.AppendHtml("<p>New paragraph.</p>");

MyEditor.Caret.SetCaretAtEnd();

MyEditor.Focus();