Struct WindowManager

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

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.

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.

pub fn grab_keys_and_run( &mut self, key_bindings: KeyBindings<X>, 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 detect_screens(&mut self) -> Result<()>

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

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.

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.

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

The currently focused client ID if there is one

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

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

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.

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

Move the currently focused Workspace to the next Screen in ‘direction’

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

Cycle focus between clients for the active Workspace

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

Focus the Client matching the given Selector

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.

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

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

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

Cycle between layouts for the active Workspace

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.

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.

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.

pub fn current_layout_symbol(&self) -> &str

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

pub fn set_root_window_name(&self, s: impl AsRef<str>) -> Result<()>

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

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.

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.

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

Switch focus back to the last workspace that had focus.

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

Move the focused client to the workspace matching ‘selector’.

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

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

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

Toggle the fullscreen state of the Client matching the given Selector

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

Kill the focused client window.

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

Get a reference to the first Screen satisfying ‘selector’. Xid 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.

pub fn active_workspace(&self) -> &Workspace

An immutable reference to the current active Workspace

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

A mutable reference to the current active Workspace

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

The currently focused workspace indices being shown on each screen

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.

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

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

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. Xid selectors will be ignored.

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

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

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

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

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

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

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.

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

Set the name of the selected Workspace

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

Take a reference to the first Client found matching ‘selector’

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

Take a mutable reference to the first Client found matching ‘selector’

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.

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.

pub fn n_screens(&self) -> usize

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

pub fn screen_size(&self, 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.

pub fn position_client( &self, id: Xid, 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: Xid) -> Result<()>

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

pub fn hide_client(&mut self, id: Xid) -> 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

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>

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

Formats the value using the given formatter.

impl<X> Deref for WindowManager<X>

where X: XConn,

type Target = WmState

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<X> DerefMut for WindowManager<X>

where X: XConn,

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.