5 Advanced scripting, assorted tricks

This chapter explains some additional possibilities of scripting Ion that are not part of the basic configuration framework documented in chapter 3.

5.1 Hooks and other callbacks

5.1.1 Hooks

Hooks are lists of functions to be called when a certain event occurs. Hook handlers are registered with the function add_to_hook and removed with remove_from_hook. Both of these functions take as argument the name of the hook (a string) and the handler, the parameters of which depend on the actual hook in question.

The following hooks are currently defined:

Hook Description

screen_workspace_switched Called when the object (not necessarily a workspace despite the name) viewed on a screen is switched. Parameters to handler: the screen and the newly switched-to region.

genframe_managed_switched Called when the region viewed in a frame is switched. Parameters to handler: the frame and the newly switched-to region.

genframe_activated Called when a WGenFrame has received the focus.

genframe_inactivated Called when a WGenFrame has lost the focus.

clientwin_added Called when a client window has been mapped by a client program and Ion has started managing it.

deinit Called when Ion is about to start deinitialising before exiting. Handler has no parameters.

More hooks can be added on request as need arises.

5.1.2 Placement methods

In addition to the hooks mentioned above there is (at the moment) one callback that is not a hook. It is the function ionws_placement_method can be used by scripts to decide in which frame a newly mapped client window should be placed within an already decided on WIonWS. The function has three parameters: the workspace, the client window and a boolean indicating whether the client window's geometry (see WRegion.geom) was specified by the user by e.g. a -geometry command line switch. The function should return a frame on the workspace or nil if it made no decision. For example. the window placement heuristics in heuristics.lua implement this function.