<BODY >
<DIV CLASS="navigation"><!--Navigation Panel-->
-<A NAME="tex2html261"
+<A NAME="tex2html288"
HREF="node5.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
-<A NAME="tex2html255"
+<A NAME="tex2html282"
HREF="ionconf.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
-<A NAME="tex2html249"
+<A NAME="tex2html276"
HREF="node3.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
-<A NAME="tex2html257"
+<A NAME="tex2html284"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
-<A NAME="tex2html259"
+<A NAME="tex2html286"
HREF="node11.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
-<B> Next:</B> <A NAME="tex2html262"
+<B> Next:</B> <A NAME="tex2html289"
HREF="node5.html">4. Graphical styles</A>
-<B> Up:</B> <A NAME="tex2html256"
+<B> Up:</B> <A NAME="tex2html283"
HREF="ionconf.html">Configuring and extending Ion3</A>
-<B> Previous:</B> <A NAME="tex2html250"
+<B> Previous:</B> <A NAME="tex2html277"
HREF="node3.html">2. Preliminaries: Key concepts</A>
- <B> <A NAME="tex2html258"
+ <B> <A NAME="tex2html285"
HREF="node1.html">Contents</A></B>
- <B> <A NAME="tex2html260"
+ <B> <A NAME="tex2html287"
HREF="node11.html">Index</A></B>
<BR>
<BR></DIV>
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL CLASS="ChildLinks">
-<LI><A NAME="tex2html263"
+<LI><A NAME="tex2html290"
HREF="node4.html#SECTION00410000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> The configuration files</A>
-<LI><A NAME="tex2html264"
+<LI><A NAME="tex2html291"
HREF="node4.html#SECTION00420000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> A walk through <SPAN CLASS="textit">cfg_ion.lua</SPAN></A>
-<LI><A NAME="tex2html265"
+<LI><A NAME="tex2html292"
HREF="node4.html#SECTION00430000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Keys and rodents</A>
<UL>
-<LI><A NAME="tex2html266"
+<LI><A NAME="tex2html293"
HREF="node4.html#SECTION00431000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Binding handlers and special variables</A>
-<LI><A NAME="tex2html267"
+<LI><A NAME="tex2html294"
HREF="node4.html#SECTION00432000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Guards</A>
-<LI><A NAME="tex2html268"
+<LI><A NAME="tex2html295"
HREF="node4.html#SECTION00433000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining the bindings</A>
-<LI><A NAME="tex2html269"
+<LI><A NAME="tex2html296"
HREF="node4.html#SECTION00434000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Examples</A>
-<LI><A NAME="tex2html270"
+<LI><A NAME="tex2html297"
HREF="node4.html#SECTION00435000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Key specifications</A>
-<LI><A NAME="tex2html271"
+<LI><A NAME="tex2html298"
HREF="node4.html#SECTION00436000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> Button specifications</A>
-<LI><A NAME="tex2html272"
+<LI><A NAME="tex2html299"
HREF="node4.html#SECTION00437000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">7</SPAN> A further note on the default binding configuration</A>
</UL>
<BR>
-<LI><A NAME="tex2html273"
+<LI><A NAME="tex2html300"
HREF="node4.html#SECTION00440000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Menus</A>
<UL>
-<LI><A NAME="tex2html274"
+<LI><A NAME="tex2html301"
HREF="node4.html#SECTION00441000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Defining menus</A>
-<LI><A NAME="tex2html275"
+<LI><A NAME="tex2html302"
HREF="node4.html#SECTION00442000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Special menus</A>
-<LI><A NAME="tex2html276"
+<LI><A NAME="tex2html303"
HREF="node4.html#SECTION00443000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining context menus</A>
-<LI><A NAME="tex2html277"
+<LI><A NAME="tex2html304"
HREF="node4.html#SECTION00444000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">4</SPAN> Displaying menus</A>
</UL>
<BR>
-<LI><A NAME="tex2html278"
+<LI><A NAME="tex2html305"
HREF="node4.html#SECTION00450000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Winprops</A>
<UL>
-<LI><A NAME="tex2html279"
- HREF="node4.html#SECTION00451000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Classes, roles and instances</A>
-<LI><A NAME="tex2html280"
- HREF="node4.html#SECTION00452000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Finding window identification</A>
-<LI><A NAME="tex2html281"
- HREF="node4.html#SECTION00453000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Some common examples</A>
+<LI><A NAME="tex2html306"
+ HREF="node4.html#SECTION00451000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Sizehint winprops</A>
+<LI><A NAME="tex2html307"
+ HREF="node4.html#SECTION00452000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Classes, roles and instances</A>
+<LI><A NAME="tex2html308"
+ HREF="node4.html#SECTION00453000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Finding window identification</A>
+<LI><A NAME="tex2html309"
+ HREF="node4.html#SECTION00454000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Some common examples</A>
<UL>
-<LI><A NAME="tex2html282"
- HREF="node4.html#SECTION00453100000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Acrobat Reader</A>
-<LI><A NAME="tex2html283"
- HREF="node4.html#SECTION00453200000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Fixing a Mozilla Firebird transient</A>
-<LI><A NAME="tex2html284"
- HREF="node4.html#SECTION00453300000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Forcing newly created windows in named frames</A>
+<LI><A NAME="tex2html310"
+ HREF="node4.html#SECTION00454100000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Acrobat Reader</A>
+<LI><A NAME="tex2html311"
+ HREF="node4.html#SECTION00454200000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Forcing newly created windows in named frames</A>
+</UL>
+</UL>
+<BR>
+<LI><A NAME="tex2html312"
+ HREF="node4.html#SECTION00460000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> The statusbar</A>
+<UL>
+<LI><A NAME="tex2html313"
+ HREF="node4.html#SECTION00461000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">1</SPAN> The template</A>
+<LI><A NAME="tex2html314"
+ HREF="node4.html#SECTION00462000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">2</SPAN> The systray</A>
+<LI><A NAME="tex2html315"
+ HREF="node4.html#SECTION00463000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN> Monitors</A>
+<UL>
+<LI><A NAME="tex2html316"
+ HREF="node4.html#SECTION00463100000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Date</A>
+<LI><A NAME="tex2html317"
+ HREF="node4.html#SECTION00463200000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Load</A>
+<LI><A NAME="tex2html318"
+ HREF="node4.html#SECTION00463300000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Mail</A>
</UL></UL></UL>
<!--End of Table of Child-Links-->
<HR>
<A HREF="#sec:walkthrough">3.2</A>.
How keys and mouse action are bound to functions is described in detail
in <A HREF="#sec:bindings">3.3</A> and in section <A HREF="#sec:winprops">3.5</A> winprops are
-explained. For a reference on exported functions, see section
-<A HREF="node7.html#sec:exports">6</A>.
+explained. Finally, the statusbar is explained in <A HREF="#sec:statusbar">3.6</A>.
+For a reference on exported functions, see section <A HREF="node7.html#sec:exports">6</A>.
<P>
Ion3, to which document applies, stores its stock configuration files in
<SPAN CLASS="textit">/usr/local/etc/ion3/</SPAN> unless you, the OS package maintainer or
whoever installed the package on the system has modified the variables
-<TT>PREFIX</TT><A NAME="584"></A> or
-<TT>ETCDIR</TT><A NAME="585"></A> in
-<SPAN CLASS="textit">system.mk</SPAN><A NAME="586"></A> before compiling Ion.
+<TT>PREFIX</TT><A NAME="582"></A> or
+<TT>ETCDIR</TT><A NAME="583"></A> in
+<SPAN CLASS="textit">system.mk</SPAN><A NAME="584"></A> before compiling Ion.
In the first case you probably know where to find the files and in
the other case the system administrator or the OS package maintainer
should have provided documentation to point to the correct location.
files are attempted before <SPAN CLASS="textit">.lua</SPAN> files.
<P>
-All the configuration files are named <SPAN CLASS="textit">cfg_*.lua</SPAN> with the ''<SPAN CLASS="textit">*</SPAN>''
+All the configuration files are named <SPAN CLASS="textit">cfg_*.lua</SPAN> with the ``<SPAN CLASS="textit">*</SPAN>''
part varying. The configuration file for each module <SPAN CLASS="textit">mod_modname</SPAN> is
<SPAN CLASS="textit">cfg_modname.lua</SPAN>, with <SPAN CLASS="textit">modname</SPAN> varying by the module in
question. The following table summarises these and other configuration
<TD ALIGN="LEFT">Settings to get some applications behave more nicely have been
collected here. See section <A HREF="#sec:winprops">3.5</A>.</TD>
</TR>
+<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN CLASS="textit">cfg_layouts.lua</SPAN></TD>
+<TD ALIGN="LEFT">Some workspace layouts are defined here.</TD>
+</TR>
<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN CLASS="textit">cfg_tiling.lua</SPAN>
<SPAN CLASS="textit">cfg_query.lua</SPAN>
<SPAN CLASS="textit">cfg_menu.lua</SPAN>
the necessary modules and other configuration files configuring some
more specific aspects of Ion are loaded there. In this section we
take a walk through the stock <SPAN CLASS="textit">cfg_ion.lua</SPAN>.
-Notice that most of the settings are commented-out (<TT>-</TT> is a
+Notice that most of the settings are commented-out (<code>--</code> is a
line comment in Lua) in the actual file, as they're the defaults
nevertheless.
<P>
-The first thing one in the file is to set
+The first thing done in the file, is to set
<PRE>
META="Mod1+"
ALTMETA=""
</PRE>
These settings cause most of Ion's key bindings to use <SPAN CLASS="textbf">Mod1</SPAN> as the
-modifier key. If <TT>ALTMETA</TT> is set, it is used as modifier for the keys
-that don't normally use a modifier. for details on modifiers and key
-binding setup in general see section <A HREF="#sec:bindings">3.3</A>.
+modifier key. If <TT>ALTMETA</TT> is set, it is used as modifier for the
+keys that don't normally use a modifier. Note that these two are Lua
+variables used in the configuration files only, and not Ion settings.
+For details on modifiers and key binding setup in general, see section
+<A HREF="#sec:bindings">3.3</A>.
<P>
Next we do some basic feel configuration:
move frames and other objects mirror you actions immediately. If opaque
resize is disabled, a XOR rubber band is shown during the mode instead.
This will, unfortunately, cause Ion to also grab the X server and has some
-side effects.
+side effects.
<P>
-Next we load the configuration for Ion's core, and some kludges:
+There are some other options as well; see the documentation
+for <A HREF="node7.html#fn:ioncore.set"><TT>ioncore.set</TT></A> for details.
+
+<P>
+As a next step, in the actual <SPAN CLASS="textit">cfg_ion.lua</SPAN> file, we load
+<SPAN CLASS="textit">cfg_defaults.lua</SPAN>. However, it is merely a convenience file for
+doing exactly what we will going through below, and what is commented
+out in the actual file. If you do not want to load what
+<SPAN CLASS="textit">cfg_defaults.lua</SPAN> loads, just comment out the corresponding
+line, and uncomment the lines for the files that you want:
<P>
<PRE>
+--dopath("cfg_defaults")
dopath("cfg_ioncore")
dopath("cfg_kludges")
+dopath("cfg_layouts")
</PRE>
<P>
Most bindings and menus are defined in <SPAN CLASS="textit">cfg_ioncore.lua</SPAN>.
Details on making such definitions follow in sections <A HREF="#sec:bindings">3.3</A>
and <A HREF="#sec:menus">3.4</A>, respectively.
-some kludges or ''winprops'' to make some applications behave better
-under Ion are colledted in <SPAN CLASS="textit">cfg_kludges.lua</SPAN>; see section
+some kludges or ``winprops'' to make some applications behave better
+under Ion are collected in <SPAN CLASS="textit">cfg_kludges.lua</SPAN>; see section
<A HREF="#sec:winprops">3.5</A> for details. In addition to these, this file
lists quite a few statements of the form
<PRE>
a rule to construct a new title of a match occurs. This particular
rule is used to shorten e.g. 'Foo: barbaz<3>' to 'barba...<3>'; for
details see the function reference entry for <A HREF="node7.html#fn:ioncore.defshortening"><TT>ioncore.defshortening</TT></A>.
+Finally, <SPAN CLASS="textit">cfg_layouts.lua</SPAN> defines some workspace layouts, available
+through the <SPAN CLASS="textbf">F9</SPAN> workspace creation query.
<P>
To actually be able to do something besides display windows in full screen
<P>
<PRE>
-dopath("cfg_modules")
---dopath("mod_query")
---dopath("mod_menu")
---dopath("mod_tiling")
---dopath("mod_statusbar")
+dopath("mod_query")
+dopath("mod_menu")
+dopath("mod_tiling")
+dopath("mod_statusbar")
--dopath("mod_dock")
---dopath("mod_sp")
+dopath("mod_sp")
</PRE>
-<P>
-We actually load there another file listing the default selection of
-modules. If you only want to load additional modules, just uncomment
-the corresponding line. If you want to disable loading some modules,
-comment out the the line loading <SPAN CLASS="textit">cfg_modules</SPAN>, and uncomment
-the lines for the modules you want, or add more.
-
<P>
<H2><A NAME="SECTION00430000000000000000"></A>
<P>
Bindings are defined by calling the function
-<A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> with the ''context'' of the
+<A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> with the ``context'' of the
bindings and the a table of new bindings to make. The context is simply
string indicating one of the classes of regions (or modes such as
WMoveresMode) introduced in section <A HREF="node3.html#sec:objects">2.2</A>, and fully
<P>
There has been some confusion among users about the need to define the
-''context'' for each binding, so let me try to explain this design
+``context'' for each binding, so let me try to explain this design
decision here. The thing is that if there was a just a simple 'bind this
key to this action' method without knowledge of the context, some
limitations would have to be made on the available actions and writing
bind the same function to different key for different types of objects.
Indeed, the workspace and frame tab switching functions are the same both
classes being based on WMPlex, and in the stock configuration the
-switch to <SPAN CLASS="MATH"></SPAN>:th workspaces is bound to <SPAN CLASS="textbf">Mod1+n</SPAN> while the switch to
-<SPAN CLASS="MATH"></SPAN>:th tab is bound to the sequence <SPAN CLASS="textbf">Mod1+k n</SPAN>.
-
-<P>
-Currently known ''contexts'' include:
-<TT>WScreen</TT>,
-<TT>WMPlex</TT>,
-<TT>WMPlex.toplevel</TT>,
-<TT>WFrame</TT>,
-<TT>WFrame.toplevel</TT>,
-<TT>WFrame.floating</TT>,
-<TT>WFrame.tiled</TT>,
-<TT>WFrame.transient</TT>,
-<TT>WMoveresMode</TT>,
-<TT>WGroup</TT>,
-<TT>WGroupCW</TT>,
-<TT>WGroupWS</TT>,
-<TT>WClientWin</TT>,
-<TT>WTiling</TT>, and
-<TT>WStatusBar</TT>.
+switch to <SPAN CLASS="MATH"><IMG
+ WIDTH="15" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
+ SRC="img1.png"
+ ALT="$n$"></SPAN>:th workspaces is bound to <SPAN CLASS="textbf">Mod1+n</SPAN> while the switch to
+<SPAN CLASS="MATH"><IMG
+ WIDTH="15" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
+ SRC="img1.png"
+ ALT="$n$"></SPAN>:th tab is bound to the sequence <SPAN CLASS="textbf">Mod1+k n</SPAN>.
+
+<P>
+Currently known contexts include:
+`<TT>WScreen</TT>',
+`<TT>WMPlex</TT>',
+`<TT>WMPlex.toplevel</TT>',
+`<TT>WFrame</TT>',
+`<TT>WFrame.toplevel</TT>',
+`<TT>WFrame.floating</TT>',
+`<TT>WFrame.tiled</TT>',
+`<TT>WFrame.transient</TT>',
+`<TT>WMoveresMode</TT>',
+`<TT>WGroup</TT>',
+`<TT>WGroupCW</TT>',
+`<TT>WGroupWS</TT>',
+`<TT>WClientWin</TT>',
+`<TT>WTiling</TT>', and
+`<TT>WStatusBar</TT>'.
Most of these should be self-explanatory, corresponding to objects
-of class with the same name. The ones with <TT>.toplevel</TT> suffix
-refer to screens and ''toplevel'' frames, i.e. frames that are
-not used for transient windows. Likewise <TT>.transient</TT> refers
-to frames in transient mode, and <TT>.tiled</TT> and <TT>.floating</TT>
+of class with the same name. The ones with `<TT>.toplevel</TT>' suffix
+refer to screens and ``toplevel'' frames, i.e. frames that are
+not used for transient windows. Likewise `<TT>.transient</TT>' refers
+to frames in transient mode, and `<TT>.tiled</TT>' and `<TT>.floating</TT>'
to frames in, respectively, tiled and floating modes.
<P>
<P>
Unlike in Ion2, in Ion3 binding handlers are not normally passed as
-''anonymous functions'', although this is still possible. The preferred
-method now is to pass the code of the handler as a string. Two special
-variables are available in this code. These are
+``anonymous functions'', although this is still possible. The preferred
+method now is to pass the code of the handler as a string. Two following
+special variables are available in this code.
<P>
<TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
</TR>
<TR><TD ALIGN="LEFT"><TT>_chld</TT></TD>
<TD ALIGN="LEFT">Object corresponding to the currently active child window of the
- object referred to by <TT>_</TT>.</TD>
+ object referred to by <TT>_</TT>. This should seldom be needed.</TD>
</TR>
</TABLE>
<P>
-For example, supposing '<TT>_</TT>' is a WFrame, the following
-handler should move the active window to the right, if possible:
+For example, supposing <TT>_</TT> (underscore) is a WFrame, the
+following handler should move the active window to the right, if
+possible:
<P>
<PRE>
<P>
To suppress error messages, each binding handler may also be accompanied
-by a ''guard'' expression that blocks the handler from being called when
+by a ``guard'' expression that blocks the handler from being called when
the guard condition is not met. Currently the following guard expressions
are supported (for both <TT>_sub</TT> and <TT>_chld</TT>):
<TR><TD ALIGN="LEFT">Guard</TD>
<TD ALIGN="LEFT">Description</TD>
</TR>
-<TR><TD ALIGN="LEFT"><TT>"_sub:non-nil"</TT></TD>
+<TR><TD ALIGN="LEFT">`<TT>_sub:non-nil</TT>'</TD>
<TD ALIGN="LEFT">The <TT>_sub</TT> parameter must be set.</TD>
</TR>
-<TR><TD ALIGN="LEFT"><TT>"_sub:SomeClass"</TT></TD>
+<TR><TD ALIGN="LEFT">`<TT>_sub:SomeClass</TT>'</TD>
<TD ALIGN="LEFT">The <TT>_sub</TT> parameter must be member
of class SomeClass.</TD>
</TR>
Key presses:
<UL>
-<LI><A HREF="#fn:kpress"><TT>kpress</TT></A><TT>(keyspec, handler [, guard])</TT>,
+<LI><A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A>, and
+ <A HREF="node7.html#fn:ioncore.kpress_wait"><TT>kpress_wait</TT></A><TT>(keyspec, handler [, guard])</TT>.
</LI>
-<LI><A HREF="#fn:kpress_wait"><TT>kpress_wait</TT></A><TT>(keyspec, handler [, guard])</TT> and
+<LI><A HREF="node7.html#fn:ioncore.submap"><TT>submap</TT></A><TT>(keyspec, { ... more key bindings ... })</TT>.
</LI>
-<LI><A HREF="#fn:submap"><TT>submap</TT></A><TT>(keyspec, { ... more key bindings ... })</TT>.
+<LI><A HREF="node7.html#fn:ioncore.submap_enter"><TT>submap_enter</TT></A>, and
+ <A HREF="node7.html#fn:ioncore.submap_wait"><TT>submap_wait</TT></A><TT>(handler [, guard])</TT>.
</LI>
</UL>
Mouse actions:
<UL>
-<LI><A HREF="#fn:mclick"><TT>mclick</TT></A><TT>(buttonspec, handler [, guard])</TT>,
-</LI>
-<LI><A HREF="#fn:mdblclick"><TT>mdblclick</TT></A><TT>(buttonspec, handler [, guard])</TT>,
-</LI>
-<LI><A HREF="#fn:mpress"><TT>mpress</TT></A><TT>(buttonspec, handler [, guard])</TT> and
-</LI>
-<LI><A HREF="#fn:mdrag"><TT>mdrag</TT></A><TT>(buttonspec, handler [, guard])</TT>.
+<LI><A HREF="node7.html#fn:ioncore.mclick"><TT>mclick</TT></A>,
+ <A HREF="node7.html#fn:ioncore.mdblclick"><TT>mdblclick</TT></A>,
+ <A HREF="node7.html#fn:ioncore.mpress"><TT>mpress</TT></A>, and
+ <A HREF="node7.html#fn:ioncore.mdrag"><TT>mdrag</TT></A><TT>(buttonspec, handler [, guard])</TT>.
</LI>
</UL>
<P>
The actions that most of these functions correspond to should be clear
-and as explained in the reference, <A HREF="#fn:kpress_wait"><TT>kpress_wait</TT></A> is simply
-<A HREF="#fn:kpress"><TT>kpress</TT></A> with a flag set instructing Ioncore wait for all
-modifiers to be released before processing any further actions.
+and as explained in the reference, <A HREF="node7.html#fn:ioncore.kpress_wait"><TT>kpress_wait</TT></A> is simply
+<A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A> with a flag set instructing Ioncore wait for
+all modifiers to be released before processing any further actions.
This is to stop one from accidentally calling e.g.
-<A HREF="node7.html#fn:WRegion.rqclose"><TT>WRegion.rqclose</TT></A> multiple times in a row. The <A HREF="#fn:submap"><TT>submap</TT></A>
-function is used to define submaps or ''prefix maps''. The second
-argument to this function is table listing the key press actions
-(<A HREF="#fn:kpress"><TT>kpress</TT></A>) in the submap
+<A HREF="node7.html#fn:WRegion.rqclose"><TT>WRegion.rqclose</TT></A> multiple times in a row. The
+<A HREF="node7.html#fn:ioncore.submap"><TT>submap</TT></A> function is used to define submaps or
+``prefix maps''. The second argument to this function is table listing
+the key press actions (<A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A>) in the submap.
+The <A HREF="node7.html#fn:ioncore.submap_enter"><TT>submap_enter</TT></A> handler is called when the submap
+is entered, in which this handler is defined. Likewise, the
+<A HREF="node7.html#fn:ioncore.submap_wait"><TT>submap_wait</TT></A> handler is called when all modifiers
+have been released while waiting for further key presses in the submap.
<P>
The parameters <TT>keyspec</TT> and <TT>buttonspec</TT> are explained below
As seen above, the functions that create key binding specifications require
a <TT>keyspec</TT> argument. This argument should be a string containing the
name of a key as listed in the X header file <SPAN CLASS="textit">keysymdef.h</SPAN><A NAME="tex2html7"
- HREF="#foot857"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A> without the <TT>XK_</TT> prefix.
-<A NAME="858"></A>
+ HREF="#foot876"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A> without the <TT>XK_</TT> prefix.
+<A NAME="877"></A>
Most of the key names are quite intuitive while some are not. For example,
the <SPAN CLASS="textbf">Enter</SPAN> key on the main part of the keyboard has the less common
name <SPAN CLASS="textbf">Return</SPAN> while the one the numpad is called <SPAN CLASS="textbf">KP_Enter</SPAN>.
<P>
-The <TT>keyspec</TT> string may optionally have multiple ''modifier'' names
+The <TT>keyspec</TT> string may optionally have multiple ``modifier'' names
followed by a plus sign (<TT>+</TT>) as a prefix. X defines the following
modifiers:
-<BLOCKQUOTE>
+
+<P>
<SPAN CLASS="textbf">Shift</SPAN>, <SPAN CLASS="textbf">Control</SPAN>, <SPAN CLASS="textbf">Mod1</SPAN> to <SPAN CLASS="textbf">Mod5</SPAN>,
<SPAN CLASS="textbf">AnyModifier</SPAN> and <SPAN CLASS="textbf">Lock</SPAN>.
-<A NAME="859"></A>
-<A NAME="860"></A>
-<A NAME="861"></A>
-<A NAME="862"></A>
-<A NAME="863"></A>
-
-</BLOCKQUOTE>
+<A NAME="878"></A>
+<A NAME="879"></A>
+<A NAME="880"></A>
+<A NAME="881"></A>
+<A NAME="882"></A>
<P>
X allows binding all of these modifiers to almost any key and while this
list of modifiers does not explicitly list keys such as
-<SPAN CLASS="textbf">Alt</SPAN><A NAME="864"></A> that are common on modern keyboards, such
+<SPAN CLASS="textbf">Alt</SPAN><A NAME="883"></A> that are common on modern keyboards, such
keys are bound to one of the <SPAN CLASS="textbf">ModN</SPAN>. On systems running XFree86
<SPAN CLASS="textbf">Alt</SPAN> is usually <SPAN CLASS="textbf">Mod1</SPAN>. On Suns <SPAN CLASS="textbf">Mod1</SPAN> is the diamond key
-and <SPAN CLASS="textbf">Alt</SPAN> something else. One of the ''flying window'' keys on so
+and <SPAN CLASS="textbf">Alt</SPAN> something else. One of the ``flying window'' keys on so
called Windows-keyboards is probably mapped to <SPAN CLASS="textbf">Mod3</SPAN> if you have
-such a key. Use the program <SPAN CLASS="textit">xmodmap</SPAN><A NAME="865"></A>
+such a key. Use the program <SPAN CLASS="textit">xmodmap</SPAN><A NAME="884"></A>
to find out what exactly is bound where.
<P>
default.
<P>
-Ion ignores the <SPAN CLASS="textbf">Lock</SPAN> modifier and any <SPAN CLASS="textbf">ModN</SPAN> (<SPAN CLASS="MATH"></SPAN>)
-bound to <SPAN CLASS="textbf">NumLock</SPAN><A NAME="866"></A> or
-<SPAN CLASS="textbf">ScrollLock</SPAN><A NAME="867"></A>
+Ion ignores the <SPAN CLASS="textbf">Lock</SPAN> modifier and any <SPAN CLASS="textbf">ModN</SPAN> (<SPAN CLASS="MATH"><IMG
+ WIDTH="82" HEIGHT="15" ALIGN="BOTTOM" BORDER="0"
+ SRC="img2.png"
+ ALT="$N=1{\ldots} 5$"></SPAN>)
+bound to <SPAN CLASS="textbf">NumLock</SPAN><A NAME="885"></A> or
+<SPAN CLASS="textbf">ScrollLock</SPAN><A NAME="886"></A>
by default because such<A NAME="tex2html8"
- HREF="#foot836"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A> locking keys may otherwise
+ HREF="#foot855"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A> locking keys may otherwise
cause confusion.
<P>
Button specifications are similar to key definitions but now
instead of specifying modifiers and a key, you specify modifiers
and one of the button names <SPAN CLASS="textbf">Button1</SPAN> to
-<SPAN CLASS="textbf">Button5</SPAN><A NAME="868"></A>. Additionally the
+<SPAN CLASS="textbf">Button5</SPAN><A NAME="887"></A>. Additionally the
specification may end with an optional area name following an @-sign.
Only frames currently support areas, and the supported values in this
case are
-<TT>"border"</TT>, <TT>"tab"</TT>, <TT>"empty_tab"</TT>, <TT>"client"</TT> and
-<TT>nil</TT> (for the whole frame).
+`<TT>border</TT>', `<TT>tab</TT>', `<TT>empty_tab</TT>', `<TT>client</TT>'
+and <TT>nil</TT> (for the whole frame).
<P>
For example, the following code binds dragging a tab with the first
<P>
The default binding configuration contains references to the variables
<TT>META</TT> and <TT>ALTMETA</TT> instead of directly using the default
-values of <TT>"Mod1+"</TT> and <TT>""</TT> (nothing). As explained in
+values of `<TT>Mod1+</TT>' and `' (nothing). As explained in
section <A HREF="#sec:walkthrough">3.2</A>, the definitions of these variables
appear in <SPAN CLASS="textit">cfg_ion.lua</SPAN>. This way you can easily change the the
modifiers used by all bindings in the default configuration without
</H3>
<P>
-<A NAME="1114"></A>
-<A NAME="1171"></A>
-<A NAME="1172"></A>
-<A NAME="1173"></A>
+<A NAME="1144"></A>
+<A NAME="1198"></A>
+<A NAME="1199"></A>
+<A NAME="1200"></A>
In the stock configuration file setup, menus are defined in the file
<SPAN CLASS="textit">cfg_menus.lua</SPAN> as previously mentioned. The <SPAN CLASS="textit">mod_menu</SPAN> module
must be loaded for one to be able to define menus, and this is done with
<TR><TD ALIGN="LEFT">Menu name</TD>
<TD ALIGN="LEFT">Description</TD>
</TR>
-<TR><TD ALIGN="LEFT"><TT>windowlist</TT></TD>
+<TR><TD ALIGN="LEFT">`<TT>windowlist</TT>'</TD>
<TD ALIGN="LEFT">List of all client windows. Activating an entry jumps to that window.</TD>
</TR>
-<TR><TD ALIGN="LEFT"><TT>workspacelist</TT></TD>
+<TR><TD ALIGN="LEFT">`<TT>workspacelist</TT>'</TD>
<TD ALIGN="LEFT">List of all workspaces. Activating an entry jumps to that workspaces.</TD>
</TR>
-<TR><TD ALIGN="LEFT"><TT>focuslist</TT></TD>
+<TR><TD ALIGN="LEFT">`<TT>focuslist</TT>'</TD>
<TD ALIGN="LEFT">List of client windows with recent activity in them, followed by
previously focused client windows.</TD>
</TR>
-<TR><TD ALIGN="LEFT"><TT>focuslist_</TT></TD>
+<TR><TD ALIGN="LEFT">`<TT>focuslist_</TT>'</TD>
<TD ALIGN="LEFT">List of previously focused client windows.</TD>
</TR>
-<TR><TD ALIGN="LEFT"><TT>stylemenu</TT></TD>
+<TR><TD ALIGN="LEFT">`<TT>stylemenu</TT>'</TD>
<TD ALIGN="LEFT">List of available <SPAN CLASS="textit">look_*.lua</SPAN> style files. Activating an entry
loads that style and ask to save the selection.</TD>
</TR>
-<TR><TD ALIGN="LEFT"><TT>ctxmenu</TT></TD>
+<TR><TD ALIGN="LEFT">`<TT>ctxmenu</TT>'</TD>
<TD ALIGN="LEFT">Context menu for given object.</TD>
</TR>
</TABLE>
</H3>
<P>
-The ''ctxmenu'' is a special menu that is assembled from a defined context
+The ``ctxmenu'' is a special menu that is assembled from a defined context
menu for the object for which the menu was opened for, but also includes
the context menus for the manager objects as submenus.
</PRE>
<P>
-Some of the same ''modes'' as were available for some bindings
-may also be used: <TT>WFrame.tiled</TT>, <TT>WFrame.floating</TT>,
-and <TT>WFrame.transient</TT>.
+Some of the same ``modes'' as were available for some bindings
+may also be used: `<TT>WFrame.tiled</TT>', `<TT>WFrame.floating</TT>',
+and `<TT>WFrame.transient</TT>'.
<P>
<TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.grabmenu"><TT>mod_menu.grabmenu</TT></A></TD>
<TD ALIGN="LEFT">A special version of <A HREF="node7.html#fn:mod_menu.menu"><TT>mod_menu.menu</TT></A> that grabs the keyboard
and is scrolled with a given key until all modifiers have been released,
- after which the selected entry is activated. This function is meant to
- be used for implementing, for example, Win***s-style <SPAN CLASS="textbf">Alt-Tab</SPAN>
- handling.<A NAME="tex2html9"
- HREF="#foot1174"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A></TD>
+ after which the selected entry is activated.</TD>
</TR>
</TABLE>
</H2>
<P>
-The so-called ''winprops''<A NAME="1269"></A> can be used to change how
+The so-called ``winprops''<A NAME="1291"></A> can be used to change how
specific windows are handled and to set up some kludges to deal with
badly behaving applications. They are defined by calling the function
<TT>defwinprop</TT> with a table containing the properties to set and the
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1429"></A>
+<DD><A NAME="1458"></A>
Set this to <TT>true</TT> for Acrobat Reader. It has an annoying
habit of trying to manage its dialogs instead of setting them as
transients and letting the window manager do its job, causing
</DD>
</DL>
-<P>
-
- <DL>
-<DT><STRONG>Winprop:</STRONG></DT>
-<DD><TT>aspect</TT> (table)
-
-</DD>
-<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1430"></A>
- The table should contain the entries <TT>w</TT> and <TT>h</TT> that
- override application-supplied aspect ratio hint.
-
-</DD>
-</DL>
-
<P>
<DL>
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1431"></A>
+<DD><A NAME="1459"></A>
Set this to open the window in a floating frame, when
in a group.
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1432"></A>
+<DD><A NAME="1460"></A>
Should the window be initially in full screen mode?
</DD>
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1433"></A>
+<DD><A NAME="1461"></A>
Should configure requests on the window be ignored?
Only has effect on floating windows.
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1434"></A>
+<DD><A NAME="1462"></A>
Ignore extended WM hints <TT>_NET_ACTIVE_WINDOW</TT> request.
</DD>
</DL>
-<P>
-
- <DL>
-<DT><STRONG>Winprop:</STRONG></DT>
-<DD><TT>ignore_resizeinc</TT> (boolean)
-
-</DD>
-<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1435"></A>
- Should application supplied size increments be ignored?
-
-</DD>
-</DL>
-
<P>
<DL>
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1436"></A>
+<DD><A NAME="1463"></A>
Should a newly created client window always be made
active, even if the allocated frame isn't.
<DL>
<DT><STRONG>Winprop:</STRONG></DT>
-<DD><TT>max_size</TT> (table)
-
-</DD>
-<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1437"></A>
- The table should contain the entries <TT>w</TT> and <TT>h</TT> that
- override application-supplied maximum size hint.
-
-</DD>
-</DL>
-
-<P>
-
- <DL>
-<DT><STRONG>Winprop:</STRONG></DT>
-<DD><TT>min_size</TT> (table)
+<DD><TT>new_group</TT> (string)
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1438"></A>
- Similar to <TT>max_size</TT> but for the minimum size hint.
+<DD><A NAME="1464"></A>
+ If the region specified by <TT>target</TT> winprop does not exist
+ (or that winprop is not set), create a new workspace using the
+ previously stored layout (see <A HREF="node7.html#fn:ioncore.deflayout"><TT>ioncore.deflayout</TT></A>) named by
+ this property. After creating the workspace, <TT>target</TT> is
+ attempted to be found again. (If that still fails, the newly
+ created workspace is still asked to manage the client window.)
</DD>
</DL>
<DL>
<DT><STRONG>Winprop:</STRONG></DT>
-<DD><TT>new_group</TT> (string)
+<DD><TT>oneshot</TT> (boolean)
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1439"></A>
- If the region specified by <TT>target</TT> winprop does not exist
- (or that winprop is not set), create a new workspace using the
- previously stored layout (see <A HREF="node7.html#fn:ioncore.deflayout"><TT>ioncore.deflayout</TT></A>) named by
- this property. After creating the workspace, <TT>target</TT> is
- attempted to be found again. (If that still fails, the newly
- created workspace is still asked to manage the client window.)
+<DD><A NAME="1465"></A>
+ Discard this winprop after first use.
</DD>
</DL>
<DL>
<DT><STRONG>Winprop:</STRONG></DT>
-<DD><TT>oneshot</TT> (boolean)
+<DD><TT>orientation</TT> (string)
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1440"></A>
- Discard this winprop after first use.
+<DD><A NAME="1466"></A>
+ The orientation of the window: one of `<TT>vertical</TT>' or
+ `<TT>horizontal</TT>'. This is only useful when using the
+ window as a status display.
</DD>
</DL>
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1441"></A>
- Put the window on the statusbar, in the named tray component,
- (The default tray component is called simply ``<TT>systray</TT>'',
+<DD><A NAME="1467"></A>
+ Put the window in the statusbar, in the named tray component,
+ (The default tray component is called simply `<TT>systray</TT>',
and others you give names to in your custom template, always
- prefixed by ``<TT>systray_</TT>''.
+ prefixed by `<TT>systray_</TT>'.
</DD>
</DL>
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1442"></A>
+<DD><A NAME="1468"></A>
Should a newly mapped client window be switched to within
its frame.
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1443"></A>
+<DD><A NAME="1469"></A>
The name of an object (workspace, frame) that should manage
windows of this type. See also <TT>new_group</TT>.
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1444"></A>
- "normal": No change in behaviour. "current": The window
- should be thought of as a transient for the current active
- client window (if any) even if it is not marked as a
- transient by the application. "off": The window should be
- handled as a normal window even if it is marked as a
+<DD><A NAME="1470"></A>
+ `<TT>normal</TT>': No change in behaviour. `<TT>current</TT>':
+ The window should be thought of as a transient for the current
+ active client window (if any) even if it is not marked as a
+ transient by the application. `<TT>off</TT>': The window should
+ be handled as a normal window even if it is marked as a
transient by the application.
</DD>
</DL>
-<P>
-
- <DL>
-<DT><STRONG>Winprop:</STRONG></DT>
-<DD><TT>transients_at_top</TT> (boolean)
-
-</DD>
-<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1445"></A>
- When transients are managed by the client window itself (as it
- is the case on tiled workspaces), should the transients be
- placed at the top of the window instead of bottom?
-
-</DD>
-</DL>
-
<P>
<DL>
</DD>
<DT><STRONG>Description:</STRONG></DT>
-<DD><A NAME="1446"></A>
+<DD><A NAME="1471"></A>
Should frames be made transparent when this window is selected?
<BR>
<P>
-<H3><A NAME="SECTION00451000000000000000"></A>
+<H3><A NAME="SECTION00451000000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Sizehint winprops</A>
+</H3>
+
+<P>
+Additionally, the winprops
+<TT>max_size</TT><A NAME="1472"></A>,
+<TT>min_size</TT><A NAME="1473"></A>,
+<TT>aspect</TT><A NAME="1474"></A>,
+<TT>resizeinc</TT><A NAME="1475"></A>,
+and
+<TT>ignore_max_size</TT><A NAME="1476"></A>,
+<TT>ignore_min_size</TT><A NAME="1477"></A>,
+<TT>ignore_aspect</TT><A NAME="1478"></A>,
+<TT>ignore_resizeinc</TT><A NAME="1479"></A>,
+may be used to override application-supplied size hints. The four
+first ones are tables with the fields <TT>w</TT> and <TT>h</TT>, indicating
+the width and height size hints in pixels, and the latter ignore
+winprop is a boolean.
+
+<P>
+Finally, the boolean
+<TT>userpos</TT><A NAME="1480"></A> option may be used to
+override the <TT>USPosition</TT> flag of the size hints. Normally,
+when this flag is set, Ion tries to respect the supplied window
+position more than when it is not set. Obviously, this makes sense
+only for floating windows.
+
+<P>
+
+<H3><A NAME="SECTION00452000000000000000"></A>
<A NAME="sec:classesrolesinstances"></A>
<BR>
-<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Classes, roles and instances
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Classes, roles and instances
</H3>
<P>
-The identification information in the winprop specification is usually the
-<TT>class</TT><A NAME="1447"></A>,
-<TT>role</TT><A NAME="1448"></A>,
-<TT>instance</TT><A NAME="1449"></A> and
-<TT>name</TT>
-of the window. The <TT>name</TT> field is a Lua-style regular expression
-matched against the window's title and the rest are strings that must
-exactly match the corresponding window information. It is not necessary
-to specify all of these fields.
+The identification information supported are
+<TT>class</TT><A NAME="1481"></A>,
+<TT>role</TT><A NAME="1482"></A>,
+<TT>instance</TT><A NAME="1483"></A>,
+<TT>name</TT><A NAME="1484"></A>,
+<TT>is_transient</TT><A NAME="1485"></A>, and
+<TT>is_dockapp</TT><A NAME="1486"></A>.
+It is not necessary to specify all of these fields.
+The first three are strings, and must exactly match the
+corresponding information obtained from the window's properties.
+The <TT>name</TT> field is a Lua-style regular expression matched against
+the window's title. The <TT>is_transient</TT> field is a boolean that can
+be used to include or exclude transients only, while the <TT>is_dockapp</TT>
+field is set by Ion for the dock windows of Window Maker dockapp protocol
+dockapps. Usually this is the only information available for these
+<SPAN CLASS="textit">icon</SPAN> windows.
<P>
Ion looks for a matching winprop in the order listed by the following
<TR><TD ALIGN="LEFT"><TT>class</TT></TD>
<TD ALIGN="LEFT"><TT>role</TT></TD>
<TD ALIGN="LEFT"><TT>instance</TT></TD>
-<TD ALIGN="LEFT"><TT>name</TT></TD>
+<TD ALIGN="LEFT">other</TD>
</TR>
<TR><TD ALIGN="LEFT">E</TD>
<TD ALIGN="LEFT">E</TD>
</DIV>
<P>
-If there are multiple winprops with other identification information
-the same but different <TT>name</TT>, the longest match is chosen.
+If there are multiple matching winprops with the same
+<TT>class</TT>, <TT>role</TT> and <TT>instance</TT>, but other information
+different, the most recently defined one is used.
<P>
-<H3><A NAME="SECTION00452000000000000000">
-<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Finding window identification</A>
+<H3><A NAME="SECTION00453000000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Finding window identification</A>
</H3>
<P>
for a window and all the transient windows managed within it.
<P>
-<A NAME="1402"></A>
+<A NAME="1435"></A>
Another way to get the identification information is to use <TT>xprop</TT>.
Simply run To get class and instance, simply run <TT>xprop WM_CLASS</TT>
and click on the particular window of interest. The class is the latter of
This method, however, will not work on transients.
<P>
-<A NAME="1406"></A>
-So-called ''transient windows'' are usually short-lived dialogs (although
+<A NAME="1439"></A>
+So-called ``transient windows'' are usually short-lived dialogs (although
some programs abuse this property) that have a parent window that they are
-''transient for''. On tiled workspaces Ion displays these windows
-simulatenously with the parent window at the bottom of the same frame.
+``transient for''. On tiled workspaces Ion displays these windows
+simultaneously with the parent window at the bottom of the same frame.
Unfortunately <TT>xprop</TT> is stupid and can't cope with this situation,
returning the parent window's properties when the transient is clicked on.
For this reason you'll have to do a little extra work to get the properties
-for that window.<A NAME="tex2html11"
- HREF="#foot1451"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN></SUP></A>
+for that window.<A NAME="tex2html9"
+ HREF="#foot1488"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A>
<P>
Finally, it should be mentioned that too many authors these days
-''forget'' to set this vital identification to anything meaningful:
-everything except name is the same for all of the programs's
-windows, for example.
+``forget'' to set this vital identification to anything meaningful:
+everything except name is the same for all of the program's
+windows, for example. Some other programs only set this information
+after the window has been mapped, i.e. the window manager has been
+told to start managing it, which is obviously too late.
+Gtk applications in particular are often guilty on both counts.
<P>
-<H3><A NAME="SECTION00453000000000000000">
-<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Some common examples</A>
+<H3><A NAME="SECTION00454000000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Some common examples</A>
</H3>
<P>
-<H4><A NAME="SECTION00453100000000000000">
-<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Acrobat Reader</A>
+<H4><A NAME="SECTION00454100000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Acrobat Reader</A>
</H4>
<P>
<P>
-<H4><A NAME="SECTION00453200000000000000">
-<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Fixing a Mozilla Firebird transient</A>
-</H4>
-
-<P>
-Mozilla Firebird (0.7) incorrectly does not set the <TT>WM_TRANSIENT_FOR</TT>
-property for the dialog that is used to ask the action to take for a file.
-It, however, sets the the property point to the main window for the save
-dialog. This can be annoying and confusing, as the first dialog is not
-closed before the second is displayed.
-
-<P>
-We'd like the first dialog to be transient to the main window. The closest
-we can get to that is to consider it transient to the current window (if
-there's one). Unfortunately Firebird does not set any meaningful classes,
-instances or roles for the windows, so we'll have to rely on an ugly title
-match.
-
-<P>
-<PRE>
-defwinprop{
- class = "MozillaFirebird-bin",
- name = "Opening .*",
- transient_mode = "current",
-}
-</PRE>
-
-<P>
-
-<H4><A NAME="SECTION00453300000000000000">
-<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Forcing newly created windows in named frames</A>
+<H4><A NAME="SECTION00454200000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Forcing newly created windows in named frames</A>
</H4>
<P>
<P>
For this example to work, we have to somehow create a frame named
-<TT>sysmonframe</TT>. One way to do this is to make the following
+`<TT>sysmonframe</TT>'. One way to do this is to make the following
call in the <SPAN CLASS="textbf">Mod1+F3</SPAN> Lua code query:
<P>
Recall that <TT>_</TT> points to the multiplexer (frame or screen) in which
the query was opened. Running this code should open a new query prefilled
with the current name of the frame. In our example we would change the
-name to <TT>sysmonframe</TT>, but we could just as well have used the
+name to `<TT>sysmonframe</TT>', but we could just as well have used the
default name formed from the frame's class name and an instance number.
<P>
+<H2><A NAME="SECTION00460000000000000000"></A>
+<A NAME="sec:statusbar"></A>
+<BR>
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> The statusbar
+</H2>
+
+<P>
+The <SPAN CLASS="textit">mod_statusbar</SPAN> module provides a statusbar that adapts to
+layouts of tilings, using only the minimal space needed. Ion only
+supports one adaptive ``status display'' object per screen, so this
+statusbar is mutually exclusive with the embedded mode of <SPAN CLASS="textit">mod_dock</SPAN>
+docks.
+
+<P>
+The statusbar is configured in <SPAN CLASS="textit">cfg_statusbar.lua</SPAN>. Typically,
+the configuration consists of two steps: creating a statusbar with
+<A HREF="node7.html#fn:mod_statusbar.create"><TT>mod_statusbar.create</TT></A>, and then launching the separate
+<TT>ion-statusd</TT> status daemon process with
+<A HREF="node7.html#fn:mod_statusbar.launch_statusd"><TT>mod_statusbar.launch_statusd</TT></A>. This latter phase is done
+automatically, if it was not done by the configuration file, but
+the configuration file may pass extra parameters to <TT>ion-statusd</TT>
+monitors. (See Section <A HREF="node6.html#sec:statusd">5.4</A> for more information on
+writing <TT>ion-statusd</TT> monitors.)
+
+<P>
+A typical <SPAN CLASS="textit">cfg_statusbar.lua</SPAN> configuration might look as follows:
+
+<P>
+<PRE>
+-- Create a statusbar
+mod_statusbar.create{
+ screen = 0, -- First screen,
+ pos = 'bl', -- bottom left corner
+ systray = true, -- Swallow systray windows
+
+ -- The template
+ template = "[ %date || load:% %>load || mail:% %>mail_new/%>mail_total ]"
+ .. " %filler%systray",
+}
+
+-- Launch ion-statusd.
+mod_statusbar.launch_statusd{
+ -- Date meter
+ date={
+ -- ISO-8601 date format with additional abbreviated day name
+ date_format='%a %Y-%m-%d %H:%M',
+ },
+}
+</PRE>
+
+<P>
+
+<H3><A NAME="SECTION00461000000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">1</SPAN> The template</A>
+</H3>
+
+<P>
+The template specifies what is shown on the statusbar; for information
+on the other options to <A HREF="node7.html#fn:mod_statusbar.create"><TT>mod_statusbar.create</TT></A>, see the reference.
+Strings of the form `<TT>%spec</TT>' tokens specially interpreter by
+the statusbar; the rest appears verbatim. The <TT>spec</TT> typically
+consists of the name of the value/meter to display (beginning with a latin
+alphabet), but may be preceded by an alignment specifier and a number
+specifying the minimum width. The alignment specifiers are: `<TT>></TT>'
+for right, `<TT><</TT>' for left, and `<TT>|</TT>' for centring. Additionally,
+space following `<TT>%</TT>' (that is, the string `<TT>% </TT>'), adds
+``stretchable space'' at that point. The special string `<TT>%filler</TT>'
+may be used to flush the rest of the template to the right end of
+the statusbar.
+
+<P>
+The stretchable space works as follows: <SPAN CLASS="textit">mod_statusbar</SPAN> remembers
+the widest string (in terms of graphical presentation) that it has
+seen for each meter, unless the width has been otherwise constrained.
+If there is stretchable space in the template, it tries to make the
+meter always take this much space, by stretching any space found in
+the direction indicated by the alignment specifier: the opposite
+direction for left or right alignment, and both for centring.
+
+<P>
+
+<H3><A NAME="SECTION00462000000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">2</SPAN> The systray</A>
+</H3>
+
+<P>
+The special `<TT>%systray</TT>' and `<TT>%systray_*</TT>'
+(`<TT>*</TT>' varying) monitors indicate where to place system tray
+windows. There may be multiple of these. KDE-protocol system tray
+icons are placed in `<TT>%systray</TT>' automatically, unless disabled
+with the <TT>systray</TT> option. Otherwise the <TT>statusbar</TT> winprop may
+be used to place any window in any particular `<TT>%systray_*</TT>'.
+
+<P>
+
+<H3><A NAME="SECTION00463000000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN> Monitors</A>
+</H3>
+
+<P>
+The part before the first
+underscore of each monitor name, describes the script/plugin/module
+that provides the meter, and any configuration should be passed
+in the a corresponding sub-table <A HREF="node7.html#fn:mod_statusbar.launch_statusd"><TT>mod_statusbar.launch_statusd</TT></A>.
+Ion comes with date, load and mail (for plain old mbox)
+<TT>ion-statusd</TT> monitor scripts. More may be obtained from
+the scripts repository [<A
+ HREF="node12.html#scripts">1</A>]. These included scripts
+provide the following monitors and their options
+
+<P>
+
+<H4><A NAME="SECTION00463100000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Date</A>
+</H4>
+
+<P>
+Options: <TT>date_format</TT>: The date format in as seen above,
+in the usual <TT>strftime</TT> format. <TT>formats</TT>: table of
+formats for additional date monitors, the key being the name
+of the monitor (without the `<TT>date_</TT>' prefix).
+
+<P>
+Monitors: `<TT>date</TT>' and other user-specified ones with the
+`<TT>date_</TT>' prefix.
+
+<P>
+
+<H4><A NAME="SECTION00463200000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Load</A>
+</H4>
+
+<P>
+Options: <TT>update_interval</TT>: Update interval in milliseconds
+(default 10s). <TT>important_threshold</TT>: Threshold above which
+the load is marked as important (default 1.5), so that the
+drawing engine may be suitably hinted. <TT>critical_threshold</TT>:
+Threshold above which the load is marked as critical (default 4.0).
+
+<P>
+Monitors: `<TT>load</TT>' (for all three values),
+`<TT>load_1min</TT>', `<TT>load_5min</TT>' and `<TT>load_15min</TT>'.
+
+<P>
+
+<H4><A NAME="SECTION00463300000000000000">
+<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Mail</A>
+</H4>
+
+<P>
+Options: <TT>update_interval</TT>: Update interval in milliseconds
+(default 1min). <TT>mbox</TT>: mbox-format mailbox location
+(default <code>$MAIL</code>).
+<TT>files</TT>: list of additional mailboxes, the key giving the
+name of the monitor.
+
+<P>
+Monitors: `<TT>mail_new</TT>', `<TT>mail_unread</TT>',
+`<TT>mail_total</TT>', and corresponding
+`<TT>mail_*_new</TT>', `<TT>mail_*_unread</TT>', and `<TT>mail_*_total</TT>'
+for the additional mailboxes (`<TT>*</TT>' varying).
+
+<P>
+
<P>
<BR><HR><H4>Footnotes</H4>
<DL>
-<DT><A NAME="foot857">...keysymdef.h</A><A
+<DT><A NAME="foot876">...keysymdef.h</A><A
HREF="node4.html#tex2html7"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
<DD>This file can usually be found in the directory
<SPAN CLASS="textit">/usr/X11R6/include/X11/</SPAN>.
</DD>
-<DT><A NAME="foot836">... such</A><A
+<DT><A NAME="foot855">... such</A><A
HREF="node4.html#tex2html8"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A></DT>
<DD>Completely useless keys that should be
gotten rid of in the author's opinion.
</DD>
-<DT><A NAME="foot1174">... handling.</A><A
+<DT><A NAME="foot1488">... window.</A><A
HREF="node4.html#tex2html9"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A></DT>
-<DD>See the <SPAN CLASS="textit">wcirculate.lua</SPAN> script in the Ion
- scripts repository <TT><A NAME="tex2html10"
- HREF="http://iki.fi/tuomov/repos/ion-scripts-3/">http://iki.fi/tuomov/repos/ion-scripts-3/</A></TT>.
-
-</DD>
-<DT><A NAME="foot1451">... window.</A><A
- HREF="node4.html#tex2html11"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN></SUP></A></DT>
<DD>There's a patch to <TT>xprop</TT> to
fix this, but nothing seems to be happening with respect to including it in
XFree86.
</DL>
<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
-<A NAME="tex2html261"
+<A NAME="tex2html288"
HREF="node5.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
-<A NAME="tex2html255"
+<A NAME="tex2html282"
HREF="ionconf.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
-<A NAME="tex2html249"
+<A NAME="tex2html276"
HREF="node3.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
-<A NAME="tex2html257"
+<A NAME="tex2html284"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
-<A NAME="tex2html259"
+<A NAME="tex2html286"
HREF="node11.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
-<B> Next:</B> <A NAME="tex2html262"
+<B> Next:</B> <A NAME="tex2html289"
HREF="node5.html">4. Graphical styles</A>
-<B> Up:</B> <A NAME="tex2html256"
+<B> Up:</B> <A NAME="tex2html283"
HREF="ionconf.html">Configuring and extending Ion3</A>
-<B> Previous:</B> <A NAME="tex2html250"
+<B> Previous:</B> <A NAME="tex2html277"
HREF="node3.html">2. Preliminaries: Key concepts</A>
- <B> <A NAME="tex2html258"
+ <B> <A NAME="tex2html285"
HREF="node1.html">Contents</A></B>
- <B> <A NAME="tex2html260"
+ <B> <A NAME="tex2html287"
HREF="node11.html">Index</A></B> </DIV>
<!--End of Navigation Panel-->