Stricter file handling when following Read statements (fvwm-convert-2.6).

[fvwm.git] / modules / FvwmTabs / FvwmTabs.pod

# Generate this man page with:
#
# pod2man -c "Fvwm Modules" -r "FvwmTabs" FvwmTabs.pod >! FvwmTabs.1
#
# View this man page with:
#
# pod2man -c "Fvwm Modules" -r "FvwmTabs" FvwmTabs.pod | nroff -man | less
#
# Generate a HTML version of the man page with:
#
# pod2html -t "FvwmTabs" FvwmTabs.pod >! FvwmTabs.man.html


=head1 NAME

B<FvwmTabs> - a generic tabbing module for the fvwm window manager.

=head1 SYNOPSIS

B<FvwmTabs> is spawned by fvwm, so no command line invocation is possible.

=head1 DESCRIPTION

The B<FvwmTabs> module is capable of swallowing any fvwm window & treating it as a tab in a I<tab-manager> window. A tab-manager is sometimes called a I<tabber>.

Each tab-manager can store any number of windows, each in its own I<tab>. 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.)

=head1 INVOCATION

B<FvwmTabs> can be invoked by inserting the line C<Module FvwmTabs> in your .fvwmrc file. This can be placed on a line by itself, if B<FvwmTabs> is to be spawned during fvwm's initialization, or can be bound to a menu or mouse button or keystroke to invoke it later.

=head1 INSTALLING DEPENDENCIES

B<FvwmTabs> requires 2 CPAN modules (that are NOT distributed with fvwm) to be installed on your system. They are I<Tk> and I<X11::Protocol>.

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

To install either package:

tar zxvf $name.tar.gz ; cd $name ; perl Makefile.PL ; make install

B<FvwmTabs> will tell you if you do not have these packages installed when you (try to) start it.

=head1 CONFIGURATION OPTIONS

B<FvwmTabs> reads the same config file as fvwm when it starts up.

The following options are recognised by B<FvwmTabs>:

=over

=item E<42>FvwmTabs: activeFG I<color>

The text color of the button for the visible tab. The default color is yellow.

=item E<42>FvwmTabs: activeBG I<color>

The backgound color of the button for the visible tab. The default color is MidnightBlue.

=item E<42>FvwmTabs: inactiveFG I<color>

The text color of the buttons for the invisible tabs. The default color is antiquewhite.

=item E<42>FvwmTabs: inactiveBG I<color>>

The backgound color of the buttons for the invisible tabs. The default color is royalblue.

=item E<42>FvwmTabs: titleFG I<color>

The text color used in the titlebar. The default color is black.

=item E<42>FvwmTabs: titleBG I<color>

The background color used in the titlebar. The default color is antiquewhite.

=item E<42>FvwmTabs: activeRelief I<style>

The relief style to use for active buttons. I<style> can be either I<raised>, I<flat> or I<sunken>. The default style is I<sunken>.

=item E<42>FvwmTabs: inactiveRelief I<style>

The relief style to use for inactive buttons. I<style> can be either I<raised>, I<flat> or I<sunken>. The default style is I<flat>.

=item E<42>FvwmTabs: buttonYPadding I<pixels>

How much padding to use around top and bottom of tab buttons. The default value is I<3> pixels.

=item E<42>FvwmTabs: pollRate I<ms>

Specifies how often to check for X events. I<ms> is time in milliseconds. The default value, I<250>, should be fine for most users. If you are on a very slow machine you may wish to increase this.

=item E<42>FvwmTabs: buttonFont I<font>

The font to use on the tab buttons. The default font is I<Helvetica -12 bold>.

=item E<42>FvwmTabs: titleFont I<font>

The font to use on the titlebar. The default font is I<Helvetica -12>.

=item E<42>FvwmTabs: menuFont I<font>

The font to use on the menus. The default font is I<Helvetica -12>.

=item E<42>FvwmTabs: fontSelector I<fontProgram>

The external font chooser program to launch when dynamically changing fonts. The default I<fontProgram> is I<gfontsel --print -f "%f">. Anti-gnome users might try I<xfontsel -print -pattern "%f">. If set to I<none>, no font menu options will appear.

=item E<42>FvwmTabs: autoSwallowClass I<className> [I<tabManagerId>], ...

=item E<42>FvwmTabs: autoSwallowResource I<resourceName> [I<tabManagerId>], ...

=item E<42>FvwmTabs: autoSwallowName I<name> [I<tabManagerId>], ...

Specify windows to swallow automatically. These are comma-separated lists that specify the class/resource/name of a window & 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 I<NewTabber> 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 I<className>/I<resourceName>/I<name> can be a (Perl) regular expression.

=item E<42>FvwmTabs: balloonBG I<color>

The backgound color of the balloon popups that appear over the tab buttons. The default color is I<#C0C080>.

=item E<42>FvwmTabs: balloonFont I<font>

The font to use on the balloon popups. The default font is I<Helvetica -12>.

=item E<42>FvwmTabs: balloonWait I<ms>

How long the mouse cursor must pause (in milliseconds) over a tab button before the balloon pops up. The default value is I<250>.

=item E<42>FvwmTabs: balloonMsg I<msg>

Message to display in balloon popups. The default value is I<%tabNo:\n%iconText\n%title>.

=item E<42>FvwmTabs: autoResize I<bool>

I<bool> can be either I<true> or I<false>. If true, windows in the tab-manager automatically resize to the dimensions of the largest window in the tab-manager. The default value is I<false>. 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.

=item E<42>FvwmTabs: stateFile I<file>

B<FvwmTabs> has the ability to preserve its state (ie. remember the windows it has swallowed as tabs) b/w fvwm restarts. I<file> specifies the name of a temporary file to record the state in, so it can be reconstructed when B<FvwmTabs> restarts. The default file is C<$FVWM_USERDIR/.fvwmtabs.state>.

=item E<42>FvwmTabs: fixedSizeTabs I<bool>

I<bool> can be either I<true> or I<false>. 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 I<false>.

=item E<42>FvwmTabs: showTitlebar I<bool>

Show internal titlebar. If set to I<true> a titlebar appears below the row of tab-buttons & displays the title associated with the current window. This titlebar is capable of displaying long or multi-line titles. The default value is I<true>.

=item E<42>FvwmTabs: useTMTitlebar I<bool>

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 I<true>.

=item E<42>FvwmTabs: dragDropIcon I<imageFile>

Specify the icon to display when performing a drag-&-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 I<none>. If I<none> (or an invalid file) is specified a E<42> is used.

=item E<42>FvwmTabs: bBuggyFocus I<bool>

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 I<true>. 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.

=item E<42>FvwmTabs: enableSwallowDND I<bool>

Swallow windows that (are moved to) overlap a tabber.
Note: drag-&-drop can be enabled for individual tabbers via the menu.
The default value is I<true>.

=item E<42>FvwmTabs: swallowDNDTolerance I<tol>

Determines how much a window must overlap a tabber
for it to be swallowed when drag-&-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 I<10> (pixels).

=item E<42>FvwmTabs: useIconsOnTabs I<bool>

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
should be rectified in the near future.
The default value is I<true>.

=item E<42>FvwmTabs: killIcon I<image>

Image to use on kill toolbar button. Default is I<none>.

=item E<42>FvwmTabs: addIcon I<image>

Image to use on add toolbar button. Default is I<none>.

=item E<42>FvwmTabs: swallowIcon I<image>

Image to use on add toolbar button when tabber will swallow next window to popup. Default is I<none>. By using a separate icon to I<addIcon>, this option provides visual feedback on when a tabber will unconditionally swallow the next window to popup.

=item E<42>FvwmTabs: releaseIcon I<image>

Image to use on release toolbar button. Default is I<none>.

=item E<42>FvwmTabs: menuIcon I<image>

Image to use on menu toolbar button. Default is I<none>.

=back

=head1 FVWM FUNCTIONS FOR KEY BINDINGS

A number of fvwm functions are available once the B<FvwmTabs> module is started.

=over

=item NewTabber

Create a new tabber. Optional argument is tabber name. No whitespace is allowed in the tabber name. Can also prefix --geometry argument.

Example: NewTabber --geometry=+200+400 scottie

=item Tabize

Add a window (as a tab) to a tabber.

=item NextTab

Show/select the next tab.

=item PrevTab

Show/select the previous tab.

=item LastTab

Show/select the last selected tab (if there was one).

=item ReleaseTab

Release a tabbed window back to fvwm.

=item ReleaseIconifyTab

Release a tabbed window back to fvwm & iconify it.

=item ReleaseAllTabs

Release all windows in a tab-manager back to fvwm.

=item ReleaseIconifyAllTabs

Release all windows in a tab-manager back to fvwm & iconify them.

=item CloseTabber

Destroy a tab-manager. All windows in the tab-manager are released back to fvwm.

=item AddTab

Pick a new window to add to a tab-manager. Selecting this option & clicking on a window will add the selected window to the tab-manager.

=item MultiAddTab

Pick & add new windows to a tab-manager until ESC is pressed.

=item ShowTab I<tabNo>

Show/select tab I<tabNo> in the tab-manager. I<tabNo> is zero-based. ie. 0 is the first tab, 1 is the second, etc.

=item AddToTabber

Add a window (as a tab) to a tab-manager.

=item SwapLeft

Swap the selected window with the window on its immediate left.

=item SwapRight

Swap the selected window with the window on its immediate right.

=item SelectTabber

Select a tab-manager for a new window to be added to.

=item EnableDND

Swallow windows that (are moved to) overlap a tabber.

=back

=head1 KEY BINDINGS

By default, B<FvwmTabs> reads a default user configuration file F<FvwmTabs-DefaultSetup> which defines several useful key-bindings for B<FvwmTabs>. You can tell B<FvwmTabs> NOT to read this file with C<SetEnv FvwmTabs_NoDefaultSetup> - this environment variable must be set I<before> starting the module.

All of the key bindings can be changed using the standard fvwm I<Key> command & making use of the aforementioned fvwm functions. ie.

Key (FvwmTabs*) A A CM Function AddTab

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.

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

=over

=item Ctrl-Alt-a

AddTab

=item Ctrl-Alt-c

CloseTabber

=item Ctrl-Alt-i

ReleaseIconifyTab

=item Ctrl-Alt-Shift-I

ReleaseIconifyAllTabs

=item Ctrl-Alt-l

LastTab

=item Ctrl-Alt-m

MultiAddTab

=item Ctrl-Alt-n & Ctrl-Alt-Tab

NextTab

=item Ctrl-Alt-p

PrevTab

=item Ctrl-Alt-r

ReleaseTab

=item Ctrl-Alt-Shift-R

ReleaseAllTabs

=item Ctrl-Alt-t

NewTabber

=item Ctrl-Alt-I<num>

ShowTab I<num>.

=item Ctrl-Alt-Left

SwapLeft

=item Ctrl-Alt-Right

SwapRight

=back

=head1 MOUSE BINDINGS

=head2 Mouse bindings on Tab Buttons

I<Mouse-1> on a tab-button displays the window associated with the tab.

I<Mouse-2> on a tab-button releases the window associated with the tab back to the window manager as a standalone window.

I<Mouse-3> on a tab-button releases the window associated with the tab back to the window manager & iconifies it.

The tab-buttons can be reordered with a drag-&-drop operation initiated with I<Ctrl-Mouse-2>. A dragged tab is inserted before the tab-button onto which it is dropped.

=head2 Mouse bindings on Toolbar Icons

I<Mouse-1> on the "menu" button will bring up a menu of options. See MENU BINDINGS.

I<Mouse-1> on the "release" button will release the selected window from the tabber.

I<Mouse-2> on the "release" button will release all windows from the tabber, and iconify them.

I<Mouse-3> on the "release" button will release all windows from the tabber.

I<Mouse-1> on the "add" button will add the next window you click on to the tabber.

I<Mouse-2> on the "add" button will add the next window to popup to the tabber.

I<Mouse-3> on the "add" button will add every window you click on (until you press Esc) to the tabber.

I<Mouse-1> on the "kill" button will I<Close> the selected window.

I<Mouse-2> on the "kill" button causes I<FvwmTabs> to try to kill the selected window itself.

I<Mouse-3> on the "kill" button will I<Kill> the selected window.


=head1 MENU BINDINGS

I<Mouse-1> on the "menu" button will bring up a menu of options:

I<Release All> will release all tabbed programs back to the window manager as standalone windows.

I<Release All (Iconify)> will release all tabbed programs back to the window manager as iconised standalone windows.

I<Add> will add the next mouse-clicked window to the tab-manager.

I<Add Next> will add the next window that is created to the tab-manager.

I<Multi Add> keeps 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.

I<Font> shows a sub-menu enabling you to dynamically configure the button/title/menu fonts, using the external program identified by the I<fontSelector> option.

I<Show Titlebar> toggles the display of the titlebar below the tab-buttons.

I<Window Tabizer Dialog> will 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.)

The menu options between the separators 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.)

I<About> pops up a dialog with version/developer information.

I<Close> will close the B<FvwmTabs> window, invoking Release All in the process.

=head1 BUGS

=over

=item *
Tab-managers don't take focus when iconified.

=item *
FvwmTabs doesn't obey C<ClickToFocus> mode.

=item *
FvwmTabs has a problem swallowing shaded windows.

=item *
Using C<Maximise> to resize tab-manager windows prevents dynamic resizing from working.

=back

Please send bug reports, feature requests & queries about B<FvwmTabs> to the fvwm mailing list: I<fvwm@fvwm.org>. Be sure to include the word "FvwmTabs" somewhere in the subject line.

=head1 TODO

Features to be added to B<FvwmTabs> in the future (in no particular order):

=over

=item *
Colorset support. (use Colorset tracker from fvwm-perllib)

=item *
Use Ctrl-Mouse-1 instead of Ctrl-Mouse-2 to reorder (drag-&-drop) windows.

=item *
option: menu item to sort tabs by name, file extension, etc.

=item *
For autoSwallow options that specify a tab-manager, create the tab-manager if it doesn't already exist. (default behaviour is not to swallow it)

=back

=head1 FVWMTABS HOMEPAGE

There is some useful information about FvwmTabs, including a short tutorial, on the authors website:

L<http://members.optusnet.com.au/~scottsmedley/fvwmtabs/>.

=head1 LICENSING

B<FvwmTabs> is GPL software.

See L<http://www.gnu.org/licenses/gpl.html>

=head1 AUTHOR

Scott Smedley
<ss@aao.gov.au>