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