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