conf-winprops.tex

   1 \section{Winprops}
   2 \label{sec:winprops}
   3
   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.
  11
  12 %\begin{table}
  13 %\begin{htmlonly}
  14 %\docode % latex2html kludge
  15 %\end{htmlonly}
  16 %\caption{Supported winprops}
  17 %\label{tab:winprops}
  18
  19 \newenvironment{winprop}[2]{
  20   \begin{function}%
  21       % Sigh. (La)TeX is a mess.
  22       %\index{%
  23       %  \ifx\\#1\\%
  24       %  #2\else#1\fi%
  25       %  @\expandafter\var{#2}}
  26       \item[Winprop:] \var{#1} (#2)
  27       \item[Description:]
  28 }
  29 {
  30   \end{function}
  31 }
  32
  33
  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
  40     opened.
  41 \end{winprop}
  42
  43
  44 \begin{winprop}{aspect}{table}
  45     \index{aspect@\var{aspect}}
  46     The table should contain the entries \var{w} and \var{h} that
  47     override application-supplied aspect ratio hint.
  48 \end{winprop}
  49
  50
  51 \begin{winprop}{float}{boolean}
  52     \index{float@\var{float}}
  53     Set this to open the window in a floating frame, when
  54     in a group.
  55 \end{winprop}
  56
  57
  58 \begin{winprop}{fullscreen}{boolean}
  59     \index{fullscreen@\var{fullscreen}}
  60     Should the window be initially in full screen mode?
  61 \end{winprop}
  62
  63
  64 \begin{winprop}{ignore_cfgrq}{boolean}
  65     \index{ignore-cfgrq@\var{ignore_cfgrq}}
  66     Should configure requests on the window be ignored?
  67     Only has effect on floating windows.
  68 \end{winprop}
  69
  70
  71 \begin{winprop}{ignore_net_active_window}{boolean}
  72     \index{ignore-net-active-window@\var{ignore_net_active_window}}
  73     Ignore extended WM hints \code{_NET_ACTIVE_WINDOW} request.
  74 \end{winprop}
  75
  76
  77 \begin{winprop}{ignore_resizeinc}{boolean}
  78     \index{ignore-resizeinc@\var{ignore_resizeinc}}
  79     Should application supplied size increments be ignored?
  80 \end{winprop}
  81
  82
  83 \begin{winprop}{jumpto}{boolean}
  84     \index{jumpto@\var{jumpto}}
  85     Should a newly created client window always be made
  86     active, even if the allocated frame isn't.
  87 \end{winprop}
  88
  89
  90 \begin{winprop}{max_size}{table}
  91     \index{max-size@\var{max_size}}
  92     The table should contain the entries \var{w} and \var{h} that
  93     override application-supplied maximum size hint.
  94 \end{winprop}
  95
  96
  97 \begin{winprop}{min_size}{table}
  98     \index{min-size@\var{min_size}}
  99     Similar to \var{max_size} but for the minimum size hint.
 100 \end{winprop}
 101
 102
 103 \begin{winprop}{oneshot}{boolean}
 104     \index{oneshot@\var{oneshot}}
 105     Discard this winprop after first use.
 106 \end{winprop}
 107
 108
 109 \begin{winprop}{switchto}{boolean}
 110     \index{switchto@\var{switchto}}
 111     Should a newly mapped client window be switched to within
 112     its frame.
 113 \end{winprop}
 114
 115
 116 \begin{winprop}{target}{string}
 117     \index{target@\var{target}}
 118     The name of an object (workspace, frame) that should manage
 119     windows of this type.
 120 \end{winprop}
 121
 122
 123 \begin{winprop}{transient_mode}{string}
 124     \index{transient-mode@\var{transient_mode}}
 125     "normal": No change in behaviour. "current": The window
 126     should be thought of as a transient for the current active
 127     client window (if any) even if it is not marked as a
 128     transient by the application. "off": The window should be
 129     handled as a normal window even if it is marked as a
 130     transient by the application.
 131 \end{winprop}
 132
 133
 134 \begin{winprop}{transients_at_top}{boolean}
 135     \index{transients-at-top@\var{transients_at_top}}
 136     When transients are managed by the client window itself (as it
 137     is the case on tiled workspaces), should the transients be
 138     placed at the top of the window instead of bottom?
 139 \end{winprop}
 140
 141
 142 \begin{winprop}{transparent}{boolean}
 143     \index{transparent@\var{transparent}}
 144     Should frames be made transparent when this window is selected? \\
 145 \end{winprop}
 146
 147
 148
 149 \subsection{Classes, roles and instances}
 150 \label{sec:classesrolesinstances}
 151
 152 The identification information in the winprop specification is usually the
 153 \var{class}\index{class@\var{class}!winprop},
 154 \var{role}\index{role@\var{role}!winprop},
 155 \var{instance}\index{instance@\var{instance}!winprop} and
 156 \var{name}
 157 of the window. The \var{name} field is a Lua-style regular expression
 158 matched against the window's title and the rest are strings that must
 159 exactly match the corresponding window information. It is not necessary
 160 to specify all of these fields.
 161
 162 Ion looks for a matching winprop in the order listed by the following
 163 table. An 'E' indicates that the field must be set in the winprop
 164 and it must match the window's corresponding property exactly or, in
 165 case of \var{name}, the regular expression must match the window
 166 title. An asterisk '*' indicates that a winprop where the field is
 167 not specified (or is itself an asterisk in case of the first three
 168 fields) is tried.
 169
 170 \begin{center}
 171 \begin{tabular}{llll}
 172   \tabhead{\var{class} & \var{role} & \var{instance} & \var{name}}
 173   E            & E          & E              & E \\
 174   E            & E          & E              & * \\
 175   E            & E          & *              & E \\
 176   E            & E          & *              & * \\
 177   E            & *          & E              & E \\
 178   E            & *          & E              & * \\
 179   E            & *          & *              & E \\
 180   \vdots       & \vdots     & \vdots         & etc. \\
 181 \end{tabular}
 182 \end{center}
 183
 184 If there are multiple winprops with other identification information
 185 the same but different \var{name}, the longest match is chosen.
 186
 187 \subsection{Finding window identification}
 188
 189 The 'Window info' context menu entry (\key{Mod1+M} or \key{Button3} on a tab)
 190 can be used to list the identification information required to set winprops
 191 for a window and all the transient windows managed within it.
 192
 193 \index{xprop}
 194 Another way to get the identification information is to use \command{xprop}.
 195 Simply run To get class and instance, simply run \command{xprop WM_CLASS}
 196 and click on the particular window of interest. The class is the latter of
 197 the strings while the instance is the former.  To get the role -- few
 198 windows have this property -- use the command \command{xprop WM_ROLE}.
 199 This method, however, will not work on transients.
 200
 201 \index{transient}
 202 So-called ''transient windows'' are usually short-lived dialogs (although
 203 some programs abuse this property) that have a parent window that they are
 204 ''transient for''. On tiled workspaces Ion displays these windows
 205 simulatenously with the parent window at the bottom of the same frame.
 206 Unfortunately \command{xprop} is stupid and can't cope with this situation,
 207 returning the parent window's properties when the transient is clicked on.
 208 For this reason you'll have to do a little extra work to get the properties
 209 for that window.\footnote{There's a patch to \command{xprop} to
 210 fix this, but nothing seems to be happening with respect to including it in
 211 XFree86.}
 212
 213 Finally, it should be mentioned that too many authors these days
 214 ''forget'' to set this vital identification to anything meaningful:
 215 everything except name is the same for all of the programs's
 216 windows, for example.
 217
 218 \subsection{Some common examples}
 219
 220 \subsubsection{Acrobat Reader}
 221
 222 The following is absolutely necessary for Acrobat reader:
 223
 224 \begin{verbatim}
 225 defwinprop{
 226     class = "AcroRead",
 227     instance = "documentShell",
 228     acrobatic = true,
 229 }
 230 \end{verbatim}
 231
 232 \subsubsection{Fixing a Mozilla Firebird transient}
 233
 234 Mozilla Firebird (0.7) incorrectly does not set the \code{WM_TRANSIENT_FOR}
 235 property for the dialog that is used to ask the action to take for a file.
 236 It, however, sets the the property point to the main window for the save
 237 dialog. This can be annoying and confusing, as the first dialog is not
 238 closed before the second is displayed.
 239
 240 We'd like the first dialog to be transient to the main window. The closest
 241 we can get to that is to consider it transient to the current window (if
 242 there's one). Unfortunately Firebird does not set any meaningful classes,
 243 instances or roles for the windows, so we'll have to rely on an ugly title
 244 match.
 245
 246 \begin{verbatim}
 247 defwinprop{
 248     class = "MozillaFirebird-bin",
 249     name = "Opening .*",
 250     transient_mode = "current",
 251 }
 252 \end{verbatim}
 253
 254 \subsubsection{Forcing newly created windows in named frames}
 255
 256 The following winprop should place xterm started with command-line parameter
 257 \mbox{\code{-name sysmon}} and running a system monitoring program in a
 258 particular frame:
 259 \begin{verbatim}
 260 defwinprop{
 261     class = "XTerm",
 262     instance = "sysmon",
 263     target = "sysmonframe",
 264 }
 265 \end{verbatim}
 266
 267 For this example to work, we have to somehow create a frame named
 268 \code{sysmonframe}. One way to do this is to make the following
 269 call in the \key{Mod1+F3} Lua code query:
 270
 271 \begin{verbatim}
 272 mod_query.query_renameframe(_)
 273 \end{verbatim}
 274
 275 Recall that \code{_} points to the multiplexer (frame or screen) in which
 276 the query was opened. Running this code should open a new query prefilled
 277 with the current name of the frame. In our example we would change the
 278 name to \code{sysmonframe}, but we could just as well have used the
 279 default name formed from the frame's class name and an instance number.