[Snowcap] Composable Program feedback

[Ph4ntomas]

I've been busy porting Glacier to the composable programs. Here are some thought/feedback from using it more than the toy tests during the Review, before pushing for upstreaming stuff.

I have some auto-hiding widgets (e.g. the prompt, various text box). I'd much prefer if they were able to return None when there's nothing to view. (I've open #427 then #428, but I'll present some thought after the overall feedback)

Right now, the plugins can opt-in to have full, constant access to the handle. This means they have 2 channels to send messages, (through signals and through the handle messages). It also causes some issues with separation of responsibility.
As an example, when activating a prompt, the widget need to be focused and the layer need to get keyboard interactivity. In my previous iteration, there was a separate Widget trait, which acted as a program-light which did not keep access to the surface outside of the update function (and even then it was only used for popup). This meant the prompt needed to forward the focus request to the Program hosting it, which then used the surface handle to focus & take keyboard interactivity. With the new design, both the 'toplevel' Program and any of it's subprogram may act on the handle to change focus & interactivity, and there's nothing to prevent that.

The UniversalMessage object & Universal trait could be improved a bit for use in toplevel program. I have a few messages handled both by the toplevel Program & the widget (e.g. for focus management), meaning my bar need to clone every universal messages to probe whether it might need to be handled or not. IMO we either need a way to test the message type (is<T>() -> bool), or to access the message content as a reference (downcast_ref<T>() -> Option<&T>)

It might be because I haven't had enough time to play with it but I feel having the same trait for both 'toplevel' program that are tightly integrated with the surface they're on and 'hosted' may lead to some issue down the line with incompatible 'hosted programs' because they expect the toplevel to act a certain way.

Some closing thought:

IMO we could improve some of this by having a Program-like trait hosted::Program, with the following changes:

• SurfaceHandle would be replaced by a more restrictive/weak type (hosted::SurfaceHandle), so the hosted::Program can't just access the raw handle.
• some of hosted::SurfaceHandle methods wouldn't be applied to the underlying handle, but instead bubbled-up to the hosting Program (e.g. operate, close). Less critical ones may be kept as-is (e.g. send_message, force_redraw). (Note: critical methods like operate & close could be replaced by signal, too).
• hosted::Program::view doesn't have to return a WidgetDef (instead of merging snowcap: Make Program::view return an option #428).
• hosted::Program can be composed from other hosted::Program only. Program may decide to forward call to the Program trait to other Program, and should otherwise properly call hosted::Program functions.
• hosted::Program are surface-agnostics and Program agnostic, while Program may access the raw Handle that was passed during the created call.
• standard hosted::Program are expected to use UniversalMessages. Standard Program should if they are also hosted::Program.
• standard Program may also define their own Message type for when they're not hosted. Their custom message type must be convertible from Universal. Example use case: a Bar may an hypotetical "HideBar" which it can only use in hosting mode. When hosted, it must abide by the hosting Program Message, meaning it can't make use of it. Regardless, it must handle the UniversalMessage to forward them to its children.

This proposal shouldn't hurt composability, as Program could also implement hosted::Program and re-use most of the code but wouldn't mess with the toplevel Program expectations when hosted. Host-only program can be more tightly integrated with their surface and ensure correct behavior (e.g. focus-arbitration if the user hit tab or escape, correct order of operation if a widget discard focus while another-one has it, etc.). Hosted-only Program can be written with some expectation about the behavior of the host Program.

@Ottatop Sorry I did not spot these issue during the review. Let me know if you're interested in some POC implementation.

[Ph4ntomas]

Just to add some additional context on why host::Program::view returning None is useful:

It's useful for widget that don't have to be shown all of the time. The parent widget handles the layout of several widget that may not all be relevant at that point. An empty row still has presence in the tree: if the parent widget is laying a Row with spacing, displaying one element alone is not the same as displaying an element + two empty row + 2x spacing.

As a small example: I have two prompt and a textbox in my bar central area. If I must return an empty row to hide them, the parent widget may render this as [][promp][], instead of the more logical [prompt].

#427 (comment)

[Ottatop]

With the new design, both the 'toplevel' Program and any of it's subprogram may act on the handle to change focus & interactivity, and there's nothing to prevent that.

Hm that's a good point.

I feel having the same trait for both 'toplevel' program that are tightly integrated with the surface they're on and 'hosted' may lead to some issue down the line with incompatible 'hosted programs' because they expect the toplevel to act a certain way.

(From #427:) I think I would prefer a clearer separation between program able to act as toplevel (for those it makes sense to enforce some widget to be returned) and programs meant only as hosted widgets.

I feel the opposite way, actually—imo programs should be written to be surface-agnostic. I want to allow wacky things like putting a whole taskbar in a decoration, for example.

I think to address these points we should look towards abstracting core parts of each surface. Honestly, we might even want to not provide handles entirely and just create signals like there are in Glacier and like you mentioned.

pub struct Operation(widget::Operation);
pub struct RequestClose;
// other stuff

There's still a problem when multiple subprograms want to change the focus state simultaneously. I propose the following signals:

pub struct RequestGrabFocus {
    id: String, // or some other type
}
pub struct RequestUngrabFocus {
    id: String, // or some other type
}

For now only a layer would handle these, setting its KeyboardExclusivity to Exclusive when grabbed and whatever it was previously when ungrabbed. A HashSet is used to track grabs.

The UniversalMessage object & Universal trait could be improved a bit for use in toplevel program. I have a few messages handled both by the toplevel Program & the widget (e.g. for focus management), meaning my bar need to clone every universal messages to probe whether it might need to be handled or not. IMO we either need a way to test the message type (is<T>() -> bool), or to access the message content as a reference (downcast_ref<T>() -> Option<&T>)

Yea, it's probably a good idea to provide external handling of the opaque message for non-generic programs. I'll implement this shortly.

IMO we could improve some of this by having a Program-like trait hosted::Program, with the following changes:

I'm concerned that we're introducing another level/bit of complexity here. Not only that, but it creates a dichotomy between programs that can and can't be used at the top level, and likewise programs that can and can't be used as subprograms. I don't really want that.

Moving towards surface-agnostic programs by removing handles altogether is a possible path forward. Let me know your thoughts.

[Ph4ntomas]

I think to address these points we should look towards abstracting core parts of each surface. Honestly, we might even want to not provide handles entirely and just create signals like there are in Glacier and like you mentioned.

This causes an issue with popup, since we'd need to bubble up the Popup Program via signal, and the handle via Message (but I guess a weak-ish handle passed on update would do the trick). There's nothing wrong in moving the popup program around, but it felt weird to have to do so.

I'm concerned that we're introducing another level/bit of complexity here. Not only that, but it creates a dichotomy between programs that can and can't be used at the top level, and likewise programs that can and can't be used as subprograms. I don't really want that.

Moving towards surface-agnostic programs by removing handles altogether is a possible path forward. Let me know your thoughts.

My understanding is that you'd push focus arbitration & signal handling (and maybe other stuff) to the surface handle. I think it would address most issues I raised, but I also feel it remove a bit of flexibility.

Having that dichotomy means the toplevel Object can decide how to handle standard signals, and it can add its own signal/operation/messages without the need to change pinnacle code. (This can still be done using the same handle capture trick I did in Glacier, but I'd prefer a standardized way to customize that behavior).

Not only that, but it creates a dichotomy between programs that can and can't be used at the top level,

I don't think that's much of a concern. Most programs are meant to be hosted and shouldn't care about their parent or the surface they're on. I don't think it will make much of a difference if the parent is the SurfaceHandle ot a toplevel Program. I mean you can run a prompt as a toplevel, but a default Program could just wrap it to handle focus & operation. I don't think it make much of a difference.

and likewise programs that can and can't be used as subprograms.

This can solved by making Program a subtrait of hosted::Program. All Program must be able to be hosted, but some can get additional feature when tightly integrated to their surface

Let me know your thoughts.

I agree that we should make Program surface agnostic, but I'd prefer having some way to define/override the surface behavior instead of folding it in the handle. We could then provide a default implementation, but let user-code override it if needed.

[Ottatop]

This causes an issue with popup, since we'd need to bubble up the Popup Program via signal, and the handle via Message (but I guess a weak-ish handle passed on update would do the trick). There's nothing wrong in moving the popup program around, but it felt weird to have to do so.

I'm gonna be real I completely forgot that was the main reason we're providing the handle in the first place 😅. Maybe just an opaque parent handle is better.

Having that dichotomy means the toplevel Object can decide how to handle standard signals, and it can add its own signal/operation/messages without the need to change pinnacle code.

How useful is this, though? I believe it's already possible to handle signals from child programs by intercepting them instead of forwarding to the surface. Same thing with custom stuff: nothing has to reach the surface to be used. Or maybe I don't understand what you mean by "handle".

All Program must be able to be hosted, but some can get additional feature when tightly integrated to their surface

This is the kind of coupling that I don't want, frankly. A program that has surface-specific handling should be split into the program and the handler.

I'd prefer having some way to define/override the surface behavior instead of folding it in the handle. We could then provide a default implementation, but let user-code override it if needed.

I suppose this is one way to go about doing that. Instead of programs with toplevel-specific quirks or delegating everything to hard-coded surface implementations, we could move surface handling out of the program and handle and into some interface. Not sure how that's gonna look like.

Realistically though, all of this introduces some level of complexity that makes the whole API a bit more cumbersome. What use cases are there for custom surface handlers?

[Ph4ntomas]

Maybe just an opaque parent handle is better.

I think that would work. It enforce a single stream for sending messages/operation. What methods are defined on that handle can be tweaked down the line, too.

How useful is this, though? I believe it's already possible to handle signals from child programs by intercepting them instead of forwarding to the surface. Same thing with custom stuff: nothing has to reach the surface to be used. Or maybe I don't understand what you mean by "handle".

Ah yeah you're right. A Program can intercept signals, convert them to a "SendMessage", and deal with the side effect during update. I did not think of that. (Same goes for Messages, nothing forces the Program to forward them it they are only meant for it)

I suppose this is one way to go about doing that. Instead of programs with toplevel-specific quirks or delegating everything to hard-coded surface implementations, we could move surface handling out of the program and handle and into some interface. Not sure how that's gonna look like.

Realistically though, all of this introduces some level of complexity that makes the whole API a bit more cumbersome. What use cases are there for custom surface handlers?

I see at least a case for overriding focus arbitration. There are several way to deal with focus. You can send an Unfocus message to every widget when a new one request it, or you can maintain an IndexSet of focused widget so the Unfocus action actually transfers the focus back to the previous widget that had it. Both have their pros & cons depending on the context, and I don't think of a clean way to have a one-size fit all implementation folded into the handle.

Another thing I had at some point in "Glacier" (well it might be before I split it from my config) was to allow widgets to register hooks on keyboard events, or grab it altogether. It was useful before TextInput was merged because my prompts were 3 texts in a trench coat (pre-cursor|cursor|post-cursor). It worked by temporarily swapping the callback, which requires access to the raw handle and knowledge that that handle support keyboard interactivity.
There is one remnant of this as the Bar still have a keyboard handling function to handle "Escape" to close active widget and give back keyboard interactivity (which ties back to the previous point), but I would prefer some standard way of overriding/extending the default behavior.

TBH I don't know how useful that would be. The keyboard trick can still be managed by the object creating the layer, and I can think of e few workaround for the focus management (e.g. when a Focus signal is seen, emit a first "unfocus all" signal/message then forward the Focus). I feel that would make some Program more complex than they need to be tho, since they would have to deal with some stuff just to bypass the underlying surface behavior.

[Ottatop]

I see at least a case for overriding focus arbitration. There are several way to deal with focus. You can send an Unfocus message to every widget when a new one request it, or you can maintain an IndexSet of focused widget so the Unfocus action actually transfers the focus back to the previous widget that had it.

Is a focus stack actually useful here? I don't see the use case within a single surface, and otherwise you'd open other surfaces and let the compositor deal with surface focus.

Another thing I had at some point in "Glacier" (well it might be before I split it from my config) was to allow widgets to register hooks on keyboard events, or grab it altogether.

Hooks feel like per-program keybinds, which makes me believe that we need to nail down the focus model before thinking about them. Currently only individual widgets like TextInput are focusable, but maybe we want to extend this idea to focusable programs. Honestly though, iced has "Centralized focus management" as a goal for 0.15 and I feel like we should wait for that first. There's also accessibility to think about but iced has been stalled on that front for a while.

Throwing some ideas out here, there's possibly the idea of making some programs additionally return a "program handle" that allows people to bind keys to actions on those handles. Like Awesome has mod+r bound to prompt:run() for example. Unfortunately that's not a mechanism to define default behavior like Escape to close a prompt, and it requires manual keybinding/listening. There's also the possibility of emitting signals for keys maybe idk.

Let's not worry about focus for now. Here's my plan currently:

1. Downgrade the full handles we provide in Program::created to opaque surface handles.
2. Add additional standard signals for closing, operations, and (at the very least) grabbing focus
   • I like the idea of signals for standard surface operations. It allows programs to possibly intercept things like unwanted closes.
3. Handle those signals at each toplevel surface

Now, we might be able to thread the ability to call on_key_event through the opaque handle to allow e.g. a prompt to bind "hide" to the Escape key. A problem with this is that it's global to the surface it's on, though I don't know how much that matters.

[Ottatop]

Honestly, I'm still on the fence about making Program::view return None. Perhaps instead of widgets internally deciding whether they should be hidden, that should be the choice of the parent program? I'm not sure how ergonomic that is vs. internal hiding though.

[Ph4ntomas]

Perhaps instead of widgets internally deciding whether they should be hidden, that should be the choice of the parent program?

The parent program can always hide widgets, but children need some way to communicate to their parent that they have nothing to show.

Doing otherwise prevent writing generic parents like bars, since such programs would need to know the state of their children.

An alternative could be to have some signal to bubble up that information to the parent, but that still make the child program decide it can/should be hidden/shown, and the parent now need to track which child is hidden instead of the simpler filtering returning None allows

[Ph4ntomas]

Now, we might be able to thread the ability to call on_key_event through the opaque handle to allow e.g. a prompt to bind "hide" to the Escape key. A problem with this is that it's global to the surface it's on, though I don't know how much that matters.

Some thought:
The TextInput is currently limited, so I was planning to write an extended version for Prompt which would add a message for autocompletion, and possibly allow user to define keys/key-combo to triggers autocompletion, history navigation, etc.

It would be possible to write a focus able "keyboard area" to wrap other widgets to enhance them. A Program using that would become focusable from the perspective of their parents.

[Ottatop]

Doing otherwise prevent writing generic parents like bars, since such programs would need to know the state of their children.

An alternative could be to have some signal to bubble up that information to the parent, but that still make the child program decide it can/should be hidden/shown, and the parent now need to track which child is hidden instead of the simpler filtering returning None allows

All good points, let's make view return None then.

The TextInput is currently limited, so I was planning to write an extended version for Prompt which would add a message for autocompletion, and possibly allow user to define keys/key-combo to triggers autocompletion, history navigation, etc.

I'll have to see a POC of this before I give thoughts.

It would be possible to write a focus able "keyboard area" to wrap other widgets to enhance them. A Program using that would become focusable from the perspective of their parents.

This is an interesting idea and definitely something to experiment with.

[Ph4ntomas]

Throwing some ideas out here, there's possibly the idea of making some programs additionally return a "program handle" that allows people to bind keys to actions on those handles. Like Awesome has mod+r bound to prompt:run() for example. Unfortunately that's not a mechanism to define default behavior like Escape to close a prompt, and it requires manual keybinding/listening. There's also the possibility of emitting signals for keys maybe idk.

Let's not worry about focus for now. Here's my plan currently:
[...]

I can implement that if you want. #415 is dependent on Programs, and I'd like to port Glacier's bar to composable program to have something to test it with :)

[Better prompt widget]

I'll have to see a POC of this before I give thoughts.

Yeah, I've only added that for context and because it's on my to-do list (Glacier's prompt is usable, but the lack of auto-completion is painful, and there's no way to implement that properly without some server-side support to know where the cursor is, and ideally I'd want the key to be captured by the widget, not the layer it's on).

This is an interesting idea and definitely something to experiment with.

Yeah, I'll do a POC when we get to it.

Throwing some ideas out here, there's possibly the idea of making some programs additionally return a "program handle" that allows people to bind keys to actions on those handles.

That's essentially what I've been doing in Glacier

[Ottatop]

I can implement that if you want. #415 is dependent on Programs, and I'd like to port Glacier's bar to composable program to have something to test it with :)

In that case go for it.