Skip to main content

TextCursor

Struct TextCursor 

Source
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

Source

pub fn position(&self) -> usize

Current cursor position (between characters).

Source

pub fn anchor(&self) -> usize

Anchor position. Equal to position() when no selection.

Source

pub fn has_selection(&self) -> bool

Returns true if there is a selection.

Source

pub fn selection_start(&self) -> usize

Start of the selection (min of position and anchor).

Source

pub fn selection_end(&self) -> usize

End of the selection (max of position and anchor).

Source

pub fn selected_text(&self) -> Result<String>

Get the selected text. Returns empty string if no selection.

Source

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.

Source

pub fn clear_selection(&self)

Collapse the selection by moving anchor to position.

Source

pub fn at_block_start(&self) -> bool

True if the cursor is at the start of a block.

Source

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.

Source

pub fn at_start(&self) -> bool

True if the cursor is at position 0.

Source

pub fn at_end(&self) -> bool

True if the cursor is at the very end of the document.

Source

pub fn block_number(&self) -> usize

The block number (0-indexed) containing the cursor.

Source

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.

Source

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).

Source

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.

Source

pub fn select(&self, selection: SelectionType)

Select a region relative to the cursor position.

Source

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.

Source

pub fn content_locale(&self) -> Option<String>

The language set by set_content_locale.

Source

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.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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.

Source

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).

Source

pub fn insert_block(&self) -> Result<()>

Insert a block break (new paragraph). Replaces selection if any.

Source

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.

Source

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).

Source

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.

Source

pub fn insert_markdown(&self, markdown: &str) -> Result<()>

Source

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.

Source

pub fn insert_djot(&self, djot: &str) -> Result<()>

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn insert_frame(&self) -> Result<()>

Insert a new frame at the cursor.

Source

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.

Source

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).

Source

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.

Source

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.).

Source

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.

Source

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.

Source

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, …

Source

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_*.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn remove_table(&self, table_id: usize) -> Result<()>

Remove a table from the document by its ID.

Source

pub fn insert_table_row(&self, table_id: usize, row_index: usize) -> Result<()>

Insert a row into a table at the given index.

Source

pub fn insert_table_column( &self, table_id: usize, column_index: usize, ) -> Result<()>

Insert a column into a table at the given index.

Source

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.

Source

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.

Source

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.

Source

pub fn split_table_cell( &self, cell_id: usize, split_rows: usize, split_columns: usize, ) -> Result<()>

Split a previously merged cell.

Source

pub fn set_table_format( &self, table_id: usize, format: &TableFormat, ) -> Result<()>

Set formatting on a table.

Source

pub fn set_table_cell_format( &self, cell_id: usize, format: &CellFormat, ) -> Result<()>

Set formatting on a table cell.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn is_cell_selection(&self) -> bool

Returns true when the current selection involves whole-cell selection.

Source

pub fn selected_cell_range(&self) -> Option<CellRange>

Returns the rectangular cell range if the cursor has a cell selection.

Source

pub fn selected_cells(&self) -> Vec<TableCellRef>

Returns all cells in the selected rectangular range.

Source

pub fn select_table_cell(&self, table_id: usize, row: usize, col: usize)

Set an explicit single-cell selection override.

Source

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.

Source

pub fn clear_cell_selection(&self)

Clear any cell-selection override without changing position/anchor.

Source

pub fn delete_char(&self) -> Result<()>

Delete the character after the cursor (Delete key).

Source

pub fn delete_previous_char(&self) -> Result<()>

Delete the character before the cursor (Backspace key).

Source

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.

Source

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.

Source

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.

Source

pub fn insert_list(&self, style: ListStyle) -> Result<()>

Insert a new list item at the cursor position.

Source

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).

Source

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.

Source

pub fn add_block_to_list(&self, block_id: usize, list_id: usize) -> Result<()>

Add a block to a list by their IDs.

Source

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.

Source

pub fn remove_block_from_list(&self, block_id: usize) -> Result<()>

Remove a block from its list by block ID.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn set_char_format(&self, format: &TextFormat) -> Result<()>

Set the character format for the selection.

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.

Source

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.

Source

pub fn merge_char_format(&self, format: &TextFormat) -> Result<()>

Merge a character format into the selection.

Source

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.

Source

pub fn set_frame_format( &self, frame_id: usize, format: &FrameFormat, ) -> Result<()>

Set the frame format.

Source

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.

Source

pub fn end_edit_block(&self)

End the current edit block.

Source

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

Source

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.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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).

Source

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.

Source

pub fn recorded_anchor(&self) -> usize

Where the cursor’s anchor is in the document as recorded, as recorded_position says of its position.

Trait Implementations§

Source§

impl Clone for TextCursor

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.