logo

Trait penrose::core::Hook[−][src]

pub trait Hook<X: XConn> {

Show 14 methods    fn startup(&mut self, wm: &mut WindowManager<X>) -> Result<()> { ... }

    fn new_client(&mut self, wm: &mut WindowManager<X>, id: Xid) -> Result<()> { ... }

    fn remove_client(
        &mut self, 
        wm: &mut WindowManager<X>, 
        id: Xid
    ) -> Result<()> { ... }

    fn client_added_to_workspace(
        &mut self, 
        wm: &mut WindowManager<X>, 
        id: Xid, 
        wix: usize
    ) -> Result<()> { ... }

    fn client_name_updated(
        &mut self, 
        wm: &mut WindowManager<X>, 
        id: Xid, 
        name: &str, 
        is_root: bool
    ) -> Result<()> { ... }

    fn layout_applied(
        &mut self, 
        wm: &mut WindowManager<X>, 
        workspace_index: usize, 
        screen_index: usize
    ) -> Result<()> { ... }

    fn layout_change(
        &mut self, 
        wm: &mut WindowManager<X>, 
        workspace_index: usize, 
        screen_index: usize
    ) -> Result<()> { ... }

    fn workspace_change(
        &mut self, 
        wm: &mut WindowManager<X>, 
        previous_workspace: usize, 
        new_workspace: usize
    ) -> Result<()> { ... }

    fn workspaces_updated(
        &mut self, 
        wm: &mut WindowManager<X>, 
        names: &[&str], 
        active: usize
    ) -> Result<()> { ... }

    fn screen_change(
        &mut self, 
        wm: &mut WindowManager<X>, 
        screen_index: usize
    ) -> Result<()> { ... }

    fn screens_updated(
        &mut self, 
        wm: &mut WindowManager<X>, 
        dimensions: &[Region]
    ) -> Result<()> { ... }

    fn randr_notify(&mut self, wm: &mut WindowManager<X>) -> Result<()> { ... }

    fn focus_change(&mut self, wm: &mut WindowManager<X>, id: Xid) -> Result<()> { ... }

    fn event_handled(&mut self, wm: &mut WindowManager<X>) -> Result<()> { ... }

}
Expand description

User defined functionality triggered by WindowManager actions.

impls of Hook can be registered to receive events during WindowManager operation. Each hook point is documented as individual methods detailing when and how they will be called. All registered hooks will be called for each trigger so the required methods all provide a no-op default implementation that must be overriden to provide functionality. Hooks may subscribe to multiple triggers to implement more complex behaviours and may store additional state.

Care should be taken when writing Hook impls to ensure that infinite loops are not created by nested triggers and that, where possible, support for other hooks running from the same triggers is possible.

Implementing Hook

For an example of how to write Hooks, please see the module level documentation.

Note that you only need to implement the methods for triggers you intended to respond to: all hook methods have a default empty implementation that is ignored by the WindowManager.

Provided methods

Trigger Point

Called once at WindowManager startup in grab_keys_and_run after setting up signal handlers and grabbing key / mouse bindings but before entering the main event loop that polls for XEvents.

Example Uses

When this trigger is reached, the WindowManager will have initialised all of its internal state, including setting up Workspaces and Screens so any set up logic for Hooks that requires access to this should be placed in a startup hook as opposed to being attempted in the new method of the hook itself.

Trigger Point

Called when a new Client has been created in response to map request and all penrose specific state has been initialised, but before the client has been added to the active Workspace and before any Layouts have been applied.

The client argument is the newly created Client which can be modified if desired and optionally marked as externally_managed which will prevent penrose from adding it to a workspace. If the hook takes ownership of the client in this way then it is responsible for ensuring that it mapped and unmapped.

Example Uses

Inspecting newly created clients is the first and most obvious use of this hook but more advanced actions can be performed if the hook takes ownership of the client. For an example, see the Scratchpad extension which uses this hook to capture a spawned client.

Trigger Point

Called after a Client is removed from internal WindowManager state, either through a user initiated kill_client action or the underlying program exiting.

Example Uses

This hook is called after the client has already been removed, so it is not possible to interact with the client in any way. This is typically used as a companion to new_client when managing a target client externally.

Trigger Point

Called whenever an existing Client is added to a Workspace. This includes newly created clients when they are first mapped and clients being moved between workspaces using the client_to_workspace method on WindowManager.

Example Uses

The built in status bar widget Workspaces uses this to keep track of whether or not each workspace is occupied or not.

Trigger Point

Called whenever something updates the WM_NAME or _NET_WM_NAME property on a window. is_root == true indicates that this is the root window that is being modified.

Example Uses

This allows for simple setting / fetching of string data from individual clients or the root X window. In particular, this allows for a dwm style API for controlling something like a status bar by setting the root window name and then reading it inside of a hook.

Trigger Point

Called after a Layout is applied to the active Workspace.

Arguments are indices into the WindowManager workspace and screen rings (internal data structures that support indexing) which can be used to fetch references to the active Workspace and Screen. Note that this is called for every application of the layout which includes:

  • changing the active workspace
  • adding or removing a client from the active workspace
  • updating the main ratio or number of master clients
  • user calls to the layout_screen method on WindowManager
Example Uses

Running logic that applies after windows have been positioned for a given workspace: for example, ensuring that a particular window is always in a certain position or that it floats above all other windows.

Trigger Point

Called after a workspace’s Layout has been updated via cycle_layout.

Arguments are indices into the WindowManager workspace and screen rings (internal data structures that support indexing) which can be used to fetch references to the active Workspace and Screen.

Example Uses

Running additional setup logic for more complex layout functions that can not be done when the layout itself is invoked.

Trigger Point

Called after the active Workspace is changed on a Screen.

Arguments are indices into the WindowManager workspace ring (internal data structure that supports indexing) for the previous and new workspace.

Example Uses

Triggering logic when a particular workspace gains or loses focus.

Trigger Point

Called whenever a Workspace is dynamically added or removed from the list of known workspaces once penrose is running.

Example Uses

Updating hooks that care about tracking workspaces when the list of available workspaces is being dynamically updated while the WindowManager is running.

Trigger Point

Called after focus moves to a new Screen.

Argument is a index into the WindowManager screen ring (internal data structure that supports indexing) for the new Screen.

Example Uses

Tracking which screen is currently focused without needing to poll state in the WindowManager.

Trigger Point

Called when the list of known Screens is updated via the detect_screens method on the WindowManager.

Example Uses

Tracking Screen sizes and details without needing to poll / check every time your hook is called.

Trigger Point

Called when the underlying XConn emitted a RandrNotify event.

This hook will run before polling state for newly connected screens and running the screens_updated hook.

Example Uses

This is where any logic you want to run when external monitors are added / removed should be placed.

Trigger Point

Called after a Client gains focus.

Argument is the focused Client ID which can be used to fetch the internal Client state if needed.

Example Uses

Updating information about the focused client, such as in the ActiveWindowName status bar widget.

Trigger Point

Called at the bottom of the main WindowManager event loop after each XEvent is handled.

Example Uses

Useful if you want to ensure that all other event processing has taken place before you take action in response as part of a more complex hook.

Implementors