1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
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 -->
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">
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">
20 <LINK REL="STYLESHEET" HREF="ionconf.css">
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">
30 <DIV CLASS="navigation"><!--Navigation Panel-->
33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
47 <B> Next:</B> <A NAME="tex2html288"
48 HREF="node5.html">4. Graphical styles</A>
49 <B> Up:</B> <A NAME="tex2html282"
50 HREF="ionconf.html">Configuring and extending Ion3</A>
51 <B> Previous:</B> <A NAME="tex2html276"
52 HREF="node3.html">2. Preliminaries: Key concepts</A>
53 <B> <A NAME="tex2html284"
54 HREF="node1.html">Contents</A></B>
55 <B> <A NAME="tex2html286"
56 HREF="node11.html">Index</A></B>
59 <!--End of Navigation Panel-->
60 <!--Table of Child-Links-->
61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
63 <UL CLASS="ChildLinks">
64 <LI><A NAME="tex2html289"
65 HREF="node4.html#SECTION00410000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> The configuration files</A>
66 <LI><A NAME="tex2html290"
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="tex2html291"
69 HREF="node4.html#SECTION00430000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Keys and rodents</A>
71 <LI><A NAME="tex2html292"
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="tex2html293"
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="tex2html294"
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="tex2html295"
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="tex2html296"
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="tex2html297"
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="tex2html298"
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>
87 <LI><A NAME="tex2html299"
88 HREF="node4.html#SECTION00440000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Menus</A>
90 <LI><A NAME="tex2html300"
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="tex2html301"
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="tex2html302"
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="tex2html303"
97 HREF="node4.html#SECTION00444000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">4</SPAN> Displaying menus</A>
100 <LI><A NAME="tex2html304"
101 HREF="node4.html#SECTION00450000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Winprops</A>
103 <LI><A NAME="tex2html305"
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="tex2html306"
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="tex2html307"
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="tex2html308"
110 HREF="node4.html#SECTION00454000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Some common examples</A>
112 <LI><A NAME="tex2html309"
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="tex2html310"
115 HREF="node4.html#SECTION00454200000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Forcing newly created windows in named frames</A>
119 <LI><A NAME="tex2html311"
120 HREF="node4.html#SECTION00460000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> The statusbar</A>
122 <LI><A NAME="tex2html312"
123 HREF="node4.html#SECTION00461000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">1</SPAN> The template</A>
124 <LI><A NAME="tex2html313"
125 HREF="node4.html#SECTION00462000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">2</SPAN> The systray</A>
126 <LI><A NAME="tex2html314"
127 HREF="node4.html#SECTION00463000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN> Monitors</A>
129 <LI><A NAME="tex2html315"
130 HREF="node4.html#SECTION00463100000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Date</A>
131 <LI><A NAME="tex2html316"
132 HREF="node4.html#SECTION00463200000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Load</A>
133 <LI><A NAME="tex2html317"
134 HREF="node4.html#SECTION00463300000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Mail</A>
136 <!--End of Table of Child-Links-->
139 <H1><A NAME="SECTION00400000000000000000"></A>
140 <A NAME="chap:config"></A>
142 <SPAN CLASS="arabic">3</SPAN>. Basic configuration
146 This chapter should help your configure Ion to your liking. As the your
147 probably already know, Ion uses Lua as a configuration and extension
148 language. If you're new to it, you might first want to read some Lua
149 documentation as already suggested and pointed to in the Introduction
150 before continuing with this chapter.
153 Section <A HREF="#sec:conffiles">3.1</A> is an overview of the multiple configuration
154 files Ion uses and as a perhaps more understandable introduction to the
155 general layout of the configuration files, a walk-through of the main
156 configuration file <SPAN CLASS="textit">cfg_ion.lua</SPAN> is provided in section
157 <A HREF="#sec:walkthrough">3.2</A>.
158 How keys and mouse action are bound to functions is described in detail
159 in <A HREF="#sec:bindings">3.3</A> and in section <A HREF="#sec:winprops">3.5</A> winprops are
160 explained. Finally, the statusbar is explained in <A HREF="#sec:statusbar">3.6</A>.
161 For a reference on exported functions, see section <A HREF="node7.html#sec:exports">6</A>.
165 <H2><A NAME="SECTION00410000000000000000"></A>
166 <A NAME="sec:conffiles"></A>
168 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> The configuration files
172 Ion3, to which document applies, stores its stock configuration files in
173 <SPAN CLASS="textit">/usr/local/etc/ion3/</SPAN> unless you, the OS package maintainer or
174 whoever installed the package on the system has modified the variables
175 <TT>PREFIX</TT><A NAME="581"></A> or
176 <TT>ETCDIR</TT><A NAME="582"></A> in
177 <SPAN CLASS="textit">system.mk</SPAN><A NAME="583"></A> before compiling Ion.
178 In the first case you probably know where to find the files and in
179 the other case the system administrator or the OS package maintainer
180 should have provided documentation to point to the correct location.
181 If these instructions are no help in locating the correct directory,
182 the command <TT>locate cfg_ion.lua</TT> might help provided <TT>updatedb</TT>
183 has been run recently.
186 User configuration files go in <SPAN CLASS="textit">~/.ion3/</SPAN>.
187 Ion always searches the user configuration file directory before the stock
188 configuration file directory for files. Therefore, if you want to change
189 some setting, it is advised against that you modify the stock configuration
190 files in-place as subsequent installs of Ion will restore the stock
191 configuration files. Instead you should always make a copy of the stock
192 file in <SPAN CLASS="textit">~/.ion3/</SPAN> and modify this file. For sake of maintainability
193 of your customised configuration, it is recommended against copying all of
194 the files there. Only copy those files you actually need to modify. Most
195 simple customisations, such as changes in a few bindings, are best done
196 entirely within <SPAN CLASS="textit">cfg_ion.lua</SPAN>.
199 All the configuration files are named <SPAN CLASS="textit">cfg_*.lua</SPAN> with the ``<SPAN CLASS="textit">*</SPAN>''
200 part varying. The configuration file for each module <SPAN CLASS="textit">mod_modname</SPAN> is
201 <SPAN CLASS="textit">cfg_modname.lua</SPAN>, with <SPAN CLASS="textit">modname</SPAN> varying by the module in
202 question. Configuration files can also be compiled into <SPAN CLASS="textit">.lc</SPAN> files,
203 and these are attempted by the configuration file search routines before
204 <SPAN CLASS="textit">.lua</SPAN> files.
207 The following table summarises these and other configuration
211 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
212 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1>File</TD>
213 <TD ALIGN="LEFT">Description</TD>
215 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN CLASS="textit">cfg_ion.lua</SPAN></TD>
216 <TD ALIGN="LEFT">The main configuration file</TD>
218 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN CLASS="textit">cfg_ioncore.lua</SPAN></TD>
219 <TD ALIGN="LEFT">Configuration file for Ion's core library.
220 Most of the bindings and menus are configured here. Bindings that are
221 specific to some module are configured in the module's configuration
222 file. For details, see section <A HREF="#sec:bindings">3.3</A>.</TD>
224 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN CLASS="textit">cfg_kludges.lua</SPAN></TD>
225 <TD ALIGN="LEFT">Settings to get some applications behave more nicely have been
226 collected here. See section <A HREF="#sec:winprops">3.5</A>.</TD>
228 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN CLASS="textit">cfg_layouts.lua</SPAN></TD>
229 <TD ALIGN="LEFT">Some workspace layouts are defined here.</TD>
231 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=1><SPAN CLASS="textit">cfg_tiling.lua</SPAN>
232 <SPAN CLASS="textit">cfg_query.lua</SPAN>
233 <SPAN CLASS="textit">cfg_menu.lua</SPAN>
234 <SPAN CLASS="textit">cfg_dock.lua</SPAN>
235 <SPAN CLASS="textit">cfg_statusbar.lua</SPAN>
237 <TD ALIGN="LEFT">Configuration files for different modules.</TD>
242 Additionally, there's the file <SPAN CLASS="textit">look.lua</SPAN> that configures the
243 drawing engine, but it is covered in chapter <A HREF="node5.html#chap:gr">4</A>.
247 <H2><A NAME="SECTION00420000000000000000"></A>
248 <A NAME="sec:walkthrough"></A>
250 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> A walk through <SPAN CLASS="textit">cfg_ion.lua</SPAN>
254 As already mentioned <SPAN CLASS="textit">cfg_ion.lua</SPAN> is Ion's main configuration
255 file. Some basic 'feel' settings are usually configured there and
256 the necessary modules and other configuration files configuring some
257 more specific aspects of Ion are loaded there. In this section we
258 take a walk through the stock <SPAN CLASS="textit">cfg_ion.lua</SPAN>.
259 Notice that most of the settings are commented-out (<code>--</code> is a
260 line comment in Lua) in the actual file, as they're the defaults
264 The first thing done in the file, is to set
269 These settings cause most of Ion's key bindings to use <SPAN CLASS="textbf">Mod1</SPAN> as the
270 modifier key. If <TT>ALTMETA</TT> is set, it is used as modifier for the
271 keys that don't normally use a modifier. Note that these two are Lua
272 variables used in the configuration files only, and not Ion settings.
273 For details on modifiers and key binding setup in general, see section
274 <A HREF="#sec:bindings">3.3</A>.
277 Next we do some basic feel configuration:
288 These two will set the delay between button presses in a double click, and
289 the timeout to quit resize mode in milliseconds.
300 The first of these two settings enables opaque resize mode: in move/resize
301 move frames and other objects mirror you actions immediately. If opaque
302 resize is disabled, a XOR rubber band is shown during the mode instead.
303 This will, unfortunately, cause Ion to also grab the X server and has some
307 There are some other options as well; see the documentation
308 for <A HREF="node7.html#fn:ioncore.set"><TT>ioncore.set</TT></A> for details.
311 As a next step, in the actual <SPAN CLASS="textit">cfg_ion.lua</SPAN> file, we load
312 <SPAN CLASS="textit">cfg_defaults.lua</SPAN>. However, it is merely a convenience file for
313 doing exactly what we will going through below, and what is commented
314 out in the actual file. If you do not want to load what
315 <SPAN CLASS="textit">cfg_defaults.lua</SPAN> loads, just comment out the corresponding
316 line, and uncomment the lines for the files that you want:
320 --dopath("cfg_defaults")
321 dopath("cfg_ioncore")
322 dopath("cfg_kludges")
323 dopath("cfg_layouts")
327 Most bindings and menus are defined in <SPAN CLASS="textit">cfg_ioncore.lua</SPAN>.
328 Details on making such definitions follow in sections <A HREF="#sec:bindings">3.3</A>
329 and <A HREF="#sec:menus">3.4</A>, respectively.
330 some kludges or ``winprops'' to make some applications behave better
331 under Ion are collected in <SPAN CLASS="textit">cfg_kludges.lua</SPAN>; see section
332 <A HREF="#sec:winprops">3.5</A> for details. In addition to these, this file
333 lists quite a few statements of the form
335 ioncore.defshortening("[^:]+: (.*)(<[0-9]+>)", "$1$2$|$1$<...$2")
337 These are used to configure how Ion attempts to shorten window titles
338 when they do not fit in a Tab. The first argument is a POSIX regular
339 expression that is used to match against the title and the next is
340 a rule to construct a new title of a match occurs. This particular
341 rule is used to shorten e.g. 'Foo: barbaz<3>' to 'barba...<3>'; for
342 details see the function reference entry for <A HREF="node7.html#fn:ioncore.defshortening"><TT>ioncore.defshortening</TT></A>.
343 Finally, <SPAN CLASS="textit">cfg_layouts.lua</SPAN> defines some workspace layouts, available
344 through the <SPAN CLASS="textbf">F9</SPAN> workspace creation query.
347 To actually be able to do something besides display windows in full screen
348 mode, we must next load some modules:
355 dopath("mod_statusbar")
362 <H2><A NAME="SECTION00430000000000000000"></A>
363 <A NAME="sec:bindings"></A>
365 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Keys and rodents
369 In the stock configuration file setup, most key and mouse bindings are set
370 from the file <SPAN CLASS="textit">cfg_ioncore.lua</SPAN> while module-specific bindings
371 are set from the modules' main configuration files (<SPAN CLASS="textit">cfg_modname.lua</SPAN>).
372 This, however, does not have to be so as long as the module has been
373 loaded prior to defining any module-specific bindings.
376 Bindings are defined by calling the function
377 <A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> with the ``context'' of the
378 bindings and the a table of new bindings to make. The context is simply
379 string indicating one of the classes of regions (or modes such as
380 WMoveresMode) introduced in section <A HREF="node3.html#sec:objects">2.2</A>, and fully
381 listed in appendix <A HREF="node9.html#app:fullhierarchy">B</A>, although not all define
382 a binding map. For example, the following skeleton would be used to
383 define new bindings for all frames:
387 defbindings("WFrame", {
388 -- List of bindings to make goes here.
393 There has been some confusion among users about the need to define the
394 ``context'' for each binding, so let me try to explain this design
395 decision here. The thing is that if there was a just a simple 'bind this
396 key to this action' method without knowledge of the context, some
397 limitations would have to be made on the available actions and writing
398 custom handlers would be more complicated. In addition one may want to
399 bind the same function to different key for different types of objects.
400 Indeed, the workspace and frame tab switching functions are the same both
401 classes being based on WMPlex, and in the stock configuration the
402 switch to <SPAN CLASS="MATH"><IMG
403 WIDTH="15" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
405 ALT="$n$"></SPAN>:th workspaces is bound to <SPAN CLASS="textbf">Mod1+n</SPAN> while the switch to
406 <SPAN CLASS="MATH"><IMG
407 WIDTH="15" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
409 ALT="$n$"></SPAN>:th tab is bound to the sequence <SPAN CLASS="textbf">Mod1+k n</SPAN>.
412 Currently known contexts include:
415 `<TT>WMPlex.toplevel</TT>',
417 `<TT>WFrame.toplevel</TT>',
418 `<TT>WFrame.floating</TT>',
419 `<TT>WFrame.tiled</TT>',
420 `<TT>WFrame.transient</TT>',
421 `<TT>WMoveresMode</TT>',
425 `<TT>WClientWin</TT>',
426 `<TT>WTiling</TT>', and
427 `<TT>WStatusBar</TT>'.
428 Most of these should be self-explanatory, corresponding to objects
429 of class with the same name. The ones with `<TT>.toplevel</TT>' suffix
430 refer to screens and ``toplevel'' frames, i.e. frames that are
431 not used for transient windows. Likewise `<TT>.transient</TT>' refers
432 to frames in transient mode, and `<TT>.tiled</TT>' and `<TT>.floating</TT>'
433 to frames in, respectively, tiled and floating modes.
436 The following subsections describe how to construct elements of the
437 binding table. Note that <A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> adds
438 the the newly defined bindings to the previous bindings of the context,
439 overriding duplicates. To unbind an event, set the handler parameter
440 to <TT>nil</TT> for each of the functions to be described in the following
444 Also note that when multiple objects want to handle a binding, the
445 innermost (when the root window is considered the outermost) active object
446 in the parent-child hierarchy (see Figure <A HREF="node3.html#fig:parentship">2.2</A>) of objects
447 gets to handle the action.
451 <H3><A NAME="SECTION00431000000000000000">
452 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Binding handlers and special variables</A>
456 Unlike in Ion2, in Ion3 binding handlers are not normally passed as
457 ``anonymous functions'', although this is still possible. The preferred
458 method now is to pass the code of the handler as a string. Two following
459 special variables are available in this code.
462 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
463 <TR><TD ALIGN="LEFT">Variable</TD>
464 <TD ALIGN="LEFT">Description</TD>
466 <TR><TD ALIGN="LEFT"><TT>_</TT> (underscore)</TD>
467 <TD ALIGN="LEFT">Reference to the object on which the
468 binding was triggered. The object is of the same class as the the
469 context of the <A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> call
470 defining the binding.</TD>
472 <TR><TD ALIGN="LEFT"><TT>_sub</TT></TD>
473 <TD ALIGN="LEFT">Usually, the currently active <SPAN CLASS="textit">managed object</SPAN> of the
474 object referred to by <TT>_</TT>, but sometimes (e.g. mouse actions
475 on tabs of frames) something else relevant to the action triggering
478 <TR><TD ALIGN="LEFT"><TT>_chld</TT></TD>
479 <TD ALIGN="LEFT">Object corresponding to the currently active child window of the
480 object referred to by <TT>_</TT>. This should seldom be needed.</TD>
485 For example, supposing <TT>_</TT> (underscore) is a WFrame, the
486 following handler should move the active window to the right, if
496 <H3><A NAME="SECTION00432000000000000000">
497 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Guards</A>
501 To suppress error messages, each binding handler may also be accompanied
502 by a ``guard'' expression that blocks the handler from being called when
503 the guard condition is not met. Currently the following guard expressions
504 are supported (for both <TT>_sub</TT> and <TT>_chld</TT>):
507 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
508 <TR><TD ALIGN="LEFT">Guard</TD>
509 <TD ALIGN="LEFT">Description</TD>
511 <TR><TD ALIGN="LEFT">`<TT>_sub:non-nil</TT>'</TD>
512 <TD ALIGN="LEFT">The <TT>_sub</TT> parameter must be set.</TD>
514 <TR><TD ALIGN="LEFT">`<TT>_sub:SomeClass</TT>'</TD>
515 <TD ALIGN="LEFT">The <TT>_sub</TT> parameter must be member
516 of class SomeClass.</TD>
522 <H3><A NAME="SECTION00433000000000000000"></A>
523 <A NAME="sec:binddef"></A>
525 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining the bindings
529 The descriptions of the individual bindings in the binding table argument
530 to <A HREF="node7.html#fn:ioncore.defbindings"><TT>defbindings</TT></A> should be constructed with the following
537 <LI><A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A>, and
538 <A HREF="node7.html#fn:ioncore.kpress_wait"><TT>kpress_wait</TT></A><TT>(keyspec, handler [, guard])</TT>.
540 <LI><A HREF="node7.html#fn:ioncore.submap"><TT>submap</TT></A><TT>(keyspec, { ... more key bindings ... })</TT>.
542 <LI><A HREF="node7.html#fn:ioncore.submap_enter"><TT>submap_enter</TT></A>, and
543 <A HREF="node7.html#fn:ioncore.submap_wait"><TT>submap_wait</TT></A><TT>(handler [, guard])</TT>.
549 <LI><A HREF="node7.html#fn:ioncore.mclick"><TT>mclick</TT></A>,
550 <A HREF="node7.html#fn:ioncore.mdblclick"><TT>mdblclick</TT></A>,
551 <A HREF="node7.html#fn:ioncore.mpress"><TT>mpress</TT></A>, and
552 <A HREF="node7.html#fn:ioncore.mdrag"><TT>mdrag</TT></A><TT>(buttonspec, handler [, guard])</TT>.
557 The actions that most of these functions correspond to should be clear
558 and as explained in the reference, <A HREF="node7.html#fn:ioncore.kpress_wait"><TT>kpress_wait</TT></A> is simply
559 <A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A> with a flag set instructing Ioncore wait for
560 all modifiers to be released before processing any further actions.
561 This is to stop one from accidentally calling e.g.
562 <A HREF="node7.html#fn:WRegion.rqclose"><TT>WRegion.rqclose</TT></A> multiple times in a row. The
563 <A HREF="node7.html#fn:ioncore.submap"><TT>submap</TT></A> function is used to define submaps or
564 ``prefix maps''. The second argument to this function is table listing
565 the key press actions (<A HREF="node7.html#fn:ioncore.kpress"><TT>kpress</TT></A>) in the submap.
566 The <A HREF="node7.html#fn:ioncore.submap_enter"><TT>submap_enter</TT></A> handler is called when the submap
567 is entered, in which this handler is defined. Likewise, the
568 <A HREF="node7.html#fn:ioncore.submap_wait"><TT>submap_wait</TT></A> handler is called when all modifiers
569 have been released while waiting for further key presses in the submap.
572 The parameters <TT>keyspec</TT> and <TT>buttonspec</TT> are explained below
573 in detail. The parameter <TT>handler</TT> is the handler for the binding,
574 and the optional parameter <TT>guard</TT> its guard. These should normally
575 be strings as explained above.
579 <H3><A NAME="SECTION00434000000000000000">
580 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Examples</A>
584 For example, to just bind the key <SPAN CLASS="textbf">Mod1+1</SPAN> to switch to the first
585 workspace and <SPAN CLASS="textbf">Mod1+Right</SPAN> to the next workspace, you would make the
588 defbindings("WScreen", {
589 kpress("Mod1+Right", "_:switch_next()"),
590 kpress("Mod1+1", "_:switch_nth(1)"),
595 Note that <TT>_:switch_nth(1)</TT> is the same as calling
596 <A HREF="node7.html#fn:WMPlex.switch_next"><TT>WMPlex.switch_next</TT></A><TT>(_, 1)</TT> as WScreen inherits
597 WMPlex and this is where the function is actually defined.
600 Similarly to the above example, to bind the key sequence <SPAN CLASS="textbf">Mod1+k n</SPAN>
601 switch to the next managed object within a frame, and <SPAN CLASS="textbf">Mod1+k 1</SPAN> to the
602 first, you would issue the following call:
604 defbindings("WFrame", {
606 kpress("Right", "_:switch_next()"),
607 kpress("1", "_:switch_nth(1)"),
614 <H3><A NAME="SECTION00435000000000000000">
615 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Key specifications</A>
619 As seen above, the functions that create key binding specifications require
620 a <TT>keyspec</TT> argument. This argument should be a string containing the
621 name of a key as listed in the X header file <SPAN CLASS="textit">keysymdef.h</SPAN><A NAME="tex2html7"
622 HREF="#foot878"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A> without the <TT>XK_</TT> prefix.
624 Most of the key names are quite intuitive while some are not. For example,
625 the <SPAN CLASS="textbf">Enter</SPAN> key on the main part of the keyboard has the less common
626 name <SPAN CLASS="textbf">Return</SPAN> while the one the numpad is called <SPAN CLASS="textbf">KP_Enter</SPAN>.
629 The <TT>keyspec</TT> string may optionally have multiple ``modifier'' names
630 followed by a plus sign (<TT>+</TT>) as a prefix. X defines the following
634 <SPAN CLASS="textbf">Shift</SPAN>, <SPAN CLASS="textbf">Control</SPAN>, <SPAN CLASS="textbf">Mod1</SPAN> to <SPAN CLASS="textbf">Mod5</SPAN>,
635 <SPAN CLASS="textbf">AnyModifier</SPAN> and <SPAN CLASS="textbf">Lock</SPAN>.
643 X allows binding all of these modifiers to almost any key and while this
644 list of modifiers does not explicitly list keys such as
645 <SPAN CLASS="textbf">Alt</SPAN><A NAME="885"></A> that are common on modern keyboards, such
646 keys are bound to one of the <SPAN CLASS="textbf">ModN</SPAN>. On systems running XFree86
647 <SPAN CLASS="textbf">Alt</SPAN> is usually <SPAN CLASS="textbf">Mod1</SPAN>. On Suns <SPAN CLASS="textbf">Mod1</SPAN> is the diamond key
648 and <SPAN CLASS="textbf">Alt</SPAN> something else. One of the ``flying window'' keys on so
649 called Windows-keyboards is probably mapped to <SPAN CLASS="textbf">Mod3</SPAN> if you have
650 such a key. Use the program <SPAN CLASS="textit">xmodmap</SPAN><A NAME="886"></A>
651 to find out what exactly is bound where.
654 Ion defaults to <SPAN CLASS="textbf">AnyModifier</SPAN> in submaps. This can sometimes lead to
655 unwanted effects when the same key is used with and without explicitly
656 specified modifiers in nested regions. For this reason, Ion recognises
657 <SPAN CLASS="textbf">NoModifier</SPAN> as a special modifier that can be used to reset this
661 Ion ignores the <SPAN CLASS="textbf">Lock</SPAN> modifier and any <SPAN CLASS="textbf">ModN</SPAN> (<SPAN CLASS="MATH"><IMG
662 WIDTH="82" HEIGHT="15" ALIGN="BOTTOM" BORDER="0"
664 ALT="$N=1{\ldots} 5$"></SPAN>)
665 bound to <SPAN CLASS="textbf">NumLock</SPAN><A NAME="887"></A> or
666 <SPAN CLASS="textbf">ScrollLock</SPAN><A NAME="888"></A>
667 by default because such<A NAME="tex2html8"
668 HREF="#foot857"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A> locking keys may otherwise
673 <H3><A NAME="SECTION00436000000000000000">
674 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> Button specifications</A>
678 Button specifications are similar to key definitions but now
679 instead of specifying modifiers and a key, you specify modifiers
680 and one of the button names <SPAN CLASS="textbf">Button1</SPAN> to
681 <SPAN CLASS="textbf">Button5</SPAN><A NAME="889"></A>. Additionally the
682 specification may end with an optional area name following an @-sign.
683 Only frames currently support areas, and the supported values in this
685 `<TT>border</TT>', `<TT>tab</TT>', `<TT>empty_tab</TT>', `<TT>client</TT>'
686 and <TT>nil</TT> (for the whole frame).
689 For example, the following code binds dragging a tab with the first
690 button pressed to initiate tab drag&drop handling:
694 defbindings("WFrame", {
695 mdrag("Button1@tab", "_:p_tabdrag()"),
701 <H3><A NAME="SECTION00437000000000000000">
702 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">7</SPAN> A further note on the default binding configuration</A>
706 The default binding configuration contains references to the variables
707 <TT>META</TT> and <TT>ALTMETA</TT> instead of directly using the default
708 values of `<TT>Mod1+</TT>' and `' (nothing). As explained in
709 section <A HREF="#sec:walkthrough">3.2</A>, the definitions of these variables
710 appear in <SPAN CLASS="textit">cfg_ion.lua</SPAN>. This way you can easily change the the
711 modifiers used by all bindings in the default configuration without
712 changing the whole binding configuration. Quite a few people prefer
713 to use the Windows keys as modifiers because many applications already
714 use <SPAN CLASS="textbf">Alt</SPAN>. Nevertheless, <SPAN CLASS="textbf">Mod1</SPAN> is the default as a key bound
715 to it is available virtually everywhere.
719 <H2><A NAME="SECTION00440000000000000000"></A>
720 <A NAME="sec:menus"></A>
722 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Menus
727 <H3><A NAME="SECTION00441000000000000000">
728 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Defining menus</A>
736 In the stock configuration file setup, menus are defined in the file
737 <SPAN CLASS="textit">cfg_menus.lua</SPAN> as previously mentioned. The <SPAN CLASS="textit">mod_menu</SPAN> module
738 must be loaded for one to be able to define menus, and this is done with
739 the function <A HREF="#fn:mod_menu.defmenu"><TT>defmenu</TT></A> provided by it.
742 Here's an example of the definition of a rather simple menu with a submenu:
746 defmenu("exitmenu", {
747 menuentry("Restart", "ioncore.restart()"),
748 menuentry("Exit", "ioncore.shutdown()"),
751 defmenu("mainmenu", {
752 menuentry("Lock screen", "ioncore.exec('xlock')"),
753 menuentry("Help", "mod_query.query_man(_)"),
754 submenu("Exit", "exitmenu"),
759 The <A HREF="#fn:mod_menu.menuentry"><TT>menuentry</TT></A> function is used to create an entry in the
760 menu with a title and an entry handler to be called when the menu entry
761 is activated. The parameters to the handler are similar to those of binding
762 handlers, and usually the same as those of the binding that opened the menu.
765 The <A HREF="#fn:mod_menu.submenu"><TT>submenu</TT></A> function is used to insert a submenu at that
766 point in the menu. (One could as well just pass a table with the menu
767 entries, but it is not encouraged.)
771 <H3><A NAME="SECTION00442000000000000000">
772 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Special menus</A>
776 The menu module predefines the following special menus. These can be used
777 just like the menus defined as above.
780 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
781 <TR><TD ALIGN="LEFT">Menu name</TD>
782 <TD ALIGN="LEFT">Description</TD>
784 <TR><TD ALIGN="LEFT">`<TT>windowlist</TT>'</TD>
785 <TD ALIGN="LEFT">List of all client windows. Activating an entry jumps to that window.</TD>
787 <TR><TD ALIGN="LEFT">`<TT>workspacelist</TT>'</TD>
788 <TD ALIGN="LEFT">List of all workspaces. Activating an entry jumps to that workspaces.</TD>
790 <TR><TD ALIGN="LEFT">`<TT>focuslist</TT>'</TD>
791 <TD ALIGN="LEFT">List of client windows with recent activity in them, followed by
792 previously focused client windows.</TD>
794 <TR><TD ALIGN="LEFT">`<TT>focuslist_</TT>'</TD>
795 <TD ALIGN="LEFT">List of previously focused client windows.</TD>
797 <TR><TD ALIGN="LEFT">`<TT>stylemenu</TT>'</TD>
798 <TD ALIGN="LEFT">List of available <SPAN CLASS="textit">look_*.lua</SPAN> style files. Activating an entry
799 loads that style and ask to save the selection.</TD>
801 <TR><TD ALIGN="LEFT">`<TT>ctxmenu</TT>'</TD>
802 <TD ALIGN="LEFT">Context menu for given object.</TD>
808 <H3><A NAME="SECTION00443000000000000000">
809 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining context menus</A>
813 The ``ctxmenu'' is a special menu that is assembled from a defined context
814 menu for the object for which the menu was opened for, but also includes
815 the context menus for the manager objects as submenus.
818 Context menus for a given region class are defined with the
819 <A HREF="#fn:mod_menu.defctxmenu"><TT>defctxmenu</TT></A> function. This is other ways similar to
820 <A HREF="#fn:mod_menu.defmenu"><TT>defmenu</TT></A>, but the first argument instead being the name
821 of the menu, the name of the region class to define context menu for.
822 For example, here's part of the stock WFrame context menu
827 defctxmenu("WFrame", {
828 menuentry("Close", "WRegion.rqclose_propagate(_, _sub)"),
829 menuentry("Kill", "WClientWin.kill(_sub)", "_sub:WClientWin"),
834 Some of the same ``modes'' as were available for some bindings
835 may also be used: `<TT>WFrame.tiled</TT>', `<TT>WFrame.floating</TT>',
836 and `<TT>WFrame.transient</TT>'.
840 <H3><A NAME="SECTION00444000000000000000"></A>
841 <A NAME="sec:menudisp"></A>
843 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">4</SPAN> Displaying menus
847 The following functions may be used to display menus from binding
848 handlers (and elsewhere):
851 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
852 <TR><TD ALIGN="LEFT">Function</TD>
853 <TD ALIGN="LEFT">Description</TD>
855 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.menu"><TT>mod_menu.menu</TT></A></TD>
856 <TD ALIGN="LEFT">Keyboard (or mouse) operated menus that open in the bottom-left corner
857 of a screen or frame.</TD>
859 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.pmenu"><TT>mod_menu.pmenu</TT></A></TD>
860 <TD ALIGN="LEFT">Mouse-operated drop-down menus. This function can only be called from a
861 mouse press or drag handler.</TD>
863 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.grabmenu"><TT>mod_menu.grabmenu</TT></A></TD>
864 <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
865 and is scrolled with a given key until all modifiers have been released,
866 after which the selected entry is activated.</TD>
871 The <A HREF="node7.html#fn:mod_menu.grabmenu"><TT>grabmenu</TT></A> function takes the extra key parameter, but
872 aside from that each of these functions takes three arguments, which when
873 called from a binding handler, should be the parameters to the handler, and
874 the name of the menu. For example, the following snippet of of code binds
875 the both ways to open a context menu for a frame:
879 defbindings("WFrame", {
880 kpress(MOD1.."M", "mod_menu.menu(_, _sub, 'ctxmenu')"),
881 mpress("Button3", "mod_menu.pmenu(_, _sub, 'ctxmenu')"),
887 <H2><A NAME="SECTION00450000000000000000"></A>
888 <A NAME="sec:winprops"></A>
890 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Winprops
894 The so-called ``winprops''<A NAME="1289"></A> can be used to change how
895 specific windows are handled and to set up some kludges to deal with
896 badly behaving applications. They are defined by calling the function
897 <TT>defwinprop</TT> with a table containing the properties to set and the
898 necessary information to identify a window. The currently supported
899 winprops are listed below, and the subsequent subsections explain the
900 usual method of identifying windows, and how to obtain this information.
907 <DT><STRONG>Winprop:</STRONG></DT>
908 <DD><TT>acrobatic</TT> (boolean)
911 <DT><STRONG>Description:</STRONG></DT>
912 <DD><A NAME="1456"></A>
913 Set this to <TT>true</TT> for Acrobat Reader. It has an annoying
914 habit of trying to manage its dialogs instead of setting them as
915 transients and letting the window manager do its job, causing
916 Ion and acrobat go a window-switching loop when a dialog is
925 <DT><STRONG>Winprop:</STRONG></DT>
926 <DD><TT>float</TT> (boolean)
929 <DT><STRONG>Description:</STRONG></DT>
930 <DD><A NAME="1457"></A>
931 Set this to open the window in a floating frame, when
940 <DT><STRONG>Winprop:</STRONG></DT>
941 <DD><TT>fullscreen</TT> (boolean)
944 <DT><STRONG>Description:</STRONG></DT>
945 <DD><A NAME="1458"></A>
946 Should the window be initially in full screen mode?
954 <DT><STRONG>Winprop:</STRONG></DT>
955 <DD><TT>ignore_cfgrq</TT> (boolean)
958 <DT><STRONG>Description:</STRONG></DT>
959 <DD><A NAME="1459"></A>
960 Should configure requests on the window be ignored?
961 Only has effect on floating windows.
969 <DT><STRONG>Winprop:</STRONG></DT>
970 <DD><TT>ignore_net_active_window</TT> (boolean)
973 <DT><STRONG>Description:</STRONG></DT>
974 <DD><A NAME="1460"></A>
975 Ignore extended WM hints <TT>_NET_ACTIVE_WINDOW</TT> request.
983 <DT><STRONG>Winprop:</STRONG></DT>
984 <DD><TT>jumpto</TT> (boolean)
987 <DT><STRONG>Description:</STRONG></DT>
988 <DD><A NAME="1461"></A>
989 Should a newly created client window always be made
990 active, even if the allocated frame isn't.
998 <DT><STRONG>Winprop:</STRONG></DT>
999 <DD><TT>new_group</TT> (string)
1002 <DT><STRONG>Description:</STRONG></DT>
1003 <DD><A NAME="1462"></A>
1004 If the region specified by <TT>target</TT> winprop does not exist
1005 (or that winprop is not set), create a new workspace using the
1006 previously stored layout (see <A HREF="node7.html#fn:ioncore.deflayout"><TT>ioncore.deflayout</TT></A>) named by
1007 this property. After creating the workspace, <TT>target</TT> is
1008 attempted to be found again. (If that still fails, the newly
1009 created workspace is still asked to manage the client window.)
1017 <DT><STRONG>Winprop:</STRONG></DT>
1018 <DD><TT>oneshot</TT> (boolean)
1021 <DT><STRONG>Description:</STRONG></DT>
1022 <DD><A NAME="1463"></A>
1023 Discard this winprop after first use.
1031 <DT><STRONG>Winprop:</STRONG></DT>
1032 <DD><TT>orientation</TT> (string)
1035 <DT><STRONG>Description:</STRONG></DT>
1036 <DD><A NAME="1464"></A>
1037 The orientation of the window: one of `<TT>vertical</TT>' or
1038 `<TT>horizontal</TT>'. This is only useful when using the
1039 window as a status display.
1047 <DT><STRONG>Winprop:</STRONG></DT>
1048 <DD><TT>statusbar</TT> (string)
1051 <DT><STRONG>Description:</STRONG></DT>
1052 <DD><A NAME="1465"></A>
1053 Put the window in 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>'.
1064 <DT><STRONG>Winprop:</STRONG></DT>
1065 <DD><TT>switchto</TT> (boolean)
1068 <DT><STRONG>Description:</STRONG></DT>
1069 <DD><A NAME="1466"></A>
1070 Should a newly mapped client window be switched to within
1079 <DT><STRONG>Winprop:</STRONG></DT>
1080 <DD><TT>target</TT> (string)
1083 <DT><STRONG>Description:</STRONG></DT>
1084 <DD><A NAME="1467"></A>
1085 The name of an object (workspace, frame) that should manage
1086 windows of this type. See also <TT>new_group</TT>.
1094 <DT><STRONG>Winprop:</STRONG></DT>
1095 <DD><TT>transient_mode</TT> (string)
1098 <DT><STRONG>Description:</STRONG></DT>
1099 <DD><A NAME="1468"></A>
1100 `<TT>normal</TT>': No change in behaviour. `<TT>current</TT>':
1101 The window should be thought of as a transient for the current
1102 active client window (if any) even if it is not marked as a
1103 transient by the application. `<TT>off</TT>': The window should
1104 be handled as a normal window even if it is marked as a
1105 transient by the application.
1113 <DT><STRONG>Winprop:</STRONG></DT>
1114 <DD><TT>transparent</TT> (boolean)
1117 <DT><STRONG>Description:</STRONG></DT>
1118 <DD><A NAME="1469"></A>
1119 Should frames be made transparent when this window is selected?
1127 <H3><A NAME="SECTION00451000000000000000">
1128 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Sizehint winprops</A>
1132 Additionally, the winprops
1133 <TT>max_size</TT><A NAME="1470"></A>,
1134 <TT>min_size</TT><A NAME="1471"></A>,
1135 <TT>aspect</TT><A NAME="1472"></A>,
1136 <TT>resizeinc</TT><A NAME="1473"></A>,
1138 <TT>ignore_max_size</TT><A NAME="1474"></A>,
1139 <TT>ignore_min_size</TT><A NAME="1475"></A>,
1140 <TT>ignore_aspect</TT><A NAME="1476"></A>,
1141 <TT>ignore_resizeinc</TT><A NAME="1477"></A>,
1142 may be used to override application-supplied size hints. The four
1143 first ones are tables with the fields <TT>w</TT> and <TT>h</TT>, indicating
1144 the width and height size hints in pixels, and the latter ignore
1145 winprop is a boolean.
1148 Finally, the boolean
1149 <TT>userpos</TT><A NAME="1478"></A> option may be used to
1150 override the <TT>USPosition</TT> flag of the size hints. Normally,
1151 when this flag is set, Ion tries to respect the supplied window
1152 position more than when it is not set. Obviously, this makes sense
1153 only for floating windows.
1157 <H3><A NAME="SECTION00452000000000000000"></A>
1158 <A NAME="sec:classesrolesinstances"></A>
1160 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Classes, roles and instances
1164 The identification information supported are
1165 <TT>class</TT><A NAME="1479"></A>,
1166 <TT>role</TT><A NAME="1480"></A>,
1167 <TT>instance</TT><A NAME="1481"></A>,
1168 <TT>name</TT><A NAME="1482"></A>,
1169 <TT>is_transient</TT><A NAME="1483"></A>, and
1170 <TT>is_dockapp</TT><A NAME="1484"></A>.
1171 It is not necessary to specify all of these fields.
1172 The first three are strings, and must exactly match the
1173 corresponding information obtained from the window's properties.
1174 The <TT>name</TT> field is a Lua-style regular expression matched against
1175 the window's title. The <TT>is_transient</TT> field is a boolean that can
1176 be used to include or exclude transients only, while the <TT>is_dockapp</TT>
1177 field is set by Ion for the dock windows of Window Maker dockapp protocol
1178 dockapps. Usually this is the only information available for these
1179 <SPAN CLASS="textit">icon</SPAN> windows.
1182 Ion looks for a matching winprop in the order listed by the following
1183 table. An 'E' indicates that the field must be set in the winprop
1184 and it must match the window's corresponding property exactly or, in
1185 case of <TT>name</TT>, the regular expression must match the window
1186 title. An asterisk '*' indicates that a winprop where the field is
1187 not specified (or is itself an asterisk in case of the first three
1191 <DIV ALIGN="CENTER">
1192 <TABLE CELLPADDING=3 BORDER="1">
1193 <TR><TD ALIGN="LEFT"><TT>class</TT></TD>
1194 <TD ALIGN="LEFT"><TT>role</TT></TD>
1195 <TD ALIGN="LEFT"><TT>instance</TT></TD>
1196 <TD ALIGN="LEFT">other</TD>
1198 <TR><TD ALIGN="LEFT">E</TD>
1199 <TD ALIGN="LEFT">E</TD>
1200 <TD ALIGN="LEFT">E</TD>
1201 <TD ALIGN="LEFT">E</TD>
1203 <TR><TD ALIGN="LEFT">E</TD>
1204 <TD ALIGN="LEFT">E</TD>
1205 <TD ALIGN="LEFT">E</TD>
1206 <TD ALIGN="LEFT">*</TD>
1208 <TR><TD ALIGN="LEFT">E</TD>
1209 <TD ALIGN="LEFT">E</TD>
1210 <TD ALIGN="LEFT">*</TD>
1211 <TD ALIGN="LEFT">E</TD>
1213 <TR><TD ALIGN="LEFT">E</TD>
1214 <TD ALIGN="LEFT">E</TD>
1215 <TD ALIGN="LEFT">*</TD>
1216 <TD ALIGN="LEFT">*</TD>
1218 <TR><TD ALIGN="LEFT">E</TD>
1219 <TD ALIGN="LEFT">*</TD>
1220 <TD ALIGN="LEFT">E</TD>
1221 <TD ALIGN="LEFT">E</TD>
1223 <TR><TD ALIGN="LEFT">E</TD>
1224 <TD ALIGN="LEFT">*</TD>
1225 <TD ALIGN="LEFT">E</TD>
1226 <TD ALIGN="LEFT">*</TD>
1228 <TR><TD ALIGN="LEFT">E</TD>
1229 <TD ALIGN="LEFT">*</TD>
1230 <TD ALIGN="LEFT">*</TD>
1231 <TD ALIGN="LEFT">E</TD>
1233 <TR><TD ALIGN="LEFT"> </TD>
1234 <TD ALIGN="LEFT"> </TD>
1235 <TD ALIGN="LEFT"> </TD>
1236 <TD ALIGN="LEFT">etc.</TD>
1242 If there are multiple matching winprops with the same
1243 <TT>class</TT>, <TT>role</TT> and <TT>instance</TT>, but other information
1244 different, the most recently defined one is used.
1248 <H3><A NAME="SECTION00453000000000000000">
1249 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Finding window identification</A>
1253 The 'Window info' context menu entry (<SPAN CLASS="textbf">Mod1+M</SPAN> or <SPAN CLASS="textbf">Button3</SPAN> on a tab)
1254 can be used to list the identification information required to set winprops
1255 for a window and all the transient windows managed within it.
1259 Another way to get the identification information is to use <TT>xprop</TT>.
1260 Simply run To get class and instance, simply run <TT>xprop WM_CLASS</TT>
1261 and click on the particular window of interest. The class is the latter of
1262 the strings while the instance is the former. To get the role - few
1263 windows have this property - use the command <TT>xprop WM_ROLE</TT>.
1264 This method, however, will not work on transients.
1268 So-called ``transient windows'' are usually short-lived dialogs (although
1269 some programs abuse this property) that have a parent window that they are
1270 ``transient for''. On tiled workspaces Ion displays these windows
1271 simultaneously with the parent window at the bottom of the same frame.
1272 Unfortunately <TT>xprop</TT> is stupid and can't cope with this situation,
1273 returning the parent window's properties when the transient is clicked on.
1274 For this reason you'll have to do a little extra work to get the properties
1275 for that window.<A NAME="tex2html9"
1276 HREF="#foot1486"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A>
1278 Finally, it should be mentioned that too many authors these days
1279 ``forget'' to set this vital identification to anything meaningful:
1280 everything except name is the same for all of the program's
1281 windows, for example. Some other programs only set this information
1282 after the window has been mapped, i.e. the window manager has been
1283 told to start managing it, which is obviously too late.
1284 Gtk applications in particular are often guilty on both counts.
1288 <H3><A NAME="SECTION00454000000000000000">
1289 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Some common examples</A>
1294 <H4><A NAME="SECTION00454100000000000000">
1295 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Acrobat Reader</A>
1299 The following is absolutely necessary for Acrobat reader:
1305 instance = "documentShell",
1312 <H4><A NAME="SECTION00454200000000000000">
1313 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Forcing newly created windows in named frames</A>
1317 The following winprop should place xterm started with command-line parameter
1318 <TT>-name sysmon</TT> and running a system monitoring program in a
1323 instance = "sysmon",
1324 target = "sysmonframe",
1329 For this example to work, we have to somehow create a frame named
1330 `<TT>sysmonframe</TT>'. One way to do this is to make the following
1331 call in the <SPAN CLASS="textbf">Mod1+F3</SPAN> Lua code query:
1335 mod_query.query_renameframe(_)
1339 Recall that <TT>_</TT> points to the multiplexer (frame or screen) in which
1340 the query was opened. Running this code should open a new query prefilled
1341 with the current name of the frame. In our example we would change the
1342 name to `<TT>sysmonframe</TT>', but we could just as well have used the
1343 default name formed from the frame's class name and an instance number.
1347 <H2><A NAME="SECTION00460000000000000000"></A>
1348 <A NAME="sec:statusbar"></A>
1350 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> The statusbar
1354 The <SPAN CLASS="textit">mod_statusbar</SPAN> module provides a statusbar that adapts to
1355 layouts of tilings, using only the minimal space needed. Ion only
1356 supports one adaptive ``status display'' object per screen, so this
1357 statusbar is mutually exclusive with the embedded mode of <SPAN CLASS="textit">mod_dock</SPAN>
1361 The statusbar is configured in <SPAN CLASS="textit">cfg_statusbar.lua</SPAN>. Typically,
1362 the configuration consists of two steps: creating a statusbar with
1363 <A HREF="node7.html#fn:mod_statusbar.create"><TT>mod_statusbar.create</TT></A>, and then launching the separate
1364 <TT>ion-statusd</TT> status daemon process with
1365 <A HREF="node7.html#fn:mod_statusbar.launch_statusd"><TT>mod_statusbar.launch_statusd</TT></A>. This latter phase is done
1366 automatically, if it was not done by the configuration file, but
1367 the configuration file may pass extra parameters to <TT>ion-statusd</TT>
1368 monitors. (See Section <A HREF="node6.html#sec:statusd">5.4</A> for more information on
1369 writing <TT>ion-statusd</TT> monitors.)
1372 A typical <SPAN CLASS="textit">cfg_statusbar.lua</SPAN> configuration might look as follows:
1376 -- Create a statusbar
1377 mod_statusbar.create{
1378 screen = 0, -- First screen,
1379 pos = 'bl', -- bottom left corner
1380 systray = true, -- Swallow systray windows
1383 template = "[ %date || load:% %>load || mail:% %>mail_new/%>mail_total ]"
1384 .. " %filler%systray",
1387 -- Launch ion-statusd.
1388 mod_statusbar.launch_statusd{
1391 -- ISO-8601 date format with additional abbreviated day name
1392 date_format='%a %Y-%m-%d %H:%M',
1399 <H3><A NAME="SECTION00461000000000000000">
1400 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">1</SPAN> The template</A>
1404 The template specifies what is shown on the statusbar; for information
1405 on the other options to <A HREF="node7.html#fn:mod_statusbar.create"><TT>mod_statusbar.create</TT></A>, see the reference.
1406 Strings of the form `<TT>%spec</TT>' tokens specially interpreter by
1407 the statusbar; the rest appears verbatim. The <TT>spec</TT> typically
1408 consists of the name of the value/meter to display (beginning with a latin
1409 alphabet), but may be preceded by an alignment specifier and a number
1410 specifying the minimum width. The alignment specifiers are: `<TT>></TT>'
1411 for right, `<TT><</TT>' for left, and `<TT>|</TT>' for centring. Additionally,
1412 space following `<TT>%</TT>' (that is, the string `<TT>% </TT>'), adds
1413 ``stretchable space'' at that point. The special string `<TT>%filler</TT>'
1414 may be used to flush the rest of the template to the right end of
1418 The stretchable space works as follows: <SPAN CLASS="textit">mod_statusbar</SPAN> remembers
1419 the widest string (in terms of graphical presentation) that it has
1420 seen for each meter, unless the width has been otherwise constrained.
1421 If there is stretchable space in the template, it tries to make the
1422 meter always take this much space, by stretching any space found in
1423 the direction indicated by the alignment specifier: the opposite
1424 direction for left or right alignment, and both for centring.
1428 <H3><A NAME="SECTION00462000000000000000">
1429 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">2</SPAN> The systray</A>
1433 The special `<TT>%systray</TT>' and `<TT>%systray_*</TT>'
1434 (`<TT>*</TT>' varying) monitors indicate where to place system tray
1435 windows. There may be multiple of these. KDE-protocol system tray
1436 icons are placed in `<TT>%systray</TT>' automatically, unless disabled
1437 with the <TT>systray</TT> option. Otherwise the <TT>statusbar</TT> winprop may
1438 be used to place any window in any particular `<TT>%systray_*</TT>'.
1442 <H3><A NAME="SECTION00463000000000000000">
1443 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN> Monitors</A>
1447 The part before the first
1448 underscore of each monitor name, describes the script/plugin/module
1449 that provides the meter, and any configuration should be passed
1450 in the a corresponding sub-table <A HREF="node7.html#fn:mod_statusbar.launch_statusd"><TT>mod_statusbar.launch_statusd</TT></A>.
1451 Ion comes with date, load and mail (for plain old mbox)
1452 <TT>ion-statusd</TT> monitor scripts. More may be obtained from
1453 the scripts repository [<A
1454 HREF="node12.html#scripts">1</A>]. These included scripts
1455 provide the following monitors and their options
1459 <H4><A NAME="SECTION00463100000000000000">
1460 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Date</A>
1464 Options: <TT>date_format</TT>: The date format in as seen above,
1465 in the usual <TT>strftime</TT> format. <TT>formats</TT>: table of
1466 formats for additional date monitors, the key being the name
1467 of the monitor (without the `<TT>date_</TT>' prefix).
1470 Monitors: `<TT>date</TT>' and other user-specified ones with the
1471 `<TT>date_</TT>' prefix.
1475 <H4><A NAME="SECTION00463200000000000000">
1476 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Load</A>
1480 Options: <TT>update_interval</TT>: Update interval in milliseconds
1481 (default 10s). <TT>important_threshold</TT>: Threshold above which
1482 the load is marked as important (default 1.5), so that the
1483 drawing engine may be suitably hinted. <TT>critical_threshold</TT>:
1484 Threshold above which the load is marked as critical (default 4.0).
1487 Monitors: `<TT>load</TT>' (for all three values),
1488 `<TT>load_1min</TT>', `<TT>load_5min</TT>' and `<TT>load_15min</TT>'.
1492 <H4><A NAME="SECTION00463300000000000000">
1493 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Mail</A>
1497 Options: <TT>update_interval</TT>: Update interval in milliseconds
1498 (default 1min). <TT>mbox</TT>: mbox-format mailbox location
1499 (default <code>$MAIL</code>).
1500 <TT>files</TT>: list of additional mailboxes, the key giving the
1501 name of the monitor.
1504 Monitors: `<TT>mail_new</TT>', `<TT>mail_unread</TT>',
1505 `<TT>mail_total</TT>', and corresponding
1506 `<TT>mail_*_new</TT>', `<TT>mail_*_unread</TT>', and `<TT>mail_*_total</TT>'
1507 for the additional mailboxes (`<TT>*</TT>' varying).
1512 <BR><HR><H4>Footnotes</H4>
1514 <DT><A NAME="foot878">...keysymdef.h</A><A
1515 HREF="node4.html#tex2html7"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
1516 <DD>This file can usually be found in the directory
1517 <SPAN CLASS="textit">/usr/X11R6/include/X11/</SPAN>.
1520 <DT><A NAME="foot857">... such</A><A
1521 HREF="node4.html#tex2html8"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A></DT>
1522 <DD>Completely useless keys that should be
1523 gotten rid of in the author's opinion.
1526 <DT><A NAME="foot1486">... window.</A><A
1527 HREF="node4.html#tex2html9"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A></DT>
1528 <DD>There's a patch to <TT>xprop</TT> to
1529 fix this, but nothing seems to be happening with respect to including it in
1534 <DIV CLASS="navigation"><HR>
1535 <!--Navigation Panel-->
1536 <A NAME="tex2html287"
1538 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
1539 <A NAME="tex2html281"
1540 HREF="ionconf.html">
1541 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
1542 <A NAME="tex2html275"
1544 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
1545 <A NAME="tex2html283"
1547 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
1548 <A NAME="tex2html285"
1550 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
1552 <B> Next:</B> <A NAME="tex2html288"
1553 HREF="node5.html">4. Graphical styles</A>
1554 <B> Up:</B> <A NAME="tex2html282"
1555 HREF="ionconf.html">Configuring and extending Ion3</A>
1556 <B> Previous:</B> <A NAME="tex2html276"
1557 HREF="node3.html">2. Preliminaries: Key concepts</A>
1558 <B> <A NAME="tex2html284"
1559 HREF="node1.html">Contents</A></B>
1560 <B> <A NAME="tex2html286"
1561 HREF="node11.html">Index</A></B> </DIV>
1562 <!--End of Navigation Panel-->