diff options
author | Aram Drevekenin <aram@poor.dev> | 2023-06-18 13:57:27 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-06-18 13:57:27 +0200 |
commit | 76019acf00a421dcdac5c548a2d016eff3f6192c (patch) | |
tree | 919943066e2444abef22ac8d619a49dcc7194352 /zellij-tile | |
parent | e79c3a96b785f461a84f0a4eefdffcb02edc698f (diff) |
docs(plugins): better zellij-tile-docs (#2560)
* docs(plugins): better zellij-tile-docs
* docs(code): fix examples - thanks cargo!
Diffstat (limited to 'zellij-tile')
-rw-r--r-- | zellij-tile/src/lib.rs | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/zellij-tile/src/lib.rs b/zellij-tile/src/lib.rs index cca2a8769..98f141942 100644 --- a/zellij-tile/src/lib.rs +++ b/zellij-tile/src/lib.rs @@ -1,20 +1,61 @@ +//! The zellij-tile crate acts as the Rust API for developing plugins for Zellij. +//! +//! To read more about Zellij plugins: +//! [https://zellij.dev/documentation/plugins](https://zellij.dev/documentation/plugins) +//! +//! ### Interesting things in this libary: +//! - The [`ZellijPlugin`] trait for implementing plugins combined with the +//! [`register_plugin!`](register_plugin) macro to register them. +//! - The list of [commands](shim) representing what a plugin can do. +//! - The list of [`Events`](prelude::Event) a plugin can subscribe to +//! - The [`ZellijWorker`] trait for implementing background workers combined with the +//! [`register_worker!`](register_worker) macro to register them +//! +//! ### Full Example and Development Environment +//! For a working plugin example as well as a development environment, please see: +//! [https://github.com/zellij-org/rust-plugin-example](https://github.com/zellij-org/rust-plugin-example) +//! pub mod prelude; pub mod shim; use serde::{Deserialize, Serialize}; use zellij_utils::data::Event; +/// This trait should be implemented - once per plugin - on a struct (normally representing the +/// plugin state). This struct should then be registered with the +/// [`register_plugin!`](register_plugin) macro. #[allow(unused_variables)] pub trait ZellijPlugin: Default { + /// Will be called when the plugin is loaded, this is a good place to [`subscribe`](shim::subscribe) to events that are interesting for this plugin. fn load(&mut self) {} + /// Will be called with an [`Event`](prelude::Event) if the plugin is subscribed to said event. + /// If the plugin returns `true` from this function, Zellij will know it should be rendered and call its `render` function. fn update(&mut self, event: Event) -> bool { false } // return true if it should render + /// Will be called either after an `update` that requested it, or when the plugin otherwise needs to be re-rendered (eg. on startup, or when the plugin is resized). + /// The `rows` and `cols` values represent the "content size" of the plugin (this will not include its surrounding frame if the user has pane frames enabled). fn render(&mut self, rows: usize, cols: usize) {} } +/// This trait is used to create workers. Workers can be used by plugins to run longer running +/// background tasks without blocking their own rendering (eg. and showing some sort of loading +/// indication in part of the UI as needed while waiting for the task to complete). +/// +/// ## Starting workers on plugin load +/// Implement this trait on a struct (typically representing the worker state) and register it with +/// the [`register_worker!`](register_worker) macro. +/// +/// ## Sending messages to workers and back to the plugin +/// Send messages to workers with the [`post_message_to`](shim::post_message_to) method. +/// Send messages from workers back to plugins with the +/// [`post_message_to_plugin`](shim::post_message_to_plugin) method (but be sure the plugin has +/// [`subscribe`](shim::subscribe)d to the [`CustomMessage`](prelude::Event::CustomMessage)) event +/// first! #[allow(unused_variables)] pub trait ZellijWorker<'de>: Default + Serialize + Deserialize<'de> { + /// Triggered whenever the plugin sends the worker a message using the + /// [`post_message_to`](shim::post_message_to) method. fn on_message(&mut self, message: String, payload: String) {} } @@ -30,6 +71,21 @@ Please refer to the documentation for further information: https://github.com/zellij-org/zellij/blob/main/CONTRIBUTING.md#building "; +/// Used to register a plugin implementing the [`ZellijPlugin`] trait. +/// +/// eg. +/// ```rust +/// use zellij_tile::prelude::*; +/// +/// #[derive(Default)] +/// pub struct MyPlugin {} +/// +/// impl ZellijPlugin for MyPlugin { +/// // ... +/// } +/// +/// register_plugin!(MyPlugin); +/// ``` #[macro_export] macro_rules! register_plugin { ($t:ty) => { @@ -76,6 +132,28 @@ macro_rules! register_plugin { }; } +/// Used to register a plugin worker implementing the [`ZellijWorker`] trait. +/// +/// eg. +/// ```rust +/// use zellij_tile::prelude::*; +/// use serde::{Deserialize, Serialize}; +/// +/// #[derive(Default, Serialize, Deserialize)] +/// pub struct FileSearchWorker {} +/// +/// impl ZellijWorker<'_> for FileSearchWorker { +/// fn on_message(&mut self, message: String, payload: String) { +/// // ... +/// } +/// } +/// +/// register_worker!( +/// FileSearchWorker, +/// file_search_worker, // registers the worker as the namespace "file_search" +/// FILE_SEARCH_WORKER // expanded to a static variable in which the worker state it held +/// ); +/// ``` #[macro_export] macro_rules! register_worker { ($worker:ty, $worker_name:ident, $worker_static_name:ident) => { |