cvsimport

[fvwm.git] / doc / modules / FvwmTabs.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id: FvwmTabs.xml,v 1.6 2008/01/08 10:31:00 griph Exp $ -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "../docbook-xml/docbookx.dtd"
[
<!ENTITY % myents SYSTEM "../fvwm.ent" >
%myents;
]>

<article>
<artheader>
        <title>FvwmTabs</title>
        <author>Scott Smedley</author>
        <titleabbrev>FvwmTabs</titleabbrev>
        <date>&releasedate;</date>
</artheader>

<section id="name">
<title>Name</title>
<para><emphasis remap='B'>FvwmTabs</emphasis> is a generic tabbing module for the fvwm window manager.</para>
</section>


<section id="synopsis">
<title>Synopsis</title>
<para><emphasis remap='B'>FvwmTabs</emphasis> is spawned by fvwm, so no command line invocation is possible.</para>
</section>


<section id="description">
<title>Description</title>
<para>The <emphasis remap='B'>FvwmTabs</emphasis> module is capable of swallowing any fvwm window &amp; treating it as a tab in a <emphasis>tab-manager</emphasis> window. A tab-manager is sometimes called a <emphasis>tabber</emphasis>. Each tab-manager can store any number of windows, each in its own <emphasis>tab</emphasis>. The number of tab-managers is limited only by system resources. Tab-managers can even be nested/swallowed within other tab-managers. (ie. a tab-manager can be added as an individual tab to another tab-manager.)</para>

<para output="html">Here is a screenshot of an FvwmTabs tab-manager with an rxvt window selected. Note the buttons at the top which allow switching between applications.</para>
<imageobject output="html"><imagedata output="html" fileref="images/FvwmTabs/screenshot.png"/></imageobject>

</section>

<section id="invocation">
<title>Invocation</title>
<para><emphasis remap='B'>FvwmTabs</emphasis> can be invoked by inserting the line:</para>

<programlisting>
<fvwmref cmd="Module"/> FvwmTabs
</programlisting>

<para>in your .fvwmrc file. This can be placed on a line by itself, if <emphasis remap='B'>FvwmTabs</emphasis> is to be spawned during fvwm's initialization, or can be bound to a menu, mouse button or keystroke to invoke it later.</para>
</section>

<section id="dependencies">
<title>Installing Dependencies</title>
<para><emphasis remap='B'>FvwmTabs</emphasis> requires 2 CPAN modules (that are NOT distributed with fvwm) to be installed on your system. They are <emphasis>Tk</emphasis> and <emphasis>X11::Protocol</emphasis>.</para>

<para>They are available at: <ulink>http://search.cpan.org/CPAN/authors/id/N/NI/NI-S/Tk-804.027.tar.gz</ulink> and <ulink>http://search.cpan.org/~smccam/X11-Protocol-0.56/</ulink>.</para>

<para>To install either package:</para>
<programlisting>
tar zxvf $name.tar.gz ; cd $name ; perl Makefile.PL ; make install
</programlisting>

<para><emphasis remap='B'>FvwmTabs</emphasis> will tell you if you do not have these packages installed when you (try to) start it.</para>
</section>

<section id="options">
<title>Configuration Options</title>
<para><emphasis remap='B'>FvwmTabs</emphasis> reads the same config file as fvwm when it starts up.</para>

<para>The following options are recognised by <emphasis remap='B'>FvwmTabs</emphasis>:</para>


<variablelist>
<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="activeFG"/> <emphasis>color</emphasis></term>
<listitem><simpara>The text color of the button for the visible tab. The default color is yellow.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="activeBG"/> <emphasis>color</emphasis></term>
<listitem><simpara>The backgound color of the button for the visible tab. The default color is MidnightBlue.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="inactiveFG"/> <emphasis>color</emphasis></term>
<listitem><simpara>The text color of the buttons for the invisible tabs. The default color is antiquewhite.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="inactiveBG"/> <emphasis>color</emphasis></term>
<listitem><simpara>The backgound color of the buttons for the invisible tabs. The default color is royalblue.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="activeRelief"/> <emphasis>style</emphasis></term>
<listitem><simpara>The relief style to use for active buttons. <emphasis>style</emphasis> can be either <emphasis>raised</emphasis>, <emphasis>flat</emphasis> or <emphasis>sunken</emphasis>. The default style is <emphasis>sunken</emphasis>.</simpara></listitem>
</varlistentry>



<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="inactiveRelief"/> <emphasis>style</emphasis></term>
<listitem><simpara>The relief style to use for inactive buttons. <emphasis>style</emphasis> can be either <emphasis>raised</emphasis>, <emphasis>flat</emphasis> or <emphasis>sunken</emphasis>. The default style is <emphasis>flat</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="buttonYPadding"/> <emphasis>pixels</emphasis></term>
<listitem><simpara>How much padding to use around top and bottom of tab buttons. The default value is <emphasis>3</emphasis> pixels.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="pollRate"/> <emphasis>ms</emphasis></term>
<listitem><simpara> Specifies how often to check for X events. <emphasis>ms</emphasis> is time in milliseconds. The default value, <emphasis>250</emphasis>, should be fine for most users. If you are on a very slow machine you may wish to increase this.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="buttonFont"/> <emphasis>font</emphasis></term>
<listitem><simpara> The font to use on the tab buttons. The default font is <emphasis>Helvetica -12 bold</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="titleFont"/> <emphasis>font</emphasis></term>
<listitem><simpara> The font to use on the titlebar. The default font is <emphasis>Helvetica -12</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="menuFont"/> <emphasis>font</emphasis></term>
<listitem><simpara> The font to use on the menus. The default font is <emphasis>Helvetica -12</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="fontSelector"/> <emphasis>fontProgram</emphasis></term>
<listitem><simpara> The external font chooser program to launch when dynamically changing fonts. The default <emphasis>fontProgram</emphasis> is <emphasis>gfontsel --print -f "%f"</emphasis>. Anti-gnome users might try <emphasis>xfontsel -print -pattern "%f"</emphasis>. If set to <emphasis>none</emphasis>, no font menu options will appear.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="autoSwallowClass"/> <emphasis>className</emphasis> [<emphasis>tabManagerId</emphasis>], ...</term>
</varlistentry>
<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="autoSwallowResource"/> <emphasis>resourceName</emphasis> [<emphasis>tabManagerId</emphasis>], ...</term>
</varlistentry>
<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="autoSwallowName"/> <emphasis>name</emphasis> [<emphasis>tabManagerId</emphasis>], ...</term>
<listitem><simpara> Specify windows to swallow automatically. These are comma-separated lists that specify the class/resource/name of a window and an optional tab-manager id into which the window should be swallowed. By default, the tab-manager id increments from zero - ie. 0 is the first tab-manager created, 1 the second, etc, but it may be overriden by specifying an argument to the <emphasis>NewTabber</emphasis> function. (No whitespace is allowed in tabber ids.) You can alternatively specify 'any' or 'lastFocus' which will put the window in the tab-manager with the least number of tabs or the last focused tab-manager, respectively. If no tab-manager number is specified, an implicit default value of 'any' is used. Note that <emphasis>className</emphasis>/<emphasis>resourceName</emphasis>/<emphasis>name</emphasis> can be a (Perl) regular expression.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="balloonBG"/> <emphasis>color</emphasis></term>
<listitem><simpara> The backgound color of the balloon popups that appear over the tab buttons. The default color is <emphasis>#C0C080</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="balloonFont"/> <emphasis>font</emphasis></term>
<listitem><simpara> The font to use on the balloon popups. The default font is <emphasis>Helvetica -12</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="balloonWait"/> <emphasis>ms</emphasis></term>
<listitem><simpara> How long the mouse cursor must pause (in milliseconds) over a tab button before the balloon pops up. The default value is <emphasis>250</emphasis>. </simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="balloonMsg"/> <emphasis>msg</emphasis></term>
<listitem><simpara> Message to display in balloon popups. The default value is <emphasis>%tabNo:\n%iconText\n%title</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="autoResize"/> <emphasis>bool</emphasis></term>
<listitem><simpara> <emphasis>bool</emphasis> can be either <emphasis>true</emphasis> or <emphasis>false</emphasis>. If true, windows in the tab-manager automatically resize to the dimensions of the largest window in the tab-manager. The default value is <emphasis>false</emphasis>. If the user performs an explicit resize of a tab-manager window, all windows in the tab-manager are resized to the new window size.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="stateFile"/> <emphasis>file</emphasis></term>
<listitem><simpara><emphasis remap='B'>FvwmTabs</emphasis> has the ability to preserve its state (ie. remember the windows it has swallowed as tabs) b/w fvwm restarts. <emphasis>file</emphasis> specifies the name of a temporary file to record the state in, so it can be reconstructed when <emphasis remap='B'>FvwmTabs</emphasis> restarts. The default file is <envar>$FVWM_USERDIR</envar>/.fvwmtabs.state.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="fixedSizeTabs"/> <emphasis>bool</emphasis></term>
<listitem><simpara> <emphasis>bool</emphasis> can be either <emphasis>true</emphasis> or <emphasis>false</emphasis>. If true, the tab-manager will ensure each tab-button has the same dimensions. If false, the selected tab is expanded so that it is fully visible. The default value is <emphasis>false</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="showTitlebar"/> <emphasis>bool</emphasis></term>
<listitem><simpara> Show internal titlebar. If set to <emphasis>true</emphasis> a titlebar appears below the row of tab-buttons and displays the title associated with the current window. This titlebar is capable of displaying long or multi-line titles. The default value is <emphasis>true</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="useTMTitlebar"/> <emphasis>bool</emphasis></term>
<listitem><simpara> Add the title associated with the selected tab to the tab-manager titlebar. (ie. the titlebar at the top of the window, distinct from the titlebar below the tab-buttons.) Default value is <emphasis>true</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="dragDropIcon"/> <emphasis>imageFile</emphasis></term>
<listitem><simpara> Specify the icon to display when performing a drag-&amp;-drop operation to reorder the tab-buttons. FvwmTabs will search the ImagePath for this image unless an absolute filename (ie. filename begins with '/') is specified. The default value is <emphasis>none</emphasis>. If <emphasis>none</emphasis> (or an invalid file) is specified a * is used.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="bBuggyFocus"/> <emphasis>bool</emphasis></term>
<listitem><simpara> FvwmTabs tries to work around a limitation in Perl/Tk (there is no way to access the timestamp associated with WM_TAKE_FOCUS events). On some systems this doesn't work and sometimes tab-managers have trouble acquiring the focus. If this happens to you, try setting this option to <emphasis>true</emphasis>. This can lead to focussing race-conditions (tab-managers temporarily "steal" focus in some situations) but this is less annoying than not being able to focus at all.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="enableSwallowDND"/> <emphasis>bool</emphasis></term>
<listitem><simpara> Swallow windows that (are moved to) overlap a tabber.</simpara>
<simpara>Note: drag-&amp;-drop can be enabled for individual tabbers via the menu.
The default value is <emphasis>true</emphasis>.</simpara>
</listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="swallowDNDTolerance"/> <emphasis>tol</emphasis></term>
<listitem><simpara>Determines how much a window must overlap a tabber for it to be swallowed when drag-&amp;-drop is enabled. If the value has a %-sign appended to it, windows must overlap by the specified percentage of the current size of the tabber. If no %-sign is present, the value is treated in units of pixels. The default value is <emphasis>10</emphasis> (pixels).</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="useIconsOnTabs"/> <emphasis>bool</emphasis></term>
<listitem><simpara> Show the mini icon associated with each window on its tab button. Note: mini icons for apps that use EWMH icons look a bit distorted.  This is because of the poor image resizing algorithm used in Tk. This sinactiveBG hould be rectified in the near future. The default value is <emphasis>true</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="killIcon"/> <emphasis>image</emphasis></term>
<listitem><simpara>Image to use on kill toolbar button. Default is <emphasis>none</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="addIcon"/> <emphasis>image</emphasis></term>
<listitem><simpara>Image to use on add toolbar button. Default is <emphasis>none</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="swallowIcon"/> <emphasis>image</emphasis></term>
<listitem><simpara> Image to use on add toolbar button when tabber will swallow next window to popup. Default is <emphasis>none</emphasis>. By using a separate icon to <emphasis>addIcon</emphasis>, this option provides visual feedback on when a tabber will unconditionally swallow the next window to popup.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="releaseIcon"/> <emphasis>image</emphasis></term>
<listitem><simpara> Image to use on release toolbar button. Default is <emphasis>none</emphasis>.</simpara></listitem>
</varlistentry>

<varlistentry>
<term>*FvwmTabs: <fvwmopt mod="FvwmTabs" opt="menuIcon"/> <emphasis>image</emphasis></term>
<listitem><simpara> Image to use on menu toolbar button. Default is <emphasis>none</emphasis>.</simpara></listitem>
</varlistentry>
</variablelist>


<section id="additionalConfiguration">
<title>Additional Configuration</title>

<para output="html">Images you may wish to use with the FvwmTabs module:
<imageobject><imagedata fileref="images/FvwmTabs/logoFvwmTabs.png"/></imageobject>
<imageobject><imagedata fileref="images/FvwmTabs/green.png"/></imageobject>
<imageobject><imagedata fileref="images/FvwmTabs/yellow.png"/></imageobject>
<imageobject><imagedata fileref="images/FvwmTabs/red.png"/></imageobject>
</para>

<para>If you use a decent shell like zsh, you might like to add these functions to your ~/.zshrc file so that tabs/titles have more meaningful names when executing commands:</para>

<programlisting>
setTitleAndIcon () {  print -nP '%{\e]2;'$1'\a\e]1;'$2'\a%}' }
preexec () { setTitleAndIcon $1 ${1%% *} }
precmd () { setTitleAndIcon %n@%m %m }
</programlisting>

<para>There are likely similar functions for other sh/csh shells.</para>
</section>
</section>


<section id="functions">
<title>Functions for Bindings</title>
<para>A number of fvwm functions are available once the FvwmTabs module is started.</para>

<variablelist>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="NewTabber"/></term>
<listitem><simpara> Create a new tabber. Optional argument is tabber name. No whitespace is allowed in the tabber name. Can also prefix --geometry argument. Example:</simpara>

<programlisting>
NewTabber --geometry=+200+400 scottie
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="Tabize"/></term>
<listitem><simpara> Add a window (as a tab) to a tabber.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="NextTab"/></term>
<listitem><simpara> Show/select the next tab.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="PrevTab"/></term>
<listitem><simpara> Show/select the previous tab.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="LastTab"/></term>
<listitem><simpara> Show/select the last selected tab (if there was one).</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="ReleaseTab"/></term>
<listitem><simpara> Release a tabbed window back to fvwm.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="ReleaseIconifyTab"/></term>
<listitem><simpara> Release a tabbed window back to fvwm &amp; iconify it.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="ReleaseAllTabs"/></term>
<listitem><simpara> Release all windows in a tab-manager back to fvwm.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="ReleaseIconifyAllTabs"/></term>
<listitem><simpara> Release all windows in a tab-manager back to fvwm &amp; iconify them.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="CloseTabber"/></term>
<listitem><simpara> Destroy a tab-manager. All windows in the tab-manager are released back to fvwm.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="AddTab"/></term>
<listitem><simpara> Pick a new window to add to a tab-manager. Selecting this option &amp; clicking on a window will add the selected window to the tab-manager.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="MultiAddTab"/></term>
<listitem><simpara> Pick &amp; add new windows to a tab-manager until ESC is pressed.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="ShowTab"/> <emphasis>tabNo</emphasis></term>
<listitem><simpara> Show/select tab <emphasis>tabNo</emphasis> in the tab-manager. <emphasis>tabNo</emphasis> is zero-based. ie. 0 is the first tab, 1 is the second, etc.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="AddToTabber"/></term>
<listitem><simpara> Add a window (as a tab) to a tab-manager.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="SwapLeft"/></term>
<listitem><simpara> Swap the selected window with the window on its immediate left.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="SwapRight"/></term>
<listitem><simpara> Swap the selected window with the window on its immediate right.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="SelectTabber"/></term>
<listitem><simpara> Select a tab-manager for a new window to be added to.</simpara></listitem>
</varlistentry>

<varlistentry>
<term><fvwmopt mod="FvwmTabs" opt="EnableDND"/></term>
<listitem><simpara> Swallow windows that (are moved to) overlap a tabber.</simpara></listitem>
</varlistentry>
</variablelist>
</section>



<section id="keyBindings">
<title>Key Bindings</title>
<para>By default, <emphasis remap='B'>FvwmTabs</emphasis> reads a default user configuration file <filename>FvwmTabs-DefaultSetup</filename> which defines several useful key-bindings for <emphasis remap='B'>FvwmTabs</emphasis>. You can tell <emphasis remap='B'>FvwmTabs</emphasis> NOT to read this file with:</para>
<programlisting>
<fvwmref cmd="SetEnv"/> FvwmTabs_NoDefaultSetup
</programlisting>
<para>This environment variable must be set <emphasis>before</emphasis> starting the module.
</para>Then, pressing Ctrl-Alt-a (when the focus is in a tab-manager) will allow you to click on a window to add to the tab-manager.

<para>All of the key bindings can be changed using the standard fvwm <fvwmref cmd="Key"/> command and making use of the aforementioned fvwm functions. ie.</para>
<programlisting>
<fvwmref cmd="Key"/> (FvwmTabs*) A A CM <fvwmref cmd="Function"/> AddTab
</programlisting>

<para>Then, pressing Ctrl-Alt-a (when the focus is in a tab-manager) will allow you to click on a window to add to the tab-manager.</para>

<para>The default key bindings (set in the <filename>FvwmTabs-DefaultSetup</filename> file) are:</para>


<variablelist>
<varlistentry>
<term><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>a</keycap></keycombo></term>
<listitem><simpara>AddTab</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-c</term>
<listitem><simpara>CloseTabber</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-i</term>
<listitem><simpara>ReleaseIconifyTab</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-Shift-I</term>
<listitem><simpara>ReleaseIconifyAllTabs</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-l</term>
<listitem><simpara>LastTab</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-m</term>
<listitem><simpara>MultiAddTab</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-n &amp; Ctrl-Alt-Tab</term>
<listitem><simpara>NextTab</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-p</term>
<listitem><simpara>PrevTab</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-r</term>
<listitem><simpara>ReleaseTab</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-Shift-R</term>
<listitem><simpara>ReleaseAllTabs</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-t</term>
<listitem><simpara>NewTabber</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-<emphasis>&lt;num&gt;</emphasis></term>
<listitem><simpara>ShowTab <emphasis>&lt;num&gt;</emphasis></simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-Left</term>
<listitem><simpara>SwapLeft</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Alt-Right</term>
<listitem><simpara>SwapRight</simpara></listitem>
</varlistentry>
</variablelist>

</section>




<section id="mouseBindings">
<title>Mouse Bindings</title>
<section id="tabMouseBindings">
<title>Mouse Bindings on Tab Buttons</title>

<informaltable>
<tgroup cols='2'>
<thead>
<row>
<entry>Mouse Button</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>
<row>
<entry align="center">1</entry>
<entry>display the window associated with the tab.</entry>
</row>
<row>
<entry align="center">2</entry>
<entry>release the window associated with the tab back to the window manager as a standalone window.</entry>
</row>
<row>
<entry align="center">Ctrl + 2</entry>
<entry>tab-buttons can be reordered with a drag-&amp;-drop operation initiated by holding down the Ctrl key and dragging with Mouse-2. A dragged tab is inserted before the tab-button onto which it is dropped.</entry>
</row>
<row>
<entry align="center">3</entry>
<entry>release the window associated with the tab back to the window manager as a standalone window.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>


<section id="toolbarMouseBindings">
<title>Mouse Bindings on Toolbar Icons</title>
<para>There are 4 toolbar icons named (L-to-R): menu, release, add and kill.</para>

<informaltable>
<tgroup cols='3'>
<thead>
<row>
<entry>Icon</entry>
<entry>Mouse Button</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>
<row>
<entry>menu</entry>
<entry align="center">1</entry>
<!--
<entry>Display main menu. See <fvwmref sect="FvwmTabs" opt="menu" name="Menu Options"/>.</entry>
-->
<entry>Display main menu. See <fvwmref mod="FvwmTabs" opt="menu" name="Menu Options"/>.</entry>
</row>
<row>
<entry>release</entry>
<entry align="center">1</entry>
<entry>release the selected window from the tabber.</entry>
</row>
<row>
<entry>release</entry>
<entry align="center">2</entry>
<entry>release all windows from the tabber, and iconify them.</entry>
</row>
<row>
<entry>release</entry>
<entry align="center">3</entry>
<entry>will release all windows from the tabber.</entry>
</row>
<row>
<entry>add</entry>
<entry align="center">1</entry>
<entry>add the next window you click on to the tabber.</entry>
</row>
<row>
<entry>add</entry>
<entry align="center">2</entry>
<entry>add the next window to popup to the tabber.</entry>
</row>
<row>
<entry>add</entry>
<entry align="center">3</entry>
<entry>add every window you click on (until you press Esc) to the tabber.</entry>
</row>
<row>
<entry>kill</entry>
<entry align="center">1</entry>
<entry><fvwmref cmd="Close"/> the selected window.</entry>
</row>
<row>
<entry>kill</entry>
<entry align="center">2</entry>
<entry>causes FvwmTabs to try to kill the selected window itself.</entry>
</row>
<row>
<entry>kill</entry>
<entry align="center">3</entry>
<entry><fvwmref cmd="Destroy"/> the selected window.</entry>
</row>

</tbody>
</tgroup>
</informaltable>
</section>
</section>


<section id="menu">
<title>Menu Options</title>
<para>Mouse-1 on the "menu" button will bring up a menu of options:</para>

<para output="html"><imagedata fileref="images/FvwmTabs/menu.png"/></para>


<informaltable>
<tgroup cols='2'>
<thead>
<row>
<entry>Menu option</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>Release All</entry>
<entry>release all tabbed programs back to the window manager as standalone windows.</entry>
</row>
<row>
<entry>Release All (Iconify)</entry>
<entry>release all tabbed programs back to the window manager as iconised standalone windows.</entry>
</row>
<row>
<entry>Add</entry>
<entry>add the next mouse-clicked window to the tab-manager.</entry>
</row>
<row>
<entry>Add Next</entry>
<entry>add the next window that is created to the tab-manager.</entry>
</row>
<row>
<entry>Multi Add</entry>
<entry>keep adding mouse-clicked windows to a tab-manager until the escape key is pressed. Useful for adding multiple windows to a tab-manager at once.</entry>
</row>
<row>
<entry>Font</entry>
<entry>shows a sub-menu enabling you to dynamically configure the button/title/menu fonts, using the external program identified by the <emphasis>fontSelector</emphasis> option.</entry>
</row>
<row>
<entry>Options</entry>
<entry>shows a sub-menu with the following items:
<variablelist>
<varlistentry>
<term>Show Internal Titlebar</term>
<listitem><simpara>toggle the display of the titlebar below the tab-buttons.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Use Main Titlebar</term>
<listitem><simpara>set the titlebar of the FvwmTabs window to the title of the selected tab.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Auto Resize</term>
<listitem><simpara>Automatically resize all windows to the dimensions of the largest window in the tab-manager..</simpara></listitem>
</varlistentry>
<varlistentry>
<term>Swallow Overlapping (D&amp;D)</term>
<listitem><simpara>toggle the swallowing of overlapping windows.</simpara></listitem>
</varlistentry>
</variablelist>
</entry>



</row>
<row>
<entry>Window Tabizer Dialog</entry>
<entry>popup a dialog box for specifying windows to swallow. Windows can be specified explicitly (by name) or by using a (Perl) regular expression matcher. (Note: / character is automatically escaped.)</entry>
</row>
<row>
<entry><emphasis>window</emphasis></entry>
<entry>The menu options between the seperators will display the window/tab associated with the text. (The menu text is actually the title associated with the window. The text on each tab-button is the icon name.)</entry>
</row>
<row>
<entry>About</entry>
<entry>pops up a dialog with version/developer information.</entry>
</row>
<row>
<entry>Close</entry>
<entry>close the FvwmTabs window, invoking Release All in the process.</entry>
</row>
</tbody>
</tgroup>
</informaltable>

</section>

<section id="tutorial" output="html">
<title>Tutorial</title>

<section id="creating">
<title>Creating a tabber</title>
<para>If the FvwmTabs module is correctly installed/configured, press Ctrl-Alt-t and a little window that looks something like this should appear:</para>
<imagedata fileref="images/FvwmTabs/fvwmTabsEmpty.png"/>
<para>A new tabber is created every time Ctrl-Alt-t is pressed.</para>
</section>

<section id="adding">
<title>Adding windows to a tabber</title>
<para>There are a number of ways to add windows to a tabber:</para>

<itemizedlist>
<listitem>To add a <emphasis role="bold">single</emphasis> window to a tabber, click the <emphasis>add</emphasis> (orange) icon (or press <keysym>Ctrl-Alt-a</keysym> when the tabber is focussed). The mouse cursor will change to a crosshair. The next window selected (clicked on) will be swallowed by the tabber.
To cancel an add-window operation, press <keysym>Esc</keysym>.</listitem>
<listitem>To add <emphasis role="bold">multiple</emphasis> windows to a tabber, click the <emphasis>add</emphasis> (orange) icon with the right mouse button (or press <keysym>Ctrl-Alt-m</keysym> when the tabber is focussed). All windows that are selected (clicked on) until <keysym>Esc</keysym> is pressed, will be swallowed by the tabber.</listitem>

<listitem>Invoke the <ulink url="http://members.optusnet.com.au/~scottsmedley/fvwmtabs/tab.zsh">tab.zsh</ulink> script from a shell to swallow the next window that pops up. For example:
<para>
<command>
tab.zsh xterm -bg blue -fg white
tab.zsh gnome-calculator
</command>
</para>

The xterm and calculator window will automatically be swallowed into the tabber that last had the focus.
</listitem>

<listitem>Invoke the fvwm SwallowNew function. Syntax is:
<programlisting>
<fvwmref cmd="Function"/> SwallowNew tabberId <emphasis>fvwmCommand</emphasis>
</programlisting>
For example:
<programlisting>
<fvwmref cmd="Function"/> SwallowNew any <fvwmref cmd="Function"/> StartupBrowser
<fvwmref cmd="Function"/> SwallowNew lastFocus <fvwmref cmd="Exec"/> exec rxvt
<fvwmref cmd="Function"/> SwallowNew 2 <fvwmref cmd="Exec"/> exec gvim header.hh
</programlisting>
The fvwm command is executed when the tabber is ready to swallow the next window that is created.
</listitem>
</itemizedlist>

</section>


<section id="releasing">
<title>Releasing windows from a tabber</title>
<para>There are a number of ways to release windows from a tabber.</para>

<para>To release a <emphasis role="bold">single</emphasis> window from a tabber: </para>

<itemizedlist>
<listitem>Click the release (middle green) icon with the left mouse button.</listitem>
<listitem>Press <keysym>Ctrl-Alt-r</keysym> when the tabber is focussed.</listitem>
<listitem>Click the tab button for the window with the middle mouse button.</listitem>
<listitem>To release and iconify a window, click the tab button for the window with the right mouse button.</listitem>
</itemizedlist>
The first two release the selected window. The last two release the window the tab button is associated with.

<para>To release all windows from a tabber:</para>
<itemizedlist>
<listitem>Click the release (left green) icon with the middle mouse button.</listitem>
<listitem>To release and iconify all windows, click the release (left green) icon with the right mouse button.</listitem>
</itemizedlist>

</section>
</section>

<section id="bugs">
<title>Known Bugs</title>
<simpara>Tab-managers don't take focus when iconified.</simpara>
<simpara>FvwmTabs doesn't obey <fvwmref cmd="Style" opt="ClickToFocus"/> mode.</simpara>
<simpara>FvwmTabs has a problem swallowing shaded windows.</simpara>
<simpara>Using <fvwmref cmd="Maximize"/> to resize tab-manager windows prevents dynamic resizing from working.</simpara>
<para>Please send bug reports, feature requests and queries about FvwmTabs to the fvwm mailing list: <email>fvwm@fvwm.org</email>. Be sure to include the word "FvwmTabs" somewhere in the subject line.</para>
</section>

<section id="licence">
<title>Licence</title>
<para>FvwmTabs is GPL software.</para>
</section>

<section id="author">
<title>Author</title>
<para>Scott Smedley <email>ss@aao.gov.au</email></para>
</section>

</article>