Struct penrose::core::manager::WindowManager

pub struct WindowManager<X: XConn> { /* fields omitted */ }

WindowManager is the primary struct / owner of the event loop for penrose.

It handles most (if not all) of the communication with the underlying XConn, responding to XEvents emitted by it. User key / mouse bindings are parsed and bound on the call to grab_keys_and_run and then triggered when corresponding XEvent instances come through in the main event loop.

A note on examples

The examples provided for each of the WindowManager methods are written using an example implementation of XConn that mocks out calls to the X server. In each case, it is assumed that you have an initialised WindowManager struct as demonstrated in the full examples for new and init.

For full examples of how to configure the WindowManager, please see the examples directory in the Penrose repo.

Implementations

impl<X: XConn> WindowManager<X>

pub fn new(
    config: Config,
    conn: X,
    hooks: Hooks<X>,
    error_handler: ErrorHandler
) -> Self

Construct a new window manager instance using a chosen XConn backed to communicate with the X server.

Example

use penrose::{
    core::{Config, WindowManager},
    xcb::XcbConnection,
    logging_error_handler
};

let mut wm = WindowManager::new(
    Config::default(),
    XcbConnection::new().unwrap(),
    vec![],
    logging_error_handler(),
);

if let Err(e) = wm.init() {
    panic!("failed to initialise WindowManager: {}", e);
}

wm.log("ready to call grab_keys_and_run!").unwrap();

pub fn init(&mut self) -> Result<()>

This initialises the WindowManager internal state but does not start processing any events from the X server. If you need to perform any custom setup logic with the WindowManager itself, it should be run after calling this method and before WindowManager::grab_keys_and_run.

Example

See new

pub fn grab_keys_and_run(
    &mut self,
    mut key_bindings: KeyBindings<X>,
    mut mouse_bindings: MouseBindings<X>
) -> Result<()>

This is the main event loop for the WindowManager.

The XConn wait_for_event method is called to fetch the next event from the X server, after which it is processed into a set of internal EventActions which are then processed by the WindowManager to update state and perform actions. This method is an infinite loop until the exit method is called, which triggers the XConn cleanup before exiting the loop. You can provide any additional teardown logic you need your main.rs after the call to grab_keys_and_run and all internal state will still be accessible, though methods requiring the use of the XConn will fail.

pub fn focused_client_id(&self) -> Option<WinId>

The WinId of the client that currently has focus.

Returns None if there are no clients to focus.

pub fn detect_screens(&mut self) -> Result<()>

Query the XConn for the current connected Screen list and reposition displayed Workspace instances if needed.

assert_eq!(manager.n_screens(), 1);

// Simulate a monitor being attached
manager.conn_mut().set_screen_count(2);

manager.detect_screens()?;
assert_eq!(manager.n_screens(), 2);

pub fn conn(&self) -> &X

Get an immutable reference to the underlying XConn impl that backs this WindowManager

A word of warning

This method is provided as a utility for allowing you to make use of implementation specific methods on the XConn impl that your WindowManager is using. You will need to take care not to manipulate X state via this as you may end up with inconsistant state in the WindowManager.

Example

// a helper method on the ExampleXConn used for these examples
assert_eq!(manager.conn().current_screen_count(), 1);

pub fn conn_mut(&mut self) -> &mut X

Get an mutable reference to the underlying XConn impl that backs this WindowManager

A word of warning

This method is provided as a utility for allowing you to make use of implementation specific methods on the XConn impl that your WindowManager is using. You will need to take care not to manipulate X state via this as you may end up with inconsistant state in the WindowManager.

Example

// a helper method on the ExampleXConn used for these examples
assert_eq!(manager.conn().current_screen_count(), 1);

manager.conn_mut().set_screen_count(2);
assert_eq!(manager.conn().current_screen_count(), 2);

pub fn log(&self, msg: impl Into<String>) -> Result<()>

Log information out at INFO level for picking up by external programs

Example

manager.log("hello from penrose!")?;
manager.log(format!("This manager has {} screens", manager.n_screens()))?;

pub fn cycle_screen(&mut self, direction: Direction) -> Result<()>

Cycle between known screens. Does not wrap from first to last

Example

// manager here is an example window manager with two screens
assert_eq!(manager.active_screen_index(), 0);

manager.cycle_screen(Forward)?;
assert_eq!(manager.active_screen_index(), 1);

// no wrapping
manager.cycle_screen(Forward)?;
assert_eq!(manager.active_screen_index(), 1);

pub fn cycle_workspace(&mut self, direction: Direction) -> Result<()>

Cycle between workspaces on the current screen.

This method will pull workspaces to the active screen if they are currently displayed on another screen.

Example

// manager here is using the default Config with 9 workspaces

assert_eq!(manager.focused_workspaces(), vec![0]);

manager.cycle_workspace(Forward)?;
assert_eq!(manager.focused_workspaces(), vec![1]);

manager.cycle_workspace(Backward)?;
manager.cycle_workspace(Backward)?;
assert_eq!(manager.focused_workspaces(), vec![8]);

pub fn drag_workspace(&mut self, direction: Direction) -> Result<()>

Move the currently focused Workspace to the next Screen in 'direction'

Example

assert_eq!(manager.focused_workspaces(), vec![0, 1]);

manager.drag_workspace(Forward)?;
assert_eq!(manager.focused_workspaces(), vec![1, 0]);

pub fn cycle_client(&mut self, direction: Direction) -> Result<()>

Cycle focus between clients for the active Workspace

Example

assert_eq!(manager.focused_client_id(), Some(0));

manager.cycle_client(Backward)?;
assert_eq!(manager.focused_client_id(), Some(1));

manager.cycle_client(Backward)?;
assert_eq!(manager.focused_client_id(), Some(2));

manager.cycle_client(Backward)?;
assert_eq!(manager.focused_client_id(), Some(0));

pub fn focus_client(
    &mut self,
    selector: &Selector<'_, Client>
) -> Result<WinId, Option<WinId>>

Focus the Client matching the given Selector

Errors

If the selector matches a known client then that client is focused and Ok(id) is returned. If the selector doesn't match (either it was invalid or there is no focused client) then Err(self.focused_client_id()) is returned.

Example

let focused = manager.focus_client(&Selector::WinId(0));
assert_eq!(focused, Ok(0));

let focused = manager.focus_client(&Selector::WinId(42));
assert_eq!(focused, Err(Some(0))); // the current focused client

let focused = manager.focus_client(&Selector::WinId(1));
assert_eq!(focused, Ok(1));

let focused = manager.focus_client(&Selector::WinId(42));
assert_eq!(focused, Err(Some(1))); // the current focused client

// Or, if there are no clients to focus
let focused = manager.focus_client(&Selector::WinId(0));
assert_eq!(focused, Err(None));

pub fn rotate_clients(&mut self, direction: Direction) -> Result<()>

Rotate the Client stack on the active Workspace.

This maintains the current window layout but permutes the positions of each window within that layout.

Example

assert_eq!(manager.active_workspace().client_ids(), vec![2, 1, 0]);

manager.rotate_clients(Forward)?;
assert_eq!(manager.active_workspace().client_ids(), vec![0, 2, 1]);

pub fn drag_client(&mut self, direction: Direction) -> Result<()>

Move the focused Client through the stack of clients on the active Workspace.

Example

assert_eq!(manager.active_workspace().client_ids(), vec![3, 2, 1, 0]);

manager.drag_client(Forward)?;
assert_eq!(manager.active_workspace().client_ids(), vec![2, 3, 1, 0]);

manager.drag_client(Forward)?;
assert_eq!(manager.active_workspace().client_ids(), vec![2, 1, 3, 0]);

pub fn cycle_layout(&mut self, direction: Direction) -> Result<()>

Cycle between layouts for the active Workspace

Example

assert_eq!(manager.current_layout_symbol(), "first");

manager.cycle_layout(Forward)?;
assert_eq!(manager.current_layout_symbol(), "second");

// Wrap at the end of the layout list
manager.cycle_layout(Forward)?;
assert_eq!(manager.current_layout_symbol(), "first");

pub fn update_max_main(&mut self, change: Change) -> Result<()>

Increase or decrease the number of clients in the main area by 1.

The change is applied to the active layout on the Workspace that currently holds focus.

Example

manager.update_max_main(More);

pub fn update_main_ratio(&mut self, change: Change) -> Result<()>

Increase or decrease the current layout main_ratio by main_ratio_step

The change is applied to the active layout on the Workspace that currently holds focus.

Example

manager.update_main_ratio(More);

pub fn exit(&mut self) -> Result<()>

Shut down the WindowManager, running any required cleanup and exiting penrose

NOTE: any registered hooks on the WindowManager will still run following calling this method, with the actual exit condition being checked and handled at the end.

Example

manager.exit();

pub fn current_layout_symbol(&self) -> &str

The layout symbol for the layout currently being used on the active workspace

Example

assert_eq!(manager.current_layout_symbol(), "first");

manager.cycle_layout(Forward)?;
assert_eq!(manager.current_layout_symbol(), "second");

pub fn set_root_window_name(&self, s: impl Into<String>) -> Result<()>

Set the root X window name. Useful for exposing information to external programs

Example

manager.set_root_window_name("hello world")?;

pub fn set_client_insert_point(&mut self, cip: InsertPoint) -> Result<()>

Set the insert point for new clients. Default is to insert at index 0.

Example

// Starting with three clients that have been inserted via InsertPoint::First
assert_eq!(manager.active_workspace().client_ids(), vec![2, 1, 0]);

// Move them all over to another workspace, still using InsertPoint::First
(0..3).try_for_each(|_| manager.client_to_workspace(&Selector::Index(1)));
manager.focus_workspace(&Selector::Index(1))?;
assert_eq!(manager.active_workspace().client_ids(), vec![0, 1, 2]);

// Change to InsertPoint::Last and move them back
manager.set_client_insert_point(InsertPoint::Last)?;

(0..3).try_for_each(|_| manager.client_to_workspace(&Selector::Index(0)));
manager.focus_workspace(&Selector::Index(0))?;
assert_eq!(manager.active_workspace().client_ids(), vec![0, 1, 2]);

pub fn focus_workspace(
    &mut self,
    selector: &Selector<'_, Workspace>
) -> Result<()>

Set the displayed workspace for the focused screen to be index in the list of workspaces passed at init.

A common way to use this method is in a refMap section when generating your keybindings and using the index_selectors helper method to make the required selectors.

Example

assert_eq!(manager.active_workspace().name(), "1");

manager.focus_workspace(&Selector::Index(3))?;
assert_eq!(manager.active_workspace().name(), "4");

manager.focus_workspace(&Selector::Condition(&|ws| ws.name() == "9"))?;
assert_eq!(manager.active_workspace().name(), "9");

pub fn toggle_workspace(&mut self) -> Result<()>

Switch focus back to the last workspace that had focus.

Example

manager.focus_workspace(&Selector::Index(1))?;
assert_eq!(manager.active_workspace().name(), "2");

manager.focus_workspace(&Selector::Index(0))?;
assert_eq!(manager.active_workspace().name(), "1");

manager.toggle_workspace()?;
assert_eq!(manager.active_workspace().name(), "2");

pub fn client_to_workspace(
    &mut self,
    selector: &Selector<'_, Workspace>
) -> Result<()>

Move the focused client to the workspace matching 'selector'.

Example

assert_eq!(manager.active_workspace().client_ids(), vec![2, 1, 0]);

(0..3).try_for_each(|_| manager.client_to_workspace(&Selector::Index(1)));
manager.focus_workspace(&Selector::Index(1))?;
assert_eq!(manager.active_workspace().client_ids(), vec![0, 1, 2]);

pub fn client_to_screen(
    &mut self,
    selector: &Selector<'_, Screen>
) -> Result<()>

Move the focused client to the active workspace on the screen matching 'selector'.

Example

assert_eq!(manager.focused_workspaces(), vec![0, 1]);

assert_eq!(manager.active_screen_index(), 0);
assert_eq!(manager.active_workspace().client_ids(), vec![2, 1, 0]);

manager.client_to_screen(&Selector::Index(1))?;
assert_eq!(manager.active_workspace().client_ids(), vec![1, 0]);

manager.cycle_screen(Forward)?;
assert_eq!(manager.active_screen_index(), 1);
assert_eq!(manager.active_workspace().client_ids(), vec![2]);

pub fn toggle_client_fullscreen(
    &mut self,
    selector: &Selector<'_, Client>
) -> Result<()>

Toggle the fullscreen state of the Client matching the given Selector

Example

assert_eq!(manager.client(&Selector::Focused).unwrap().is_fullscreen(), false);

manager.toggle_client_fullscreen(&Selector::Focused)?;
assert_eq!(manager.client(&Selector::Focused).unwrap().is_fullscreen(), true);

manager.toggle_client_fullscreen(&Selector::Focused)?;
assert_eq!(manager.client(&Selector::Focused).unwrap().is_fullscreen(), false);

pub fn kill_client(&mut self) -> Result<()>

Kill the focused client window.

Example

assert_eq!(manager.active_workspace().client_ids(), vec![0]);

manager.kill_client()?;
assert_eq!(manager.active_workspace().client_ids(), vec![]);

pub fn screen(&self, selector: &Selector<'_, Screen>) -> Option<&Screen>

Get a reference to the first Screen satisfying 'selector'. WinId selectors will return the screen containing that Client if the client is known. NOTE: It is not possible to get a mutable reference to a Screen.

Example

assert_eq!(manager.active_workspace().client_ids(), vec![2, 1, 0]);
assert_eq!(manager.focused_workspaces(), vec![0, 1]);

assert_eq!(
    manager.screen(&Selector::Focused),
    manager.screen(&Selector::Index(manager.active_screen_index()))
);

assert_eq!(
    manager.screen(&Selector::Index(0)),
    manager.screen(&Selector::WinId(0)),
);

manager.client_to_screen(&Selector::Index(1))?;

assert_eq!(
    manager.screen(&Selector::WinId(2)),
    manager.screen(&Selector::Index(1)),
);

pub fn active_workspace(&self) -> &Workspace

An immutable reference to the current active Workspace

Example

assert_eq!(manager.active_workspace().name(), "1");

pub fn active_workspace_mut(&mut self) -> &mut Workspace

A mutable reference to the current active Workspace

Example

assert_eq!(manager.active_workspace().client_ids(), vec![2, 1, 0]);

manager.active_workspace_mut().rotate_clients(Forward);
assert_eq!(manager.active_workspace().client_ids(), vec![0, 2, 1]);

pub fn focused_workspaces(&self) -> Vec<usize>

The currently focused workspace indices being shown on each screen

Example

assert_eq!(manager.focused_workspaces(), vec![0, 1]);

pub fn add_workspace(&mut self, index: usize, ws: Workspace) -> Result<()>

Add a new workspace at index, shifting all workspaces with indices greater to the right.

Example

let names: Vec<_> = manager
    .all_workspaces(&Selector::Any)
    .iter()
    .map(|w| w.name())
    .collect();

assert_eq!(names, vec!["1", "2", "3", "4", "5", "6", "7", "8", "9"]);

let ws = Workspace::new("new", example_layouts());
manager.add_workspace(1, ws)?;

let new_names: Vec<_> = manager
    .all_workspaces(&Selector::Any)
    .iter()
    .map(|w| w.name())
    .collect();

assert_eq!(new_names, vec!["1", "new", "2", "3", "4", "5", "6", "7", "8", "9"]);

pub fn push_workspace(&mut self, ws: Workspace) -> Result<()>

Add a new workspace at the end of the current workspace list

Example

let names: Vec<_> = manager
    .all_workspaces(&Selector::Any)
    .iter()
    .map(|w| w.name())
    .collect();

assert_eq!(names, vec!["1", "2", "3", "4", "5", "6", "7", "8", "9"]);

let ws = Workspace::new("new", example_layouts());
manager.push_workspace(ws)?;

let new_names: Vec<_> = manager
    .all_workspaces(&Selector::Any)
    .iter()
    .map(|w| w.name())
    .collect();

assert_eq!(new_names, vec!["1", "2", "3", "4", "5", "6", "7", "8", "9", "new"]);

pub fn remove_workspace(
    &mut self,
    selector: &Selector<'_, Workspace>
) -> Result<Option<Workspace>>

Remove a Workspace from the WindowManager. All clients that were present on the removed workspace will be destroyed. WinId selectors will be ignored.

Example

let names: Vec<_> = manager
    .all_workspaces(&Selector::Any)
    .iter()
    .map(|w| w.name())
    .collect();

assert_eq!(names, vec!["1", "2", "3", "4", "5", "6", "7", "8", "9"]);

let removed = manager.remove_workspace(&Selector::Index(2))?;
assert!(removed.is_some());
assert_eq!(removed.unwrap().name(), "3");

let new_names: Vec<_> = manager
    .all_workspaces(&Selector::Any)
    .iter()
    .map(|w| w.name())
    .collect();

assert_eq!(new_names, vec!["1", "2", "4", "5", "6", "7", "8", "9"]);

pub fn workspace(
    &self,
    selector: &Selector<'_, Workspace>
) -> Option<&Workspace>

Get a reference to the first Workspace satisfying 'selector'. WinId selectors will return the workspace containing that Client if the client is known.

Example

assert_eq!(manager.workspace(&Selector::Focused).unwrap().name(), "1");
assert_eq!(manager.workspace(&Selector::Index(3)).unwrap().name(), "4");

assert_eq!(
    manager.workspace(&Selector::Focused).unwrap().client_ids(),
    vec![2, 1, 0]
);

manager.client_to_workspace(&Selector::Index(2))?;
assert_eq!(manager.workspace(&Selector::Index(2)).unwrap().name(), "3");
assert_eq!(manager.workspace(&Selector::WinId(0)).unwrap().name(), "1");

pub fn workspace_mut(
    &mut self,
    selector: &Selector<'_, Workspace>
) -> Option<&mut Workspace>

Get a mutable reference to the first Workspace satisfying 'selector'. WinId selectors will return the workspace containing that Client if the client is known.

Example

assert_eq!(manager.active_workspace().client_ids(), vec![2, 1, 0]);

let ws2 = Selector::Index(2);

manager.client_to_workspace(&ws2)?;
manager.client_to_workspace(&ws2)?;
manager.client_to_workspace(&ws2)?;

assert_eq!(manager.workspace(&ws2).map(|w| w.client_ids()), Some(vec![0, 1, 2]));

manager.workspace_mut(&ws2).map(|w| w.rotate_clients(Forward));
assert_eq!(manager.workspace(&ws2).map(|w| w.client_ids()), Some(vec![2, 0, 1]));

pub fn all_workspaces(
    &self,
    selector: &Selector<'_, Workspace>
) -> Vec<&Workspace>

Get a vector of immutable references to all workspaces that match the provided Selector.

To return only a single workspace in the case that a selector matches multiple workspaces, use the workspace method instead.

Example

let names: Vec<&str> = manager
    .all_workspaces(&Selector::Condition(&|ws|
        ws.name().parse::<usize>().unwrap() < 5
    ))
    .iter()
    .map(|w| w.name())
    .collect();

assert_eq!(names, vec!["1", "2", "3", "4"]);

pub fn all_workspaces_mut(
    &mut self,
    selector: &Selector<'_, Workspace>
) -> Vec<&mut Workspace>

Get a vector of mutable references to all workspaces that match the provided Selector.

To return only a single workspace in the case that a selector matches multiple workspaces, use the workspace_mut method instead.

Example

let layouts: Vec<&str> = manager
    .all_workspaces(&Selector::Condition(&|ws|
        ws.name().parse::<usize>().unwrap() < 3
    ))
    .iter()
    .map(|w| w.layout_symbol())
    .collect();

assert_eq!(layouts, vec!["first", "first"]);

manager
    .all_workspaces_mut(&Selector::Condition(&|ws|
        ws.name().parse::<usize>().unwrap() < 3
    ))
    .iter_mut()
    .for_each(|ws| {
        ws.try_set_layout("second");
    });

let layouts: Vec<&str> = manager
    .all_workspaces(&Selector::Condition(&|ws|
        ws.name().parse::<usize>().unwrap() < 5
    ))
    .iter()
    .map(|w| w.layout_symbol())
    .collect();

assert_eq!(layouts, vec!["second", "second", "first", "first"]);

pub fn set_workspace_name(
    &mut self,
    name: impl Into<String>,
    selector: &Selector<'_, Workspace>
) -> Result<()>

Set the name of the selected Workspace

Example

assert_eq!(manager.active_workspace().name(), "1");

manager.set_workspace_name("foo", &Selector::Focused)?;
assert_eq!(manager.active_workspace().name(), "foo");

pub fn client(&self, selector: &Selector<'_, Client>) -> Option<&Client>

Take a reference to the first Client found matching 'selector'

Example

assert_eq!(manager.client(&Selector::Focused).unwrap().id(), 2);
assert_eq!(manager.client(&Selector::Index(2)).unwrap().id(), 0);

pub fn client_mut(
    &mut self,
    selector: &Selector<'_, Client>
) -> Option<&mut Client>

Take a mutable reference to the first Client found matching 'selector'

Example

assert_eq!(manager.client(&Selector::Focused).map(|c| c.workspace()), Some(0));

manager.client_mut(&Selector::Focused).map(|c| c.set_workspace(5));
assert_eq!(manager.client(&Selector::Focused).map(|c| c.workspace()), Some(5));

pub fn all_clients(&self, selector: &Selector<'_, Client>) -> Vec<&Client>

Get a vector of references to the Clients found matching 'selector'. The resulting vector is sorted by Client id.

Example

let all_ids: Vec<WinId> = manager
    .all_clients(&Selector::Any)
    .iter()
    .map(|c| c.id())
    .collect();

assert_eq!(all_ids, vec![0, 1, 2, 3, 4, 5]);

let ids: Vec<WinId> = manager
    .all_clients(&Selector::Condition(&|c| c.id() > 3))
    .iter()
    .map(|c| c.id())
    .collect();

assert_eq!(ids, vec![4, 5]);

pub fn all_clients_mut(
    &mut self,
    selector: &Selector<'_, Client>
) -> Vec<&mut Client>

Get a vector of mutable references to the Clients found matching 'selector'.

The resulting vector is sorted by Client id.

Example

let workspace_ids: Vec<usize> = manager
    .all_clients(&Selector::Any)
    .iter()
    .map(|c| c.workspace())
    .collect();

assert_eq!(workspace_ids, vec![0, 0, 0, 0, 0, 0]);

manager
    .all_clients_mut(&Selector::Condition(&|c| c.id() > 3))
    .iter_mut()
    .for_each(|c| c.set_workspace(5));

let workspace_ids: Vec<usize> = manager
    .all_clients(&Selector::Any)
    .iter()
    .map(|c| c.workspace())
    .collect();

assert_eq!(workspace_ids, vec![0, 0, 0, 0, 5, 5]);

pub fn n_screens(&self) -> usize

The number of detected screens currently being tracked by the WindowManager.

Example

assert_eq!(manager.n_screens(), 2);

pub fn screen_size(&self, screen_index: usize) -> Option<Region>

The current effective screen size of the target screen. Effective screen size is the physical screen size minus any space reserved for a status bar.

Example

assert_eq!(manager.screen_size(0), Some(Region::new(0, 18, 800, 582)));
assert_eq!(manager.screen_size(42), None);

pub fn position_client(
    &self,
    id: WinId,
    region: Region,
    stack_above: bool
) -> Result<()>

Position an individual client on the display. (x,y) coordinates are absolute (i.e. relative to the root window not any individual screen).

pub fn show_client(&mut self, id: WinId) -> Result<()>

Make the Client with ID 'id' visible at its last known position.

pub fn hide_client(&mut self, id: WinId) -> Result<()>

Hide the Client with ID 'id'.

pub fn layout_screen(&mut self, screen_index: usize) -> Result<()>

Layout the workspace currently shown on the given screen index.

pub fn active_screen_index(&self) -> usize

An index into the WindowManager known screens for the screen that is currently focused

Example

assert_eq!(manager.active_screen_index(), 0);

manager.cycle_screen(Forward)?;
assert_eq!(manager.active_screen_index(), 1);

impl WindowManager<XcbConnection>

pub fn xcb_connection(&self) -> &Connection

Get a handle on the underlying XCB Connection used by Api to communicate with the X server.

pub fn known_atoms(&self) -> &HashMap<Atom, u32>

The current interned Atom values known to the underlying XcbConnection

Trait Implementations

impl<X: XConn> Debug for WindowManager<X>

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.