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="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 <B> <A NAME="tex2html258"
54 HREF="node1.html">Contents</A></B>
55 <B> <A NAME="tex2html260"
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="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>
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>
87 <LI><A NAME="tex2html273"
88 HREF="node4.html#SECTION00440000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Menus</A>
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>
100 <LI><A NAME="tex2html278"
101 HREF="node4.html#SECTION00450000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Winprops</A>
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>
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>
117 <!--End of Table of Child-Links-->
120 <H1><A NAME="SECTION00400000000000000000"></A>
121 <A NAME="chap:config"></A>
123 <SPAN CLASS="arabic">3</SPAN>. Basic configuration
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.
134 Section <A HREF="#sec:conffiles">3.1</A> 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>.
146 <H2><A NAME="SECTION00410000000000000000"></A>
147 <A NAME="sec:conffiles"></A>
149 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> The configuration files
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="585"></A> or
157 <TT>ETCDIR</TT><A NAME="586"></A> in
158 <SPAN CLASS="textit">system.mk</SPAN><A NAME="587"></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.
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.
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
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>
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>
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>
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>
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>
208 <TD ALIGN="LEFT">Configuration files for different modules.</TD>
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>.
218 <H2><A NAME="SECTION00420000000000000000"></A>
219 <A NAME="sec:walkthrough"></A>
221 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> A walk through <SPAN CLASS="textit">cfg_ion.lua</SPAN>
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
235 The first thing one in the file is to set
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>.
246 Next we do some basic feel configuration:
257 These two will set the delay between button presses in a double click, and
258 the timeout to quit resize mode in milliseconds.
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
276 Next we load the configuration for Ion's core, and some kludges:
280 dopath("cfg_ioncore")
281 dopath("cfg_kludges")
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
293 ioncore.defshortening("[^:]+: (.*)(<[0-9]+>)", "$1$2$|$1$<...$2")
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<3>' to 'barba...<3>'; for
300 details see the function reference entry for <A HREF="node7.html#fn:ioncore.defshortening"><TT>ioncore.defshortening</TT></A>.
303 To actually be able to do something besides display windows in full screen
304 mode, we must next load some modules:
308 dopath("cfg_modules")
309 --dopath("mod_query")
311 --dopath("mod_tiling")
312 --dopath("mod_statusbar")
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.
326 <H2><A NAME="SECTION00430000000000000000"></A>
327 <A NAME="sec:bindings"></A>
329 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Keys and rodents
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.
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:
351 defbindings("WFrame", {
352 -- List of bindings to make goes here.
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>.
370 Currently known ''contexts'' include:
373 <TT>WMPlex.toplevel</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>,
384 <TT>WTiling</TT>, and
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.
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
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.
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>
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
420 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
421 <TR><TD ALIGN="LEFT">Variable</TD>
422 <TD ALIGN="LEFT">Description</TD>
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>
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
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>
443 For example, supposing '<TT>_</TT>' is a WFrame, the following
444 handler should move the active window to the right, if possible:
453 <H3><A NAME="SECTION00432000000000000000">
454 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Guards</A>
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>):
464 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
465 <TR><TD ALIGN="LEFT">Guard</TD>
466 <TD ALIGN="LEFT">Description</TD>
468 <TR><TD ALIGN="LEFT"><TT>"_sub:non-nil"</TT></TD>
469 <TD ALIGN="LEFT">The <TT>_sub</TT> parameter must be set.</TD>
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>
479 <H3><A NAME="SECTION00433000000000000000"></A>
480 <A NAME="sec:binddef"></A>
482 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining the bindings
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
494 <LI><A HREF="#fn:kpress"><TT>kpress</TT></A><TT>(keyspec, handler [, guard])</TT>,
496 <LI><A HREF="#fn:kpress_wait"><TT>kpress_wait</TT></A><TT>(keyspec, handler [, guard])</TT> and
498 <LI><A HREF="#fn:submap"><TT>submap</TT></A><TT>(keyspec, { ... more key bindings ... })</TT>.
504 <LI><A HREF="#fn:mclick"><TT>mclick</TT></A><TT>(buttonspec, handler [, guard])</TT>,
506 <LI><A HREF="#fn:mdblclick"><TT>mdblclick</TT></A><TT>(buttonspec, handler [, guard])</TT>,
508 <LI><A HREF="#fn:mpress"><TT>mpress</TT></A><TT>(buttonspec, handler [, guard])</TT> and
510 <LI><A HREF="#fn:mdrag"><TT>mdrag</TT></A><TT>(buttonspec, handler [, guard])</TT>.
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
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.
533 <H3><A NAME="SECTION00434000000000000000">
534 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Examples</A>
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
542 defbindings("WScreen", {
543 kpress("Mod1+Right", "_:switch_next()"),
544 kpress("Mod1+1", "_:switch_nth(1)"),
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.
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:
558 defbindings("WFrame", {
560 kpress("Right", "_:switch_next()"),
561 kpress("1", "_:switch_nth(1)"),
568 <H3><A NAME="SECTION00435000000000000000">
569 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Key specifications</A>
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="#foot858"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A> without the <TT>XK_</TT> prefix.
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>.
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
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>.
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="865"></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="866"></A>
606 to find out what exactly is bound where.
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
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="867"></A> or
618 <SPAN CLASS="textbf">ScrollLock</SPAN><A NAME="868"></A>
619 by default because such<A NAME="tex2html8"
620 HREF="#foot837"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A> locking keys may otherwise
625 <H3><A NAME="SECTION00436000000000000000">
626 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">6</SPAN> Button specifications</A>
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="869"></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
637 <TT>"border"</TT>, <TT>"tab"</TT>, <TT>"empty_tab"</TT>, <TT>"client"</TT> and
638 <TT>nil</TT> (for the whole frame).
641 For example, the following code binds dragging a tab with the first
642 button pressed to initiate tab drag&drop handling:
646 defbindings("WFrame", {
647 mdrag("Button1@tab", "_:p_tabdrag()"),
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>
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.
671 <H2><A NAME="SECTION00440000000000000000"></A>
672 <A NAME="sec:menus"></A>
674 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Menus
679 <H3><A NAME="SECTION00441000000000000000">
680 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Defining menus</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.
694 Here's an example of the definition of a rather simple menu with a submenu:
698 defmenu("exitmenu", {
699 menuentry("Restart", "ioncore.restart()"),
700 menuentry("Exit", "ioncore.shutdown()"),
703 defmenu("mainmenu", {
704 menuentry("Lock screen", "ioncore.exec('xlock')"),
705 menuentry("Help", "mod_query.query_man(_)"),
706 submenu("Exit", "exitmenu"),
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.
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.)
723 <H3><A NAME="SECTION00442000000000000000">
724 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Special menus</A>
728 The menu module predefines the following special menus. These can be used
729 just like the menus defined as above.
732 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
733 <TR><TD ALIGN="LEFT">Menu name</TD>
734 <TD ALIGN="LEFT">Description</TD>
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>
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>
742 <TR><TD ALIGN="LEFT"><TT>stylemenu</TT></TD>
743 <TD ALIGN="LEFT">List of available <SPAN CLASS="textit">look_*.lua</SPAN> style files. Activating an entry
744 loads that style and ask to save the selection.</TD>
746 <TR><TD ALIGN="LEFT"><TT>ctxmenu</TT></TD>
747 <TD ALIGN="LEFT">Context menu for given object.</TD>
753 <H3><A NAME="SECTION00443000000000000000">
754 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Defining context menus</A>
758 The ''ctxmenu'' is a special menu that is assembled from a defined context
759 menu for the object for which the menu was opened for, but also includes
760 the context menus for the manager objects as submenus.
763 Context menus for a given region class are defined with the
764 <A HREF="#fn:mod_menu.defctxmenu"><TT>defctxmenu</TT></A> function. This is other ways similar to
765 <A HREF="#fn:mod_menu.defmenu"><TT>defmenu</TT></A>, but the first argument instead being the name
766 of the menu, the name of the region class to define context menu for.
767 For example, here's part of the stock WFrame context menu
772 defctxmenu("WFrame", {
773 menuentry("Close", "WRegion.rqclose_propagate(_, _sub)"),
774 menuentry("Kill", "WClientWin.kill(_sub)", "_sub:WClientWin"),
779 Some of the same ''modes'' as were available for some bindings
780 may also be used: <TT>WFrame.tiled</TT>, <TT>WFrame.floating</TT>,
781 and <TT>WFrame.transient</TT>.
785 <H3><A NAME="SECTION00444000000000000000"></A>
786 <A NAME="sec:menudisp"></A>
788 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">4</SPAN> Displaying menus
792 The following functions may be used to display menus from binding
793 handlers (and elsewhere):
796 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
797 <TR><TD ALIGN="LEFT">Function</TD>
798 <TD ALIGN="LEFT">Description</TD>
800 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.menu"><TT>mod_menu.menu</TT></A></TD>
801 <TD ALIGN="LEFT">Keyboard (or mouse) operated menus that open in the bottom-left corner
802 of a screen or frame.</TD>
804 <TR><TD ALIGN="LEFT"><A HREF="#fn:mod_menu.bigmenu"><TT>mod_menu.bigmenu</TT></A></TD>
805 <TD ALIGN="LEFT">Same as previous, but uses another graphical style.</TD>
807 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.pmenu"><TT>mod_menu.pmenu</TT></A></TD>
808 <TD ALIGN="LEFT">Mouse-operated drop-down menus. This function can only be called from a
809 mouse press or drag handler.</TD>
811 <TR><TD ALIGN="LEFT"><A HREF="node7.html#fn:mod_menu.grabmenu"><TT>mod_menu.grabmenu</TT></A></TD>
812 <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
813 and is scrolled with a given key until all modifiers have been released,
814 after which the selected entry is activated. This function is meant to
815 be used for implementing, for example, Win***s-style <SPAN CLASS="textbf">Alt-Tab</SPAN>
816 handling.<A NAME="tex2html9"
817 HREF="#foot1173"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A></TD>
822 The <A HREF="node7.html#fn:mod_menu.grabmenu"><TT>grabmenu</TT></A> function takes the extra key parameter, but
823 aside from that each of these functions takes three arguments, which when
824 called from a binding handler, should be the parameters to the handler, and
825 the name of the menu. For example, the following snippet of of code binds
826 the both ways to open a context menu for a frame:
830 defbindings("WFrame", {
831 kpress(MOD1.."M", "mod_menu.menu(_, _sub, 'ctxmenu')"),
832 mpress("Button3", "mod_menu.pmenu(_, _sub, 'ctxmenu')"),
838 <H2><A NAME="SECTION00450000000000000000"></A>
839 <A NAME="sec:winprops"></A>
841 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN> Winprops
845 The so-called ''winprops''<A NAME="1266"></A> can be used to change how
846 specific windows are handled and to set up some kludges to deal with
847 badly behaving applications. They are defined by calling the function
848 <TT>defwinprop</TT> with a table containing the properties to set and the
849 necessary information to identify a window. The currently supported
850 winprops are listed below, and the subsequent subsections explain the
851 usual method of identifying windows, and how to obtain this information.
858 <DT><STRONG>Winprop:</STRONG></DT>
859 <DD><TT>acrobatic</TT> (boolean)
862 <DT><STRONG>Description:</STRONG></DT>
863 <DD><A NAME="1410"></A>
864 Set this to <TT>true</TT> for Acrobat Reader. It has an annoying
865 habit of trying to manage its dialogs instead of setting them as
866 transients and letting the window manager do its job, causing
867 Ion and acrobat go a window-switching loop when a dialog is
876 <DT><STRONG>Winprop:</STRONG></DT>
877 <DD><TT>aspect</TT> (table)
880 <DT><STRONG>Description:</STRONG></DT>
881 <DD><A NAME="1411"></A>
882 The table should contain the entries <TT>w</TT> and <TT>h</TT> that
883 override application-supplied aspect ratio hint.
891 <DT><STRONG>Winprop:</STRONG></DT>
892 <DD><TT>float</TT> (boolean)
895 <DT><STRONG>Description:</STRONG></DT>
896 <DD><A NAME="1412"></A>
897 Set this to open the window in a floating frame, when
906 <DT><STRONG>Winprop:</STRONG></DT>
907 <DD><TT>fullscreen</TT> (boolean)
910 <DT><STRONG>Description:</STRONG></DT>
911 <DD><A NAME="1413"></A>
912 Should the window be initially in full screen mode?
920 <DT><STRONG>Winprop:</STRONG></DT>
921 <DD><TT>ignore_cfgrq</TT> (boolean)
924 <DT><STRONG>Description:</STRONG></DT>
925 <DD><A NAME="1414"></A>
926 Should configure requests on the window be ignored?
927 Only has effect on floating windows.
935 <DT><STRONG>Winprop:</STRONG></DT>
936 <DD><TT>ignore_net_active_window</TT> (boolean)
939 <DT><STRONG>Description:</STRONG></DT>
940 <DD><A NAME="1415"></A>
941 Ignore extended WM hints <TT>_NET_ACTIVE_WINDOW</TT> request.
949 <DT><STRONG>Winprop:</STRONG></DT>
950 <DD><TT>ignore_resizeinc</TT> (boolean)
953 <DT><STRONG>Description:</STRONG></DT>
954 <DD><A NAME="1416"></A>
955 Should application supplied size increments be ignored?
963 <DT><STRONG>Winprop:</STRONG></DT>
964 <DD><TT>jumpto</TT> (boolean)
967 <DT><STRONG>Description:</STRONG></DT>
968 <DD><A NAME="1417"></A>
969 Should a newly created client window always be made
970 active, even if the allocated frame isn't.
978 <DT><STRONG>Winprop:</STRONG></DT>
979 <DD><TT>max_size</TT> (table)
982 <DT><STRONG>Description:</STRONG></DT>
983 <DD><A NAME="1418"></A>
984 The table should contain the entries <TT>w</TT> and <TT>h</TT> that
985 override application-supplied maximum size hint.
993 <DT><STRONG>Winprop:</STRONG></DT>
994 <DD><TT>min_size</TT> (table)
997 <DT><STRONG>Description:</STRONG></DT>
998 <DD><A NAME="1419"></A>
999 Similar to <TT>max_size</TT> but for the minimum size hint.
1007 <DT><STRONG>Winprop:</STRONG></DT>
1008 <DD><TT>oneshot</TT> (boolean)
1011 <DT><STRONG>Description:</STRONG></DT>
1012 <DD><A NAME="1420"></A>
1013 Discard this winprop after first use.
1021 <DT><STRONG>Winprop:</STRONG></DT>
1022 <DD><TT>switchto</TT> (boolean)
1025 <DT><STRONG>Description:</STRONG></DT>
1026 <DD><A NAME="1421"></A>
1027 Should a newly mapped client window be switched to within
1036 <DT><STRONG>Winprop:</STRONG></DT>
1037 <DD><TT>target</TT> (string)
1040 <DT><STRONG>Description:</STRONG></DT>
1041 <DD><A NAME="1422"></A>
1042 The name of an object (workspace, frame) that should manage
1043 windows of this type.
1051 <DT><STRONG>Winprop:</STRONG></DT>
1052 <DD><TT>transient_mode</TT> (string)
1055 <DT><STRONG>Description:</STRONG></DT>
1056 <DD><A NAME="1423"></A>
1057 "normal": No change in behaviour. "current": The window
1058 should be thought of as a transient for the current active
1059 client window (if any) even if it is not marked as a
1060 transient by the application. "off": The window should be
1061 handled as a normal window even if it is marked as a
1062 transient by the application.
1070 <DT><STRONG>Winprop:</STRONG></DT>
1071 <DD><TT>transients_at_top</TT> (boolean)
1074 <DT><STRONG>Description:</STRONG></DT>
1075 <DD><A NAME="1424"></A>
1076 When transients are managed by the client window itself (as it
1077 is the case on tiled workspaces), should the transients be
1078 placed at the top of the window instead of bottom?
1086 <DT><STRONG>Winprop:</STRONG></DT>
1087 <DD><TT>transparent</TT> (boolean)
1090 <DT><STRONG>Description:</STRONG></DT>
1091 <DD><A NAME="1425"></A>
1092 Should frames be made transparent when this window is selected?
1100 <H3><A NAME="SECTION00451000000000000000"></A>
1101 <A NAME="sec:classesrolesinstances"></A>
1103 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Classes, roles and instances
1107 The identification information in the winprop specification is usually the
1108 <TT>class</TT><A NAME="1426"></A>,
1109 <TT>role</TT><A NAME="1427"></A>,
1110 <TT>instance</TT><A NAME="1428"></A> and
1112 of the window. The <TT>name</TT> field is a Lua-style regular expression
1113 matched against the window's title and the rest are strings that must
1114 exactly match the corresponding window information. It is not necessary
1115 to specify all of these fields.
1118 Ion looks for a matching winprop in the order listed by the following
1119 table. An 'E' indicates that the field must be set in the winprop
1120 and it must match the window's corresponding property exactly or, in
1121 case of <TT>name</TT>, the regular expression must match the window
1122 title. An asterisk '*' indicates that a winprop where the field is
1123 not specified (or is itself an asterisk in case of the first three
1127 <DIV ALIGN="CENTER">
1128 <TABLE CELLPADDING=3 BORDER="1">
1129 <TR><TD ALIGN="LEFT"><TT>class</TT></TD>
1130 <TD ALIGN="LEFT"><TT>role</TT></TD>
1131 <TD ALIGN="LEFT"><TT>instance</TT></TD>
1132 <TD ALIGN="LEFT"><TT>name</TT></TD>
1134 <TR><TD ALIGN="LEFT">E</TD>
1135 <TD ALIGN="LEFT">E</TD>
1136 <TD ALIGN="LEFT">E</TD>
1137 <TD ALIGN="LEFT">E</TD>
1139 <TR><TD ALIGN="LEFT">E</TD>
1140 <TD ALIGN="LEFT">E</TD>
1141 <TD ALIGN="LEFT">E</TD>
1142 <TD ALIGN="LEFT">*</TD>
1144 <TR><TD ALIGN="LEFT">E</TD>
1145 <TD ALIGN="LEFT">E</TD>
1146 <TD ALIGN="LEFT">*</TD>
1147 <TD ALIGN="LEFT">E</TD>
1149 <TR><TD ALIGN="LEFT">E</TD>
1150 <TD ALIGN="LEFT">E</TD>
1151 <TD ALIGN="LEFT">*</TD>
1152 <TD ALIGN="LEFT">*</TD>
1154 <TR><TD ALIGN="LEFT">E</TD>
1155 <TD ALIGN="LEFT">*</TD>
1156 <TD ALIGN="LEFT">E</TD>
1157 <TD ALIGN="LEFT">E</TD>
1159 <TR><TD ALIGN="LEFT">E</TD>
1160 <TD ALIGN="LEFT">*</TD>
1161 <TD ALIGN="LEFT">E</TD>
1162 <TD ALIGN="LEFT">*</TD>
1164 <TR><TD ALIGN="LEFT">E</TD>
1165 <TD ALIGN="LEFT">*</TD>
1166 <TD ALIGN="LEFT">*</TD>
1167 <TD ALIGN="LEFT">E</TD>
1169 <TR><TD ALIGN="LEFT"> </TD>
1170 <TD ALIGN="LEFT"> </TD>
1171 <TD ALIGN="LEFT"> </TD>
1172 <TD ALIGN="LEFT">etc.</TD>
1178 If there are multiple winprops with other identification information
1179 the same but different <TT>name</TT>, the longest match is chosen.
1183 <H3><A NAME="SECTION00452000000000000000">
1184 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Finding window identification</A>
1188 The 'Window info' context menu entry (<SPAN CLASS="textbf">Mod1+M</SPAN> or <SPAN CLASS="textbf">Button3</SPAN> on a tab)
1189 can be used to list the identification information required to set winprops
1190 for a window and all the transient windows managed within it.
1194 Another way to get the identification information is to use <TT>xprop</TT>.
1195 Simply run To get class and instance, simply run <TT>xprop WM_CLASS</TT>
1196 and click on the particular window of interest. The class is the latter of
1197 the strings while the instance is the former. To get the role - few
1198 windows have this property - use the command <TT>xprop WM_ROLE</TT>.
1199 This method, however, will not work on transients.
1203 So-called ''transient windows'' are usually short-lived dialogs (although
1204 some programs abuse this property) that have a parent window that they are
1205 ''transient for''. On tiled workspaces Ion displays these windows
1206 simulatenously with the parent window at the bottom of the same frame.
1207 Unfortunately <TT>xprop</TT> is stupid and can't cope with this situation,
1208 returning the parent window's properties when the transient is clicked on.
1209 For this reason you'll have to do a little extra work to get the properties
1210 for that window.<A NAME="tex2html11"
1211 HREF="#foot1430"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN></SUP></A>
1213 Finally, it should be mentioned that too many authors these days
1214 ''forget'' to set this vital identification to anything meaningful:
1215 everything except name is the same for all of the programs's
1216 windows, for example.
1220 <H3><A NAME="SECTION00453000000000000000">
1221 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Some common examples</A>
1226 <H4><A NAME="SECTION00453100000000000000">
1227 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Acrobat Reader</A>
1231 The following is absolutely necessary for Acrobat reader:
1237 instance = "documentShell",
1244 <H4><A NAME="SECTION00453200000000000000">
1245 <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>
1249 Mozilla Firebird (0.7) incorrectly does not set the <TT>WM_TRANSIENT_FOR</TT>
1250 property for the dialog that is used to ask the action to take for a file.
1251 It, however, sets the the property point to the main window for the save
1252 dialog. This can be annoying and confusing, as the first dialog is not
1253 closed before the second is displayed.
1256 We'd like the first dialog to be transient to the main window. The closest
1257 we can get to that is to consider it transient to the current window (if
1258 there's one). Unfortunately Firebird does not set any meaningful classes,
1259 instances or roles for the windows, so we'll have to rely on an ugly title
1265 class = "MozillaFirebird-bin",
1266 name = "Opening .*",
1267 transient_mode = "current",
1273 <H4><A NAME="SECTION00453300000000000000">
1274 <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>
1278 The following winprop should place xterm started with command-line parameter
1279 <TT>-name sysmon</TT> and running a system monitoring program in a
1284 instance = "sysmon",
1285 target = "sysmonframe",
1290 For this example to work, we have to somehow create a frame named
1291 <TT>sysmonframe</TT>. One way to do this is to make the following
1292 call in the <SPAN CLASS="textbf">Mod1+F3</SPAN> Lua code query:
1296 mod_query.query_renameframe(_)
1300 Recall that <TT>_</TT> points to the multiplexer (frame or screen) in which
1301 the query was opened. Running this code should open a new query prefilled
1302 with the current name of the frame. In our example we would change the
1303 name to <TT>sysmonframe</TT>, but we could just as well have used the
1304 default name formed from the frame's class name and an instance number.
1309 <BR><HR><H4>Footnotes</H4>
1311 <DT><A NAME="foot858">...keysymdef.h</A><A
1312 HREF="node4.html#tex2html7"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
1313 <DD>This file can usually be found in the directory
1314 <SPAN CLASS="textit">/usr/X11R6/include/X11/</SPAN>.
1317 <DT><A NAME="foot837">... such</A><A
1318 HREF="node4.html#tex2html8"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A></DT>
1319 <DD>Completely useless keys that should be
1320 gotten rid of in the author's opinion.
1323 <DT><A NAME="foot1173">... handling.</A><A
1324 HREF="node4.html#tex2html9"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A></DT>
1325 <DD>See the <SPAN CLASS="textit">wcirculate.lua</SPAN> script in the Ion
1326 scripts repository <TT><A NAME="tex2html10"
1327 HREF="http://iki.fi/tuomov/repos/ion-scripts-3/">http://iki.fi/tuomov/repos/ion-scripts-3/</A></TT>.
1330 <DT><A NAME="foot1430">... window.</A><A
1331 HREF="node4.html#tex2html11"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN></SUP></A></DT>
1332 <DD>There's a patch to <TT>xprop</TT> to
1333 fix this, but nothing seems to be happening with respect to including it in
1338 <DIV CLASS="navigation"><HR>
1339 <!--Navigation Panel-->
1340 <A NAME="tex2html261"
1342 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
1343 <A NAME="tex2html255"
1344 HREF="ionconf.html">
1345 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
1346 <A NAME="tex2html249"
1348 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
1349 <A NAME="tex2html257"
1351 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
1352 <A NAME="tex2html259"
1354 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
1356 <B> Next:</B> <A NAME="tex2html262"
1357 HREF="node5.html">4. Graphical styles</A>
1358 <B> Up:</B> <A NAME="tex2html256"
1359 HREF="ionconf.html">Configuring and extending Ion3</A>
1360 <B> Previous:</B> <A NAME="tex2html250"
1361 HREF="node3.html">2. Preliminaries: Key concepts</A>
1362 <B> <A NAME="tex2html258"
1363 HREF="node1.html">Contents</A></B>
1364 <B> <A NAME="tex2html260"
1365 HREF="node11.html">Index</A></B> </DIV>
1366 <!--End of Navigation Panel-->