X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=doc%2Fconf-winprops.tex;h=e5e0133e3d4330be472f6b2eb918aa09e283b2af;hb=ae4260bb64817c11f9a7140324cd3e3ba113e297;hp=10c1c10fa8b3d4bc4ddf8485b4d9285ebe66c5cb;hpb=8366314611bf30a0f31d25bf5f5023186fa87692;p=ion3.git diff --git a/doc/conf-winprops.tex b/doc/conf-winprops.tex index 10c1c10..e5e0133 100644 --- a/doc/conf-winprops.tex +++ b/doc/conf-winprops.tex @@ -1,7 +1,7 @@ \section{Winprops} \label{sec:winprops} -The so-called ''winprops''\index{Winprops} can be used to change how +The so-called ``winprops''\index{Winprops} can be used to change how specific windows are handled and to set up some kludges to deal with badly behaving applications. They are defined by calling the function \code{defwinprop} with a table containing the properties to set and the @@ -41,13 +41,6 @@ usual method of identifying windows, and how to obtain this information. \end{winprop} -\begin{winprop}{aspect}{table} - \index{aspect@\var{aspect}} - The table should contain the entries \var{w} and \var{h} that - override application-supplied aspect ratio hint. -\end{winprop} - - \begin{winprop}{float}{boolean} \index{float@\var{float}} Set this to open the window in a floating frame, when @@ -74,12 +67,6 @@ usual method of identifying windows, and how to obtain this information. \end{winprop} -\begin{winprop}{ignore_resizeinc}{boolean} - \index{ignore-resizeinc@\var{ignore_resizeinc}} - Should application supplied size increments be ignored? -\end{winprop} - - \begin{winprop}{jumpto}{boolean} \index{jumpto@\var{jumpto}} Should a newly created client window always be made @@ -87,16 +74,14 @@ usual method of identifying windows, and how to obtain this information. \end{winprop} -\begin{winprop}{max_size}{table} - \index{max-size@\var{max_size}} - The table should contain the entries \var{w} and \var{h} that - override application-supplied maximum size hint. -\end{winprop} - - -\begin{winprop}{min_size}{table} - \index{min-size@\var{min_size}} - Similar to \var{max_size} but for the minimum size hint. +\begin{winprop}{new_group}{string} + \index{new-group@\var{new_group}} + If the region specified by \code{target} winprop does not exist + (or that winprop is not set), create a new workspace using the + previously stored layout (see \fnref{ioncore.deflayout}) named by + this property. After creating the workspace, \code{target} is + attempted to be found again. (If that still fails, the newly + created workspace is still asked to manage the client window.) \end{winprop} @@ -106,6 +91,15 @@ usual method of identifying windows, and how to obtain this information. \end{winprop} +\begin{winprop}{statusbar}{string} + \index{statusbar@\var{statusbar}} + Put the window in the statusbar, in the named tray component, + (The default tray component is called simply \codestr{systray}, + and others you give names to in your custom template, always + prefixed by \codestr{systray\_}. +\end{winprop} + + \begin{winprop}{switchto}{boolean} \index{switchto@\var{switchto}} Should a newly mapped client window be switched to within @@ -116,48 +110,71 @@ usual method of identifying windows, and how to obtain this information. \begin{winprop}{target}{string} \index{target@\var{target}} The name of an object (workspace, frame) that should manage - windows of this type. + windows of this type. See also \code{new_group}. \end{winprop} \begin{winprop}{transient_mode}{string} \index{transient-mode@\var{transient_mode}} - "normal": No change in behaviour. "current": The window - should be thought of as a transient for the current active - client window (if any) even if it is not marked as a - transient by the application. "off": The window should be - handled as a normal window even if it is marked as a + \codestr{normal}: No change in behaviour. \codestr{current}: + The window should be thought of as a transient for the current + active client window (if any) even if it is not marked as a + transient by the application. \codestr{off}: The window should + be handled as a normal window even if it is marked as a transient by the application. \end{winprop} -\begin{winprop}{transients_at_top}{boolean} - \index{transients-at-top@\var{transients_at_top}} - When transients are managed by the client window itself (as it - is the case on tiled workspaces), should the transients be - placed at the top of the window instead of bottom? -\end{winprop} - - \begin{winprop}{transparent}{boolean} \index{transparent@\var{transparent}} Should frames be made transparent when this window is selected? \\ \end{winprop} +\subsection{Sizehint winprops} + +Additionally, the winprops +\code{max_size}\index{max-size@\var{max_size}}, +\code{min_size}\index{min-size@\var{min_size}}, +\code{aspect}\index{aspect@\var{aspect}}, +\code{resizeinc}\index{aspect@\var{resizeinc}}, +and +\code{ignore_max_size}\index{ignore-max-size@\var{ignore_max_size}}, +\code{ignore_min_size}\index{ignore-min-size@\var{ignore_min_size}}, +\code{ignore_aspect}\index{ignore-aspect@\var{ignore_aspect}}, +\code{ignore_resizeinc}\index{ignore-aspect@\var{ignore_resizeinc}}, +may be used to override application-supplied size hints. The four +first ones are tables with the fields \var{w} and \var{h}, indicating +the width and height size hints in pixels, and the latter ignore +winprop is a boolean. + +Finally, the boolean +\code{userpos}\index{userpos@\var{userpos}} option may be used to +override the \code{USPosition} flag of the size hints. Normally, +when this flag is set, Ion tries to respect the supplied window +position more than when it is not set. Obviously, this makes sense +only for floating windows. + \subsection{Classes, roles and instances} \label{sec:classesrolesinstances} -The identification information in the winprop specification is usually the +The identification information supported are \var{class}\index{class@\var{class}!winprop}, \var{role}\index{role@\var{role}!winprop}, -\var{instance}\index{instance@\var{instance}!winprop} and -\var{name} -of the window. The \var{name} field is a Lua-style regular expression -matched against the window's title and the rest are strings that must -exactly match the corresponding window information. It is not necessary -to specify all of these fields. +\var{instance}\index{instance@\var{instance}!winprop}, +\var{name}\index{name@\var{name}!winprop}, +\var{is_transient}\index{is-transient@\var{is_transient}!winprop}, and +\var{is_dockapp}\index{is-dockapp@\var{is_dockapp}!winprop}. +It is not necessary to specify all of these fields. +The first three are strings, and must exactly match the +corresponding information obtained from the window's properties. +The \var{name} field is a Lua-style regular expression matched against +the window's title. The \var{is_transient} field is a boolean that can +be used to include or exclude transients only, while the \var{is_dockapp} +field is set by Ion for the dock windows of Window Maker dockapp protocol +dockapps. Usually this is the only information available for these +\emph{icon} windows. Ion looks for a matching winprop in the order listed by the following table. An 'E' indicates that the field must be set in the winprop @@ -169,7 +186,7 @@ fields) is tried. \begin{center} \begin{tabular}{llll} - \tabhead{\var{class} & \var{role} & \var{instance} & \var{name}} + \tabhead{\var{class} & \var{role} & \var{instance} & other} E & E & E & E \\ E & E & E & * \\ E & E & * & E \\ @@ -181,8 +198,10 @@ fields) is tried. \end{tabular} \end{center} -If there are multiple winprops with other identification information -the same but different \var{name}, the longest match is chosen. +If there are multiple matching winprops with the same +\var{class}, \var{role} and \var{instance}, but other information +different, the most recently defined one is used. + \subsection{Finding window identification} @@ -199,10 +218,10 @@ windows have this property -- use the command \command{xprop WM_ROLE}. This method, however, will not work on transients. \index{transient} -So-called ''transient windows'' are usually short-lived dialogs (although +So-called ``transient windows'' are usually short-lived dialogs (although some programs abuse this property) that have a parent window that they are -''transient for''. On tiled workspaces Ion displays these windows -simulatenously with the parent window at the bottom of the same frame. +``transient for''. On tiled workspaces Ion displays these windows +simultaneously with the parent window at the bottom of the same frame. Unfortunately \command{xprop} is stupid and can't cope with this situation, returning the parent window's properties when the transient is clicked on. For this reason you'll have to do a little extra work to get the properties @@ -211,9 +230,13 @@ fix this, but nothing seems to be happening with respect to including it in XFree86.} Finally, it should be mentioned that too many authors these days -''forget'' to set this vital identification to anything meaningful: -everything except name is the same for all of the programs's -windows, for example. +``forget'' to set this vital identification to anything meaningful: +everything except name is the same for all of the program's +windows, for example. Some other programs only set this information +after the window has been mapped, i.e. the window manager has been +told to start managing it, which is obviously too late. +Gtk applications in particular are often guilty on both counts. + \subsection{Some common examples} @@ -229,28 +252,6 @@ defwinprop{ } \end{verbatim} -\subsubsection{Fixing a Mozilla Firebird transient} - -Mozilla Firebird (0.7) incorrectly does not set the \code{WM_TRANSIENT_FOR} -property for the dialog that is used to ask the action to take for a file. -It, however, sets the the property point to the main window for the save -dialog. This can be annoying and confusing, as the first dialog is not -closed before the second is displayed. - -We'd like the first dialog to be transient to the main window. The closest -we can get to that is to consider it transient to the current window (if -there's one). Unfortunately Firebird does not set any meaningful classes, -instances or roles for the windows, so we'll have to rely on an ugly title -match. - -\begin{verbatim} -defwinprop{ - class = "MozillaFirebird-bin", - name = "Opening .*", - transient_mode = "current", -} -\end{verbatim} - \subsubsection{Forcing newly created windows in named frames} The following winprop should place xterm started with command-line parameter @@ -265,7 +266,7 @@ defwinprop{ \end{verbatim} For this example to work, we have to somehow create a frame named -\code{sysmonframe}. One way to do this is to make the following +\codestr{sysmonframe}. One way to do this is to make the following call in the \key{Mod1+F3} Lua code query: \begin{verbatim} @@ -275,5 +276,5 @@ mod_query.query_renameframe(_) Recall that \code{_} points to the multiplexer (frame or screen) in which the query was opened. Running this code should open a new query prefilled with the current name of the frame. In our example we would change the -name to \code{sysmonframe}, but we could just as well have used the +name to \codestr{sysmonframe}, but we could just as well have used the default name formed from the frame's class name and an instance number.