Crate rofi_mode

A high-level Rust library for creating Rofi plugins and custom modes

Getting started

First of all, create a new library with cargo new --lib my_awesome_plugin and add these lines to the Cargo.toml:

[lib]
crate-type = ["cdylib"]

That will force Cargo to generate your library as a .so file, which is what Rofi loads its plugins from.

Then, add this crate as a dependency using the following command:

cargo add rofi-mode

Now in your lib.rs, create a struct and implement the Mode trait for it. For example, here is a no-op mode with no entries:

struct Mode;

impl rofi_mode::Mode<'_> for Mode {
    const NAME: &'static str = "an-example-mode\0";
    fn init(_api: rofi_mode::Api<'_>) -> Result<Self, ()> {
        Ok(Self)
    }
    fn entries(&mut self) -> usize { 0 }
    fn entry_content(&self, _line: usize) -> rofi_mode::String { unreachable!() }
    fn react(
        &mut self,
        _event: rofi_mode::Event,
        _input: &mut rofi_mode::String,
    ) -> rofi_mode::Action {
        rofi_mode::Action::Exit
    }
    fn matches(&self, _line: usize, _matcher: rofi_mode::Matcher<'_>) -> bool {
        unreachable!()
    }
}

You then need to export your mode to Rofi via the export_mode! macro:

rofi_mode::export_mode!(Mode);

Build your library using cargo build then copy the resulting dylib file (e.g. /target/debug/libmy_awesome_plugin.so) into /lib/rofi so that Rofi will pick up on it when it starts up (alternatively, you can set the ROFI_PLUGIN_PATH environment variable to the directory your .so file is in). You can then run your mode from Rofi’s command line:

rofi -modi an-example-mode -show an-example-mode

Build with RUSTFLAGS="--cfg rofi_next" to support unreleased Rofi versions, and drop support for released Rofi versions. This will turn on semver-exempt features, so use with caution.

Examples

• See examples/basic for a basic example of a non-trivial Rofi mode, which allows the user to add to the list of entries by writing in the Rofi box.
• See examples/file-browser for a Rofi mode implementing a simple file browser.

Re-exports

• pub use api::Api;
• pub use cairo;
• pub use pango;
• pub use rofi_plugin_sys as ffi;

Modules

• api
  Interface to Rofi’s API.

Macros

• export_mode
  Declare a mode to be exported by this crate.
• format
  Format a Rofi String using interpolation of runtime expressions.

Structs

• Attributes
  A collection of attributes that can be applied to text.
• Matcher
  A pattern matcher.
• String
  A UTF-8-encoded growable string buffer suitable for FFI with Rofi.
• Style
  The style of a text entry in the list.

Enums

• Action
  An action caused by reacting to an Event.
• Event
  An event triggered by the user.

Traits

• Mode
  A mode supported by Rofi.

Functions

• format
  Format a Rofi String using a set of format arguments.
• raw_mode
  Convert an implementation of Mode to its raw FFI Mode struct.