i3monkit/lib.rs
1// Copyright (C) 2019, Hao Hou
2
3//! # i3monkit - The i3 Status Bar Monitor Toolkit
4//!
5//! This is a toolkit for building customized i3 status bar for the [i3 tiling window manager](https://i3wm.org).
6//! i3 has its default status bar program called `i3status`, but it's somehow limited and hard to
7//! extend and customize. This crate gives you the ability to reimplement an status bar program for
8//! i3 quickly.
9//!
10//! 
11//!
12//! It comes with a set of builtin widget as well, such as, CPU usage bar, Network speed meter,
13//! etc.
14//!
15//! You can crate your own status bar with just a few lines of code in Rust.
16//!
17//! First, you need to crate a crate and import this crate
18//!
19//! ```toml
20//! [dependencies]
21//! i3mokit = "*"
22//!
23//! ```
24//!
25//! Then, config your customized i3 status bar
26//!
27//! ```rust
28//! use i3monkit::*;
29//! use i3monkit::widgets::*;
30//!
31//! fn main() {
32//! let mut bar = WidgetCollection::new();
33//!
34//! //Add realtime stock prices, for example: Microsoft, AMD and Facebook
35//! let stock_client = StockClient::new("your-alphavantage-API-key");
36//! bar.push(StockClient::create_widget(&stock_client, "MSFT"));
37//! bar.push(StockClient::create_widget(&stock_client, "AMD"));
38//! bar.push(StockClient::create_widget(&stock_client, "FB"));
39//!
40//! //Realtime upload/download rate for a interface
41//! bar.push(NetworkSpeedWidget::new("wlp58s0"));
42//!
43//! //Display all the cpu usage for each core
44//! for i in 0..4 {
45//! bar.push(CpuWidget::new(i));
46//! }
47//!
48//! //Volume widget
49//! bar.push(VolumeWidget::new("default", "Master", 0));
50//!
51//! //Battery status
52//! bar.push(BatteryWidget::new(0));
53//!
54//! //Time
55//! bar.push(DateTimeWidget::new());
56//!
57//! // Then start updating the satus bar
58//! bar.update_loop(I3Protocol::new(Header::new(1), std::io::stdout()));
59//! }
60//! ```
61//!
62//! Finally, you can change `~/.config/i3/config` to make i3wm uses your status bar program
63//!
64//! ``` config
65//! # Start i3bar to display a workspace bar (plus the system information i3status
66//! # finds out, if available)
67//! bar {
68//! status_command path/to/your/customized/status/program
69//! tray_output primary
70//! colors {
71//! background #222222
72//! statusline #00ee22
73//! separator #666666
74//! # border backgr. text
75//! focused_workspace #4c7899 #285577 #ffffff
76//! inactive_workspace #333333 #222222 #888888
77//! urgent_workspace #2f343a #900000 #ffffff
78//! }
79//! }
80//! ```
81//! ## Write your own widget
82//!
83//! You can also add your customized widget to the framework by implementing the `Widget` trait.
84//!
85//! ```
86//! use i3monkit::{Block, Widget, WidgetUpdate};
87//! struct Greeter(&'static str);
88//! impl Widget for Greeter {
89//! fn update(&mut self) -> Option<WidgetUpdate> {
90//! Some(WidgetUpdate{
91//! refresh_interval: std::time::Duration::new(3600,0),
92//! data: Some(Block::new().append_full_text(self.0).clone())
93//! })
94//! }
95//! }
96//!
97//! fn main() {
98//! let bar = WidgetCollection::new();
99//! bar.push(Greeter("hello world"));
100//! .....
101//! }
102//! ```
103//!
104mod protocol;
105mod widget;
106pub mod widgets;
107
108pub use crate::protocol::{Header, I3Protocol, Block};
109pub use crate::widget::{Widget, WidgetUpdate, WidgetCollection, Decoratable};