ewwii_plugin_api/
lib.rs

1//! # ewwii_plugin_api - A plugin interface for ewwii
2//! 
3//! `ewwii_plguin_api` is a shared list of traits
4//! that both ewwii and its plugins can use.
5//! This crate simplifies and provides a safe way for building
6//! plugins for ewwii.
7//!
8//! ## Example
9//!
10//! The following example shows how this crate shall be used to build ewwii plugins:
11//!
12//! ```rust
13//! use ewwii_plugin_api::{EwwiiAPI, Plugin, export_plugin};
14//!
15//! pub struct DummyStructure;
16//!
17//! impl Plugin for DummyStructure {
18//!     // critical for ewwii to launch the plugin
19//!     fn init(&self, host: &dyn EwwiiAPI) {
20//!         // will be printed by the host
21//!         host.log("Plugin says Hello!");
22//!     }
23//! }
24//!
25//! // Critical for ewwii to load the plugin
26//! export_plugin!(DummyStructure);
27//! ```
28
29mod export_macros;
30
31pub mod example;
32pub mod widget_backend;
33
34#[cfg(feature = "include-rhai")]
35pub use rhai;
36
37#[cfg(feature = "include-gtk4")]
38pub use gtk4;
39
40/// The shared trait defining the Ewwii plugin API
41pub trait EwwiiAPI: Send + Sync {
42    // == General Stuff == //
43    /// Print a message from the host
44    fn print(&self, msg: &str);
45    /// Log a message from the host
46    fn log(&self, msg: &str);
47    /// Log a warning from the host
48    fn warn(&self, msg: &str);
49    /// Log an error from the host
50    fn error(&self, msg: &str);
51
52    // == Rhai Manipulation Stuff == //
53    /// _(include-rhai)_ Perform actions on the latest rhai engine.
54    ///
55    /// # Example
56    ///
57    /// ```rust
58    /// use ewwii_plugin_api::{EwwiiAPI, Plugin};
59    ///
60    /// pub struct DummyStructure;
61    ///
62    /// impl Plugin for DummyStructure {
63    ///     fn init(&self, host: &dyn EwwiiAPI) {
64    ///         host.rhai_engine_action(Box::new(|eng| {
65    ///             // eng = rhai::Engine
66    ///             eng.set_max_expr_depths(128, 128);
67    ///         }));
68    ///     }
69    /// }
70    /// ```
71    #[cfg(feature = "include-rhai")]
72    fn rhai_engine_action(
73        &self,
74        f: Box<dyn FnOnce(&mut rhai::Engine) + Send>,
75    ) -> Result<(), String>;
76
77    /// _(include-rhai)_ Expose a function that rhai configuration can call.
78    ///
79    /// # Example
80    ///
81    /// ```rust
82    /// use ewwii_plugin_api::{EwwiiAPI, Plugin};
83    /// use rhai::Dynamic;
84    ///
85    /// pub struct DummyStructure;
86    ///
87    /// impl Plugin for DummyStructure {
88    ///     fn init(&self, host: &dyn EwwiiAPI) {
89    ///         host.register_function("my_func".to_string(), Box::new(|args| {
90    ///             // Do stuff
91    ///             // - Perform things on the args (if needed)
92    ///             // - And return a value
93    ///             
94    ///             Dynamic::new() // return empty
95    ///         }));
96    ///     }
97    /// }
98    /// ```
99    #[cfg(feature = "include-rhai")]
100    fn register_function(
101        &self, 
102        name: String,
103        f: Box<dyn Fn(rhai::Array) -> rhai::Dynamic + Send + Sync>,
104    ) -> Result<(), String>;
105
106    // == Widget Rendering & Logic == //
107    /// Get the list of all widget id's
108    fn list_widget_ids(&self) -> Result<Vec<u64>, String>;
109
110    /// _(include-gtk4)_ Perform actions on the latest widget registry.
111    ///
112    /// # Example
113    ///
114    /// ```rust
115    /// use ewwii_plugin_api::{EwwiiAPI, Plugin};
116    ///
117    /// pub struct DummyStructure;
118    ///
119    /// impl Plugin for DummyStructure {
120    ///     fn init(&self, host: &dyn EwwiiAPI) {
121    ///         host.widget_reg_action(Box::new(|wrg| {
122    ///             // wrg = widget_backend::WidgetRegistryRepr
123    ///             // The gtk4::Widget can be modified here.
124    ///         }));
125    ///     }
126    /// }
127    /// ```
128    #[cfg(feature = "include-gtk4")]
129    fn widget_reg_action(
130        &self,
131        f: Box<dyn FnOnce(&mut widget_backend::WidgetRegistryRepr) + Send>,
132    ) -> Result<(), String>;
133}
134
135/// The API format that the plugin should follow.
136/// This trait should be implemented for a structure and
137/// that structure should be exported via FFI.
138///
139/// ## Example
140///
141/// ```rust
142/// use ewwii_plugin_api::{Plugin, EwwiiAPI, export_plugin};
143///
144/// struct MyStruct;
145///
146/// impl Plugin for MyStruct {
147///     fn init(&self, host: &dyn EwwiiAPI) {
148///         /* Implementation Skipped */   
149///      }
150/// }
151///
152/// // Automatically does all the FFI related exports
153/// export_plugin!(MyStruct);
154/// ```
155pub trait Plugin: Send + Sync {
156    /// Function ran by host to startup plugin (and its a must-have for plugin loading)
157    fn init(&self, host: &dyn EwwiiAPI);
158}
ewwii_plugin_api/lib.rs

ewwii_plugin_api/
lib.rs
