doc/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}{new_group}{string}
 104     \index{new-group@\var{new_group}}
 105     If the region specified by \code{target} winprop does not exist
 106     (or that winprop is not set), create a new workspace using the
 107     previously stored layout (see \fnref{ioncore.deflayout}) named by
 108     this property. After creating the workspace, \code{target} is
 109     attempted to be found again. (If that still fails, the newly
 110     created workspace is still asked to manage the client window.)
 111 \end{winprop}
 112
 113
 114 \begin{winprop}{oneshot}{boolean}
 115     \index{oneshot@\var{oneshot}}
 116     Discard this winprop after first use.
 117 \end{winprop}
 118
 119
 120 \begin{winprop}{statusbar}{string}
 121     \index{statusbar@\var{statusbar}}
 122     Put the window on the statusbar, in the named tray component,
 123     (The default tray component is called simply ``\code{systray}'',
 124     and others you give names to in your custom template, always
 125     prefixed by ``\code{systray_}''.
 126 \end{winprop}
 127
 128
 129 \begin{winprop}{switchto}{boolean}
 130     \index{switchto@\var{switchto}}
 131     Should a newly mapped client window be switched to within
 132     its frame.
 133 \end{winprop}
 134
 135
 136 \begin{winprop}{target}{string}
 137     \index{target@\var{target}}
 138     The name of an object (workspace, frame) that should manage
 139     windows of this type. See also \code{new_group}.
 140 \end{winprop}
 141
 142
 143 \begin{winprop}{transient_mode}{string}
 144     \index{transient-mode@\var{transient_mode}}
 145     "normal": No change in behaviour. "current": The window
 146     should be thought of as a transient for the current active
 147     client window (if any) even if it is not marked as a
 148     transient by the application. "off": The window should be
 149     handled as a normal window even if it is marked as a
 150     transient by the application.
 151 \end{winprop}
 152
 153
 154 \begin{winprop}{transients_at_top}{boolean}
 155     \index{transients-at-top@\var{transients_at_top}}
 156     When transients are managed by the client window itself (as it
 157     is the case on tiled workspaces), should the transients be
 158     placed at the top of the window instead of bottom?
 159 \end{winprop}
 160
 161
 162 \begin{winprop}{transparent}{boolean}
 163     \index{transparent@\var{transparent}}
 164     Should frames be made transparent when this window is selected? \\
 165 \end{winprop}
 166
 167
 168
 169 \subsection{Classes, roles and instances}
 170 \label{sec:classesrolesinstances}
 171
 172 The identification information in the winprop specification is usually the
 173 \var{class}\index{class@\var{class}!winprop},
 174 \var{role}\index{role@\var{role}!winprop},
 175 \var{instance}\index{instance@\var{instance}!winprop} and
 176 \var{name}
 177 of the window. The \var{name} field is a Lua-style regular expression
 178 matched against the window's title and the rest are strings that must
 179 exactly match the corresponding window information. It is not necessary
 180 to specify all of these fields.
 181
 182 Ion looks for a matching winprop in the order listed by the following
 183 table. An 'E' indicates that the field must be set in the winprop
 184 and it must match the window's corresponding property exactly or, in
 185 case of \var{name}, the regular expression must match the window
 186 title. An asterisk '*' indicates that a winprop where the field is
 187 not specified (or is itself an asterisk in case of the first three
 188 fields) is tried.
 189
 190 \begin{center}
 191 \begin{tabular}{llll}
 192   \tabhead{\var{class} & \var{role} & \var{instance} & \var{name}}
 193   E            & E          & E              & E \\
 194   E            & E          & E              & * \\
 195   E            & E          & *              & E \\
 196   E            & E          & *              & * \\
 197   E            & *          & E              & E \\
 198   E            & *          & E              & * \\
 199   E            & *          & *              & E \\
 200   \vdots       & \vdots     & \vdots         & etc. \\
 201 \end{tabular}
 202 \end{center}
 203
 204 If there are multiple winprops with other identification information
 205 the same but different \var{name}, the longest match is chosen.
 206
 207 \subsection{Finding window identification}
 208
 209 The 'Window info' context menu entry (\key{Mod1+M} or \key{Button3} on a tab)
 210 can be used to list the identification information required to set winprops
 211 for a window and all the transient windows managed within it.
 212
 213 \index{xprop}
 214 Another way to get the identification information is to use \command{xprop}.
 215 Simply run To get class and instance, simply run \command{xprop WM_CLASS}
 216 and click on the particular window of interest. The class is the latter of
 217 the strings while the instance is the former.  To get the role -- few
 218 windows have this property -- use the command \command{xprop WM_ROLE}.
 219 This method, however, will not work on transients.
 220
 221 \index{transient}
 222 So-called ''transient windows'' are usually short-lived dialogs (although
 223 some programs abuse this property) that have a parent window that they are
 224 ''transient for''. On tiled workspaces Ion displays these windows
 225 simulatenously with the parent window at the bottom of the same frame.
 226 Unfortunately \command{xprop} is stupid and can't cope with this situation,
 227 returning the parent window's properties when the transient is clicked on.
 228 For this reason you'll have to do a little extra work to get the properties
 229 for that window.\footnote{There's a patch to \command{xprop} to
 230 fix this, but nothing seems to be happening with respect to including it in
 231 XFree86.}
 232
 233 Finally, it should be mentioned that too many authors these days
 234 ''forget'' to set this vital identification to anything meaningful:
 235 everything except name is the same for all of the programs's
 236 windows, for example.
 237
 238 \subsection{Some common examples}
 239
 240 \subsubsection{Acrobat Reader}
 241
 242 The following is absolutely necessary for Acrobat reader:
 243
 244 \begin{verbatim}
 245 defwinprop{
 246     class = "AcroRead",
 247     instance = "documentShell",
 248     acrobatic = true,
 249 }
 250 \end{verbatim}
 251
 252 \subsubsection{Fixing a Mozilla Firebird transient}
 253
 254 Mozilla Firebird (0.7) incorrectly does not set the \code{WM_TRANSIENT_FOR}
 255 property for the dialog that is used to ask the action to take for a file.
 256 It, however, sets the the property point to the main window for the save
 257 dialog. This can be annoying and confusing, as the first dialog is not
 258 closed before the second is displayed.
 259
 260 We'd like the first dialog to be transient to the main window. The closest
 261 we can get to that is to consider it transient to the current window (if
 262 there's one). Unfortunately Firebird does not set any meaningful classes,
 263 instances or roles for the windows, so we'll have to rely on an ugly title
 264 match.
 265
 266 \begin{verbatim}
 267 defwinprop{
 268     class = "MozillaFirebird-bin",
 269     name = "Opening .*",
 270     transient_mode = "current",
 271 }
 272 \end{verbatim}
 273
 274 \subsubsection{Forcing newly created windows in named frames}
 275
 276 The following winprop should place xterm started with command-line parameter
 277 \mbox{\code{-name sysmon}} and running a system monitoring program in a
 278 particular frame:
 279 \begin{verbatim}
 280 defwinprop{
 281     class = "XTerm",
 282     instance = "sysmon",
 283     target = "sysmonframe",
 284 }
 285 \end{verbatim}
 286
 287 For this example to work, we have to somehow create a frame named
 288 \code{sysmonframe}. One way to do this is to make the following
 289 call in the \key{Mod1+F3} Lua code query:
 290
 291 \begin{verbatim}
 292 mod_query.query_renameframe(_)
 293 \end{verbatim}
 294
 295 Recall that \code{_} points to the multiplexer (frame or screen) in which
 296 the query was opened. Running this code should open a new query prefilled
 297 with the current name of the frame. In our example we would change the
 298 name to \code{sysmonframe}, but we could just as well have used the
 299 default name formed from the frame's class name and an instance number.