A Rust library for controlling i3-wm through its IPC interface
Switch branches/tags
Nothing to show
Clone or download
Latest commit c9ddf98 Sep 20, 2018
Permalink
Failed to load latest commit information.
examples Remove unneeded calls to ok() Nov 18, 2017
src Merge pull request #28 from emersion/sway Sep 20, 2018
.gitignore Work on requests + replies Jul 11, 2015
.travis.yml Rely on docs.rs insted of Travis Sep 25, 2017
Cargo.toml 0.8.4 Sep 20, 2018
LICENSE.md Add LICENSE.md Jul 15, 2015
README.md 0.8.4 Sep 20, 2018

README.md

i3ipc-rs

Build Status Crate Docs

A Rust library for controlling i3-wm through its IPC interface.

Usage

Add this to your Cargo.toml

[dependencies.i3ipc]
version = "0.8.4"

Messages:

extern crate i3ipc;
use i3ipc::I3Connection;

fn main() {
    // establish a connection to i3 over a unix socket
    let mut connection = I3Connection::connect().unwrap();
    
    // request and print the i3 version
    println!("{}", connection.get_version().unwrap().human_readable);
    
    // fullscreen the focused window
    connection.run_command("fullscreen").unwrap();
}

Events:

extern crate i3ipc;
use i3ipc::I3EventListener;
use i3ipc::Subscription;
use i3ipc::event::Event;

fn main() {
    // establish connection.
    let mut listener = I3EventListener::connect().unwrap();

    // subscribe to a couple events.
    let subs = [Subscription::Mode, Subscription::Binding];
    listener.subscribe(&subs).unwrap();

    // handle them
    for event in listener.listen() {
        match event.unwrap() {
            Event::ModeEvent(e) => println!("new mode: {}", e.change),
            Event::BindingEvent(e) => println!("user input triggered command: {}", e.binding.command),
            _ => unreachable!()
        }
    }
}

Versioning

By default i3ipc-rs targets minimum i3 version 4.11. To unlock additional features you can increase this by selecting one of "i3-4-12", ..., "i3-4-14" in Cargo.toml.

[dependencies.i3ipc]
version = "0.8.4"
features = ["i3-4-14"]

Additions to the i3 IPC interface that are not understood by your compiled binary will generally return an Unknown value and log a warning to the target "i3ipc" using the log crate. Binaries using this library should install a logger to view details of such additions.