Struct FileBuilder

Source

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

Expand description

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: &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: &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: &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 CmdLine to the bottom.
    builder.push(CmdLine::cfg());
});

Implementations§

Source §

impl FileBuilder
where U: Ui,

Source

pub fn push<W: Widget>( &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: &FileBuilder<U>| {
    let line_numbers_cfg = LineNumbers::cfg().rel_abs();
    builder.push(line_numbers_cfg);

    let status_line_cfg = status!({ File::name } " " selections_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.

Source

pub fn push_to<W: Widget>( &self, cfg: impl WidgetCfg<U, Widget = W>, area: U::Area, ) -> (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 paralel to each other, yet on the same edge.

One example of where you might want to do this is if you want to have multiple StatusLines in a single File, each showing their own distinct information:

hooks::remove("FileWidgets");
hooks::add::<OnFileOpen<U>>(|builder: &FileBuilder<U>| {
    builder.push(LineNumbers::cfg());
     
    let right_status = status!(
        { File::name } " " selections_fmt " " main_fmt
    );
    let (right_status_area, _) = builder.push(right_status);

    let left_status = status!(mode_fmt).push_left();
    builder.push_to(left_status, right_status_area);

    builder.push(CmdLine::cfg());
});