pub struct TextCursor { /* private fields */ }Expand description
A cursor into a TextDocument.
Multiple cursors can coexist on the same document (like Qt’s QTextCursor).
When any cursor edits text, all other cursors’ positions are automatically
adjusted by the document.
Cloning a cursor creates an independent cursor at the same position.
Implementations§
Source§impl TextCursor
impl TextCursor
Sourcepub fn has_selection(&self) -> bool
pub fn has_selection(&self) -> bool
Returns true if there is a selection.
Sourcepub fn selection_start(&self) -> usize
pub fn selection_start(&self) -> usize
Start of the selection (min of position and anchor).
Sourcepub fn selection_end(&self) -> usize
pub fn selection_end(&self) -> usize
End of the selection (max of position and anchor).
Sourcepub fn selected_text(&self) -> Result<String>
pub fn selected_text(&self) -> Result<String>
Get the selected text. Returns empty string if no selection.
Sourcepub fn text_before(&self, max_len: usize) -> Result<String>
pub fn text_before(&self, max_len: usize) -> Result<String>
Up to max_len characters of plain text immediately preceding the cursor position,
bounded and read directly from the store — the same fast block lookup
char_format uses, never materializing the whole document the
way selected_text’s
document_inspection_commands::get_text_at_position does internally. Block
boundaries appear as '\n'. Returns fewer than max_len characters near the start of
the document.
Falls back to the (correct, but O(document size)) slow path for documents containing
tables or unmirrored sub-frames, where the fast rope-index lookup doesn’t apply — see
common::database::rope_helpers::find_block_at_char_position’s own doc comment for
exactly which documents that is.
Sourcepub fn clear_selection(&self)
pub fn clear_selection(&self)
Collapse the selection by moving anchor to position.
Sourcepub fn at_block_start(&self) -> bool
pub fn at_block_start(&self) -> bool
True if the cursor is at the start of a block.
Sourcepub fn at_block_end(&self) -> bool
pub fn at_block_end(&self) -> bool
True if the cursor is at the end of a block: at the end of every paragraph, not only the last one.
Sourcepub fn block_number(&self) -> usize
pub fn block_number(&self) -> usize
The block number (0-indexed) containing the cursor.
Sourcepub fn position_in_block(&self) -> usize
pub fn position_in_block(&self) -> usize
The cursor’s column within the current block (0-indexed): at the end of a paragraph, the paragraph’s length.
Sourcepub fn set_position(&self, position: usize, mode: MoveMode)
pub fn set_position(&self, position: usize, mode: MoveMode)
Set the cursor to an absolute position.
When extending a selection (KeepAnchor) across a table’s edge, the
selection takes the whole table, as LibreOffice and Word take a table a
selection runs into or out of: partial table selections from outside a
table are not allowed.
- Moved into a table from outside it, the position goes to the table’s edge on the far side: moving forward, to the end of the table’s last cell; moving back, to the table’s anchor, its start. The selection then spans exactly what its removal takes. It ended at the start of the paragraph after the table, one position more than the removal takes, since the two paragraphs are not joined: an editor moving the selection by its two ends put the text one character before the drop point.
- Moved out of the table the selection started in, the anchor goes to the table’s edge on the far side, so the selection holds the table whole, from its anchor or to the end of its last cell. The cell it started in is remembered: moved back into that table, the selection starts there again.
The selection this leaves is what selection
copies and what remove_selected_text,
typing and pasting over it remove: the anchor stayed in the cell, so an
editor showed the table’s cells up to it selected while the copy held
the whole table, the removal emptied the cells it met, and a cut pasted
back put the table in twice. The position was moved instead, to the
other side of the table: a selection from a cell to the end of the
text removed the table and kept the paragraphs after it.
Nothing snaps when mode is MoveAnchor (a plain click or move).
Sourcepub fn move_position(
&self,
operation: MoveOperation,
mode: MoveMode,
n: usize,
) -> bool
pub fn move_position( &self, operation: MoveOperation, mode: MoveMode, n: usize, ) -> bool
Move the cursor by a semantic operation.
n is used as a repeat count for character-level movements
(NextCharacter, PreviousCharacter, Left, Right).
For all other operations it is ignored. Returns true if the cursor moved.
A move starting in the main text stops at its end: the bodies of the footnote
definitions a document holds come after it, and no view shows them. A cursor placed
in a body with set_position moves in the bodies freely.
A selection holding a table whole, its moving end at the table’s edge (see
set_position), gives the table back when that end steps back
into it toward where the selection started: the end goes to the table’s other side.
The character moves and NextBlock (so Down) that keep no anchor
(MoveMode::MoveAnchor) do not stop on the positions a table’s anchor takes in the
text, where the caret would stand in the first cell without having moved: Right (or
NextCharacter, or NextBlock and Down) from the end of the paragraph before a table
goes to the start of its first cell in one step, and Left (or PreviousCharacter)
from there goes back to the end of that paragraph. A caret standing on an anchor is
already in the first cell: Right takes it on from there (unless n is 0), Left to
the paragraph before. When the table opens the document there is nothing before it,
and Left from its first cell stays. A move keeping the anchor (MoveMode::KeepAnchor)
does stop on the anchor, so that a selection can take a table whole, and the
deletions (delete_char, delete_previous_char) are not moves. The other operations
are as they were, and two of them still land on the anchor of a table that opens the
document, position 0: Start, and PreviousWord or WordLeft from the first cell.
Sourcepub fn select(&self, selection: SelectionType)
pub fn select(&self, selection: SelectionType)
Select a region relative to the cursor position.
Sourcepub fn set_content_locale(&self, locale: Option<&str>)
pub fn set_content_locale(&self, locale: Option<&str>)
The language this cursor reads its text as, for the sentence operations. A BCP-47-ish
tag ("en", "fr-FR"); None — the default — means untailored UAX #29.
Transient, per-cursor and non-persisted: it never reaches an entity, an undo command or
an export. The enum-driven select / move_position
have nowhere to take a locale argument, so it is set once on the cursor instead —
TextDocument::sentence_at takes the same value per
call for callers that would rather not hold a cursor at all.
Sourcepub fn content_locale(&self) -> Option<String>
pub fn content_locale(&self) -> Option<String>
The language set by set_content_locale.
Sourcepub fn insert_text(&self, text: &str) -> Result<()>
pub fn insert_text(&self, text: &str) -> Result<()>
Insert plain text at the cursor. Replaces selection if any.
Reports InsertionOrigin::Unspecified — the caller did not say. Use
insert_text_with_origin to say.
Sourcepub fn insert_text_with_origin(
&self,
text: &str,
origin: InsertionOrigin,
) -> Result<()>
pub fn insert_text_with_origin( &self, text: &str, origin: InsertionOrigin, ) -> Result<()>
Insert plain text at the cursor, saying which channel it came through.
The origin reaches consumers as DocumentEvent::TextInserted. It is a
fact about the channel and never about who was at the other end of it.
Sourcepub fn replace(
&self,
start: usize,
end: usize,
text: &str,
policy: ReplaceFormatPolicy,
) -> Result<()>
pub fn replace( &self, start: usize, end: usize, text: &str, policy: ReplaceFormatPolicy, ) -> Result<()>
Replace [start, end) with text, choosing what the replacement wears where it
overwrites formatted text — see crate::ReplaceFormatPolicy. Lands as one atomic
edit (one undo entry), with the cursor left at the end of the inserted text.
The counterpart to insert_text for callers that must choose
the replacement’s formatting rather than inherit whatever precedes the range — a
spell-check correction picked from a context menu, an autocorrect, a
replace-this-occurrence action. start/end may be given in either order.
A range crossing a block boundary falls back to composing delete + insert as a single
undo unit, exactly like insert_text’s existing cross-block
fallback — format_policy only has meaning within one block, since
crate::ReplaceFormatPolicy operates on a single block’s format runs.
With transient edits outstanding, they are reverted first, and
start and end, read in the document as it was with them, are moved back so that
the range holds the recorded text it held (see the
module documentation). A non-empty range that comes
back empty held only transient text and names nothing left: nothing is replaced, and
the call returns DocumentError::TransientEdits so the caller can tell (the
transient edits are reverted all the same).
Sourcepub fn insert_formatted_text(
&self,
text: &str,
format: &TextFormat,
) -> Result<()>
pub fn insert_formatted_text( &self, text: &str, format: &TextFormat, ) -> Result<()>
Insert text with a specific character format. Replaces selection if any.
Reports InsertionOrigin::Unspecified — the caller did not say.
Sourcepub fn insert_formatted_text_with_origin(
&self,
text: &str,
format: &TextFormat,
origin: InsertionOrigin,
) -> Result<()>
pub fn insert_formatted_text_with_origin( &self, text: &str, format: &TextFormat, origin: InsertionOrigin, ) -> Result<()>
As insert_formatted_text, saying which
channel the text came through.
Sourcepub fn insert_line_break(&self) -> Result<()>
pub fn insert_line_break(&self) -> Result<()>
Insert a line break inside the block, the one Shift+Enter makes in a word processor. Replaces selection if any.
The next line is more of the same paragraph, list item, quotation or heading,
where insert_block starts a new one. The block’s text
holds it as one LINE_SEPARATOR, which every writer
puts out as its format’s own line break.
Reports InsertionOrigin::Unspecified, as insert_text
does. Use insert_line_break_with_origin
to say.
Sourcepub fn insert_line_break_with_origin(
&self,
origin: InsertionOrigin,
) -> Result<()>
pub fn insert_line_break_with_origin( &self, origin: InsertionOrigin, ) -> Result<()>
insert_line_break, saying which channel it came
through (see insert_text_with_origin).
Sourcepub fn insert_block(&self) -> Result<()>
pub fn insert_block(&self) -> Result<()>
Insert a block break (new paragraph). Replaces selection if any.
Sourcepub fn insert_html_with_origin(
&self,
html: &str,
origin: InsertionOrigin,
) -> Result<()>
pub fn insert_html_with_origin( &self, html: &str, origin: InsertionOrigin, ) -> Result<()>
Insert an HTML fragment at the cursor position. Replaces selection if any.
As insert_html, saying which channel the text came
through.
Sourcepub fn insert_html(&self, html: &str) -> Result<()>
pub fn insert_html(&self, html: &str) -> Result<()>
Insert an HTML fragment at the cursor position. Replaces selection if any.
A <pre> goes in as paragraphs, one for each of its lines (see
DocumentFragment::from_html).
Sourcepub fn insert_markdown_with_origin(
&self,
markdown: &str,
origin: InsertionOrigin,
) -> Result<()>
pub fn insert_markdown_with_origin( &self, markdown: &str, origin: InsertionOrigin, ) -> Result<()>
Insert a Markdown fragment at the cursor position. Replaces selection if any.
As insert_markdown, saying which channel the text came
through.
pub fn insert_markdown(&self, markdown: &str) -> Result<()>
Sourcepub fn insert_djot_with_origin(
&self,
djot: &str,
origin: InsertionOrigin,
) -> Result<()>
pub fn insert_djot_with_origin( &self, djot: &str, origin: InsertionOrigin, ) -> Result<()>
Insert a djot fragment at the cursor position. Replaces selection if any.
As insert_djot, saying which channel the text came
through.
pub fn insert_djot(&self, djot: &str) -> Result<()>
Sourcepub fn insert_footnote_reference(&self, label: &str) -> Result<()>
pub fn insert_footnote_reference(&self, label: &str) -> Result<()>
Insert a footnote reference naming label at the cursor.
Goes through Djot rather than a dedicated editing use case, and
deliberately: [^label] is what Content stores and what a reload
parses, so the reference on screen and the reference that survives a save
are produced by the same code path. An insertion route of its own would
work right up until the document was closed and reopened.
The label is the note’s durable identity, minted by the caller. It is never the number — that is derived at render time from document order, so inserting a note above this one renumbers it without touching a character of the prose.
Refused, with the text left as it was, in a code block: a code block is verbatim text, which the save writes without a reference.
Sourcepub fn insert_fragment(&self, fragment: &DocumentFragment) -> Result<()>
pub fn insert_fragment(&self, fragment: &DocumentFragment) -> Result<()>
Insert a document fragment at the cursor. Replaces selection if any.
Reports InsertionOrigin::Unspecified — the caller did not say.
A list the fragment carries goes in with every item, in its order, at
most 16 levels deep, where an editor’s own nesting gestures stop: an
item nested deeper lands at the 16th level, beside the items there. This
holds for insert_djot,
insert_html and
insert_markdown as well, which insert a
fragment. Loading a document keeps its lists as they are.
A quotation, a code block and a paragraph’s alignment go in as they stood, so selecting all of a text and inserting another’s Djot gives the text a load of that Djot gives. A quotation goes in as deep as it stood, never less deep than the caret already is (one pasted into a quotation is not quoted twice); in a table cell or a footnote’s body, which hold paragraphs, it goes in as its paragraphs, and in a table cell a code block goes in as a paragraph (a table cell is written as one line of text).
Inserted over a selection holding the whole text (from its start to its end, or
select(SelectionType::Document), even of an empty text), or into
the empty paragraph a removal of such a selection left, a whole text (a fragment
from_djot,
from_markdown or
from_document, and so what
insert_djot and insert_markdown
insert) keeps its own formatting rather than taking that of the empty paragraph the
removal leaves, which is the first removed paragraph’s: the text reads as the
fragment loaded. So does any other fragment with a structure of its own: several
paragraphs, a table, a quotation, or a paragraph of its own format. That empty
paragraph is replaced whichever cursor removed the text, and after an undo or a
redo back to it, as long as it looks as the removal left it. A phrase, one plain
paragraph copied from a text or pasted as HTML, goes into it as typed text does and
keeps its formatting: its direction, alignment, heading level and quotation. An
empty paragraph the writer formatted (a heading line, a list item, a quotation),
in an empty text as anywhere else, is the paragraph a paste goes into, as typed text
does: a heading line stays a heading, and a quotation made for an epigraph holds
what is pasted into it. The bodies of footnote definitions
the document holds stay where they are, as
remove_selected_text says. A paste that
would put an image or a footnote reference into a code block is refused, the
text left as it was: a code block is verbatim text, which the save writes
without them.
Sourcepub fn insert_fragment_with_origin(
&self,
fragment: &DocumentFragment,
origin: InsertionOrigin,
) -> Result<()>
pub fn insert_fragment_with_origin( &self, fragment: &DocumentFragment, origin: InsertionOrigin, ) -> Result<()>
As insert_fragment, saying which channel the
text came through. This is the path a paste, a drop and an import all
take, so it is the one that most needs to be able to say so.
Sourcepub fn selection(&self) -> DocumentFragment
pub fn selection(&self) -> DocumentFragment
Extract the current selection as a DocumentFragment.
The fragment holds the text the selection starts in: the main text, with the quotations its whole paragraphs stand in, or the one footnote body it starts in. A note’s reference travels; its body stays where it is defined. Each paragraph is held once, in reading order. A table the selection holds the anchor of, runs into from the text beside it, or runs out of into the text beside it, is held whole, in a quotation as anywhere else, as a removal of the same selection takes it. An ordered list keeps the numbers its items wore. An empty paragraph closing the text is held when the selection reaches the text’s end.
Sourcepub fn insert_image(
&self,
name: &str,
alt: &str,
width: u32,
height: u32,
) -> Result<()>
pub fn insert_image( &self, name: &str, alt: &str, width: u32, height: u32, ) -> Result<()>
Insert an image at the cursor. Replaces selection if any.
name keys the image’s bytes in the document’s resource table (see
crate::TextDocument::add_resource); alt is its accessible
description and its export representation, and may be empty.
Refused, with the text left as it was, in a code block: a code block is verbatim text, which the save writes without an image.
Sourcepub fn insert_frame(&self) -> Result<()>
pub fn insert_frame(&self) -> Result<()>
Insert a new frame at the cursor.
Sourcepub fn insert_table(&self, rows: usize, columns: usize) -> Result<TextTable>
pub fn insert_table(&self, rows: usize, columns: usize) -> Result<TextTable>
Insert a table at the cursor position.
Creates a rows × columns table with empty cells.
The cursor moves into the first cell of the table.
Returns a handle to the created table.
Sourcepub fn current_table(&self) -> Option<TextTable>
pub fn current_table(&self) -> Option<TextTable>
Returns the table the cursor is currently inside, if any.
Returns None if the cursor is in the main document flow
(not inside a table cell).
Sourcepub fn current_table_cell(&self) -> Option<TableCellRef>
pub fn current_table_cell(&self) -> Option<TableCellRef>
Returns the table cell the cursor is currently inside, if any.
Returns None if the cursor is not inside a table cell.
When Some, provides the table, row, and column.
Sourcepub fn current_frame(&self) -> Option<FrameRef>
pub fn current_frame(&self) -> Option<FrameRef>
The innermost frame enclosing the cursor’s current block, or None
if the cursor sits directly in the root frame (no enclosing
sub-frame). The returned depth is the nesting level from the root
(1 for a direct child of root, 2 for a grandchild, etc.).
Sourcepub fn is_in_blockquote(&self) -> bool
pub fn is_in_blockquote(&self) -> bool
True if the cursor’s block lives inside any blockquote frame (at any nesting level). The block is the caret’s: at the end of a quoted paragraph, that paragraph, whatever follows it.
Sourcepub fn current_blockquote_frame_id(&self) -> Option<usize>
pub fn current_blockquote_frame_id(&self) -> Option<usize>
Id of the innermost blockquote frame enclosing the cursor’s block,
or None if not in a blockquote.
Sourcepub fn blockquote_depth_at_cursor(&self) -> usize
pub fn blockquote_depth_at_cursor(&self) -> usize
Nesting depth of the cursor inside blockquote frames: 0 = not in any quote, 1 = top-level quote, 2 = quote inside a quote, …
Sourcepub fn is_first_block_in_current_frame(&self) -> bool
pub fn is_first_block_in_current_frame(&self) -> bool
True iff the cursor’s block is the first positive entry in its
owning frame’s child_order. Used by the keyboard handler to
decide whether Backspace should unwrap the enclosing frame.
A single-block frame returns true for both is_first_* and
is_last_*.
Sourcepub fn is_last_block_in_current_frame(&self) -> bool
pub fn is_last_block_in_current_frame(&self) -> bool
True iff the cursor’s block is the last positive entry in its
owning frame’s child_order. Used by the keyboard handler to
decide whether forward Delete should unwrap the enclosing frame.
Sourcepub fn current_block_is_empty(&self) -> bool
pub fn current_block_is_empty(&self) -> bool
True iff the block at the cursor has no characters of content. Used by the Enter handler to decide whether to exit a blockquote.
Sourcepub fn selection_spans_multiple_frames(&self) -> bool
pub fn selection_spans_multiple_frames(&self) -> bool
True iff the cursor’s anchor and head sit in different frames. Used by the toolbar to disable the “toggle blockquote” button on selections that cross frame boundaries.
Sourcepub fn wrap_selection_in_blockquote(&self) -> Result<()>
pub fn wrap_selection_in_blockquote(&self) -> Result<()>
Wrap the current block (or the blocks in the current selection) in a new blockquote frame nested inside the cursor’s current parent frame. Returns an error if the selection spans multiple frames.
Sourcepub fn insert_blockquote(&self) -> Result<()>
pub fn insert_blockquote(&self) -> Result<()>
Wrap the current block in a new blockquote frame at the current
nesting level. Equivalent to wrap_selection_in_blockquote()
when there is no selection.
Sourcepub fn toggle_blockquote(&self) -> Result<()>
pub fn toggle_blockquote(&self) -> Result<()>
If the cursor is inside any blockquote, unwrap the innermost one (lift its blocks into the parent frame and delete the frame). Otherwise, wrap the current block / selection in a new blockquote. Mirrors the toggle behaviour of a toolbar button.
Sourcepub fn unwrap_current_frame(&self) -> Result<()>
pub fn unwrap_current_frame(&self) -> Result<()>
Unwrap the innermost frame enclosing the cursor (any frame, not just blockquotes). Errors if the cursor’s block sits in the root frame.
Sourcepub fn unwrap_current_block_from_blockquote(&self) -> Result<()>
pub fn unwrap_current_block_from_blockquote(&self) -> Result<()>
Extract the cursor’s current block from its innermost enclosing blockquote frame, lifting it one nesting level. If the cursor is not in a blockquote, errors.
Sourcepub fn increase_blockquote_depth(&self) -> Result<()>
pub fn increase_blockquote_depth(&self) -> Result<()>
Wrap the current block in a new blockquote frame. If the cursor is already inside a blockquote, this creates a deeper nested quote (depth + 1). If outside, this creates a top-level quote.
Sourcepub fn decrease_blockquote_depth(&self) -> Result<()>
pub fn decrease_blockquote_depth(&self) -> Result<()>
Pop the cursor out of one nesting level of blockquotes. If the cursor is in a depth-N quote with multiple blocks, the current block is extracted (splitting the quote if needed). If the current block is the only one in the quote, the whole quote is unwrapped.
Sourcepub fn remove_table(&self, table_id: usize) -> Result<()>
pub fn remove_table(&self, table_id: usize) -> Result<()>
Remove a table from the document by its ID.
Sourcepub fn insert_table_row(&self, table_id: usize, row_index: usize) -> Result<()>
pub fn insert_table_row(&self, table_id: usize, row_index: usize) -> Result<()>
Insert a row into a table at the given index.
Sourcepub fn insert_table_column(
&self,
table_id: usize,
column_index: usize,
) -> Result<()>
pub fn insert_table_column( &self, table_id: usize, column_index: usize, ) -> Result<()>
Insert a column into a table at the given index.
Sourcepub fn remove_table_row(&self, table_id: usize, row_index: usize) -> Result<()>
pub fn remove_table_row(&self, table_id: usize, row_index: usize) -> Result<()>
Remove a row from a table. Fails if only one row remains.
Sourcepub fn remove_table_column(
&self,
table_id: usize,
column_index: usize,
) -> Result<()>
pub fn remove_table_column( &self, table_id: usize, column_index: usize, ) -> Result<()>
Remove a column from a table. Fails if only one column remains.
Sourcepub fn merge_table_cells(
&self,
table_id: usize,
start_row: usize,
start_column: usize,
end_row: usize,
end_column: usize,
) -> Result<()>
pub fn merge_table_cells( &self, table_id: usize, start_row: usize, start_column: usize, end_row: usize, end_column: usize, ) -> Result<()>
Merge a rectangular range of cells within a table.
Sourcepub fn split_table_cell(
&self,
cell_id: usize,
split_rows: usize,
split_columns: usize,
) -> Result<()>
pub fn split_table_cell( &self, cell_id: usize, split_rows: usize, split_columns: usize, ) -> Result<()>
Split a previously merged cell.
Sourcepub fn set_table_format(
&self,
table_id: usize,
format: &TableFormat,
) -> Result<()>
pub fn set_table_format( &self, table_id: usize, format: &TableFormat, ) -> Result<()>
Set formatting on a table.
Sourcepub fn set_table_cell_format(
&self,
cell_id: usize,
format: &CellFormat,
) -> Result<()>
pub fn set_table_cell_format( &self, cell_id: usize, format: &CellFormat, ) -> Result<()>
Set formatting on a table cell.
Sourcepub fn remove_current_table(&self) -> Result<()>
pub fn remove_current_table(&self) -> Result<()>
Remove the table the cursor is currently inside. Returns an error if the cursor is not inside a table.
Sourcepub fn insert_row_above(&self) -> Result<()>
pub fn insert_row_above(&self) -> Result<()>
Insert a row above the cursor’s current row. Returns an error if the cursor is not inside a table.
Sourcepub fn insert_row_below(&self) -> Result<()>
pub fn insert_row_below(&self) -> Result<()>
Insert a row below the cursor’s current row. Returns an error if the cursor is not inside a table.
Sourcepub fn insert_column_before(&self) -> Result<()>
pub fn insert_column_before(&self) -> Result<()>
Insert a column before the cursor’s current column. Returns an error if the cursor is not inside a table.
Sourcepub fn insert_column_after(&self) -> Result<()>
pub fn insert_column_after(&self) -> Result<()>
Insert a column after the cursor’s current column. Returns an error if the cursor is not inside a table.
Sourcepub fn remove_current_row(&self) -> Result<()>
pub fn remove_current_row(&self) -> Result<()>
Remove the row at the cursor’s current position. Returns an error if the cursor is not inside a table.
Sourcepub fn remove_current_column(&self) -> Result<()>
pub fn remove_current_column(&self) -> Result<()>
Remove the column at the cursor’s current position. Returns an error if the cursor is not inside a table.
Sourcepub fn merge_selected_cells(&self) -> Result<()>
pub fn merge_selected_cells(&self) -> Result<()>
Merge cells spanned by the current selection.
Both cursor position and anchor must be inside the same table. The cell range is derived from the cells at position and anchor. Returns an error if the cursor is not inside a table or position and anchor are in different tables.
Sourcepub fn split_current_cell(
&self,
split_rows: usize,
split_columns: usize,
) -> Result<()>
pub fn split_current_cell( &self, split_rows: usize, split_columns: usize, ) -> Result<()>
Split the cell at the cursor’s current position. Returns an error if the cursor is not inside a table.
Sourcepub fn set_current_table_format(&self, format: &TableFormat) -> Result<()>
pub fn set_current_table_format(&self, format: &TableFormat) -> Result<()>
Set formatting on the table the cursor is currently inside. Returns an error if the cursor is not inside a table.
Sourcepub fn set_current_cell_format(&self, format: &CellFormat) -> Result<()>
pub fn set_current_cell_format(&self, format: &CellFormat) -> Result<()>
Set formatting on the cell the cursor is currently inside. Returns an error if the cursor is not inside a table.
Sourcepub fn selection_kind(&self) -> SelectionKind
pub fn selection_kind(&self) -> SelectionKind
Determine the kind of selection the cursor currently has.
Returns Cells when position and anchor are in
different cells of the same table (rectangular cell selection), or
when an explicit cell-selection override is active.
Sourcepub fn is_cell_selection(&self) -> bool
pub fn is_cell_selection(&self) -> bool
Returns true when the current selection involves whole-cell selection.
Sourcepub fn selected_cell_range(&self) -> Option<CellRange>
pub fn selected_cell_range(&self) -> Option<CellRange>
Returns the rectangular cell range if the cursor has a cell selection.
Sourcepub fn selected_cells(&self) -> Vec<TableCellRef>
pub fn selected_cells(&self) -> Vec<TableCellRef>
Returns all cells in the selected rectangular range.
Sourcepub fn select_table_cell(&self, table_id: usize, row: usize, col: usize)
pub fn select_table_cell(&self, table_id: usize, row: usize, col: usize)
Set an explicit single-cell selection override.
Sourcepub fn select_cell_range(
&self,
table_id: usize,
start_row: usize,
start_col: usize,
end_row: usize,
end_col: usize,
)
pub fn select_cell_range( &self, table_id: usize, start_row: usize, start_col: usize, end_row: usize, end_col: usize, )
Set an explicit rectangular cell-range selection override.
Sourcepub fn clear_cell_selection(&self)
pub fn clear_cell_selection(&self)
Clear any cell-selection override without changing position/anchor.
Sourcepub fn delete_char(&self) -> Result<()>
pub fn delete_char(&self) -> Result<()>
Delete the character after the cursor (Delete key).
Sourcepub fn delete_previous_char(&self) -> Result<()>
pub fn delete_previous_char(&self) -> Result<()>
Delete the character before the cursor (Backspace key).
Sourcepub fn remove_selected_text(&self) -> Result<String>
pub fn remove_selected_text(&self) -> Result<String>
Delete the selected text. Returns the deleted text. No-op if no selection.
A selection edits the text it starts in: the main text, or the one footnote body it
starts in. Selecting from the main text to the end of the document, or all of it,
takes the main text and leaves the notes’ bodies, which come after it, as they are;
selection copies the same text. A body stays even when the
removal took every reference to its note, as a cut does before the paste that puts
the references back: the document keeps it, every save writes it as a definition no
reference names, and no move of a caret from the main text reaches it.
clear and the loads replace everything, bodies
included.
A removal that leaves the text empty leaves this cursor standing for all of that
empty text: a fragment inserted next at the caret replaces the text, as it would have
replaced the selection (see insert_fragment), so a cut of
all of a text pasted back is the text as it was. Typed text keeps the formatting of
the empty paragraph, which is the first removed paragraph’s.
A selection with one end in a table and the other outside it takes the whole table,
as selection copies it (see
set_position). A selection from inside one paragraph to
inside another, holding whole the tables between them, joins the two paragraphs, as
a selection of text does.
Backspace and Delete across a paragraph that would bring an image or a footnote reference into a code block join nothing, and a selection across one takes its text and joins nothing.
Sourcepub fn current_list(&self) -> Option<TextList>
pub fn current_list(&self) -> Option<TextList>
Returns the list that the block at the cursor position belongs to,
or None if the current block is not a list item.
The block is the caret’s (see TextDocument::block_at_caret):
at the end of a list item, that item. This and the other list helpers
acting on the current block used to read the block at the character
index, the next paragraph there, so moving an item a level in or out
with the caret at the end of its text moved the item after it.
Sourcepub fn create_list(&self, style: ListStyle) -> Result<()>
pub fn create_list(&self, style: ListStyle) -> Result<()>
Turn the block(s) in the selection into a list.
The blocks may sit in the main text, a quotation, a table cell or a footnote’s body. A list runs on inside one frame only, and only as long as no quotation or table comes between its items, so a selection crossing one makes a list on each side of it. Blocks that leave another list for this one take that list away when they were all it held.
Sourcepub fn insert_list(&self, style: ListStyle) -> Result<()>
pub fn insert_list(&self, style: ListStyle) -> Result<()>
Insert a new list item at the cursor position.
Sourcepub fn set_list_format(&self, list_id: usize, format: &ListFormat) -> Result<()>
pub fn set_list_format(&self, list_id: usize, format: &ListFormat) -> Result<()>
Set formatting on a list by its ID. A format whose style turns a numbered list into a
bullet list, or the reverse, resets the prefix and suffix it leaves None (see
ListFormat).
Sourcepub fn set_current_list_format(&self, format: &ListFormat) -> Result<()>
pub fn set_current_list_format(&self, format: &ListFormat) -> Result<()>
Set formatting on the list that the current block belongs to. Returns an error if the cursor is not inside a list item.
Sourcepub fn add_block_to_list(&self, block_id: usize, list_id: usize) -> Result<()>
pub fn add_block_to_list(&self, block_id: usize, list_id: usize) -> Result<()>
Add a block to a list by their IDs.
Sourcepub fn add_current_block_to_list(&self, list_id: usize) -> Result<()>
pub fn add_current_block_to_list(&self, list_id: usize) -> Result<()>
Add the block at the cursor position to a list: the caret’s block, as
current_list reads it.
Sourcepub fn remove_block_from_list(&self, block_id: usize) -> Result<()>
pub fn remove_block_from_list(&self, block_id: usize) -> Result<()>
Remove a block from its list by block ID.
Sourcepub fn remove_current_block_from_list(&self) -> Result<()>
pub fn remove_current_block_from_list(&self) -> Result<()>
Remove the block at the cursor position from its list: the caret’s
block, as current_list reads it.
Returns an error if the current block is not a list item.
Sourcepub fn remove_list_item(&self, list_id: usize, index: usize) -> Result<()>
pub fn remove_list_item(&self, list_id: usize, index: usize) -> Result<()>
Remove a list item by index within the list. Resolves the index to a block, then removes it from the list.
Sourcepub fn char_format(&self) -> Result<TextFormat>
pub fn char_format(&self) -> Result<TextFormat>
Get the character format at the cursor position. Reads the
covering FormatRun (or image anchor) directly from the store.
Sourcepub fn block_format(&self) -> Result<BlockFormat>
pub fn block_format(&self) -> Result<BlockFormat>
Get the block format of the block containing the cursor.
Resolved with caret semantics, as “containing the cursor” says: a cursor at the end of a paragraph is still in it. Reading the character-index answer instead reported the NEXT paragraph’s format there — which is what the editor’s format panel showed for the whole time the caret sat at the end of the line being typed.
Sourcepub fn set_char_format(&self, format: &TextFormat) -> Result<()>
pub fn set_char_format(&self, format: &TextFormat) -> Result<()>
Set the character format for the selection.
Sourcepub fn link_at_caret(&self) -> Option<LinkExtent>
pub fn link_at_caret(&self) -> Option<LinkExtent>
The hyperlink the cursor sits in, with its full reach.
A link has no identity of its own — it is a stretch of runs agreeing on
a destination — so this reports the extent, coalesced across any runs
an inner bold or italic split it into. See LinkExtent.
None when the cursor is not on a link. Uses the same caret semantics
as block_format: a cursor at the end of a link
is still in it.
Sourcepub fn clear_char_anchor(&self) -> Result<()>
pub fn clear_char_anchor(&self) -> Result<()>
Remove the hyperlink from the selection.
Not expressible through merge_char_format:
its fields merge, so anchor_href: None means “leave the link alone”,
never “take it off”. Which is why the removal is its own verb, and why
TextFormat::clear_link exists as a
flag rather than as an absent field.
Note the selection must be non-empty — a zero-width range formats
nothing, here as everywhere else. Callers editing an existing link
should select its LinkExtent first.
Sourcepub fn merge_char_format(&self, format: &TextFormat) -> Result<()>
pub fn merge_char_format(&self, format: &TextFormat) -> Result<()>
Merge a character format into the selection.
Sourcepub fn set_block_format(&self, format: &BlockFormat) -> Result<()>
pub fn set_block_format(&self, format: &BlockFormat) -> Result<()>
Set the block format for the current block (or all blocks in selection).
Making a paragraph that holds an image or a footnote reference a code block is refused, the text left as it was: a code block is verbatim text, which the save writes without them. A table cell’s paragraph is never made a code block: a table cell is written as one line of text, and the other formats asked for still apply.
Sourcepub fn set_frame_format(
&self,
frame_id: usize,
format: &FrameFormat,
) -> Result<()>
pub fn set_frame_format( &self, frame_id: usize, format: &FrameFormat, ) -> Result<()>
Set the frame format.
Sourcepub fn begin_edit_block(&self)
pub fn begin_edit_block(&self)
Begin a group of operations that will be undone as a single unit.
The block belongs to the document, not to this cursor: the edits of every cursor go
into it while it is open, and any cursor’s end_edit_block
ends the innermost block open on the document. Every begin must be balanced by one
end: a block left open keeps gathering every later edit, and none of them reaches
the undo history until it ends.
Sourcepub fn end_edit_block(&self)
pub fn end_edit_block(&self)
End the current edit block.
Sourcepub fn join_previous_edit_block(&self)
pub fn join_previous_edit_block(&self)
Alias for begin_edit_block.
Semantically indicates that the new composite should be merged with
the previous one (e.g., consecutive keystrokes grouped into a single
undo unit). The current backend treats this identically to
begin_edit_block; future versions may implement automatic merging.
Source§impl TextCursor
impl TextCursor
Sourcepub fn insert_text_transient(&self, text: &str) -> Result<()>
pub fn insert_text_transient(&self, text: &str) -> Result<()>
Insert plain text at the cursor, replacing the selection if any, without recording it in the undo history.
For an input method’s composition, shown in the text while it is being made, or any
tentative text a host shows and then either commits or takes back. The text goes in
as insert_text puts it, with the format of the text before it,
and the cursor is left after it. The document announces the change as it does every
edit (DocumentEvent::ContentsChanged, and the block and flow events when they
apply), so views lay it out and draw it; it announces no
DocumentEvent::TextInserted, since nothing has arrived yet, no
DocumentEvent::UndoRedoChanged, since the history has not moved, and leaves
is_modified as it was.
Nothing is pushed on the undo stack, the redo stack is kept, and the next recorded
edit coalesces with the one before the transient edits as it would have without
them. To replace the text a composition showed with its next state, select it and
call this again: TextDocument::transient_range says where it is.
The edit joins the document’s outstanding transient edits, which a revert, a commit or any recorded write ends (see the module documentation).
Refused with DocumentError::TransientEdits, the document left as it was, while a
load in place (set_djot and its siblings) is still
writing the document, and when the selection crosses a table’s cells or holds part
of a table and text outside it.
Sourcepub fn insert_formatted_text_transient(
&self,
text: &str,
format: &TextFormat,
) -> Result<()>
pub fn insert_formatted_text_transient( &self, text: &str, format: &TextFormat, ) -> Result<()>
As insert_text_transient, with a character format,
as insert_formatted_text inserts it. Refused as
insert_text_transient is.
Sourcepub fn insert_text_transient_merged(
&self,
text: &str,
format: &TextFormat,
) -> Result<()>
pub fn insert_text_transient_merged( &self, text: &str, format: &TextFormat, ) -> Result<()>
As insert_text_transient, with format merged into
the inserted text: the text takes the format it inherits, as typed text does, and
every field format sets replaces that field of it, the others staying inherited.
For a composition shown in the format the writer toggled on the caret before it
(Bold with nothing selected), where
insert_formatted_text_transient would also
set the fields left unset (the font family and size among them).
One transient edit, refused as insert_text_transient is and reverted, committed or
ended by a recorded write in the same way. The merged format is part of what the
transient edits show and goes with them: a commit records the text it is given in
the format it inherits, and a host that wants the format recorded merges it into the
committed text in the same edit block
(begin_edit_block).
Sourcepub fn remove_selected_text_transient(&self) -> Result<String>
pub fn remove_selected_text_transient(&self) -> Result<String>
Remove the selected text without recording it in the undo history. Returns the removed text; nothing happens without a selection.
As remove_selected_text removes it, announced and
refused as insert_text_transient is, and recorded no
more. The removed text may be recorded text: an input method that converts a
committed syllable (Korean Hanja conversion, a reconversion in Japanese) takes it out
transiently, shows its candidates in its place, and the commit then records the
whole replacement as one step, which an undo takes back to the syllable.
Sourcepub fn commit_transient_text(&self, text: &str) -> Result<()>
pub fn commit_transient_text(&self, text: &str) -> Result<()>
Commit the outstanding transient edits as text, recorded as one undo step of its
own.
The transient edits are reverted, and the text they changed in the recorded document
(see TextDocument::transient_range) is replaced with text: after a composition
inserted transiently, text goes in where it was shown, over the text the
composition took the place of; after a transient removal of recorded text (a
syllable an input method converts), it replaces that text, so an undo gives it back.
The cursor is left after text.
The step is closed on both sides, as
break_undo_merge closes one: it does not
coalesce with the typing before the composition, and what is typed after it starts a
step of its own, so an undo takes back exactly the committed text. Inside an open
edit block, the commit joins the block instead. A replaced range within one block
entirely in one format keeps it (ReplaceFormatPolicy::PreserveIfFullyCovered);
inserted text, and text replacing a range across blocks, takes the format of the text
before it, as typed text does.
With no transient edits outstanding, text replaces the cursor’s selection, or goes
in at the cursor, as the same one closed step. An empty text records the removal
of the recorded text the transient edits had replaced (or of the selection, with
none outstanding); when there is none it records nothing and, like a cancel
(TextDocument::revert_transient_edits), closes no step.
On an error from the recorded half, the transient edits are reverted all the same and nothing is recorded, but the step before them is closed already: the typing on either side of the failed commit no longer coalesces.
Reports InsertionOrigin::Unspecified, as
insert_text does. Use
commit_transient_text_with_origin to say,
InsertionOrigin::Composed for an input method.
Refused with DocumentError::TransientEdits, the transient edits left as they
were, when they changed the document in more than one place: the recorded text
between them would be replaced too.
Sourcepub fn commit_transient_text_with_origin(
&self,
text: &str,
origin: InsertionOrigin,
) -> Result<()>
pub fn commit_transient_text_with_origin( &self, text: &str, origin: InsertionOrigin, ) -> Result<()>
As commit_transient_text, saying which channel the
text came through (see insert_text_with_origin).
Sourcepub fn recorded_position(&self) -> usize
pub fn recorded_position(&self) -> usize
Where the cursor’s position is in the document as recorded: where
TextDocument::revert_transient_edits would put it. Its
position when no transient edits are outstanding.
For a view that shows the recorded document
(TextDocument::snapshot_recorded_flow_masked) to draw this cursor on the text it
shows. Read with recorded_anchor, a selection holds the
same recorded text the revert leaves it holding.
Sourcepub fn recorded_anchor(&self) -> usize
pub fn recorded_anchor(&self) -> usize
Where the cursor’s anchor is in the document as recorded, as
recorded_position says of its position.