Crate penrose

Penrose: a library for building your very own tiling window manager

Penrose is inspired by similar projects such as dwm, xmonad and qtile which allow you to configure your window manager in code and compile it for your system. It is most similar to xmonad in that it is more of a library for building a window manager (with low level details taken care of for you) rather than a minimal window manager that you edit and patch directly (such as dwm). Penrose strives to be as simple as possible in its implementation in order to make the guts of the window manager easier to understand. Given the nature of what this involves, this is not always possible but effort has been made to keep the source readable and with relatively free of magic.

Using Penrose

Penrose itself is not a binary application that you can build, install and run. You need to write your own main.rs as a rust binary crate that uses Penrose as a dependency to set up, configure and run your very own window manager exactly how you want it. In short, you will need to write some code and you will need to know Rust to some degree.

For learning rust itself, there are some fantastic official guides available on rust-lang.org and if you are sticking to using the out of the box functionality provided by the penrose crate, working through The Rust Book before diving into penrose should be more than enough to get you started.

On GitHub you can find up to date examples of how to set up and configure a window manager using penrose, ranging from bare bones minimal to custom extensions and hooks.

NOTE: in order to use the xcb implementation of penrose, you will need to install the C libraries that are dependencies (namely xcb, Cairo and Pango).

Digging into the API

The suggested reading order for getting to grips with the penrose API is to first look at the pure data structures that represent the logical state of your window manager before digging in to the core module which contains the majority of the functionality you are likely to want to work with. If you are interested in the lower level X11 interactions (or need to make requests to the X server directly) you should check out the x module and its associated traits. To add functionality and flexability to your window manager, there are the builtin and extensions modules which offer capabilities built on top of the rest of penrose.

Modules

• builtin
  Built-in functionality for penrose.
• core
  Core data structures and user facing functionality for the window manager
• extensions
  Extensions to the base behaviour of Penrose
• pure
  Side effect free management of internal window manager state
• util
  Utility functions for use in other parts of penrose
• x
  Logic for interacting with the X server
• x11rb
  Helpers and utilities for using x11rb as a back end for penrose

Macros

• custom_error
  Quickly create a crate::Error::Custom
• impl_message
  Mark a type as being usable as a Message for sending to a Layout
• manage_hooks
  Compose together a set of ManageHook query/hook rules into a single ManageHook that can be added to your Config.
• map
  Make creating a pre-defined HashMap a little less verbose
• simple_transformer
  Quickly define a LayoutTransformer from a single element tuple struct and a transformation function: fn(Rect, Vec<(Xid, Rect)>) -> Vec<(Xid, Rect)>.
• stack
  Create a Stack containing the arguments. The only required element is the focus, it is not possible to create an empty Stack;

Structs

• Color
  A simple RGBA based color
• Xid
  An X11 ID for a given resource

Enums

• Error
  Error variants from the core penrose library.

Type Aliases

• Result
  A Result where the error type is a penrose Error