Subsections


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

Hooks are lists of functions to be called when a certain event occurs. There are two types of them; normal and ''alternative'' hooks. Normal hooks do not return anything, but alt-hooks should return a boolean indicating whether it handled its assigned task succesfully. In the case that true is returned, remaining handlers are not called.

Hook handlers are registered by first finding the hook with ioncore.get_hook and then calling WHook.add on the (succesfull) result with the handler as parameter. Similarly handlers are unregistered with WHook.remove. For example:

ioncore.get_hook("ioncore_snapshot_hook"):add(
    function() print("Snapshot hook called.") end
)

In this example the hook handler has no parameters, but many hook handlers do. The types of parameters for each hook are listed in the hook reference, section 6.10.

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 non-WClientWin region with an exact known name, use ioncore.lookup_region. If you want a list of all regions, use ioncore.region_list. Both functions accept an optional argument that can be used to specify that the returned region(s) must be of a more specific type. Client windows live in a different namespace and for them you should use the equivalent functions ioncore.lookup_clientwin and ioncore.clientwin_list.

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

It is possible to write more complex winprop selection routines than those described in section 3.5. To match a particular winprop using whatever way you want to, just set the match field of the winprop to a function that receives the client window as its sole parameter, and that returns true if the winprop matches, and false otherwise.

The class, instance and role properties can be obtained with WClientWin.get_ident, and the title with WRegion.name. If you want to match against (almost) arbitrary window properties, have a look at the documentation for the following functions, and their standard Xlib counterparts: ioncore.x_intern_atom (XInternAtom), ioncore.x_get_window_property (XGetWindowProperty), and ioncore.x_get_text_property (XGetTextProperty).