Tagged current upstream version.

[ion3-doc.git] / conf-winprops.tex

diff --git a/conf-winprops.tex b/conf-winprops.tex
index 9a416d3ec0c20bf50db277185d25f23067e2d0c5..db70e5fb89c8b4373917683efd5d99b5158e807d 100644 (file)
--- a/conf-winprops.tex
+++ b/conf-winprops.tex
@@ -1,7 +1,7 @@
 \section{Winprops}
 \label{sec:winprops}
 
 \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
 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}
 
 
 \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
 \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}
 
 
 \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
 \begin{winprop}{jumpto}{boolean}
     \index{jumpto@\var{jumpto}}
     Should a newly created client window always be made


@@ -87,19 +74,6 @@ usual method of identifying windows, and how to obtain this information.
 \end{winprop}
 
 
 \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. 
-\end{winprop}
-
-

 \begin{winprop}{new_group}{string}
     \index{new-group@\var{new_group}}
     If the region specified by \code{target} winprop does not exist
 \begin{winprop}{new_group}{string}
     \index{new-group@\var{new_group}}
     If the region specified by \code{target} winprop does not exist


@@ -117,12 +91,20 @@ usual method of identifying windows, and how to obtain this information.
 \end{winprop}
 
 
 \end{winprop}
 
 

+\begin{winprop}{orientation}{string}
+    \index{orientation@\var{orientation}}
+    The orientation of the window: one of \codestr{vertical} or
+    \codestr{horizontal}. This is only useful when using the
+    window as a status display.
+\end{winprop}
+
+

 \begin{winprop}{statusbar}{string}
     \index{statusbar@\var{statusbar}}
 \begin{winprop}{statusbar}{string}
     \index{statusbar@\var{statusbar}}

-    Put the window on the statusbar, in the named tray component,
-    (The default tray component is called simply ``\code{systray}'', 
+    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 
     and others you give names to in your custom template, always 

-    prefixed by ``\code{systray_}''.
+    prefixed by \codestr{systray\_}.

 \end{winprop}
 
 
 \end{winprop}
 
 


@@ -142,42 +124,65 @@ usual method of identifying windows, and how to obtain this information.
         
 \begin{winprop}{transient_mode}{string}
     \index{transient-mode@\var{transient_mode}}
         
 \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}
 
 
     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}
 
 
 \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}
 
 
 \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{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
 
 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


@@ -189,7 +194,7 @@ fields) is tried.
 
 \begin{center}
 \begin{tabular}{llll}
 
 \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 \\
   E           & E          & E              & E \\
   E           & E          & E              & * \\
   E           & E          & *              & E \\


@@ -201,8 +206,10 @@ fields) is tried.
 \end{tabular}
 \end{center}
 
 \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}
 
 
 \subsection{Finding window identification}
 


@@ -219,10 +226,10 @@ windows have this property -- use the command \command{xprop WM_ROLE}.
 This method, however, will not work on transients. 
 
 \index{transient}
 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
 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
 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


@@ -231,9 +238,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
 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}
 
 
 \subsection{Some common examples}
 


@@ -249,28 +260,6 @@ defwinprop{
 }
 \end{verbatim}
 
 }
 \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
 \subsubsection{Forcing newly created windows in named frames}
 
 The following winprop should place xterm started with command-line parameter


@@ -285,7 +274,7 @@ defwinprop{
 \end{verbatim}
 
 For this example to work, we have to somehow create a frame named
 \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}
 call in the \key{Mod1+F3} Lua code query:
 
 \begin{verbatim}


@@ -295,5 +284,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 
 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.
 default name formed from the frame's class name and an instance number.