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