FvwmRearrange, update to changes in fvwm3 1.1.1.

Wiki/Modules/FvwmRearrange/index.md

@@ -7,81 +7,163 @@ description: |
 ---
 # FvwmRearrange
 
+<div class="alert alert-warning text-dark">
+FvwmRerrange options changed in fvwm3 1.1.1, below only
+applies to that version and newer. For older versions
+refer to the manual page for the options.
+</div>
+
 * TOC
 {:toc}
 
 This module can be called to tile or cascade windows.
 
-When tiling the module attempts to tile windows on the current
-screen subject to certain constraints. Horizontal or vertical tiling
-is performed so that each window does not overlap another,
-and by default each window is resized to its nearest
-resize increment (note sometimes some space might appear between
-tiled windows -- this is why).
+When tiling the module rearranges all the windows on the current
+monitor into a grid (or matrix). By default FvwmRearrange will
+tile the windows into a grid that is close to a square grid as
+possible based on the number of windows on the monitor. The size
+(and direction) of the grid can be configured using various options.
 
-When cascading the module attempts to cascade windows on the
-current screen subject to certain constraints. Layering is performed
-so consecutive windows will have their window titles visible underneath
-the previous.
+When cascading the module will resize (to 75% the size of the monitor)
+then place them starting from the top left of the monitor, and place
+each window down and to the left of the previous window so its title
+bar and borders can be seen behind it. Both the size windows are
+resized to and the size of the increments can be configured using
+various options.
 
 ## Configuration and Use
 
-FvwmRearrange is invoked from a menu, pop-up, or button. Several
-command line options can be used to constrain the layering. For a full
-list of FvwmRearrange configuration options see the FvwmRearrange manpage.
+FvwmRearrange is a module that must be invoked from fvwm. It can be
+add to a menu, key binding, event, and so on. FvwmRearrange is configured
+using command line options (all with a single `-`). These options affect
+the placement, resizing, ordering of windows and so on. For a full list
+of FvwmRearrange configuration options see the FvwmRearrange manpage.
 
-Here is a sample configuration for tiling with 2 columns.
+The simplest way to run FvwmRerrange is with no options, which 
+will auto tile (the same as the `-auto_tile` option) the windows
+on the current monitor. You can additionally specific a specific
+monitor to rearrange, and how to order the windows. For example
+to auto tile all the windows by their class in reverse alphabetical
+order on the RandR monitor `DP-2` use:
 
 {% fvwm2rc %}
-FvwmRearrange -tile -r -mn 2 -maximize 0 0
+FvwmRearrange -screen DP-2 -order_class -reverse
 {% endfvwm2rc %}
 
-To restore the windows, FvwmRearrange doesn't reverse the options,
-use this for all.
+By default FvwmRerrange cannot restore the position of the windows.
+If you want to be able to return windows to their original position
+you can by including the `-maximze` option, which will put all the
+windows into a maximized state. This allows you to return the window
+to its original position by unmaximizing them. For example:
 
 {% fvwm2rc %}
+# Auto tile all windows on RandR monitor DP-2
+FvwmRearrange -screen DP-2 -maximize
+
+# Restore the windows original position
 All (CurrentPage, !Iconic, CirculateHit, !Sticky) Maximize Off
 {% endfvwm2rc %}
 
-## Example
-
-This advanced example is attached to key binding (alt-t) with functions that
-do the tiling with 3 columns. With the same key binding, it restores all
-windows. The below screenshot, before and after tiling, and the following configuration demonstrates this :
+## Tiling Windows
+
+Tiling windows will place them in a grid, whose size can be controlled
+using various options. By default FvwmRerrange will use an auto tile mode
+which will compute a grid that is as close to a square as possible depending
+on the number of windows available. For instance if you have 6 windows, a
+2x2 grid is too small, while a 3x3 grid is too big, so a 3x2 grid will be
+used instead (if the option `-swap` is included the grid will be 2x3).
+
+If the number of windows doesn't match the size of the grid some cells are
+initially empty, for example if there are only 5 windows and a 3x2 grid is
+used this leaving one cell of the grid empty. In auto tile mode the option
+`-fill_start` is implied, which will resize the fill row (or column if
+`-swap` is used) with the first two windows, and then place the remaining
+3 windows on the second row using all the space. The option `-fill_end` can
+be used to instead fill the first row with the first three windows, then
+fill the last row with the remaining two windows.
+
+The size of the grid can be controlled in various ways. If using auto tile
+mode, the option `-max_n N` can be used to offset the size of the grid. For
+example `-max_n 2` will mean there is always at least two more columns than
+rows, so 5-8 windows will cause a 4x2 grid (or a 2x4 grid with `-swap`). For
+more control of the grid use the `-tile` option, which will put all windows
+into a single row (or column with `-swap`). If you combine `-tile` with
+`-max_n N`, then you can specify the maximum number of columns (or rows).
+For example `-tile -max_n 3` will tile the windows so there is at most three
+columns, and the number of rows is based off the number of windows tiled.
+By default `-tile` will leave cells empty unless the `-fill_start` or
+`-fill_end` option is included.
+
+Last, windows are resized to fit into their respective cells subject to
+EWMH size hints. That means windows like terminals that include hints to
+only allowing resizing by specific increments (equal to the size of a single
+character in terminals) and some windows may not completely fill their cell
+leaving gaps. If you want to override this behavior, tell fvwm to ignore
+resize hints using the following style:
 
-|![image](before-after-tile.png)|
+{% fvwm2rc %}
+Style * ResizeHintOverride
+{% endfvwm2rc %}
 
-Tiling with 3 columns.
+## Cascading Windows
+
+FvwmRerrange can be used to cascade windows using the `-cascade` option.
+This option mimics the fvwm `CascadePlacement` style where windows are placed
+starting in the upper left corner of the monitor, placing each window on top
+of the previous window shifted down and to the left so the title bar and
+border of the previous window is seen behind it.
+
+By default FvwmRerrange will resize the windows to be 75% the size of the
+current monitor. The option `-noresize` can be used to prevent FvwmRearrange
+from resizing the windows, while the option `-nostretch` will prevent
+FvwmRerrange from making windows bigger, but will shrink them to fit if they
+are too big. The options `-cascadew X` and `-cascadeh Y` can be used to
+specify the width and height of the windows. `X` and `Y` are taken to be
+percent of the bounding box, or pixel sizes if they are suffixed with a `p`.
+
+The options `-inc_equal` can used to make the horizontal and vertical offsets
+the same. The options `-incx X` and `-incy Y` can be used to specify additional
+offsets in the respective direction. The values `X` and `Y` are percent values
+or pixel sizes if suffixed with a `p`. The options `flatx` and `flaty` will
+disable auto increments, and if used with `-incx X` and `-incy Y` can be used
+to specify the exact increments.
+
+The following example will cascade and resize the windows to have a width
+of 60% the monitor, a height of 75% the monitor, and make the horizontal
+and vertical offsets equal.
 
 {% fvwm2rc %}
-DestroyFunc 3Tile
-AddToFunc 3Tile
-+ I FvwmRearrange -tile -r -mn 3 -maximize 1 3 92 92
+FvwmRearrange -cascade -inc_equal -cascadew 60
 {% endfvwm2rc %}
 
-Tile switch on and off.
+## Example
+
+This example is attached to key binding (alt-T) which will auto tile all
+windows on the current monitor. With the same keybinding, it will restore
+all windows to their original position. To work in a multiple monitor
+setup, the current state is saved in an `InfoStore` variable
+`TitleSwitch<monitor name>`.
 
 {% fvwm2rc %}
-InfoStoreAdd TileSwitch "ON"
+DestroyFunc AutoTile
+AddToFunc AutoTile
++ I FvwmRearrange -maximize
 
 DestroyFunc Tile
 AddToFunc Tile
-+ I Test (EnvMatch infostore.TileSwitch ON) TileOn
-+ I TestRc (NoMatch) TileOff
++ I Test (EnvMatch infostore.TileSwitch$[monitor.current] ON) TileOff
++ I TestRc (NoMatch) TileOn
 
 DestroyFunc TileOn
 AddToFunc TileOn
-+ I 3Tile
-+ I InfoStoreAdd TileSwitch OFF
++ I AutoTile
++ I InfoStoreAdd TileSwitch$[monitor.current] ON
 
 DestroyFunc TileOff
 AddToFunc TileOff
 + I All (CurrentPage, !Iconic, CirculateHit, !Sticky) Maximize Off
-+ I InfoStoreAdd TileSwitch ON
-{% endfvwm2rc %}
++ I InfoStoreAdd TileSwitch$[monitor.current] OFF
 
-Key binding (alt-t)
-
-{% fvwm2rc %}
+# Alt-T key binding
 Key t A M Tile
 {% endfvwm2rc %}