Struct Cursor 

pub struct Cursor<'w, W: Widget + ?Sized = Buffer> { /* private fields */ }

A selection that can edit Text, but can’t alter selections.

This struct will be used only inside functions passed to the edit_* family of methods from the Handle.

To make edits, you can use three different functions. You can, those being replace, insert, and append. replace will completely replace the Selection’s selection. insert will place text behind the caret, and append will place it after the caret.

You can also move the Selection’s selection in many different ways, which are described below, in the impl section for this struct.

let sel = handle.edit_main(&mut pa, |mut c| {
    c.set_anchor();
    c.set_caret_on_end();
    c.replace("my replacement");
    c.append(" and my edit");

    c.swap_ends();
    c.insert("This is ");
    c.swap_ends();

    c.move_hor(" and my edit".chars().count() as i32);
    c.set_anchor();
    c.move_hor(-("This is my replacement and my edit".chars().count() as i32));
    c.selection().to_string()
});

assert_eq!(&sel, "This is my replacement and my edit");

Implementations

impl<'w, W: Widget + ?Sized> Cursor<'w, W>

pub fn replace(&mut self, edit: impl ToString)

Replaces the entire selection with new text.

If there is a selection, then it is treated as inclusive, therefore, a selection where caret == anchor will remove the character where the caret is. If there is no selection, then this has the same effect as insert. If you wish to append to the caret instead, see append.

After replacing the sele tion, if the caret is behind the anchor (or in the same spot), it will be placed on the start of the selection, while the anchor will be placed on the new end. If it is ahead, it will be placed ahead.

pub fn insert(&mut self, edit: impl ToString)

Inserts new text directly behind the caret.

If the anchor is ahead of the caret, it will move forwards by the number of chars in the new text.

If you wish to replace the selected text, see replace, if you want to append after the caret instead, see append

pub fn append(&mut self, edit: impl ToString)

Appends new text directly after the caret.

If the anchor is ahead of the caret, it will move forwards by the number of chars in the new text.

If you wish to replace the selected text, see replace, if you want to insert before the caret instead, see insert

pub fn move_hor(&mut self, by: i32) -> i32

Moves the selection horizontally. May cause vertical movement.

Returns the distance traveled, in character indices

pub fn move_ver(&mut self, by: i32) -> bool

Moves the selection vertically. May cause horizontal movement.

Returns true if the caret actually moved at all.

pub fn move_ver_wrapped(&mut self, count: i32) -> bool

Moves the selection vertically a number of wrapped lines. May cause horizontal movement.

Returns true if the caret actually moved at all.

pub fn move_to(&mut self, point_or_points: impl CaretOrRange)

Moves the selection to a Point or a range of Points.

If you give it just a Point, it will move the caret, without affecting the anchor. If you give it a range of Points, the anchor will be placed at the start, while the caret will be placed at the end of said range. You can flip those positions with a function like swap_ends.

If a Point is not valid, it will be corrected and clamped to the lenght of the Text.

pub fn move_to_start(&mut self)

Moves the selection to Point::default, i.c., the start of the Text.

pub fn move_to_coords(&mut self, line: usize, column: usize)

Moves the selection to a line and a column.

• If the coords isn’t valid, it will move to the “maximum” position allowed.

pub fn move_to_col(&mut self, column: usize)

Moves to a column on the current line.

pub fn unset_anchor(&mut self) -> Option<Point>

Returns and takes the anchor of the Selection, if there was one.

pub fn set_anchor(&mut self)

Sets the anchor to the current caret.

pub fn set_anchor_if_needed(&mut self) -> bool

Sets the anchor if it was not already set.

Returns true if the anchor was set by this command.

pub fn swap_ends(&mut self)

Swaps the position of the caret and anchor.

pub fn set_caret_on_start(&mut self) -> bool

Sets the caret of the Selection on the start of the selection.

Returns true if a swap occurred

pub fn set_caret_on_end(&mut self) -> bool

Sets the caret of the Selection on the end of the selection.

Returns true if a swap occurred

pub fn reset(&mut self)

Resets the Selection to how it was before being modified.

pub fn copy(&mut self) -> Cursor<'_, W>

Copies the current Selection in place.

This will leave an additional Selection with the current selection. Do note that normal intersection rules apply, so if at the end of the movement, this selection intersects with any other, they will be merged into one.

When this Cursor is dropped, like with normal Cursors, its Selection will be added to the Selections, unless you destroy it.

pub fn destroy(self)

Destroys the current Selection.

Will not destroy it if it is the last Selection left

If this was the main selection, the main selection will now be the selection immediately behind it.

pub fn set_desired_vcol(&mut self, x: usize)

Sets the “desired visual column”.

The desired visual column determines at what point in a line the caret will be placed when moving up and down through lines of varying lengths.

Will also set the “desired wrapped visual column”, which is the same thing but used when moving vertically in a wrapped fashion.

pub fn matches_pat<R: RegexPattern>(&self, pat: R) -> bool

Wether the current selection matches a regex pattern.

pub fn search<R: RegexPattern>(&self, pat: R) -> CursorMatches<'_, R>

Returns an Iterator over the matches of a RegexPattern.

This Iterator normally covers the entire range of the Text, however, there are methods that you can use to narrow it down to ranges relative to the Cursor’s caret.

For example, CursorMatches::from_caret will narrow the searched range from the beginning of the caret’s char all the way until the end of the Text.

This Iterator also implements DoubleEndedIterator, which means you can search in reverse as well.

pub fn char(&self) -> char

Returns the char in the caret.

pub fn char_at(&self, i: impl TextIndex) -> Option<char>

Returns the char at a given Point.

pub fn selection(&self) -> &Strs

Returns the Selection’s selection.

The reason why this return value is IntoIter<&str, 2> is because the Text utilizes an underlying GapBuffer to store the characters. This means that the text is always separated into two distinct chunks.

If this Selection’s selection happens to be entirely within one of these chunks, the other &str will just be empty.

pub fn strs(&self, range: impl TextRange) -> &Strs

Returns the Strs for the given [TextRange].

Panics

Panics if the range doesn’t start and end in valid utf8 boundaries. If you’d like to handle that scenario, check out Cursor::try_strs.

pub fn try_strs(&self, range: impl TextRange) -> Option<&Strs>

Returns the Strs for the given [TextRange].

It will return None if the range does not start or end in valid utf8 boundaries. If you expect the value to alway be Some, consider Cursor::strs isntead.

pub fn len(&self) -> Point

Returns the length of the Text, in Point.

pub fn last_point(&self) -> Point

Returns the position of the last char if there is one.

pub fn indent(&self) -> usize

Gets the current level of indentation.

pub fn indent_on(&self, line: usize) -> usize

Gets the indentation level on a given line.

This is the total “amount of spaces”, that is, how many ' ' character equivalents are here. This depends on your PrintOpts because of the tabstop field.

pub fn caret(&self) -> Point

Returns the caret.

pub fn anchor(&self) -> Option<Point>

Returns the anchor.

pub fn range(&self) -> Range<Point>

The Point range of the Selection.

This is an inclusive range (not Rust’s RangeInclusive however), this means that, even if there is no anchor, the lenght of this range will always be at least 1.

If you want an exclusive range, see Cursor::range_excl.

pub fn range_excl(&self) -> Range<Point>

An exclusive Point range of the Selection.

If you wish for an inclusive range, whose length is always greater than or equal to 1, see RangeInclusive.

pub fn v_caret(&self) -> VPoint

The VPoint range of the Selection.

Use only if you need the things that the VPoint provides, in order to preven extraneous calculations.

pub fn v_anchor(&self) -> Option<VPoint>

The VPoint of the anchor, if it exists.

Use only if you need the things that the VPoint provides, in order to preven extraneous calculations.

pub fn anchor_is_start(&self) -> bool

Returns true if the anchor exists before the caret.

pub fn is_main(&self) -> bool

Whether or not this is the main Selection.

pub fn text(&self) -> &Text

The Text of the Widget.

pub fn opts(&self) -> PrintOpts

The PrintOpts in use.

pub fn widget(&self) -> &W

The Widget being modified.

impl Cursor<'_, Buffer>

pub fn buffer_id(&self) -> BufferId

A unique identifier for this Buffer.

This is more robust than identifying it by its path or name, or even PathKind, since those could change, but this cannot.

Trait Implementations

impl<'a, W: Widget + ?Sized> Debug for Cursor<'a, W>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.