Struct Cursor

pub struct Cursor<'a, W: Widget<A::Ui>, A: RawArea, S> { /* 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: String = 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().into_iter().collect()
});

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

Implementations

impl<'a, W: Widget<A::Ui>, A: RawArea, S> Cursor<'a, W, A, S>

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

Replaces the entire selection with new text

If the caret is behind the anchor (or in the same spot), after replacing the selection, the caret 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.

If there is no selection, then this has the same effect as insert. If you wish to append to the caret instead, see append.

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, count: i32) -> i32

Moves the selection horizontally. May cause vertical movement

Returns the distance moved in chars.

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

Moves the selection vertically. May cause horizontal movement

Returns the distance moved in lines.

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

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

Returns the distance moved in wrapped lines.

pub fn move_to(&mut self, point: Point)

Moves the selection to a Point

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

pub fn move_to_start(&mut self)

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

pub fn move_to_coords(&mut self, line: usize, col: 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 unset_anchor(&mut self) -> Option<Point>

Returns and takes the anchor of the Selection.

pub fn set_anchor(&mut self)

Sets the anchor to the current caret

pub fn set_anchor_if_needed(&mut self)

Sets the anchor if it was not already set

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, A, S>

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 chars_fwd(&self) -> impl Iterator<Item = (Point, char)> + '_

Iterates over the chars

This iteration will begin on the caret. It will also include the Point of each char

pub fn chars_rev(&self) -> impl Iterator<Item = (Point, char)> + '_

Iterates over the chars, in reverse

This iteration will begin on the caret. It will also include the Point of each char

pub fn search_fwd<R: RegexPattern>( &mut self, pat: R, end: Option<Point>, ) -> impl Iterator<Item = R::Match> + '_

Searches the Text for a regex

The search will begin on the caret, and returns the bounding Points, alongside the match. If an end is provided, the search will stop at the given Point.

Panics

If the regex is not valid, this method will panic.

fn search_nth_paren<U: Ui, S>(pa: &mut Pass, handle: &mut Handle<File<U>, U, S>, n: usize) {
    handle.edit_all(pa, |mut e| {
        let mut nth = e.search_fwd('(', None).nth(n);
        if let Some([p0, p1]) = nth {
            e.move_to(p0);
            e.set_anchor();
            e.move_to(p1);
        }
    })
}

pub fn search_rev<R: RegexPattern>( &mut self, pat: R, start: Option<Point>, ) -> impl Iterator<Item = R::Match> + '_

Searches the Text for a regex, in reverse

The search will begin on the caret, and returns the bounding Points, alongside the match. If a start is provided, the search will stop at the given Point.

Panics

If the regex is not valid, this method will panic.

fn search_nth_paren<U: Ui, S>(
    pa: &mut Pass,
    handle: &mut Handle<File<U>, U, S>,
    s: &str,
    n: usize,
) {
    handle.edit_all(pa, |mut e| {
        let mut nth = e.search_rev(s, None).nth(n);
        if let Some([p0, p1]) = nth {
            e.move_to(p0);
            e.set_anchor();
            e.move_to(p1);
        }
    })
}

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

Wether the current selection matches a regex pattern

pub fn char(&self) -> char

Returns the char in the caret

pub fn char_at(&self, p: Point) -> 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 contiguous_in(&mut self, range: impl TextRange) -> &str

Shifts the gap within the GapBuffer in order to return a contiguous &str

pub fn len(&self) -> Point

Returns the length of the Text, in Point

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

Returns the position of the last char if there is one

pub fn lines_on(&mut self, range: impl TextRange) -> Lines<'_>

An Iterator over the lines in a given range

pub fn indent(&self) -> usize

Gets the current level of indentation

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

Gets the indentation level on the given Point

pub fn caret(&self) -> Point

Returns the caret

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

Returns the anchor

pub fn range(&self) -> [Point; 2]

The Point range of the Selection

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 cfg(&self) -> PrintCfg

The PrintCfg in use

impl<U: Ui, S> Cursor<'_, File<U>, U::Area, S>

pub fn read_bytes_and_reader<R: Reader<U>, Ret>( &self, f: impl FnOnce(&Bytes, &R) -> Ret, ) -> Option<Ret>

Reads the Bytes and a Reader

impl<W: Widget<A::Ui>, A: RawArea> Cursor<'_, W, A, Searcher>

Incremental search functions, only available on IncSearchers

pub fn search_inc_fwd( &mut self, end: Option<Point>, ) -> impl Iterator<Item = [Point; 2]> + '_

Search incrementally from an IncSearch request

This will match the Regex pattern from the current position of the caret. if end is Some, the search will end at the requested Point.

pub fn search_inc_rev( &mut self, start: Option<Point>, ) -> impl Iterator<Item = [Point; 2]> + '_

Search incrementally from an IncSearch request in reverse

This will match the Regex pattern from the current position of the caret in reverse. if start is Some, the search will end at the requested Point.

pub fn matches_inc(&mut self) -> bool

Whether the Selection’s selection matches the IncSearch request

Trait Implementations

impl<'a, W: Widget<A::Ui> + 'a, A: RawArea + 'a, S: 'a> Drop for Cursor<'a, W, A, S>

fn drop(&mut self)

Executes the destructor for this type.