Struct WindowBuilder

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

A constructor helper for window initiations

This helper is used primarily to push widgets around the window, surrounding the “main area” which contains all Files and widgets added via the OnFileOpen hook.

It is used whenever the OnWindowOpen hook is triggered, which happens whenever a new window is opened:

setup_duat!(setup);
use duat::prelude::*;

fn setup() {
    hook::add::<OnWindowOpen>(|pa, builder| {
        // Push a StatusLine to the bottom.
        builder.push(pa, StatusLine::cfg());
        // Push a PromptLine to the bottom.
        builder.push(pa, PromptLine::cfg());
    });
}

Contrast this with the example in the FileBuilder docs, where a similar hook is added, but with OnFileOpen instead of OnWindowOpen. In that scenario, the widgets are added to each file that is opened, while in this one, only one instance of these widgets will be created per window.

The existence of these two hooks lets the user make some more advanced choices on the layout:

setup_duat!(setup);
use duat::prelude::*;

fn setup() {
    hook::remove("FileWidgets");
    hook::add::<OnFileOpen>(|pa, builder| {
        builder.push(pa, LineNumbers::cfg());
        builder.push(pa, StatusLine::cfg());
    });

    hook::remove("WindowWidgets");
    hook::add::<OnWindowOpen>(|pa, builder| {
        builder.push(pa, PromptLine::cfg());
    });
}

In this case, each file gets a StatusLine, and the window will get one PromptLine, after all, what is the point of having more than one command line?

You can go further with this idea, like a status line on each file, that shows different information from the status line for the whole window, and so on and so forth.

Implementations

impl<U: Ui> WindowBuilder<U>

pub fn push<W: WidgetAlias<U, impl BuilderDummy>>( &mut self, pa: &mut Pass, widget: W, ) -> (U::Area, Option<U::Area>)

Pushes a widget to an edge of the window, given a cfg

This widget will be pushed to the “main” area, i.e., the area that contains all other widgets. After that, the widget’s parent will become the main area, which can be pushed onto again.

This means that, if you push widget A to the right of the window, then you push widget B to the bottom of the window, and then you push widget C to the left of the window,you will end up with something like this:

╭───┬───────────┬───╮
│   │           │   │
│   │ main area │ A │
│ C │           │   │
│   ├───────────┴───┤
│   │       B       │
╰───┴───────────────╯

This method returns the Area created for this widget, as well as an Area for the parent of the two widgets, if a new one was created.

pub fn push_to<W: WidgetCfg<U>>( &mut self, pa: &mut Pass, area: U::Area, cfg: W, ) -> (U::Area, Option<U::Area>)

Pushes a widget to a specific area

Unlike push, this method will push the widget to an area that is not the main area. This can be used to create more intricate layouts.

For example, let’s say I push a StatusLine below the main area, and then I push a PromptLine on the left of the status’s area:

setup_duat!(setup);
use duat::prelude::*;

fn setup() {
    hook::add::<OnWindowOpen>(|pa, builder| {
        // StatusLine goes below by default
        let (status_area, _) = builder.push(pa, StatusLine::cfg());
        let prompt_cfg = PromptLine::cfg().left_ratioed(3, 5);
        builder.push_to(pa, status_area, prompt_cfg);
    });
}

The following would happen:

╭────────────────────────────────────╮
│                                    │
│              main area             │
│                                    │
├─────────────┬──────────────────────┤
│ PromptLine  │      StatusLine      │
╰─────────────┴──────────────────────╯

This is the layout that Kakoune uses by default, and is also avaliable as commented option in the default config.

Trait Implementations

impl<U: Ui> UiBuilder<U> for WindowBuilder<U>

fn push_cfg<W: WidgetCfg<U>>( &mut self, pa: &mut Pass, cfg: W, ) -> (U::Area, Option<U::Area>)

Pushes a Widget to this UiBuilder, on its main U::Area

fn push_cfg_to<W: WidgetCfg<U>>( &mut self, pa: &mut Pass, area: U::Area, cfg: W, ) -> (U::Area, Option<U::Area>)

Pushes a Widget to this UiBuilder, on a given U::Area