Add docs for Painter & Controller

[cmyr]

This is the first part of the major section going over custom
widgets and the general widget model.

[luleyleo]

Looks like a good start!
I think I got a realistic example for the use of Controller 😄
(Plus one nit pick)

[luleyleo]

Maybe move the part in braces after the example, makes the reading flow a bit nicer.

[luleyleo]

This is what came to my mind based on #787 .
A TextBox that fires an action (e.g. for search) when hitting enter or 300 ms after the last key press.

const ACTION: Selector = Selector::new("hello.textbox-action");

struct TextBoxActionController {
    timer: Option<TimerToken>,
}

impl TextBoxActionController {
    pub fn new() -> Self {
        TextBoxActionController { timer: None }
    }

    // Fire ACTION after 300 ms
    fn deadline() -> Instant {
        Instant::now() + Duration::from_millis(300)
    }
}

impl Controller<String, TextBox> for TextBoxActionController {
    fn event(
        &mut self,
        child: &mut TextBox,
        ctx: &mut EventCtx,
        event: &Event,
        data: &mut String,
        env: &Env,
    ) {
        match event {
            Event::KeyDown(k) if k.key_code == KeyCode::Return => {
                ctx.submit_command(ACTION, None);
            }
            Event::KeyUp(k) if k.key_code != KeyCode::Return => {
                self.timer = Some(ctx.request_timer(Self::deadline()));
                child.event(ctx, event, data, env);
            }
            Event::Timer(token) if Some(*token) == self.timer => {
                ctx.submit_command(ACTION, None);
            }
            _ => child.event(ctx, event, data, env),
        }
    }
}

[cmyr]

thanks, I've changed the example to this.

[luleyleo]

I think going just with the constant in the example is enough

[luleyleo]

I was not sure my suggestions made it as my internet died the very moment I pressed 'submit review' but looks like I was lucky 😅

[xStrom]

Always good to have better docs!