<!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>
distrib
>
Mandriva
>
10.2
>
i586
>
media
>
contrib
>
by-pkgid
>
da02ac665899b94a7a5216482a9c0701
>
files
>
96
