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}{float}{boolean}
  45     \index{float@\var{float}}
  46     Set this to open the window in a floating frame, when
  47     in a group.
  48 \end{winprop}
  49
  50
  51 \begin{winprop}{fullscreen}{boolean}
  52     \index{fullscreen@\var{fullscreen}}
  53     Should the window be initially in full screen mode?
  54 \end{winprop}
  55
  56
  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.
  61 \end{winprop}
  62
  63
  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.
  67 \end{winprop}
  68
  69
  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.
  74 \end{winprop}
  75
  76
  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.)
  85 \end{winprop}
  86
  87
  88 \begin{winprop}{oneshot}{boolean}
  89     \index{oneshot@\var{oneshot}}
  90     Discard this winprop after first use.
  91 \end{winprop}
  92
  93
  94 \begin{winprop}{orientation}{string}
  95     \index{orientation@\var{orientation}}
  96     The orientation of the window: one of \codestr{vertical} or
  97     \codestr{horizontal}. This is only useful when using the
  98     window as a status display.
  99 \end{winprop}
 100
 101
 102 \begin{winprop}{statusbar}{string}
 103     \index{statusbar@\var{statusbar}}
 104     Put the window in the statusbar, in the named tray component,
 105     (The default tray component is called simply \codestr{systray},
 106     and others you give names to in your custom template, always
 107     prefixed by \codestr{systray\_}.
 108 \end{winprop}
 109
 110
 111 \begin{winprop}{switchto}{boolean}
 112     \index{switchto@\var{switchto}}
 113     Should a newly mapped client window be switched to within
 114     its frame.
 115 \end{winprop}
 116
 117
 118 \begin{winprop}{target}{string}
 119     \index{target@\var{target}}
 120     The name of an object (workspace, frame) that should manage
 121     windows of this type. See also \code{new_group}.
 122 \end{winprop}
 123
 124
 125 \begin{winprop}{transient_mode}{string}
 126     \index{transient-mode@\var{transient_mode}}
 127     \codestr{normal}: No change in behaviour. \codestr{current}:
 128     The window should be thought of as a transient for the current
 129     active client window (if any) even if it is not marked as a
 130     transient by the application. \codestr{off}: The window should
 131     be handled as a normal window even if it is marked as a
 132     transient by the application.
 133 \end{winprop}
 134
 135
 136 \begin{winprop}{transparent}{boolean}
 137     \index{transparent@\var{transparent}}
 138     Should frames be made transparent when this window is selected? \\
 139 \end{winprop}
 140
 141
 142 \subsection{Sizehint winprops}
 143
 144 Additionally, the winprops
 145 \code{max_size}\index{max-size@\var{max_size}},
 146 \code{min_size}\index{min-size@\var{min_size}},
 147 \code{aspect}\index{aspect@\var{aspect}},
 148 \code{resizeinc}\index{aspect@\var{resizeinc}},
 149 and
 150 \code{ignore_max_size}\index{ignore-max-size@\var{ignore_max_size}},
 151 \code{ignore_min_size}\index{ignore-min-size@\var{ignore_min_size}},
 152 \code{ignore_aspect}\index{ignore-aspect@\var{ignore_aspect}},
 153 \code{ignore_resizeinc}\index{ignore-aspect@\var{ignore_resizeinc}},
 154 may be used to override application-supplied size hints. The four
 155 first ones are tables with the fields \var{w} and \var{h}, indicating
 156 the width and height size hints in pixels, and the latter ignore
 157 winprop is a boolean.
 158
 159 Finally, the boolean
 160 \code{userpos}\index{userpos@\var{userpos}} option may be used to
 161 override the \code{USPosition} flag of the size hints. Normally,
 162 when this flag is set, Ion tries to respect the supplied window
 163 position more than when it is not set. Obviously, this makes sense
 164 only for floating windows.
 165
 166
 167 \subsection{Classes, roles and instances}
 168 \label{sec:classesrolesinstances}
 169
 170 The identification information supported are
 171 \var{class}\index{class@\var{class}!winprop},
 172 \var{role}\index{role@\var{role}!winprop},
 173 \var{instance}\index{instance@\var{instance}!winprop},
 174 \var{name}\index{name@\var{name}!winprop},
 175 \var{is_transient}\index{is-transient@\var{is_transient}!winprop}, and
 176 \var{is_dockapp}\index{is-dockapp@\var{is_dockapp}!winprop}.
 177 It is not necessary to specify all of these fields.
 178 The first three are strings, and must exactly match the
 179 corresponding information obtained from the window's properties.
 180 The \var{name} field is a Lua-style regular expression matched against
 181 the window's title. The \var{is_transient} field is a boolean that can
 182 be used to include or exclude transients only, while the \var{is_dockapp}
 183 field is set by Ion for the dock windows of Window Maker dockapp protocol
 184 dockapps. Usually this is the only information available for these
 185 \emph{icon} windows.
 186
 187 Ion looks for a matching winprop in the order listed by the following
 188 table. An 'E' indicates that the field must be set in the winprop
 189 and it must match the window's corresponding property exactly or, in
 190 case of \var{name}, the regular expression must match the window
 191 title. An asterisk '*' indicates that a winprop where the field is
 192 not specified (or is itself an asterisk in case of the first three
 193 fields) is tried.
 194
 195 \begin{center}
 196 \begin{tabular}{llll}
 197   \tabhead{\var{class} & \var{role} & \var{instance} & other}
 198   E            & E          & E              & E \\
 199   E            & E          & E              & * \\
 200   E            & E          & *              & E \\
 201   E            & E          & *              & * \\
 202   E            & *          & E              & E \\
 203   E            & *          & E              & * \\
 204   E            & *          & *              & E \\
 205   \vdots       & \vdots     & \vdots         & etc. \\
 206 \end{tabular}
 207 \end{center}
 208
 209 If there are multiple matching winprops with the same
 210 \var{class}, \var{role} and \var{instance}, but other information
 211 different, the most recently defined one is used.
 212
 213
 214 \subsection{Finding window identification}
 215
 216 The 'Window info' context menu entry (\key{Mod1+M} or \key{Button3} on a tab)
 217 can be used to list the identification information required to set winprops
 218 for a window and all the transient windows managed within it.
 219
 220 \index{xprop}
 221 Another way to get the identification information is to use \command{xprop}.
 222 Simply run To get class and instance, simply run \command{xprop WM_CLASS}
 223 and click on the particular window of interest. The class is the latter of
 224 the strings while the instance is the former.  To get the role -- few
 225 windows have this property -- use the command \command{xprop WM_ROLE}.
 226 This method, however, will not work on transients.
 227
 228 \index{transient}
 229 So-called ``transient windows'' are usually short-lived dialogs (although
 230 some programs abuse this property) that have a parent window that they are
 231 ``transient for''. On tiled workspaces Ion displays these windows
 232 simultaneously with the parent window at the bottom of the same frame.
 233 Unfortunately \command{xprop} is stupid and can't cope with this situation,
 234 returning the parent window's properties when the transient is clicked on.
 235 For this reason you'll have to do a little extra work to get the properties
 236 for that window.\footnote{There's a patch to \command{xprop} to
 237 fix this, but nothing seems to be happening with respect to including it in
 238 XFree86.}
 239
 240 Finally, it should be mentioned that too many authors these days
 241 ``forget'' to set this vital identification to anything meaningful:
 242 everything except name is the same for all of the program's
 243 windows, for example. Some other programs only set this information
 244 after the window has been mapped, i.e. the window manager has been
 245 told to start managing it, which is obviously too late.
 246 Gtk applications in particular are often guilty on both counts.
 247
 248
 249 \subsection{Some common examples}
 250
 251 \subsubsection{Acrobat Reader}
 252
 253 The following is absolutely necessary for Acrobat reader:
 254
 255 \begin{verbatim}
 256 defwinprop{
 257     class = "AcroRead",
 258     instance = "documentShell",
 259     acrobatic = true,
 260 }
 261 \end{verbatim}
 262
 263 \subsubsection{Forcing newly created windows in named frames}
 264
 265 The following winprop should place xterm started with command-line parameter
 266 \mbox{\code{-name sysmon}} and running a system monitoring program in a
 267 particular frame:
 268 \begin{verbatim}
 269 defwinprop{
 270     class = "XTerm",
 271     instance = "sysmon",
 272     target = "sysmonframe",
 273 }
 274 \end{verbatim}
 275
 276 For this example to work, we have to somehow create a frame named
 277 \codestr{sysmonframe}. One way to do this is to make the following
 278 call in the \key{Mod1+F3} Lua code query:
 279
 280 \begin{verbatim}
 281 mod_query.query_renameframe(_)
 282 \end{verbatim}
 283
 284 Recall that \code{_} points to the multiplexer (frame or screen) in which
 285 the query was opened. Running this code should open a new query prefilled
 286 with the current name of the frame. In our example we would change the
 287 name to \codestr{sysmonframe}, but we could just as well have used the
 288 default name formed from the frame's class name and an instance number.