4 The so-called ''winprops''\index{Winprops} can be used to change how
5 specific windows are handled and to set up some kludges to deal with
6 badly behaving applications. They are defined by calling the function
7 \code{defwinprop} with a table containing the properties to set and the
8 necessary information to identify a window. The currently supported
9 winprops are listed below, and the subsequent subsections explain the
10 usual method of identifying windows, and how to obtain this information.
14 %\docode % latex2html kludge
16 %\caption{Supported winprops}
19 \newenvironment{winprop}[2]{
21 % Sigh. (La)TeX is a mess.
25 % @\expandafter\var{#2}}
26 \item[Winprop:] \var{#1} (#2)
34 \begin{winprop}{acrobatic}{boolean}
35 \index{acrobatic@\var{acrobatic}}
36 Set this to \code{true} for Acrobat Reader. It has an annoying
37 habit of trying to manage its dialogs instead of setting them as
38 transients and letting the window manager do its job, causing
39 Ion and acrobat go a window-switching loop when a dialog is
44 \begin{winprop}{float}{boolean}
45 \index{float@\var{float}}
46 Set this to open the window in a floating frame, when
51 \begin{winprop}{fullscreen}{boolean}
52 \index{fullscreen@\var{fullscreen}}
53 Should the window be initially in full screen mode?
57 \begin{winprop}{ignore_cfgrq}{boolean}
58 \index{ignore-cfgrq@\var{ignore_cfgrq}}
59 Should configure requests on the window be ignored?
60 Only has effect on floating windows.
64 \begin{winprop}{ignore_net_active_window}{boolean}
65 \index{ignore-net-active-window@\var{ignore_net_active_window}}
66 Ignore extended WM hints \code{_NET_ACTIVE_WINDOW} request.
70 \begin{winprop}{jumpto}{boolean}
71 \index{jumpto@\var{jumpto}}
72 Should a newly created client window always be made
73 active, even if the allocated frame isn't.
77 \begin{winprop}{new_group}{string}
78 \index{new-group@\var{new_group}}
79 If the region specified by \code{target} winprop does not exist
80 (or that winprop is not set), create a new workspace using the
81 previously stored layout (see \fnref{ioncore.deflayout}) named by
82 this property. After creating the workspace, \code{target} is
83 attempted to be found again. (If that still fails, the newly
84 created workspace is still asked to manage the client window.)
88 \begin{winprop}{oneshot}{boolean}
89 \index{oneshot@\var{oneshot}}
90 Discard this winprop after first use.
94 \begin{winprop}{statusbar}{string}
95 \index{statusbar@\var{statusbar}}
96 Put the window in the statusbar, in the named tray component,
97 (The default tray component is called simply \code{"systray"},
98 and others you give names to in your custom template, always
99 prefixed by \code{"systray_"}.
103 \begin{winprop}{switchto}{boolean}
104 \index{switchto@\var{switchto}}
105 Should a newly mapped client window be switched to within
110 \begin{winprop}{target}{string}
111 \index{target@\var{target}}
112 The name of an object (workspace, frame) that should manage
113 windows of this type. See also \code{new_group}.
117 \begin{winprop}{transient_mode}{string}
118 \index{transient-mode@\var{transient_mode}}
119 \code{"normal"}: No change in behaviour. \code{"current"}:
120 The window should be thought of as a transient for the current
121 active client window (if any) even if it is not marked as a
122 transient by the application. \code{"off"}: The window should
123 be handled as a normal window even if it is marked as a
124 transient by the application.
128 \begin{winprop}{transparent}{boolean}
129 \index{transparent@\var{transparent}}
130 Should frames be made transparent when this window is selected? \\
134 \subsection{Sizehint winprops}
136 Additionally, the winprops
137 \code{max_size}\index{max-size@\var{max_size}},
138 \code{min_size}\index{min-size@\var{min_size}},
139 \code{aspect}\index{aspect@\var{aspect}},
140 \code{resizeinc}\index{aspect@\var{resizeinc}},
142 \code{ignore_max_size}\index{ignore-max-size@\var{ignore_max_size}},
143 \code{ignore_min_size}\index{ignore-min-size@\var{ignore_min_size}},
144 \code{ignore_aspect}\index{ignore-aspect@\var{ignore_aspect}},
145 \code{ignore_resizeinc}\index{ignore-aspect@\var{ignore_resizeinc}},
146 may be used to override application-supplied size hints. The four
147 first ones are tables with the fields \var{w} and \var{h}, indicating
148 the width and height size hints in pixels, and the latter ignore
149 winprop is a boolean.
152 \code{userpos}\index{userpos@\var{userpos}} option may be used to
153 override the \code{USPosition} flag of the size hints. Normally,
154 when this flag is set, Ion tries to respect the supplied window
155 position more than when it is not set. Obviously, this makes sense
156 only for floating windows.
159 \subsection{Classes, roles and instances}
160 \label{sec:classesrolesinstances}
162 The identification information in the winprop specification is usually the
163 \var{class}\index{class@\var{class}!winprop},
164 \var{role}\index{role@\var{role}!winprop},
165 \var{instance}\index{instance@\var{instance}!winprop} and
167 of the window. The \var{name} field is a Lua-style regular expression
168 matched against the window's title and the rest are strings that must
169 exactly match the corresponding window information. It is not necessary
170 to specify all of these fields.
172 Ion looks for a matching winprop in the order listed by the following
173 table. An 'E' indicates that the field must be set in the winprop
174 and it must match the window's corresponding property exactly or, in
175 case of \var{name}, the regular expression must match the window
176 title. An asterisk '*' indicates that a winprop where the field is
177 not specified (or is itself an asterisk in case of the first three
181 \begin{tabular}{llll}
182 \tabhead{\var{class} & \var{role} & \var{instance} & \var{name}}
190 \vdots & \vdots & \vdots & etc. \\
194 If there are multiple winprops with other identification information
195 the same but different \var{name}, the longest match is chosen.
197 \subsection{Finding window identification}
199 The 'Window info' context menu entry (\key{Mod1+M} or \key{Button3} on a tab)
200 can be used to list the identification information required to set winprops
201 for a window and all the transient windows managed within it.
204 Another way to get the identification information is to use \command{xprop}.
205 Simply run To get class and instance, simply run \command{xprop WM_CLASS}
206 and click on the particular window of interest. The class is the latter of
207 the strings while the instance is the former. To get the role -- few
208 windows have this property -- use the command \command{xprop WM_ROLE}.
209 This method, however, will not work on transients.
212 So-called ''transient windows'' are usually short-lived dialogs (although
213 some programs abuse this property) that have a parent window that they are
214 ''transient for''. On tiled workspaces Ion displays these windows
215 simulatenously with the parent window at the bottom of the same frame.
216 Unfortunately \command{xprop} is stupid and can't cope with this situation,
217 returning the parent window's properties when the transient is clicked on.
218 For this reason you'll have to do a little extra work to get the properties
219 for that window.\footnote{There's a patch to \command{xprop} to
220 fix this, but nothing seems to be happening with respect to including it in
223 Finally, it should be mentioned that too many authors these days
224 ''forget'' to set this vital identification to anything meaningful:
225 everything except name is the same for all of the programs's
226 windows, for example.
228 \subsection{Some common examples}
230 \subsubsection{Acrobat Reader}
232 The following is absolutely necessary for Acrobat reader:
237 instance = "documentShell",
242 \subsubsection{Fixing a Mozilla Firebird transient}
244 Mozilla Firebird (0.7) incorrectly does not set the \code{WM_TRANSIENT_FOR}
245 property for the dialog that is used to ask the action to take for a file.
246 It, however, sets the the property point to the main window for the save
247 dialog. This can be annoying and confusing, as the first dialog is not
248 closed before the second is displayed.
250 We'd like the first dialog to be transient to the main window. The closest
251 we can get to that is to consider it transient to the current window (if
252 there's one). Unfortunately Firebird does not set any meaningful classes,
253 instances or roles for the windows, so we'll have to rely on an ugly title
258 class = "MozillaFirebird-bin",
260 transient_mode = "current",
264 \subsubsection{Forcing newly created windows in named frames}
266 The following winprop should place xterm started with command-line parameter
267 \mbox{\code{-name sysmon}} and running a system monitoring program in a
273 target = "sysmonframe",
277 For this example to work, we have to somehow create a frame named
278 \code{sysmonframe}. One way to do this is to make the following
279 call in the \key{Mod1+F3} Lua code query:
282 mod_query.query_renameframe(_)
285 Recall that \code{_} points to the multiplexer (frame or screen) in which
286 the query was opened. Running this code should open a new query prefilled
287 with the current name of the frame. In our example we would change the
288 name to \code{sysmonframe}, but we could just as well have used the
289 default name formed from the frame's class name and an instance number.