Struct FileBuilder

pub struct FileBuilder<U: Ui> { /* private fields */ }

A constructor helper for File initiations

This helper is used primarily to push widgets around the file in question, and is only obtainable in a OnFileOpen hook:

hooks::add::<OnFileOpen<U>>(|builder: &mut FileBuilder<U>| {
    builder.push(LineNumbers::cfg());
});

In the example above, I pushed a LineNumbers widget to the File. By default, this widget will go on the left, but you can change that:

hooks::add::<OnFileOpen<U>>(|builder: &mut FileBuilder<U>| {
    let line_numbers_cfg = LineNumbers::cfg().relative().on_the_right();
    builder.push(line_numbers_cfg);
});

Note that I also made another change to the widget, it will now show relative numbers, instead of absolute, like it usually does.

By default, there already exists a hook group that adds widgets to a file, the "FileWidgets" group. If you want to get rid of this group in order to create your own widget layout, you should use hooks::remove:

hooks::remove("FileWidgets");
hooks::add::<OnFileOpen<U>>(|builder: &mut FileBuilder<U>| {
    let line_numbers_cfg = LineNumbers::cfg().relative().on_the_right();
    builder.push(line_numbers_cfg);
    // Push a StatusLine to the bottom.
    builder.push(StatusLine::cfg());
    // Push a PromptLine to the bottom.
    builder.push(PromptLine::cfg());
});

Implementations

impl<U: Ui> FileBuilder<U>

pub fn push<W: Widget<U>>( &mut self, cfg: impl WidgetCfg<U, Widget = W>, ) -> (U::Area, Option<U::Area>)

Pushes a widget to the main area of this File

This widget will be a satellite of the file. This means that, if the file is destroyed, the widget will be destroyed as well, if it is moved, the widget will be moved with it, etc.

When you push a widget, it is placed on the edge of the file. The next widget is placed on the edge of the area containing the file and the previous widget, and so on.

This means that, if you push widget A to the left of the file, then you push widget B to the bottom of the window, you will get this layout:

╭───┬──────────╮
│   │          │
│ A │   File   │
│   │          │
├───┴──────────┤
│      B       │
╰──────────────╯

Here’s an example of such a layout:

hooks::remove("FileWidgets");
hooks::add::<OnFileOpen<U>>(|builder: &mut FileBuilder<U>| {
    let line_numbers_cfg = LineNumbers::cfg().rel_abs();
    builder.push(line_numbers_cfg);

    let status_line_cfg = status!(file_fmt " " selections_fmt " " main_fmt);
    builder.push(status_line_cfg);
});

In this case, each file will have LineNumbers with relative/absolute numbering, and a StatusLine showing the file’s name and how many selections are in it.

pub fn push_to<W: Widget<U>>( &self, area: U::Area, cfg: impl WidgetCfg<U, Widget = W>, ) -> (U::Area, Option<U::Area>)

Pushes a widget to a specific area around a File

This method can be used to get some more advanced layouts, where you have multiple widgets parallel to each other, yet on the same edge.

One of the main ways in which this is used is when using a hidden Notifier widget alongside the PromptLine widget.

hooks::remove("FileWidgets");
hooks::add::<OnFileOpen<U>>(|builder: &mut FileBuilder<U>| {
    builder.push(LineNumbers::cfg());
     
    let (child, _) = builder.push(
        status!(file_fmt " " selections_fmt " " main_fmt)
    );
    let (child, _) = builder.push_to(child, PromptLine::cfg().left_ratioed(3, 5));
    builder.push_to(child, Notifier::cfg());
});

Pushing directly to the PromptLine’s Area means that they’ll share a parent that holds only them. This can then be exploited by the "HidePromptLine" hook group, which is defined as:

hooks::add_grouped::<UnfocusedFrom<PromptLine<Ui>, Ui>>("HidePromptLine", |(_, area)| {
    area.constrain_ver([Constraint::Len(0.0)]).unwrap();
});
hooks::add_grouped::<FocusedOn<PromptLine<Ui>, Ui>>("HidePromptLine", |(_, area)| {
    area.constrain_ver([Constraint::Ratio(1, 1), Constraint::Len(1.0)])
        .unwrap();
});

pub fn add_reader(&mut self, reader_cfg: impl ReaderCfg) -> Result<(), Text>

Adds a Reader to this File

Readers read changes to Text and can act accordingly by adding or removing Tags from it. They can also be accessed via a public API, in order to be used for other things, like the treesitter Reader, which, internally, creates the syntax tree and does syntax highlighting, but externally it can also be used for indentation of Text by Modes

pub fn read(&mut self) -> (ReadDataGuard<'_, File>, &U::Area)

The File that this hook is being applied to

pub fn write(&mut self) -> (WriteFileGuard<'_, U>, &U::Area)

Mutable reference to the File that this hooks is being applied to

Trait Implementations

impl<U: Ui> Drop for FileBuilder<U>

fn drop(&mut self)

Executes the destructor for this type.