<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <!--Converted with LaTeX2HTML 2002-1 (1.69) original version by: Nikos Drakos, CBLU, University of Leeds * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan * with significant contributions from: Jens Lippmann, Marek Rouchal, Martin Wilck and others --> <HTML> <HEAD> <TITLE>5. Scripting</TITLE> <META NAME="description" CONTENT="5. Scripting"> <META NAME="keywords" CONTENT="ionconf"> <META NAME="resource-type" CONTENT="document"> <META NAME="distribution" CONTENT="global"> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> <META NAME="Generator" CONTENT="LaTeX2HTML v2002-1"> <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> <LINK REL="STYLESHEET" HREF="ionconf.css"> <LINK REL="next" HREF="node7.html"> <LINK REL="previous" HREF="node5.html"> <LINK REL="up" HREF="ionconf.html"> <LINK REL="next" HREF="node7.html"> </HEAD> <BODY > <!--Navigation Panel--> <A NAME="tex2html329" HREF="node7.html"> <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> <A NAME="tex2html323" HREF="ionconf.html"> <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> <A NAME="tex2html317" HREF="node5.html"> <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> <A NAME="tex2html325" HREF="node1.html"> <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> <A NAME="tex2html327" HREF="node10.html"> <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> <BR> <B> Next:</B> <A NAME="tex2html330" HREF="node7.html">6. Function reference</A> <B> Up:</B> <A NAME="tex2html324" HREF="ionconf.html">Ion: Configuring and extending</A> <B> Previous:</B> <A NAME="tex2html318" HREF="node5.html">4. Graphical styles</A> <B> <A NAME="tex2html326" HREF="node1.html">Contents</A></B> <B> <A NAME="tex2html328" HREF="node10.html">Index</A></B> <BR> <BR> <!--End of Navigation Panel--> <!--Table of Child-Links--> <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A> <UL> <LI><A NAME="tex2html331" HREF="node6.html#SECTION00610000000000000000">5.1 Hooks and other callbacks</A> <UL> <LI><A NAME="tex2html332" HREF="node6.html#SECTION00611000000000000000">5.1.1 Hooks</A> <LI><A NAME="tex2html333" HREF="node6.html#SECTION00612000000000000000">5.1.2 Placement methods</A> </UL> <BR> <LI><A NAME="tex2html334" HREF="node6.html#SECTION00620000000000000000">5.2 Referring to regions</A> <UL> <LI><A NAME="tex2html335" HREF="node6.html#SECTION00621000000000000000">5.2.1 Direct object references</A> <LI><A NAME="tex2html336" HREF="node6.html#SECTION00622000000000000000">5.2.2 Name-based lookups</A> </UL> <BR> <LI><A NAME="tex2html337" HREF="node6.html#SECTION00630000000000000000">5.3 Alternative winprop selection criteria</A> </UL> <!--End of Table of Child-Links--> <HR> <H1><A NAME="SECTION00600000000000000000"></A> <A NAME="chap:tricks"></A> <BR> 5. Scripting </H1> <P> 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 <A HREF="node4.html#chap:config">3</A>. <P> <H2><A NAME="SECTION00610000000000000000"> 5.1 Hooks and other callbacks</A> </H2> <P> <H3><A NAME="SECTION00611000000000000000"> 5.1.1 Hooks</A> </H3> <P> Hooks are lists of functions to be called when a certain event occurs. Hook handlers are registered with the function <A HREF="node7.html#fn:add_to_hook"><TT>add_to_hook</TT></A> and removed with <A HREF="node7.html#fn:remove_from_hook"><TT>remove_from_hook</TT></A>. 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. <P> The following hooks are currently defined: <P> <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%"> <TR><TD ALIGN="LEFT">Hook</TD> <TD ALIGN="LEFT">Description</TD> </TR> <TR><TD ALIGN="LEFT"><TT>screen_workspace_switched</TT></TD> <TD ALIGN="LEFT">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.</TD> </TR> <TR><TD ALIGN="LEFT"><TT>genframe_managed_switched</TT></TD> <TD ALIGN="LEFT">Called when the region viewed in a frame is switched. Parameters to handler: the frame and the newly switched-to region.</TD> </TR> <TR><TD ALIGN="LEFT"><TT>genframe_activated</TT></TD> <TD ALIGN="LEFT">Called when a WGenFrame has received the focus.</TD> </TR> <TR><TD ALIGN="LEFT"><TT>genframe_inactivated</TT></TD> <TD ALIGN="LEFT">Called when a WGenFrame has lost the focus.</TD> </TR> <TR><TD ALIGN="LEFT"><TT>clientwin_added</TT></TD> <TD ALIGN="LEFT">Called when a client window has been mapped by a client program and Ion has started managing it.</TD> </TR> <TR><TD ALIGN="LEFT"><TT>deinit</TT></TD> <TD ALIGN="LEFT">Called when Ion is about to start deinitialising before exiting. Handler has no parameters.</TD> </TR> </TABLE> <P> More hooks can be added on request as need arises. <P> <H3><A NAME="SECTION00612000000000000000"> 5.1.2 Placement methods</A> </H3> <P> In addition to the hooks mentioned above there is (at the moment) one callback that is not a hook. It is the function <TT>ionws_placement_method</TT> 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 <A HREF="node7.html#fn:WRegion.geom"><TT>WRegion.geom</TT></A>) was specified by the user by e.g. a <TT>-geometry</TT> command line switch. The function should return a frame on the workspace or <TT>nil</TT> if it made no decision. For example. the window placement heuristics in <I>heuristics.lua</I> implement this function. <P> <H2><A NAME="SECTION00620000000000000000"> 5.2 Referring to regions</A> </H2> <P> <H3><A NAME="SECTION00621000000000000000"> 5.2.1 Direct object references</A> </H3> <P> 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 <A HREF="node7.html#fn:obj_exists"><TT>obj_exists</TT></A>. <P> As an example, the following short piece of code implements bookmarking: <P> <PRE> 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 </PRE> <P> <H3><A NAME="SECTION00622000000000000000"> 5.2.2 Name-based lookups</A> </H3> <P> If you want to a single region with an exact known name, use <A HREF="node7.html#fn:lookup_region"><TT>lookup_region</TT></A>. If you want e.g. a list of all regions, use <A HREF="node7.html#fn:complete_region"><TT>complete_region</TT></A><TT>("")</TT>. 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 <A HREF="node7.html#fn:lookup_clientwin"><TT>lookup_clientwin</TT></A>, <A HREF="node7.html#fn:lookup_workspace"><TT>lookup_workspace</TT></A>, <A HREF="node7.html#fn:complete_clientwin"><TT>complete_clientwin</TT></A> and <A HREF="node7.html#fn:complete_workspace"><TT>complete_workspace</TT></A> are also provided. <P> To get the name of an object, use <A HREF="node7.html#fn:WRegion.name"><TT>WRegion.name</TT></A>. 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 <A HREF="node7.html#fn:WRegion.set_name"><TT>WRegion.set_name</TT></A>. <P> <H2><A NAME="SECTION00630000000000000000"> 5.3 Alternative winprop selection criteria</A> </H2> <P> Ion calls the Lua function <TT>get_winprop</TT> 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 <A HREF="node7.html#fn:WClientWin.get_ident"><TT>WClientWin.get_ident</TT></A> can be used to obtain, the class, instance, role and <TT>_ION_KLUDGES</TT> properties of the window. <P> <P> <HR> <!--Navigation Panel--> <A NAME="tex2html329" HREF="node7.html"> <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> <A NAME="tex2html323" HREF="ionconf.html"> <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> <A NAME="tex2html317" HREF="node5.html"> <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> <A NAME="tex2html325" HREF="node1.html"> <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> <A NAME="tex2html327" HREF="node10.html"> <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> <BR> <B> Next:</B> <A NAME="tex2html330" HREF="node7.html">6. Function reference</A> <B> Up:</B> <A NAME="tex2html324" HREF="ionconf.html">Ion: Configuring and extending</A> <B> Previous:</B> <A NAME="tex2html318" HREF="node5.html">4. Graphical styles</A> <B> <A NAME="tex2html326" HREF="node1.html">Contents</A></B> <B> <A NAME="tex2html328" HREF="node10.html">Index</A></B> <!--End of Navigation Panel--> </BODY> </HTML>