ionconf/node4.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2
   3 <!--Converted with LaTeX2HTML 2002-2-1 (1.71)
   4 original version by:  Nikos Drakos, CBLU, University of Leeds
   5 * revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
   6 * with significant contributions from:
   7   Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
   8 <HTML>
   9 <HEAD>
  10 <TITLE>3. Basic configuration</TITLE>
  11 <META NAME="description" CONTENT="3. Basic configuration">
  12 <META NAME="keywords" CONTENT="ionconf">
  13 <META NAME="resource-type" CONTENT="document">
  14 <META NAME="distribution" CONTENT="global">
  15
  16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
  17 <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
  18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
  19
  20 <LINK REL="STYLESHEET" HREF="ionconf.css">
  21
  22 <LINK REL="next" HREF="node5.html">
  23 <LINK REL="previous" HREF="node3.html">
  24 <LINK REL="up" HREF="ionconf.html">
  25 <LINK REL="next" HREF="node5.html">
  26 </HEAD>
  27
  28 <BODY >
  29
  30 <DIV CLASS="navigation"><!--Navigation Panel-->
  31 <A NAME="tex2html288"
  32   HREF="node5.html">
  33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
  34 <A NAME="tex2html282"
  35   HREF="ionconf.html">
  36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
  37 <A NAME="tex2html276"
  38   HREF="node3.html">
  39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
  40 <A NAME="tex2html284"
  41   HREF="node1.html">
  42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
  43 <A NAME="tex2html286"
  44   HREF="node11.html">
  45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
  46 <BR>
  47 <B> Next:</B> <A NAME="tex2html289"
  48   HREF="node5.html">4. Graphical styles</A>
  49 <B> Up:</B> <A NAME="tex2html283"
  50   HREF="ionconf.html">Configuring and extending Ion3</A>
  51 <B> Previous:</B> <A NAME="tex2html277"
  52   HREF="node3.html">2. Preliminaries: Key concepts</A>
  53  &nbsp; <B>  <A NAME="tex2html285"
  54   HREF="node1.html">Contents</A></B>
  55  &nbsp; <B>  <A NAME="tex2html287"
  56   HREF="node11.html">Index</A></B>
  57 <BR>
  58 <BR></DIV>
  59 <!--End of Navigation Panel-->
  60 <!--Table of Child-Links-->
  61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
  62
  63 <UL CLASS="ChildLinks">
  64 <LI><A NAME="tex2html290"
  65   HREF="node4.html#SECTION00410000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> The configuration files</A>
  66 <LI><A NAME="tex2html291"
  67   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>
  68 <LI><A NAME="tex2html292"
  69   HREF="node4.html#SECTION00430000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Keys and rodents</A>
  70 <UL>
  71 <LI><A NAME="tex2html293"
  72   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>
  73 <LI><A NAME="tex2html294"
  74   HREF="node4.html#SECTION00432000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Guards</A>
  75 <LI><A NAME="tex2html295"
  76   HREF="node4.html#SECTION00433000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining the bindings</A>
  77 <LI><A NAME="tex2html296"
  78   HREF="node4.html#SECTION00434000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Examples</A>
  79 <LI><A NAME="tex2html297"
  80   HREF="node4.html#SECTION00435000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Key specifications</A>
  81 <LI><A NAME="tex2html298"
  82   HREF="node4.html#SECTION00436000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> Button specifications</A>
  83 <LI><A NAME="tex2html299"
  84   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>
  85 </UL>
  86 <BR>
  87 <LI><A NAME="tex2html300"
  88   HREF="node4.html#SECTION00440000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Menus</A>
  89 <UL>
  90 <LI><A NAME="tex2html301"
  91   HREF="node4.html#SECTION00441000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Defining menus</A>
  92 <LI><A NAME="tex2html302"
  93   HREF="node4.html#SECTION00442000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Special menus</A>
  94 <LI><A NAME="tex2html303"
  95   HREF="node4.html#SECTION00443000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining context menus</A>
  96 <LI><A NAME="tex2html304"
  97   HREF="node4.html#SECTION00444000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">4</SPAN> Displaying menus</A>
  98 </UL>
  99 <BR>
 100 <LI><A NAME="tex2html305"
 101   HREF="node4.html#SECTION00450000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Winprops</A>
 102 <UL>
 103 <LI><A NAME="tex2html306"
 104   HREF="node4.html#SECTION00451000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Sizehint winprops</A>
 105 <LI><A NAME="tex2html307"
 106   HREF="node4.html#SECTION00452000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Classes, roles and instances</A>
 107 <LI><A NAME="tex2html308"
 108   HREF="node4.html#SECTION00453000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Finding window identification</A>
 109 <LI><A NAME="tex2html309"
 110   HREF="node4.html#SECTION00454000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Some common examples</A>
 111 <UL>
 112 <LI><A NAME="tex2html310"
 113   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>
 114 <LI><A NAME="tex2html311"
 115   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>
 116 </UL>
 117 </UL>
 118 <BR>
 119 <LI><A NAME="tex2html312"
 120   HREF="node4.html#SECTION00460000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> The statusbar</A>
 121 <UL>
 122 <LI><A NAME="tex2html313"
 123   HREF="node4.html#SECTION00461000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">1</SPAN> The template</A>
 124 <LI><A NAME="tex2html314"
 125   HREF="node4.html#SECTION00462000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">2</SPAN> The systray</A>
 126 <LI><A NAME="tex2html315"
 127   HREF="node4.html#SECTION00463000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN> Monitors</A>
 128 <UL>
 129 <LI><A NAME="tex2html316"
 130   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>
 131 <LI><A NAME="tex2html317"
 132   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>
 133 <LI><A NAME="tex2html318"
 134   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>
 135 </UL></UL></UL>
 136 <!--End of Table of Child-Links-->
 137 <HR>
 138
 139 <H1><A NAME="SECTION00400000000000000000"></A>
 140 <A NAME="chap:config"></A>
 141 <BR>
 142 <SPAN CLASS="arabic">3</SPAN>. Basic configuration
 143 </H1>
 144
 145 <P>
 146 This chapter should help your configure Ion to your liking. As  the your
 147 probably already know, Ion uses Lua as a configuration and extension
 148 language. If you're new to it, you might first want to read some Lua
 149 documentation as already suggested and pointed to in the Introduction
 150 before continuing with this chapter.
 151
 152 <P>
 153 Section <A HREF="#sec:conffiles">3.1</A>&nbsp;is an overview of the multiple configuration
 154 files Ion uses and as a perhaps more understandable introduction to the
 155 general layout of the configuration files, a walk-through of the main
 156 configuration file <SPAN  CLASS="textit">cfg_ion.lua</SPAN> is provided in section
 157 <A HREF="#sec:walkthrough">3.2</A>.
 158 How keys and mouse action are bound to functions is described in detail
 159 in <A HREF="#sec:bindings">3.3</A> and in section <A HREF="#sec:winprops">3.5</A> winprops are
 160 explained. Finally, the statusbar is explained in <A HREF="#sec:statusbar">3.6</A>.
 161 For a reference on exported functions, see section <A HREF="node7.html#sec:exports">6</A>.
 162
 163 <P>
 164
 165 <H2><A NAME="SECTION00410000000000000000"></A>
 166 <A NAME="sec:conffiles"></A>
 167 <BR>
 168 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> The configuration files
 169 </H2>
 170
 171 <P>
 172 Ion3, to which document applies, stores its stock configuration files in
 173 <SPAN  CLASS="textit">/usr/local/etc/ion3/</SPAN> unless you, the OS package maintainer or
 174 whoever  installed the package on the system has modified the variables
 175 <TT>PREFIX</TT><A NAME="583"></A> or
 176 <TT>ETCDIR</TT><A NAME="584"></A> in
 177 <SPAN  CLASS="textit">system.mk</SPAN><A NAME="585"></A> before compiling Ion.
 178 In the first case you probably know where to find the files and in
 179 the other case the system administrator or the OS package maintainer
 180 should  have provided documentation to point to the correct location.
 181 If these instructions are no help in locating the correct directory,
 182 the command <TT>locate cfg_ion.lua</TT> might help provided <TT>updatedb</TT>
 183 has been run recently.
 184
 185 <P>
 186 User configuration files go in <SPAN  CLASS="textit">~/.ion3/</SPAN>.
 187 Ion always searches the user configuration file directory before the stock
 188 configuration file directory for files. Therefore, if you want to change
 189 some setting, it is advised against that you modify the stock configuration
 190 files in-place as subsequent installs of Ion will restore the stock
 191 configuration files. Instead you should always make a copy of the stock
 192 file in <SPAN  CLASS="textit">~/.ion3/</SPAN> and modify this file. For sake of maintainability
 193 of your customised configuration, it is recommended against copying all of
 194 the files there. Only copy those files you actually need to modify. Most
 195 simple customisations, such as changes in a few bindings, are best done
 196 entirely within <SPAN  CLASS="textit">cfg_ion.lua</SPAN>.
 197
 198 <P>
 199 All the configuration files are named <SPAN  CLASS="textit">cfg_*.lua</SPAN> with the ``<SPAN  CLASS="textit">*</SPAN>''
 200 part varying. The configuration file for each module <SPAN  CLASS="textit">mod_modname</SPAN> is
 201 <SPAN  CLASS="textit">cfg_modname.lua</SPAN>, with <SPAN  CLASS="textit">modname</SPAN> varying by the module in
 202 question. Configuration files can also be compiled into <SPAN  CLASS="textit">.lc</SPAN> files,
 203 and these are attempted by the configuration file search routines before
 204 <SPAN  CLASS="textit">.lua</SPAN> files.
 205
 206 <P>
 207 The following table summarises these and other configuration
 208 files:
 209
 210 <P>
 211 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 212 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1>File</TD>
 213 <TD ALIGN="LEFT">Description</TD>
 214 </TR>
 215 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN  CLASS="textit">cfg_ion.lua</SPAN></TD>
 216 <TD ALIGN="LEFT">The main configuration file</TD>
 217 </TR>
 218 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN  CLASS="textit">cfg_ioncore.lua</SPAN></TD>
 219 <TD ALIGN="LEFT">Configuration file for Ion's core library.
 220     Most of the bindings and menus are configured here. Bindings that are
 221     specific to some module are configured in the module's configuration
 222     file. For details, see section <A HREF="#sec:bindings">3.3</A>.</TD>
 223 </TR>
 224 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN  CLASS="textit">cfg_kludges.lua</SPAN></TD>
 225 <TD ALIGN="LEFT">Settings to get some applications behave more nicely have been
 226     collected here. See section <A HREF="#sec:winprops">3.5</A>.</TD>
 227 </TR>
 228 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN  CLASS="textit">cfg_layouts.lua</SPAN></TD>
 229 <TD ALIGN="LEFT">Some workspace layouts are defined here.</TD>
 230 </TR>
 231 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN  CLASS="textit">cfg_tiling.lua</SPAN>
 232     <SPAN  CLASS="textit">cfg_query.lua</SPAN>
 233     <SPAN  CLASS="textit">cfg_menu.lua</SPAN>
 234     <SPAN  CLASS="textit">cfg_dock.lua</SPAN>
 235     <SPAN  CLASS="textit">cfg_statusbar.lua</SPAN>
 236     ...</TD>
 237 <TD ALIGN="LEFT">Configuration files for different modules.</TD>
 238 </TR>
 239 </TABLE>
 240
 241 <P>
 242 Additionally, there's the file <SPAN  CLASS="textit">look.lua</SPAN> that configures the
 243 drawing engine, but it is covered in chapter <A HREF="node5.html#chap:gr">4</A>.
 244
 245 <P>
 246
 247 <H2><A NAME="SECTION00420000000000000000"></A>
 248 <A NAME="sec:walkthrough"></A>
 249 <BR>
 250 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> A walk through <SPAN  CLASS="textit">cfg_ion.lua</SPAN>
 251 </H2>
 252
 253 <P>
 254 As already mentioned <SPAN  CLASS="textit">cfg_ion.lua</SPAN> is Ion's main configuration
 255 file. Some basic 'feel' settings are usually configured there and
 256 the necessary modules and other configuration files configuring some
 257 more specific aspects of Ion are loaded there. In this section we
 258 take a walk through the stock <SPAN  CLASS="textit">cfg_ion.lua</SPAN>.
 259 Notice that most of the settings are commented-out (<code>--</code> is a
 260 line comment in Lua) in the actual file, as they're the defaults
 261 nevertheless.
 262
 263 <P>
 264 The first thing done in the file, is to set
 265 <PRE>
 266 META="Mod1+"
 267 ALTMETA=""
 268 </PRE>
 269 These settings cause most of Ion's key bindings to use <SPAN  CLASS="textbf">Mod1</SPAN> as the
 270 modifier key. If <TT>ALTMETA</TT> is set, it is used as modifier for the
 271 keys that don't normally use a modifier. Note that these two are Lua
 272 variables used in the configuration files only, and not Ion settings.
 273 For details on modifiers and key binding setup in general, see section
 274 <A HREF="#sec:bindings">3.3</A>.
 275
 276 <P>
 277 Next we do some basic feel configuration:
 278
 279 <P>
 280 <PRE>
 281 ioncore.set{
 282     dblclick_delay=250,
 283     kbresize_delay=1500,
 284 }
 285 </PRE>
 286
 287 <P>
 288 These two will set the delay between button presses in a double click, and
 289 the timeout to quit resize mode in milliseconds.
 290
 291 <P>
 292 <PRE>
 293 ioncore.set{
 294     opaque_resize=true,
 295     warp=true
 296 }
 297 </PRE>
 298
 299 <P>
 300 The first of these two settings enables opaque resize mode: in move/resize
 301 move frames and other objects mirror you actions immediately. If opaque
 302 resize is disabled, a XOR rubber band is shown during the mode instead.
 303 This will, unfortunately, cause Ion to also grab the X server and has some
 304 side effects.
 305
 306 <P>
 307 There are some other options as well; see the documentation
 308 for <A HREF="node7.html#fn:ioncore.set"><TT>ioncore.set</TT></A> for details.
 309
 310 <P>
 311 As a next step, in the actual <SPAN  CLASS="textit">cfg_ion.lua</SPAN> file, we load
 312 <SPAN  CLASS="textit">cfg_defaults.lua</SPAN>. However, it is merely a convenience file for
 313 doing exactly what we will going through below, and what is commented
 314 out in the actual file. If you do not want to load what
 315 <SPAN  CLASS="textit">cfg_defaults.lua</SPAN> loads, just comment out the corresponding
 316 line, and uncomment the lines for the files that you want:
 317
 318 <P>
 319 <PRE>
 320 --dopath("cfg_defaults")
 321 dopath("cfg_ioncore")
 322 dopath("cfg_kludges")
 323 dopath("cfg_layouts")
 324 </PRE>
 325
 326 <P>
 327 Most bindings and menus are defined in <SPAN  CLASS="textit">cfg_ioncore.lua</SPAN>.
 328 Details on making such definitions follow in sections <A HREF="#sec:bindings">3.3</A>
 329 and <A HREF="#sec:menus">3.4</A>, respectively.
 330 some kludges or ``winprops'' to make some applications behave better
 331 under Ion are collected in <SPAN  CLASS="textit">cfg_kludges.lua</SPAN>; see section
 332 <A HREF="#sec:winprops">3.5</A> for details. In addition to these, this file
 333 lists quite a few statements of the form
 334 <PRE>
 335 ioncore.defshortening("[^:]+: (.*)(&lt;[0-9]+&gt;)", "$1$2$|$1$&lt;...$2")
 336 </PRE>
 337 These are used to configure how Ion attempts to shorten window titles
 338 when they do not fit in a Tab. The first argument is a POSIX regular
 339 expression that is used to match against the title and the next is
 340 a rule to construct a new title of a match occurs. This particular
 341 rule is used to shorten e.g. 'Foo: barbaz&lt;3&gt;' to 'barba...&lt;3&gt;'; for
 342 details see the function reference entry for <A HREF="node7.html#fn:ioncore.defshortening"><TT>ioncore.defshortening</TT></A>.
 343 Finally, <SPAN  CLASS="textit">cfg_layouts.lua</SPAN> defines some workspace layouts, available
 344 through the <SPAN  CLASS="textbf">F9</SPAN> workspace creation query.
 345
 346 <P>
 347 To actually be able to do something besides display windows in full screen
 348 mode, we must next load some modules:
 349
 350 <P>
 351 <PRE>
 352 dopath("mod_query")
 353 dopath("mod_menu")
 354 dopath("mod_tiling")
 355 dopath("mod_statusbar")
 356 --dopath("mod_dock")
 357 dopath("mod_sp")
 358 </PRE>
 359
 360 <P>
 361
 362 <H2><A NAME="SECTION00430000000000000000"></A>
 363 <A NAME="sec:bindings"></A>
 364 <BR>
 365 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Keys and rodents
 366 </H2>
 367
 368 <P>
 369 In the stock configuration file setup, most key and mouse bindings are set
 370 from the file <SPAN  CLASS="textit">cfg_ioncore.lua</SPAN> while module-specific bindings
 371 are set from the modules' main configuration files (<SPAN  CLASS="textit">cfg_modname.lua</SPAN>).
 372 This, however, does not have to be so as long as the module has been
 373 loaded prior to defining any module-specific bindings.
 374
 375 <P>
 376 Bindings are defined by calling the function
 377 <A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> with the ``context'' of the
 378 bindings and the a table of new bindings to make. The context is simply
 379 string indicating one of the classes of regions (or modes such as
 380 WMoveresMode) introduced in section <A HREF="node3.html#sec:objects">2.2</A>, and fully
 381 listed in appendix <A HREF="node9.html#app:fullhierarchy">B</A>, although not all define
 382 a binding map. For example, the following skeleton would be used to
 383 define new bindings for all frames:
 384
 385 <P>
 386 <PRE>
 387 defbindings("WFrame", {
 388     -- List of bindings to make goes here.
 389 })
 390 </PRE>
 391
 392 <P>
 393 There has been some confusion among users about the need to define the
 394 ``context'' for each binding, so let me try to explain this design
 395 decision here. The thing is that if there was a just a simple 'bind this
 396 key to this action' method without knowledge of the context, some
 397 limitations would have to be made on the available actions and writing
 398 custom handlers would be more complicated. In addition one may want to
 399 bind the same function to different key for different types of objects.
 400 Indeed, the workspace and frame tab switching functions are the same both
 401 classes being based on WMPlex, and in the stock configuration the
 402 switch to <SPAN CLASS="MATH"><IMG
 403  WIDTH="15" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
 404  SRC="img1.png"
 405  ALT="$n$"></SPAN>:th workspaces is bound to <SPAN  CLASS="textbf">Mod1+n</SPAN> while the switch to
 406 <SPAN CLASS="MATH"><IMG
 407  WIDTH="15" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
 408  SRC="img1.png"
 409  ALT="$n$"></SPAN>:th tab is bound to the sequence <SPAN  CLASS="textbf">Mod1+k n</SPAN>.
 410
 411 <P>
 412 Currently known contexts include:
 413 `<TT>WScreen</TT>',
 414 `<TT>WMPlex</TT>',
 415 `<TT>WMPlex.toplevel</TT>',
 416 `<TT>WFrame</TT>',
 417 `<TT>WFrame.toplevel</TT>',
 418 `<TT>WFrame.floating</TT>',
 419 `<TT>WFrame.tiled</TT>',
 420 `<TT>WFrame.transient</TT>',
 421 `<TT>WMoveresMode</TT>',
 422 `<TT>WGroup</TT>',
 423 `<TT>WGroupCW</TT>',
 424 `<TT>WGroupWS</TT>',
 425 `<TT>WClientWin</TT>',
 426 `<TT>WTiling</TT>', and
 427 `<TT>WStatusBar</TT>'.
 428 Most of these should be self-explanatory, corresponding to objects
 429 of class with the same name. The ones with `<TT>.toplevel</TT>' suffix
 430 refer to screens and ``toplevel''  frames, i.e. frames that are
 431 not used for transient windows. Likewise `<TT>.transient</TT>' refers
 432 to frames in transient mode, and `<TT>.tiled</TT>' and `<TT>.floating</TT>'
 433 to frames in, respectively, tiled and floating modes.
 434
 435 <P>
 436 The following subsections describe how to construct elements of the
 437 binding table. Note that <A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> adds
 438 the the newly defined bindings to the previous bindings of the context,
 439 overriding duplicates. To unbind an event, set the handler parameter
 440 to <TT>nil</TT> for each of the functions to be described in the following
 441 subsections.
 442
 443 <P>
 444 Also note that when multiple objects want to handle a binding, the
 445 innermost (when the root window is considered the outermost) active object
 446 in the parent-child hierarchy (see Figure <A HREF="node3.html#fig:parentship">2.2</A>) of objects
 447 gets to handle the action.
 448
 449 <P>
 450
 451 <H3><A NAME="SECTION00431000000000000000">
 452 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Binding handlers and special variables</A>
 453 </H3>
 454
 455 <P>
 456 Unlike in Ion2, in Ion3 binding handlers are not normally passed as
 457 ``anonymous functions'', although this is still possible. The preferred
 458 method now is to pass the code of the handler as a string. Two following
 459 special variables are available in this code.
 460
 461 <P>
 462 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 463 <TR><TD ALIGN="LEFT">Variable</TD>
 464 <TD ALIGN="LEFT">Description</TD>
 465 </TR>
 466 <TR><TD ALIGN="LEFT"><TT>_</TT> (underscore)</TD>
 467 <TD ALIGN="LEFT">Reference to the object on which the
 468       binding was triggered. The object is of the same class as the the
 469       context of the <A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> call
 470       defining the binding.</TD>
 471 </TR>
 472 <TR><TD ALIGN="LEFT"><TT>_sub</TT></TD>
 473 <TD ALIGN="LEFT">Usually, the currently active <SPAN  CLASS="textit">managed object</SPAN> of the
 474       object referred to by <TT>_</TT>, but sometimes (e.g. mouse actions
 475       on tabs of frames) something else relevant to the action triggering
 476       the binding.</TD>
 477 </TR>
 478 <TR><TD ALIGN="LEFT"><TT>_chld</TT></TD>
 479 <TD ALIGN="LEFT">Object corresponding to the currently active child window of the
 480        object referred to by <TT>_</TT>. This should seldom be needed.</TD>
 481 </TR>
 482 </TABLE>
 483
 484 <P>
 485 For example, supposing <TT>_</TT> (underscore) is a WFrame, the
 486 following handler should move the active window to the right, if
 487 possible:
 488
 489 <P>
 490 <PRE>
 491 "_:inc_index(_sub)"
 492 </PRE>
 493
 494 <P>
 495
 496 <H3><A NAME="SECTION00432000000000000000">
 497 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Guards</A>
 498 </H3>
 499
 500 <P>
 501 To suppress error messages, each binding handler may also be accompanied
 502 by a ``guard'' expression that blocks the handler from being called when
 503 the guard condition is not met. Currently the following guard expressions
 504 are supported (for both <TT>_sub</TT> and <TT>_chld</TT>):
 505
 506 <P>
 507 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 508 <TR><TD ALIGN="LEFT">Guard</TD>
 509 <TD ALIGN="LEFT">Description</TD>
 510 </TR>
 511 <TR><TD ALIGN="LEFT">`<TT>_sub:non-nil</TT>'</TD>
 512 <TD ALIGN="LEFT">The <TT>_sub</TT> parameter must be set.</TD>
 513 </TR>
 514 <TR><TD ALIGN="LEFT">`<TT>_sub:SomeClass</TT>'</TD>
 515 <TD ALIGN="LEFT">The <TT>_sub</TT> parameter must be member
 516       of class SomeClass.</TD>
 517 </TR>
 518 </TABLE>
 519
 520 <P>
 521
 522 <H3><A NAME="SECTION00433000000000000000"></A>
 523 <A NAME="sec:binddef"></A>
 524 <BR>
 525 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining the bindings
 526 </H3>
 527
 528 <P>
 529 The descriptions of the individual bindings in the binding table argument
 530 to <A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> should be constructed with the following
 531 functions.
 532
 533 <P>
 534 Key presses:
 535
 536 <UL>
 537 <LI><A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A>, and
 538           <A HREF="node7.html#fn:ioncore.kpress_wait"><TT>kpress_wait</TT></A><TT>(keyspec, handler [, guard])</TT>.
 539 </LI>
 540 <LI><A HREF="node7.html#fn:ioncore.submap"><TT>submap</TT></A><TT>(keyspec, { ... more key bindings ... })</TT>.
 541 </LI>
 542 <LI><A HREF="node7.html#fn:ioncore.submap_enter"><TT>submap_enter</TT></A>, and
 543           <A HREF="node7.html#fn:ioncore.submap_wait"><TT>submap_wait</TT></A><TT>(handler [, guard])</TT>.
 544 </LI>
 545 </UL>
 546 Mouse actions:
 547
 548 <UL>
 549 <LI><A HREF="node7.html#fn:ioncore.mclick"><TT>mclick</TT></A>,
 550           <A HREF="node7.html#fn:ioncore.mdblclick"><TT>mdblclick</TT></A>,
 551           <A HREF="node7.html#fn:ioncore.mpress"><TT>mpress</TT></A>, and
 552           <A HREF="node7.html#fn:ioncore.mdrag"><TT>mdrag</TT></A><TT>(buttonspec, handler [, guard])</TT>.
 553 </LI>
 554 </UL>
 555
 556 <P>
 557 The actions that most of these functions correspond to should be clear
 558 and as explained in the reference, <A HREF="node7.html#fn:ioncore.kpress_wait"><TT>kpress_wait</TT></A> is simply
 559 <A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A> with a flag set instructing Ioncore wait for
 560 all modifiers to be released before processing any further actions.
 561 This is to stop one from accidentally calling e.g.
 562 <A HREF="node7.html#fn:WRegion.rqclose"><TT>WRegion.rqclose</TT></A> multiple times in a row. The
 563 <A HREF="node7.html#fn:ioncore.submap"><TT>submap</TT></A> function is used to define submaps or
 564 ``prefix maps''. The second argument to this function is table listing
 565 the key press actions (<A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A>) in the submap.
 566 The <A HREF="node7.html#fn:ioncore.submap_enter"><TT>submap_enter</TT></A> handler is called when the submap
 567 is entered, in which this handler is defined. Likewise, the
 568 <A HREF="node7.html#fn:ioncore.submap_wait"><TT>submap_wait</TT></A> handler is  called when all modifiers
 569 have been released while waiting for further key presses in the submap.
 570
 571 <P>
 572 The parameters <TT>keyspec</TT> and <TT>buttonspec</TT> are explained below
 573 in detail. The parameter <TT>handler</TT> is the handler for the binding,
 574 and the optional parameter <TT>guard</TT> its guard. These should normally
 575 be strings as explained above.
 576
 577 <P>
 578
 579 <H3><A NAME="SECTION00434000000000000000">
 580 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Examples</A>
 581 </H3>
 582
 583 <P>
 584 For example, to just bind the key <SPAN  CLASS="textbf">Mod1+1</SPAN> to switch to the first
 585 workspace and <SPAN  CLASS="textbf">Mod1+Right</SPAN> to the next workspace, you would make the
 586 following call
 587 <PRE>
 588 defbindings("WScreen", {
 589     kpress("Mod1+Right", "_:switch_next()"),
 590     kpress("Mod1+1", "_:switch_nth(1)"),
 591 })
 592 </PRE>
 593
 594 <P>
 595 Note that <TT>_:switch_nth(1)</TT> is the same as calling
 596 <A HREF="node7.html#fn:WMPlex.switch_next"><TT>WMPlex.switch_next</TT></A><TT>(_, 1)</TT> as WScreen inherits
 597 WMPlex and this is where the function is actually defined.
 598
 599 <P>
 600 Similarly to the above example, to bind the key sequence <SPAN  CLASS="textbf">Mod1+k n</SPAN>
 601 switch to the next managed object within a frame, and <SPAN  CLASS="textbf">Mod1+k 1</SPAN> to the
 602 first, you would issue the following call:
 603 <PRE>
 604 defbindings("WFrame", {
 605     submap("Mod1+K", {
 606         kpress("Right", "_:switch_next()"),
 607         kpress("1", "_:switch_nth(1)"),
 608    }),
 609 })
 610 </PRE>
 611
 612 <P>
 613
 614 <H3><A NAME="SECTION00435000000000000000">
 615 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Key specifications</A>
 616 </H3>
 617
 618 <P>
 619 As seen above, the functions that create key binding specifications require
 620 a <TT>keyspec</TT> argument. This argument should be a string containing the
 621 name of a key as listed in the X header file <SPAN  CLASS="textit">keysymdef.h</SPAN><A NAME="tex2html7"
 622   HREF="#foot880"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A> without the <TT>XK_</TT> prefix.
 623 <A NAME="881"></A>
 624 Most of the key names are quite intuitive while some are not. For example,
 625 the <SPAN  CLASS="textbf">Enter</SPAN> key on the main part of the keyboard has the less common
 626 name <SPAN  CLASS="textbf">Return</SPAN> while the one the numpad is called <SPAN  CLASS="textbf">KP_Enter</SPAN>.
 627
 628 <P>
 629 The <TT>keyspec</TT> string may optionally have multiple ``modifier'' names
 630 followed by a plus sign (<TT>+</TT>) as a prefix. X defines the following
 631 modifiers:
 632
 633 <P>
 634 <SPAN  CLASS="textbf">Shift</SPAN>, <SPAN  CLASS="textbf">Control</SPAN>, <SPAN  CLASS="textbf">Mod1</SPAN> to <SPAN  CLASS="textbf">Mod5</SPAN>,
 635 <SPAN  CLASS="textbf">AnyModifier</SPAN> and <SPAN  CLASS="textbf">Lock</SPAN>.
 636 <A NAME="882"></A>
 637 <A NAME="883"></A>
 638 <A NAME="884"></A>
 639 <A NAME="885"></A>
 640 <A NAME="886"></A>
 641
 642 <P>
 643 X allows binding all of these modifiers to almost any key and while this
 644 list of modifiers does not explicitly list keys such as
 645 <SPAN  CLASS="textbf">Alt</SPAN><A NAME="887"></A> that are common on modern keyboards, such
 646 keys are bound to one of the <SPAN  CLASS="textbf">ModN</SPAN>. On systems running XFree86
 647 <SPAN  CLASS="textbf">Alt</SPAN> is usually <SPAN  CLASS="textbf">Mod1</SPAN>. On Suns <SPAN  CLASS="textbf">Mod1</SPAN> is the diamond key
 648 and <SPAN  CLASS="textbf">Alt</SPAN> something else. One of the ``flying window'' keys on so
 649 called Windows-keyboards is probably mapped to <SPAN  CLASS="textbf">Mod3</SPAN> if you have
 650 such a key. Use the program <SPAN  CLASS="textit">xmodmap</SPAN><A NAME="888"></A>
 651 to find out what exactly is bound where.
 652
 653 <P>
 654 Ion defaults to <SPAN  CLASS="textbf">AnyModifier</SPAN> in submaps. This can sometimes lead to
 655 unwanted effects when the same key is used with and without explicitly
 656 specified modifiers in nested regions. For this reason, Ion recognises
 657 <SPAN  CLASS="textbf">NoModifier</SPAN> as a special modifier that can be used to reset this
 658 default.
 659
 660 <P>
 661 Ion ignores the <SPAN  CLASS="textbf">Lock</SPAN> modifier and any <SPAN  CLASS="textbf">ModN</SPAN> (<SPAN CLASS="MATH"><IMG
 662  WIDTH="82" HEIGHT="15" ALIGN="BOTTOM" BORDER="0"
 663  SRC="img2.png"
 664  ALT="$N=1{\ldots} 5$"></SPAN>)
 665 bound to <SPAN  CLASS="textbf">NumLock</SPAN><A NAME="889"></A> or
 666 <SPAN  CLASS="textbf">ScrollLock</SPAN><A NAME="890"></A>
 667 by default because such<A NAME="tex2html8"
 668   HREF="#foot859"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A> locking keys may otherwise
 669 cause confusion.
 670
 671 <P>
 672
 673 <H3><A NAME="SECTION00436000000000000000">
 674 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> Button specifications</A>
 675 </H3>
 676
 677 <P>
 678 Button specifications are similar to key definitions but now
 679 instead of specifying modifiers and a key, you specify modifiers
 680 and one of the button names <SPAN  CLASS="textbf">Button1</SPAN> to
 681 <SPAN  CLASS="textbf">Button5</SPAN><A NAME="891"></A>. Additionally the
 682 specification may end with an optional area name following an @-sign.
 683 Only frames currently support areas, and the supported values in this
 684 case are
 685 `<TT>border</TT>', `<TT>tab</TT>', `<TT>empty_tab</TT>', `<TT>client</TT>'
 686 and <TT>nil</TT> (for the whole frame).
 687
 688 <P>
 689 For example, the following code binds dragging a tab with the first
 690 button pressed to initiate tab drag&amp;drop handling:
 691
 692 <P>
 693 <PRE>
 694 defbindings("WFrame", {
 695     mdrag("Button1@tab", "_:p_tabdrag()"),
 696 })
 697 </PRE>
 698
 699 <P>
 700
 701 <H3><A NAME="SECTION00437000000000000000">
 702 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">7</SPAN> A further note on the default binding configuration</A>
 703 </H3>
 704
 705 <P>
 706 The default binding configuration contains references to the variables
 707 <TT>META</TT> and <TT>ALTMETA</TT> instead of directly using the default
 708 values of `<TT>Mod1+</TT>' and `' (nothing). As explained in
 709 section <A HREF="#sec:walkthrough">3.2</A>, the definitions of these variables
 710 appear in <SPAN  CLASS="textit">cfg_ion.lua</SPAN>. This way you can easily change the the
 711 modifiers used by all bindings in the default configuration without
 712 changing the whole binding configuration. Quite a few people prefer
 713 to use the Windows keys as modifiers because many applications already
 714 use <SPAN  CLASS="textbf">Alt</SPAN>. Nevertheless, <SPAN  CLASS="textbf">Mod1</SPAN> is the default as a key bound
 715 to it is available virtually everywhere.
 716
 717 <P>
 718
 719 <H2><A NAME="SECTION00440000000000000000"></A>
 720 <A NAME="sec:menus"></A>
 721 <BR>
 722 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Menus
 723 </H2>
 724
 725 <P>
 726
 727 <H3><A NAME="SECTION00441000000000000000">
 728 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Defining menus</A>
 729 </H3>
 730
 731 <P>
 732 <A NAME="1148"></A>
 733 <A NAME="1202"></A>
 734 <A NAME="1203"></A>
 735 <A NAME="1204"></A>
 736 In the stock configuration file setup, menus are defined in the file
 737 <SPAN  CLASS="textit">cfg_menus.lua</SPAN> as previously mentioned. The <SPAN  CLASS="textit">mod_menu</SPAN> module
 738 must be loaded for one to be able to define menus, and this is done with
 739 the function <A HREF="#fn:mod_menu.defmenu"><TT>defmenu</TT></A> provided by it.
 740
 741 <P>
 742 Here's an example of the definition of a rather simple menu with a submenu:
 743
 744 <P>
 745 <PRE>
 746 defmenu("exitmenu", {
 747     menuentry("Restart", "ioncore.restart()"),
 748     menuentry("Exit", "ioncore.shutdown()"),
 749 })
 750
 751 defmenu("mainmenu", {
 752     menuentry("Lock screen", "ioncore.exec('xlock')"),
 753     menuentry("Help", "mod_query.query_man(_)"),
 754     submenu("Exit", "exitmenu"),
 755 })
 756 </PRE>
 757
 758 <P>
 759 The <A HREF="#fn:mod_menu.menuentry"><TT>menuentry</TT></A> function is used to create an entry in the
 760 menu with a title and an entry handler to be called when the menu entry
 761 is activated. The parameters to the handler are similar to those of binding
 762 handlers, and usually the same as those of the binding that opened the menu.
 763
 764 <P>
 765 The <A HREF="#fn:mod_menu.submenu"><TT>submenu</TT></A> function is used to insert a submenu at that
 766 point in the menu. (One could as well just pass a table with the menu
 767 entries, but it is not encouraged.)
 768
 769 <P>
 770
 771 <H3><A NAME="SECTION00442000000000000000">
 772 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Special menus</A>
 773 </H3>
 774
 775 <P>
 776 The menu module predefines the following special menus. These can be used
 777 just like the menus defined as above.
 778
 779 <P>
 780 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 781 <TR><TD ALIGN="LEFT">Menu name</TD>
 782 <TD ALIGN="LEFT">Description</TD>
 783 </TR>
 784 <TR><TD ALIGN="LEFT">`<TT>windowlist</TT>'</TD>
 785 <TD ALIGN="LEFT">List of all client windows. Activating an entry jumps to that window.</TD>
 786 </TR>
 787 <TR><TD ALIGN="LEFT">`<TT>workspacelist</TT>'</TD>
 788 <TD ALIGN="LEFT">List of all workspaces. Activating an entry jumps to that workspaces.</TD>
 789 </TR>
 790 <TR><TD ALIGN="LEFT">`<TT>focuslist</TT>'</TD>
 791 <TD ALIGN="LEFT">List of client windows with recent activity in them, followed by
 792     previously focused client windows.</TD>
 793 </TR>
 794 <TR><TD ALIGN="LEFT">`<TT>focuslist_</TT>'</TD>
 795 <TD ALIGN="LEFT">List of previously focused client windows.</TD>
 796 </TR>
 797 <TR><TD ALIGN="LEFT">`<TT>stylemenu</TT>'</TD>
 798 <TD ALIGN="LEFT">List of available <SPAN  CLASS="textit">look_*.lua</SPAN> style files. Activating an entry
 799     loads that style and ask to save the selection.</TD>
 800 </TR>
 801 <TR><TD ALIGN="LEFT">`<TT>ctxmenu</TT>'</TD>
 802 <TD ALIGN="LEFT">Context menu for given object.</TD>
 803 </TR>
 804 </TABLE>
 805
 806 <P>
 807
 808 <H3><A NAME="SECTION00443000000000000000">
 809 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining context menus</A>
 810 </H3>
 811
 812 <P>
 813 The ``ctxmenu'' is a special menu that is assembled from a defined context
 814 menu for the object for which the menu was opened for, but also includes
 815 the context menus for the manager objects as submenus.
 816
 817 <P>
 818 Context menus for a given region class are defined with the
 819 <A HREF="#fn:mod_menu.defctxmenu"><TT>defctxmenu</TT></A> function. This is other ways similar to
 820 <A HREF="#fn:mod_menu.defmenu"><TT>defmenu</TT></A>, but the first argument instead being the name
 821 of the menu, the name of the region class to define context menu for.
 822 For example, here's part of the stock WFrame context menu
 823 definition:
 824
 825 <P>
 826 <PRE>
 827 defctxmenu("WFrame", {
 828     menuentry("Close", "WRegion.rqclose_propagate(_, _sub)"),
 829     menuentry("Kill",  "WClientWin.kill(_sub)", "_sub:WClientWin"),
 830 })
 831 </PRE>
 832
 833 <P>
 834 Some of the same ``modes'' as were available for some bindings
 835 may also be used: `<TT>WFrame.tiled</TT>', `<TT>WFrame.floating</TT>',
 836 and `<TT>WFrame.transient</TT>'.
 837
 838 <P>
 839
 840 <H3><A NAME="SECTION00444000000000000000"></A>
 841 <A NAME="sec:menudisp"></A>
 842 <BR>
 843 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">4</SPAN> Displaying menus
 844 </H3>
 845
 846 <P>
 847 The following functions may be used to display menus from binding
 848 handlers (and elsewhere):
 849
 850 <P>
 851 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 852 <TR><TD ALIGN="LEFT">Function</TD>
 853 <TD ALIGN="LEFT">Description</TD>
 854 </TR>
 855 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.menu"><TT>mod_menu.menu</TT></A></TD>
 856 <TD ALIGN="LEFT">Keyboard (or mouse) operated menus that open in the bottom-left corner
 857       of a screen or frame.</TD>
 858 </TR>
 859 <TR><TD ALIGN="LEFT"><A HREF="#fn:mod_menu.bigmenu"><TT>mod_menu.bigmenu</TT></A></TD>
 860 <TD ALIGN="LEFT">Same as previous, but uses another graphical style.</TD>
 861 </TR>
 862 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.pmenu"><TT>mod_menu.pmenu</TT></A></TD>
 863 <TD ALIGN="LEFT">Mouse-operated drop-down menus. This function can only be called from a
 864       mouse press or drag handler.</TD>
 865 </TR>
 866 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.grabmenu"><TT>mod_menu.grabmenu</TT></A></TD>
 867 <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
 868       and is scrolled with a given key until all modifiers have been released,
 869       after which the selected entry is activated.</TD>
 870 </TR>
 871 </TABLE>
 872
 873 <P>
 874 The <A HREF="node7.html#fn:mod_menu.grabmenu"><TT>grabmenu</TT></A> function takes the extra key parameter, but
 875 aside from that each of these functions takes three arguments, which when
 876 called from a binding handler, should be the parameters to the handler, and
 877 the name of the menu. For example, the following snippet of of code binds
 878 the both ways to open a context menu for a frame:
 879
 880 <P>
 881 <PRE>
 882 defbindings("WFrame", {
 883     kpress(MOD1.."M", "mod_menu.menu(_, _sub, 'ctxmenu')"),
 884     mpress("Button3", "mod_menu.pmenu(_, _sub, 'ctxmenu')"),
 885 })
 886 </PRE>
 887
 888 <P>
 889
 890 <H2><A NAME="SECTION00450000000000000000"></A>
 891 <A NAME="sec:winprops"></A>
 892 <BR>
 893 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Winprops
 894 </H2>
 895
 896 <P>
 897 The so-called ``winprops''<A NAME="1295"></A> can be used to change how
 898 specific windows are handled and to set up some kludges to deal with
 899 badly behaving applications. They are defined by calling the function
 900 <TT>defwinprop</TT> with a table containing the properties to set and the
 901 necessary information to identify a window. The currently supported
 902 winprops are listed below, and the subsequent subsections explain the
 903 usual method of identifying windows, and how to obtain this information.
 904
 905 <P>
 906
 907 <P>
 908
 909   <DL>
 910 <DT><STRONG>Winprop:</STRONG></DT>
 911 <DD><TT>acrobatic</TT> (boolean)
 912
 913 </DD>
 914 <DT><STRONG>Description:</STRONG></DT>
 915 <DD><A NAME="1462"></A>
 916     Set this to <TT>true</TT> for Acrobat Reader. It has an annoying
 917     habit of trying to manage its dialogs instead of setting them as
 918     transients and letting the window manager do its job, causing
 919     Ion and acrobat go a window-switching loop when a dialog is
 920     opened.
 921
 922 </DD>
 923 </DL>
 924
 925 <P>
 926
 927   <DL>
 928 <DT><STRONG>Winprop:</STRONG></DT>
 929 <DD><TT>float</TT> (boolean)
 930
 931 </DD>
 932 <DT><STRONG>Description:</STRONG></DT>
 933 <DD><A NAME="1463"></A>
 934     Set this to open the window in a floating frame, when
 935     in a group.
 936
 937 </DD>
 938 </DL>
 939
 940 <P>
 941
 942   <DL>
 943 <DT><STRONG>Winprop:</STRONG></DT>
 944 <DD><TT>fullscreen</TT> (boolean)
 945
 946 </DD>
 947 <DT><STRONG>Description:</STRONG></DT>
 948 <DD><A NAME="1464"></A>
 949     Should the window be initially in full screen mode?
 950
 951 </DD>
 952 </DL>
 953
 954 <P>
 955
 956   <DL>
 957 <DT><STRONG>Winprop:</STRONG></DT>
 958 <DD><TT>ignore_cfgrq</TT> (boolean)
 959
 960 </DD>
 961 <DT><STRONG>Description:</STRONG></DT>
 962 <DD><A NAME="1465"></A>
 963     Should configure requests on the window be ignored?
 964     Only has effect on floating windows.
 965
 966 </DD>
 967 </DL>
 968
 969 <P>
 970
 971   <DL>
 972 <DT><STRONG>Winprop:</STRONG></DT>
 973 <DD><TT>ignore_net_active_window</TT> (boolean)
 974
 975 </DD>
 976 <DT><STRONG>Description:</STRONG></DT>
 977 <DD><A NAME="1466"></A>
 978     Ignore extended WM hints <TT>_NET_ACTIVE_WINDOW</TT> request.
 979
 980 </DD>
 981 </DL>
 982
 983 <P>
 984
 985   <DL>
 986 <DT><STRONG>Winprop:</STRONG></DT>
 987 <DD><TT>jumpto</TT> (boolean)
 988
 989 </DD>
 990 <DT><STRONG>Description:</STRONG></DT>
 991 <DD><A NAME="1467"></A>
 992     Should a newly created client window always be made
 993     active, even if the allocated frame isn't.
 994
 995 </DD>
 996 </DL>
 997
 998 <P>
 999
1000   <DL>
1001 <DT><STRONG>Winprop:</STRONG></DT>
1002 <DD><TT>new_group</TT> (string)
1003
1004 </DD>
1005 <DT><STRONG>Description:</STRONG></DT>
1006 <DD><A NAME="1468"></A>
1007     If the region specified by <TT>target</TT> winprop does not exist
1008     (or that winprop is not set), create a new workspace using the
1009     previously stored layout (see <A HREF="node7.html#fn:ioncore.deflayout"><TT>ioncore.deflayout</TT></A>) named by
1010     this property. After creating the workspace, <TT>target</TT> is
1011     attempted to be found again. (If that still fails, the newly
1012     created workspace is still asked to manage the client window.)
1013
1014 </DD>
1015 </DL>
1016
1017 <P>
1018
1019   <DL>
1020 <DT><STRONG>Winprop:</STRONG></DT>
1021 <DD><TT>oneshot</TT> (boolean)
1022
1023 </DD>
1024 <DT><STRONG>Description:</STRONG></DT>
1025 <DD><A NAME="1469"></A>
1026     Discard this winprop after first use.
1027
1028 </DD>
1029 </DL>
1030
1031 <P>
1032
1033   <DL>
1034 <DT><STRONG>Winprop:</STRONG></DT>
1035 <DD><TT>orientation</TT> (string)
1036
1037 </DD>
1038 <DT><STRONG>Description:</STRONG></DT>
1039 <DD><A NAME="1470"></A>
1040     The orientation of the window: one of `<TT>vertical</TT>' or
1041     `<TT>horizontal</TT>'. This is only useful when using the
1042     window as a status display.
1043
1044 </DD>
1045 </DL>
1046
1047 <P>
1048
1049   <DL>
1050 <DT><STRONG>Winprop:</STRONG></DT>
1051 <DD><TT>statusbar</TT> (string)
1052
1053 </DD>
1054 <DT><STRONG>Description:</STRONG></DT>
1055 <DD><A NAME="1471"></A>
1056     Put the window in the statusbar, in the named tray component,
1057     (The default tray component is called simply `<TT>systray</TT>',
1058     and others you give names to in your custom template, always
1059     prefixed by `<TT>systray_</TT>'.
1060
1061 </DD>
1062 </DL>
1063
1064 <P>
1065
1066   <DL>
1067 <DT><STRONG>Winprop:</STRONG></DT>
1068 <DD><TT>switchto</TT> (boolean)
1069
1070 </DD>
1071 <DT><STRONG>Description:</STRONG></DT>
1072 <DD><A NAME="1472"></A>
1073     Should a newly mapped client window be switched to within
1074     its frame.
1075
1076 </DD>
1077 </DL>
1078
1079 <P>
1080
1081   <DL>
1082 <DT><STRONG>Winprop:</STRONG></DT>
1083 <DD><TT>target</TT> (string)
1084
1085 </DD>
1086 <DT><STRONG>Description:</STRONG></DT>
1087 <DD><A NAME="1473"></A>
1088     The name of an object (workspace, frame) that should manage
1089     windows of this type. See also <TT>new_group</TT>.
1090
1091 </DD>
1092 </DL>
1093
1094 <P>
1095
1096   <DL>
1097 <DT><STRONG>Winprop:</STRONG></DT>
1098 <DD><TT>transient_mode</TT> (string)
1099
1100 </DD>
1101 <DT><STRONG>Description:</STRONG></DT>
1102 <DD><A NAME="1474"></A>
1103     `<TT>normal</TT>': No change in behaviour. `<TT>current</TT>':
1104     The window should be thought of as a transient for the current
1105     active client window (if any) even if it is not marked as a
1106     transient by the application. `<TT>off</TT>': The window should
1107     be handled as a normal window even if it is marked as a
1108     transient by the application.
1109
1110 </DD>
1111 </DL>
1112
1113 <P>
1114
1115   <DL>
1116 <DT><STRONG>Winprop:</STRONG></DT>
1117 <DD><TT>transparent</TT> (boolean)
1118
1119 </DD>
1120 <DT><STRONG>Description:</STRONG></DT>
1121 <DD><A NAME="1475"></A>
1122     Should frames be made transparent when this window is selected?
1123 <BR>
1124
1125 </DD>
1126 </DL>
1127
1128 <P>
1129
1130 <H3><A NAME="SECTION00451000000000000000">
1131 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Sizehint winprops</A>
1132 </H3>
1133
1134 <P>
1135 Additionally, the winprops
1136 <TT>max_size</TT><A NAME="1476"></A>,
1137 <TT>min_size</TT><A NAME="1477"></A>,
1138 <TT>aspect</TT><A NAME="1478"></A>,
1139 <TT>resizeinc</TT><A NAME="1479"></A>,
1140 and
1141 <TT>ignore_max_size</TT><A NAME="1480"></A>,
1142 <TT>ignore_min_size</TT><A NAME="1481"></A>,
1143 <TT>ignore_aspect</TT><A NAME="1482"></A>,
1144 <TT>ignore_resizeinc</TT><A NAME="1483"></A>,
1145 may be used to override application-supplied size hints. The four
1146 first ones are tables with the fields <TT>w</TT> and <TT>h</TT>, indicating
1147 the width and height size hints in pixels, and the latter ignore
1148 winprop is a boolean.
1149
1150 <P>
1151 Finally, the boolean
1152 <TT>userpos</TT><A NAME="1484"></A> option may be used to
1153 override the <TT>USPosition</TT> flag of the size hints. Normally,
1154 when this flag is set, Ion tries to respect the supplied window
1155 position more than when it is not set. Obviously, this makes sense
1156 only for floating windows.
1157
1158 <P>
1159
1160 <H3><A NAME="SECTION00452000000000000000"></A>
1161 <A NAME="sec:classesrolesinstances"></A>
1162 <BR>
1163 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Classes, roles and instances
1164 </H3>
1165
1166 <P>
1167 The identification information supported are
1168 <TT>class</TT><A NAME="1485"></A>,
1169 <TT>role</TT><A NAME="1486"></A>,
1170 <TT>instance</TT><A NAME="1487"></A>,
1171 <TT>name</TT><A NAME="1488"></A>,
1172 <TT>is_transient</TT><A NAME="1489"></A>, and
1173 <TT>is_dockapp</TT><A NAME="1490"></A>.
1174 It is not necessary to specify all of these fields.
1175 The first three are strings, and must exactly match the
1176 corresponding information obtained from the window's properties.
1177 The <TT>name</TT> field is a Lua-style regular expression matched against
1178 the window's title. The <TT>is_transient</TT> field is a boolean that can
1179 be used to include or exclude transients only, while the <TT>is_dockapp</TT>
1180 field is set by Ion for the dock windows of Window Maker dockapp protocol
1181 dockapps. Usually this is the only information available for these
1182 <SPAN  CLASS="textit">icon</SPAN> windows.
1183
1184 <P>
1185 Ion looks for a matching winprop in the order listed by the following
1186 table. An 'E' indicates that the field must be set in the winprop
1187 and it must match the window's corresponding property exactly or, in
1188 case of <TT>name</TT>, the regular expression must match the window
1189 title. An asterisk '*' indicates that a winprop where the field is
1190 not specified (or is itself an asterisk in case of the first three
1191 fields) is tried.
1192
1193 <P>
1194 <DIV ALIGN="CENTER">
1195 <TABLE CELLPADDING=3 BORDER="1">
1196 <TR><TD ALIGN="LEFT"><TT>class</TT></TD>
1197 <TD ALIGN="LEFT"><TT>role</TT></TD>
1198 <TD ALIGN="LEFT"><TT>instance</TT></TD>
1199 <TD ALIGN="LEFT">other</TD>
1200 </TR>
1201 <TR><TD ALIGN="LEFT">E</TD>
1202 <TD ALIGN="LEFT">E</TD>
1203 <TD ALIGN="LEFT">E</TD>
1204 <TD ALIGN="LEFT">E</TD>
1205 </TR>
1206 <TR><TD ALIGN="LEFT">E</TD>
1207 <TD ALIGN="LEFT">E</TD>
1208 <TD ALIGN="LEFT">E</TD>
1209 <TD ALIGN="LEFT">*</TD>
1210 </TR>
1211 <TR><TD ALIGN="LEFT">E</TD>
1212 <TD ALIGN="LEFT">E</TD>
1213 <TD ALIGN="LEFT">*</TD>
1214 <TD ALIGN="LEFT">E</TD>
1215 </TR>
1216 <TR><TD ALIGN="LEFT">E</TD>
1217 <TD ALIGN="LEFT">E</TD>
1218 <TD ALIGN="LEFT">*</TD>
1219 <TD ALIGN="LEFT">*</TD>
1220 </TR>
1221 <TR><TD ALIGN="LEFT">E</TD>
1222 <TD ALIGN="LEFT">*</TD>
1223 <TD ALIGN="LEFT">E</TD>
1224 <TD ALIGN="LEFT">E</TD>
1225 </TR>
1226 <TR><TD ALIGN="LEFT">E</TD>
1227 <TD ALIGN="LEFT">*</TD>
1228 <TD ALIGN="LEFT">E</TD>
1229 <TD ALIGN="LEFT">*</TD>
1230 </TR>
1231 <TR><TD ALIGN="LEFT">E</TD>
1232 <TD ALIGN="LEFT">*</TD>
1233 <TD ALIGN="LEFT">*</TD>
1234 <TD ALIGN="LEFT">E</TD>
1235 </TR>
1236 <TR><TD ALIGN="LEFT">&nbsp;</TD>
1237 <TD ALIGN="LEFT">&nbsp;</TD>
1238 <TD ALIGN="LEFT">&nbsp;</TD>
1239 <TD ALIGN="LEFT">etc.</TD>
1240 </TR>
1241 </TABLE>
1242 </DIV>
1243
1244 <P>
1245 If there are multiple matching winprops with the same
1246 <TT>class</TT>, <TT>role</TT> and <TT>instance</TT>, but other information
1247 different, the most recently defined one is used.
1248
1249 <P>
1250
1251 <H3><A NAME="SECTION00453000000000000000">
1252 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Finding window identification</A>
1253 </H3>
1254
1255 <P>
1256 The 'Window info' context menu entry (<SPAN  CLASS="textbf">Mod1+M</SPAN> or <SPAN  CLASS="textbf">Button3</SPAN> on a tab)
1257 can be used to list the identification information required to set winprops
1258 for a window and all the transient windows managed within it.
1259
1260 <P>
1261 <A NAME="1439"></A>
1262 Another way to get the identification information is to use <TT>xprop</TT>.
1263 Simply run To get class and instance, simply run <TT>xprop WM_CLASS</TT>
1264 and click on the particular window of interest. The class is the latter of
1265 the strings while the instance is the former.  To get the role - few
1266 windows have this property - use the command <TT>xprop WM_ROLE</TT>.
1267 This method, however, will not work on transients.
1268
1269 <P>
1270 <A NAME="1443"></A>
1271 So-called ``transient windows'' are usually short-lived dialogs (although
1272 some programs abuse this property) that have a parent window that they are
1273 ``transient for''. On tiled workspaces Ion displays these windows
1274 simultaneously with the parent window at the bottom of the same frame.
1275 Unfortunately <TT>xprop</TT> is stupid and can't cope with this situation,
1276 returning the parent window's properties when the transient is clicked on.
1277 For this reason you'll have to do a little extra work to get the properties
1278 for that window.<A NAME="tex2html9"
1279   HREF="#foot1492"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A>
1280 <P>
1281 Finally, it should be mentioned that too many authors these days
1282 ``forget'' to set this vital identification to anything meaningful:
1283 everything except name is the same for all of the program's
1284 windows, for example. Some other programs only set this information
1285 after the window has been mapped, i.e. the window manager has been
1286 told to start managing it, which is obviously too late.
1287 Gtk applications in particular are often guilty on both counts.
1288
1289 <P>
1290
1291 <H3><A NAME="SECTION00454000000000000000">
1292 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Some common examples</A>
1293 </H3>
1294
1295 <P>
1296
1297 <H4><A NAME="SECTION00454100000000000000">
1298 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Acrobat Reader</A>
1299 </H4>
1300
1301 <P>
1302 The following is absolutely necessary for Acrobat reader:
1303
1304 <P>
1305 <PRE>
1306 defwinprop{
1307     class = "AcroRead",
1308     instance = "documentShell",
1309     acrobatic = true,
1310 }
1311 </PRE>
1312
1313 <P>
1314
1315 <H4><A NAME="SECTION00454200000000000000">
1316 <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>
1317 </H4>
1318
1319 <P>
1320 The following winprop should place xterm started with command-line parameter
1321 <TT>-name sysmon</TT> and running a system monitoring program in a
1322 particular frame:
1323 <PRE>
1324 defwinprop{
1325     class = "XTerm",
1326     instance = "sysmon",
1327     target = "sysmonframe",
1328 }
1329 </PRE>
1330
1331 <P>
1332 For this example to work, we have to somehow create a frame named
1333 `<TT>sysmonframe</TT>'. One way to do this is to make the following
1334 call in the <SPAN  CLASS="textbf">Mod1+F3</SPAN> Lua code query:
1335
1336 <P>
1337 <PRE>
1338 mod_query.query_renameframe(_)
1339 </PRE>
1340
1341 <P>
1342 Recall that <TT>_</TT> points to the multiplexer (frame or screen) in which
1343 the query was opened. Running this code should open a new query prefilled
1344 with the current name of the frame. In our example we would change the
1345 name to `<TT>sysmonframe</TT>', but we could just as well have used the
1346 default name formed from the frame's class name and an instance number.
1347
1348 <P>
1349
1350 <H2><A NAME="SECTION00460000000000000000"></A>
1351 <A NAME="sec:statusbar"></A>
1352 <BR>
1353 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> The statusbar
1354 </H2>
1355
1356 <P>
1357 The <SPAN  CLASS="textit">mod_statusbar</SPAN> module provides a statusbar that adapts to
1358 layouts of tilings, using only the minimal space needed. Ion only
1359 supports one adaptive ``status display'' object per screen, so this
1360 statusbar is mutually exclusive with the embedded mode of <SPAN  CLASS="textit">mod_dock</SPAN>
1361 docks.
1362
1363 <P>
1364 The statusbar is configured in <SPAN  CLASS="textit">cfg_statusbar.lua</SPAN>. Typically,
1365 the configuration consists of two steps: creating a statusbar with
1366 <A HREF="node7.html#fn:mod_statusbar.create"><TT>mod_statusbar.create</TT></A>, and then launching the separate
1367 <TT>ion-statusd</TT> status daemon process with
1368 <A HREF="node7.html#fn:mod_statusbar.launch_statusd"><TT>mod_statusbar.launch_statusd</TT></A>. This latter phase is done
1369 automatically, if it was not done by the configuration file, but
1370 the configuration file may pass extra parameters to <TT>ion-statusd</TT>
1371 monitors. (See Section <A HREF="node6.html#sec:statusd">5.4</A> for more information on
1372 writing <TT>ion-statusd</TT> monitors.)
1373
1374 <P>
1375 A typical <SPAN  CLASS="textit">cfg_statusbar.lua</SPAN> configuration might look as follows:
1376
1377 <P>
1378 <PRE>
1379 -- Create a statusbar
1380 mod_statusbar.create{
1381     screen = 0,     -- First screen,
1382     pos = 'bl',     -- bottom left corner
1383     systray = true, -- Swallow systray windows
1384
1385     -- The template
1386     template = "[ %date || load:% %&gt;load || mail:% %&gt;mail_new/%&gt;mail_total ]"
1387                .. " %filler%systray",
1388 }
1389
1390 -- Launch ion-statusd.
1391 mod_statusbar.launch_statusd{
1392     -- Date meter
1393     date={
1394         -- ISO-8601 date format with additional abbreviated day name
1395         date_format='%a %Y-%m-%d %H:%M',
1396     },
1397 }
1398 </PRE>
1399
1400 <P>
1401
1402 <H3><A NAME="SECTION00461000000000000000">
1403 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">1</SPAN> The template</A>
1404 </H3>
1405
1406 <P>
1407 The template specifies what is shown on the statusbar; for information
1408 on the other options to <A HREF="node7.html#fn:mod_statusbar.create"><TT>mod_statusbar.create</TT></A>, see the reference.
1409 Strings of the form `<TT>%spec</TT>' tokens specially interpreter by
1410 the statusbar; the rest appears verbatim. The <TT>spec</TT> typically
1411 consists of the name of the value/meter to display (beginning with a latin
1412 alphabet), but may be preceded by an alignment specifier and a number
1413 specifying the minimum width. The alignment specifiers are: `<TT>&gt;</TT>'
1414 for right, `<TT>&lt;</TT>' for left,  and `<TT>|</TT>' for centring. Additionally,
1415 space following `<TT>%</TT>' (that is, the string `<TT>% </TT>'), adds
1416 ``stretchable space'' at that point. The special string `<TT>%filler</TT>'
1417 may be used to flush the rest of the template to the right end of
1418 the statusbar.
1419
1420 <P>
1421 The stretchable space works as follows: <SPAN  CLASS="textit">mod_statusbar</SPAN> remembers
1422 the widest string (in terms of graphical presentation) that it has
1423 seen for each meter, unless the width has been otherwise constrained.
1424 If there is stretchable space in the template, it tries to make the
1425 meter always take this much space, by stretching any space found in
1426 the direction indicated by the alignment specifier: the opposite
1427 direction for left or right alignment, and both for centring.
1428
1429 <P>
1430
1431 <H3><A NAME="SECTION00462000000000000000">
1432 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">2</SPAN> The systray</A>
1433 </H3>
1434
1435 <P>
1436 The special `<TT>%systray</TT>' and `<TT>%systray_*</TT>'
1437 (`<TT>*</TT>' varying) monitors indicate where to place system tray
1438 windows.  There may be multiple of these. KDE-protocol system tray
1439 icons are placed in `<TT>%systray</TT>' automatically, unless disabled
1440 with the <TT>systray</TT> option. Otherwise the <TT>statusbar</TT> winprop may
1441 be used to place any window in any particular `<TT>%systray_*</TT>'.
1442
1443 <P>
1444
1445 <H3><A NAME="SECTION00463000000000000000">
1446 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN> Monitors</A>
1447 </H3>
1448
1449 <P>
1450 The part before the first
1451 underscore of each monitor name, describes the script/plugin/module
1452 that provides the meter, and any configuration should be passed
1453 in the a corresponding sub-table <A HREF="node7.html#fn:mod_statusbar.launch_statusd"><TT>mod_statusbar.launch_statusd</TT></A>.
1454 Ion comes with date, load and mail (for plain old mbox)
1455 <TT>ion-statusd</TT> monitor scripts. More may be obtained from
1456 the scripts repository [<A
1457  HREF="node12.html#scripts">1</A>]. These included scripts
1458 provide the following monitors and their options
1459
1460 <P>
1461
1462 <H4><A NAME="SECTION00463100000000000000">
1463 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Date</A>
1464 </H4>
1465
1466 <P>
1467 Options: <TT>date_format</TT>: The date format in as seen above,
1468 in the usual <TT>strftime</TT> format. <TT>formats</TT>: table of
1469 formats for additional date monitors, the key being the name
1470 of the monitor (without the `<TT>date_</TT>' prefix).
1471
1472 <P>
1473 Monitors: `<TT>date</TT>' and other user-specified ones with the
1474 `<TT>date_</TT>' prefix.
1475
1476 <P>
1477
1478 <H4><A NAME="SECTION00463200000000000000">
1479 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Load</A>
1480 </H4>
1481
1482 <P>
1483 Options: <TT>update_interval</TT>: Update interval in milliseconds
1484 (default 10s). <TT>important_threshold</TT>: Threshold above which
1485 the load is marked as important (default 1.5), so that the
1486 drawing engine may be suitably hinted. <TT>critical_threshold</TT>:
1487 Threshold above which  the load is marked as critical (default 4.0).
1488
1489 <P>
1490 Monitors: `<TT>load</TT>' (for all three values),
1491 `<TT>load_1min</TT>', `<TT>load_5min</TT>' and `<TT>load_15min</TT>'.
1492
1493 <P>
1494
1495 <H4><A NAME="SECTION00463300000000000000">
1496 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Mail</A>
1497 </H4>
1498
1499 <P>
1500 Options: <TT>update_interval</TT>: Update interval in milliseconds
1501 (default 1min). <TT>mbox</TT>: mbox-format mailbox location
1502 (default <code>$MAIL</code>).
1503 <TT>files</TT>: list of additional mailboxes, the key giving the
1504 name of the monitor.
1505
1506 <P>
1507 Monitors: `<TT>mail_new</TT>', `<TT>mail_unread</TT>',
1508 `<TT>mail_total</TT>', and corresponding
1509 `<TT>mail_*_new</TT>', `<TT>mail_*_unread</TT>', and `<TT>mail_*_total</TT>'
1510 for the additional mailboxes (`<TT>*</TT>' varying).
1511
1512 <P>
1513
1514 <P>
1515 <BR><HR><H4>Footnotes</H4>
1516 <DL>
1517 <DT><A NAME="foot880">...keysymdef.h</A><A
1518  HREF="node4.html#tex2html7"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
1519 <DD>This file can usually be found in the directory
1520 <SPAN  CLASS="textit">/usr/X11R6/include/X11/</SPAN>.
1521
1522 </DD>
1523 <DT><A NAME="foot859">... such</A><A
1524  HREF="node4.html#tex2html8"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A></DT>
1525 <DD>Completely useless keys that should be
1526 gotten rid of in the author's opinion.
1527
1528 </DD>
1529 <DT><A NAME="foot1492">... window.</A><A
1530  HREF="node4.html#tex2html9"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A></DT>
1531 <DD>There's a patch to <TT>xprop</TT> to
1532 fix this, but nothing seems to be happening with respect to including it in
1533 XFree86.
1534
1535 </DD>
1536 </DL>
1537 <DIV CLASS="navigation"><HR>
1538 <!--Navigation Panel-->
1539 <A NAME="tex2html288"
1540   HREF="node5.html">
1541 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
1542 <A NAME="tex2html282"
1543   HREF="ionconf.html">
1544 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
1545 <A NAME="tex2html276"
1546   HREF="node3.html">
1547 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
1548 <A NAME="tex2html284"
1549   HREF="node1.html">
1550 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
1551 <A NAME="tex2html286"
1552   HREF="node11.html">
1553 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
1554 <BR>
1555 <B> Next:</B> <A NAME="tex2html289"
1556   HREF="node5.html">4. Graphical styles</A>
1557 <B> Up:</B> <A NAME="tex2html283"
1558   HREF="ionconf.html">Configuring and extending Ion3</A>
1559 <B> Previous:</B> <A NAME="tex2html277"
1560   HREF="node3.html">2. Preliminaries: Key concepts</A>
1561  &nbsp; <B>  <A NAME="tex2html285"
1562   HREF="node1.html">Contents</A></B>
1563  &nbsp; <B>  <A NAME="tex2html287"
1564   HREF="node11.html">Index</A></B> </DIV>
1565 <!--End of Navigation Panel-->
1566
1567 </BODY>
1568 </HTML>