Trait runa_orbiter::shell::Shell

pub trait Shell: Sized + EventSource<ShellEvent> + 'static {
    type Token: Debug + Copy + PartialEq + Eq + Hash;
    type Buffer: BufferLike;

    // Required methods
    fn allocate(&mut self, state: SurfaceState<Self>) -> Self::Token;
    fn destroy(&mut self, key: Self::Token);
    fn get(&self, key: Self::Token) -> &SurfaceState<Self>;
    fn get_mut(&mut self, key: Self::Token) -> &mut SurfaceState<Self>;
    fn get_disjoint_mut<const N: usize>(
        &mut self,
        keys: [Self::Token; N]
    ) -> [&mut SurfaceState<Self>; N];

    // Provided methods
    fn role_added(&mut self, key: Self::Token, role: &'static str) { ... }
    fn role_deactivated(&mut self, key: Self::Token, role: &'static str) { ... }
    fn post_commit(&mut self, old: Option<Self::Token>, new: Self::Token) { ... }
}

Shell

This is the fundamental interface to the compositor’s shell. A shell needs to support management of surface states, i.e. allocation, deallocation, and access. The allocated states are reference via a token, in order to avoid lifetime and ownership difficulties.

The shell interface also defines a number of callbacks, which runa-orbiter will call in response to various operations done to surfaces.

The shell is also an event source, it must emit the event defined in ShellEvent for various interfaces implemented here to function properly.

Required Associated Types

type Token: Debug + Copy + PartialEq + Eq + Hash

A token to surfaces.

Eq and PartialEq should compare if the keys point to the same surface state.

Tokens to surface states should be reference counted, if a token to a surface state exists, the surface state should not be freed.

A token must be released, impls of Shell can choose to panic if it was dropped it without being released.

type Buffer: BufferLike

A buffer type. We allow a user supplied buffer type instead of dyn Buffer to avoid virutal call overhead, and allow for a more flexible Buffer trait.

Required Methods

fn allocate(&mut self, state: SurfaceState<Self>) -> Self::Token

Allocate a SurfaceState and returns a handle to it.

fn destroy(&mut self, key: Self::Token)

Release a token.

fn get(&self, key: Self::Token) -> &SurfaceState<Self>

Get a reference to a SurfaceState by key.

Returns None if the key is invalid.

fn get_mut(&mut self, key: Self::Token) -> &mut SurfaceState<Self>

Get a mutable reference to a SurfaceState.

fn get_disjoint_mut<const N: usize>( &mut self, keys: [Self::Token; N] ) -> [&mut SurfaceState<Self>; N]

Get mutable references to multiple SurfaceStates.

Panic

May panic if any of the keys are invalid, or if any two of the keys are equal.

Provided Methods

fn role_added(&mut self, key: Self::Token, role: &'static str)

Callback which is called when a role is added to a surface corresponds to the given surface state. A role can be attached using a committed state or a pending state, and they should have the same effects.

Panic

May panic if the handle is invalid.

fn role_deactivated(&mut self, key: Self::Token, role: &'static str)

Callback that is called when a surface has its assigned role deactivated.

Panic

May panic if the handle is invalid.

fn post_commit(&mut self, old: Option<Self::Token>, new: Self::Token)

A commit happened on the surface which used to have surface state old. The new state is new. If old is None, this is the first commit on the surface. After this call returns, new is considered currently committed.

old can be equal to new, if no changes has been made to double buffered surface states since the last commit.

Note, for synced subsurface, this is called when new became cached state.

Panic

This function may panic if either handle is invalid. Or if old has never been committed before.

Implementors