Crate onagre_launcher_toolkit
source ·Expand description
§onagre-launcher-toolkit
A toolkit to write pop-launcher client and plugin.
§Crates
launcher
: re-export the pop-launcher crate, containing all the IPC message struct and some utility functions to locate plugins.service
: re-export the pop-launcher-service crate, containing deserializable plugin config struct. This is useful if your client needs to read user defined plugins configs.plugins
: re-export pop-launcher-plugins which defines all the default pop-launcher plugins. Useful if your client needs to read default plugin configs
§Writing a plugin
Add the following to your Cargo.toml :
[dependencies]
tokio = { version = "1.18.2", features = ["rt"] }
onagre-launcher-toolkit = { git = "https://github.com/pop-os/launcher" }
And implement the PluginExt
trait:
use pop_launcher_toolkit::launcher::{Indice, PluginResponse, PluginSearchResult};
use pop_launcher_toolkit::plugin_trait::{async_trait, PluginExt};
use pop_launcher_toolkit::plugins;
// The plugin struct, here it holds the search result
pub struct MyPlugin {
data: Vec<String>
}
#[async_trait]
impl PluginExt for MyPlugin {
// Define the name of you plugin, this will be used
// to generate a logfile in $XDG_STATE_HOME at runtime.
fn name(&self) -> &str {
"my_awesome_plugin"
}
// Respond to `pop-launcher` 'search' query
async fn search(&mut self, query: &str) {
// `pop-launcher` dispatches request to plugins according to the regex defined in
// the `plugin.ron` config file, here we get rid of the prefix
// before processing the request.
let query = query.strip_prefix("plug ").unwrap();
// Iterate through our internal search results with their indices.
let search_results = self.data.iter()
.enumerate()
.filter(|(idx, data)| data.contains(query));
// Send our search results to `pop-launcher` using their indices as id.
for (idx, search_result) in search_results {
self.respond_with(PluginResponse::Append(PluginSearchResult {
id: idx as u32,
name: search_result.clone(),
description: "".to_string(),
keywords: None,
icon: None,
exec: None,
window: None,
})).await;
}
// tell `pop-launcher` we are done with this request
self.respond_with(PluginResponse::Finished).await;
}
// Respond to `pop-launcher` 'activate' query
async fn activate(&mut self, id: Indice) {
// Get the selected entry
let entry = self.data.get(id as usize).unwrap();
// Here we use xdg_open to run the entry but this could be anything
plugins::xdg_open(entry);
// Tell pop launcher we are done
self.respond_with(PluginResponse::Finished).await;
}
// Respond to `pop-launcher` 'close' request.
async fn quit(&mut self, id: Indice) {
self.respond_with(PluginResponse::Close).await;
}
}
#[tokio::main(flavor = "current_thread")]
pub async fn main() {
// Here we declare our plugin with dummy values, and never mutate them.
// In a real plugin we would probably use some kind of mutable shared reference to
// update our search results.
let mut plugin = MyPlugin {
data: vec!["https://crates.io".to_string(), "https://en.wikipedia.org".to_string()],
};
/// If you need to debug your plugin or display error messages use `tcracing` macros.
tracing::info!("Starting my_awsome_plugin");
// Call the plugin entry point function to start
// talking with pop_launcherc
plugin.run().await;
}
Re-exports§
pub use onagre_launcher as launcher;
pub use onagre_launcher_plugins as plugins;
pub use onagre_launcher_service as service;
Modules§
- A helper trait to quickly create
pop-launcher
plugins
Functions§
- Loads all plugin information found in the given path.
- Fetches plugins installed on the system in parallel.