Skip to main content

Context

Struct Context 

Source
pub struct Context { /* private fields */ }
Expand description

What a plugin is called with besides a frame: its configuration, and handles to every interface.

Implementations§

Source§

impl Context

Source

pub const fn new() -> Self

Source

pub fn config_json(&self) -> Json

The configuration document activate was called with.

Source

pub fn config<T: DeserializeOwned>(&self) -> Result<T>

The configuration, deserialized (an empty document is null).

Source

pub fn values(&self) -> Values

Examples found in repository?
examples/together_ui.rs (line 45)
43    fn reload(&mut self, cx: &Context) {
44        // A missing value (the companion has not run yet) keeps the default.
45        if let Ok(Some(status)) = cx.values().get::<Status>("together.status") {
46            self.status = status;
47        }
48    }
Source

pub fn live(&self) -> Live

Source

pub fn events(&self) -> Events

Examples found in repository?
examples/together_ui.rs (line 68)
67    fn activate(cx: &mut Context) -> Self {
68        let _ = cx.events().on("together.*");
69        let mut plugin = Self {
70            card: Surface::new("card"),
71            status: Status::default(),
72        };
73        plugin.reload(cx);
74        plugin
75    }
Source

pub fn calls(&self) -> Calls

Examples found in repository?
examples/together_ui.rs (line 105)
83    fn event(&mut self, event: Event, cx: &mut Context) {
84        match event {
85            Event::Plugin { name, .. } if name == "together.changed" => {
86                self.reload(cx);
87                self.paint();
88                // A commit from an event is sampled on the next frame;
89                // ask for one.
90                cx.request_frame();
91            }
92            Event::Resize { .. } => {
93                self.paint();
94                cx.request_frame();
95            }
96            Event::Pointer(pointer) if pointer.kind == PointerKind::Down => {
97                // Side-effect free unless this viewer is the one the user
98                // is driving, and then exactly once across viewers.
99                if !view::is_driving() {
100                    return;
101                }
102                // `send` returns at once: the companion's answer arrives as
103                // the value it writes, not here.
104                let _ = claims().once("together.rebuild", 5_000, || {
105                    let _ = cx.calls().send("rebuild", &(), Target::Singleton);
106                });
107            }
108            _ => {}
109        }
110    }
Source

pub fn claims(&self) -> Claims

Source

pub fn is_driving(&self) -> bool

Source

pub fn capabilities(&self) -> Capabilities

Source

pub fn request_frame(&self)

Asks for a frame on the next paced frame, from an event handler (inside UiPlugin::frame, use Frame::request_frame). A commit in event is otherwise sampled on the next frame something else causes.

Examples found in repository?
examples/together_ui.rs (line 90)
83    fn event(&mut self, event: Event, cx: &mut Context) {
84        match event {
85            Event::Plugin { name, .. } if name == "together.changed" => {
86                self.reload(cx);
87                self.paint();
88                // A commit from an event is sampled on the next frame;
89                // ask for one.
90                cx.request_frame();
91            }
92            Event::Resize { .. } => {
93                self.paint();
94                cx.request_frame();
95            }
96            Event::Pointer(pointer) if pointer.kind == PointerKind::Down => {
97                // Side-effect free unless this viewer is the one the user
98                // is driving, and then exactly once across viewers.
99                if !view::is_driving() {
100                    return;
101                }
102                // `send` returns at once: the companion's answer arrives as
103                // the value it writes, not here.
104                let _ = claims().once("together.rebuild", 5_000, || {
105                    let _ = cx.calls().send("rebuild", &(), Target::Singleton);
106                });
107            }
108            _ => {}
109        }
110    }
More examples
Hide additional examples
examples/scroll_list.rs (line 133)
106    fn event(&mut self, event: Event, cx: &mut Context) {
107        match event {
108            // The surface has a new, empty buffer.
109            Event::Resize { .. } => self.dirty = true,
110            Event::Key(key) if key.phase != KeyPhase::Release => match key.code {
111                KeyCode::Up => self.select(self.selected.saturating_sub(1)),
112                KeyCode::Down => self.select(self.selected.saturating_add(1)),
113                KeyCode::PageUp => self.select(self.selected.saturating_sub(self.page())),
114                KeyCode::PageDown => self.select(self.selected.saturating_add(self.page())),
115                KeyCode::Home => self.select(0),
116                KeyCode::End => self.select(ITEMS - 1),
117                _ => return,
118            },
119            // The pointer arrives in the surface's own rows, wherever the
120            // list is scrolled to, so the row names the item.
121            Event::Pointer(pointer) if pointer.kind == PointerKind::Down => {
122                let Some(item) = pointer.row.checked_sub(TITLE_ROWS) else {
123                    return;
124                };
125                if item >= ITEMS {
126                    return;
127                }
128                self.selected = item;
129                self.dirty = true;
130            }
131            _ => return,
132        }
133        cx.request_frame();
134    }
Source

pub fn wake_at(&self, at_ms: u64)

Asks for a frame at at_ms on the viewer’s clock.

Source

pub fn open(&self, surface: &str) -> Result<()>

Opens a stage surface. Only while handling a user gesture: a key, a paste, a pointer press on one of the plugin’s surfaces, or one of its commands.

Source

pub fn focus_pane(&self, pane: &str) -> Result<()>

Shows a pane in this viewer’s workspace and gives it focus, as a click on its sidebar row does. Only while handling a user gesture, as Context::open; a pane the viewer does not know is ignored.

Source

pub fn create_pane( &self, project: &str, argv: &[String], title: &str, ) -> Result<String>

Creates a pane through this driving viewer’s normal action, including on a remote project’s machine. Needs view.pane-create and a gesture. Returns its permanent id; wait for crate::view::PANE_CREATE_RESULT before treating it as created. Never takes controller authority.

Source

pub fn open_url(&self, url: &str) -> Result<()>

Opens an https:// URL in the user’s browser (crate::url::open): while handling user input, or within a second after it.

Source

pub fn open_instance( &self, surface: &str, key: &str, after: Option<&str>, ) -> Result<String>

Opens an instance of the declared pane or window surface surface, named <surface>@<key>, and returns that name: a surface of its own for events, Surface and Context::close. A pane instance with after opens right after that pane without taking focus. It needs a user gesture, as Context::open, unless the plugin holds surface.open-unprompted and names after.

Source

pub fn close(&self, surface: &str) -> Result<()>

Closes a surface Context::open opened.

Source

pub fn request_size(&self, surface: &str, cols: u32, rows: u32) -> Result<()>

Asks for surface to be cols by rows cells (0: the viewer’s choice in that dimension) instead of the manifest’s size. The viewer clamps it where it places the surface and sends Event::Resize when the size changes. A card grows to show more rows; a popover fits its content.

Source

pub fn set_label(&self, surface: &str, label: Option<&str>) -> Result<()>

Sets a short label the viewer shows at the right end of surface’s chrome title: a boxed card’s top border, a pane’s header, a column’s title row. None removes it. At most 48 characters with no control characters.

Source

pub fn set_caret(&self, surface: &str, caret: Option<(u32, u32)>) -> Result<()>

Places the viewer’s own text cursor at (col, row) of surface while the surface takes keys (an open stage, popover or pane overlay, or the surface a click or open gave input focus), so a text field draws no cursor of its own; the cursor trail moves to it. None removes it. Stays until set again.

Source

pub fn set_scroll(&self, surface: &str, scroll: Option<Scroll>) -> Result<()>

Paints the cells surface surface scroll.rows rows tall, taller than where it shows, for the viewer to scroll as it scrolls its own lists: wheel and trackpad, a finger’s drag and glide, the rubber band at each end, and pixel motion where the terminal has it. The fixed rows at the top and bottom stay in place. The viewer sends Event::Resize with the new height, so paint the whole surface as usual; pointer events arrive in the surface’s own rows and the viewer keeps the vertical wheel over the scrolling rows. None returns it to the size it shows at. Stays until set again.

Source

pub fn reveal(&self, surface: &str, first: u32, last: u32) -> Result<()>

Brings rows first..=last of the scrolling surface into view, gliding there as the viewer’s lists follow a selection. Rows in view stay put. Call it when a key moves a selection.

Source

pub fn viewport(&self, surface: &str) -> Result<Option<Viewport>>

The scrolling rows of surface that show now, for keys that move a page; None for a surface that does not scroll or has not been laid out yet.

Source

pub fn set_agent_pointer( &self, surface: &str, pointer: Option<AgentPointer>, ) -> Result<()>

Shows an agent at work in surface the way the viewer shows its own agent acting: an arrow with a name tag that glides to each place set here (it jumps under reduced motion) and plays a press when pointer.press is set. Report what the agent does, such as the clicks it sends an embedded page; the viewer draws the pointer over the surface, clipped to it. None removes it. Invalid for a place outside the surface, Unavailable while the viewer has no cell pixel size. Stays until set again.

Trait Implementations§

Source§

impl Debug for Context

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Context

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Resource for T
where T: 'static,

Source§

type Rep = Option<T>

The type which is actually stored in-memory for this resource. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.