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;
}