5 Scripting

This chapter documents some additional features of the Ion configuration and scripting interface that can be used for more advanced scripting than the basic configuration exlained 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.

5.2 Referring to regions

5.2.1 Direct object references

All Ion objects are passed to Lua scriptss as 'userdatas', and you may safely store such object references for future use. The C-side object may be destroyed while Lua still refers to the object. All exported functions gracefully fail in such a case, but if you need to explicitly test that the C-side object still exists, use obj_exists.

As an example, the following short piece of code implements bookmarking:

local bookmarks={}

-- Set bookmark bm point to the region reg
function set_bookmark(bm, reg)
    bookmarks[bm]=reg
end

-- Go to bookmark bm
function goto_bookmark(bm)
    if bookmarks[bm] then
        -- We could check that bookmarks[bm] still exists, if we
        -- wanted to avoid an error message.
        bookmarks[bm]:goto()
    end
end

5.2.2 Name-based lookups

If you want to a single region with an exact known name, use lookup_region. If you want e.g. a list of all regions, use complete_region(""). Both functions accept an optional argument that can be used to specify that the return region(s) must be of a more specific type. The convenience functions lookup_clientwin, lookup_workspace, complete_clientwin and complete_workspace are also provided.

To get the name of an object, use WRegion.name. Please be aware, that the names of client windows reflect their titles and are subject to changes. To change the name of a non-client window region, use WRegion.set_name.

5.3 Alternative winprop selection criteria

Ion calls the Lua function get_winprop to find a winprop table for a window. The sole argument to this function is the client window. To select winprops by some alternative criterion, simply redefine this function. The function WClientWin.get_ident can be used to obtain, the class, instance, role and _ION_KLUDGES properties of the window.