cvsimport

[fvwm.git] / modules / FvwmTaskBar / FvwmTaskBar.1.in

.\" t
.\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
.TH FvwmTaskBar 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
.UC
.SH NAME
FvwmTaskBar \- the fvwm taskbar module
.SH SYNOPSIS
\fBFvwmTaskBar\fP [\fIname\fP]

FvwmTaskBar is spawned by fvwm, so no command line invocation will work.

.SH DESCRIPTION
The FvwmTaskBar module provides a taskbar made up of buttons arranged by
rows, each corresponding to a window that fvwm is managing.
Clicking on first button gives focus to the corresponding top level window;
clicking on the middle button will hide a top level window; third mouse button
is reserved for a future extension (context menu).
Like the other modules, FvwmTaskBar only works when fvwm is used as the
window manager.

When started, the taskbar shows up as a single row of buttons filling the
full width of the screen, but during the work can be resized to accommodate
up to 8 rows. In addition, if the AutoStick option is used, the taskbar
will auto position itself at the top or bottom of the screen, and can be
dragged from one position to another with a normal move operation.

The first button of the taskbar, labelled "Start" sends a "Popup
StartMenu" command to the fvwm, which can be used to pop-up a
general-purpose menu when the button is pressed.

The FvwmTaskBar also displays at the right side a window showing the
current time and the built-in incoming mail indicator.

.SH COPYRIGHTS
The FvwmTaskBar module is derived from Mike Finger's FvwmWinList.

Copyright 1994, Mike Finger. The author makes no guarantees or warranties of
any kind about the use of this module.  Use this module at your own risk.
You may freely use this module or any portion of it for any purpose as long
as the copyright is kept intact.

.SH INITIALIZATION
During initialization, \fIFvwmTaskBar\fP gets configuration information
from fvwm to find the options that pertain to it.
These options are discussed in a later section.

.SH INVOCATION
FvwmTaskBar can be invoked by fvwm during initialization by inserting the
line 'Module FvwmTaskBar' in the .fvwm2rc file.

FvwmTaskBar must reside in a directory that is listed in the ModulePath
option of fvwm for it to be executed by fvwm.

.SH CONFIGURATION OPTIONS
The following options can be placed in the .fvwm2rc file

.IP "*FvwmTaskBar: Geometry \fI{+-}<X>{+-}<Y>\fP"
Specifies the location and gravity of the FvwmTaskBar window.
Currently, this option is scanned as a normal X geometry string.
You can include the width and the height in addition to the "x" and
"y" offset.  However, only the "x" and "y" offset are used.
To avoid possible future compatibility problems, only code the "x" and
"y" offset.

The actual width of the taskbar is always the full width of the screen
and the height is controlled by the *FvwmTaskBar: Rows option.

If the AutoStick option
is specified, the taskbar automatically "sticks" to the top or
the bottom of the screen, whichever is closest to the geometry specification.

To position the taskbar at the bottom of the screen, use a geometry of
"+0-0".

.IP  "*FvwmTaskBar: Rows r"
Specifies the initial number in rows of the FvwmTaskBar window. Default
is 1 and the maximum is 8.

.IP "*FvwmTaskBar: Font \fIfont\fP"
Specifies the default font to be used for labeling the buttons, when they
are not depressed. If not specified, fixed font is assumed.

.IP "*FvwmTaskBar: SelFont \fIfont\fP"
Specifies the font to be used for the depressed buttons. Note that the
Start button will always use this font even if is not pressed. If this
option is not specified, the default font is used instead.

.IP "*FvwmTaskBar: StatusFont \fIfont\fP"
Specifies the font to be used for the clock and tip windows. If this
option is not specified, fixed font is used.

.IP "*FvwmTaskBar: Fore \fIcolor\fP"
Specifies the color to use for the button names.

.IP "*FvwmTaskBar: Back \fIcolor\fP"
Specifies the background color for the bar and buttons.

.IP "*FvwmTaskBar: Colorset \fIcolorset\fP"
Tells the module to use colorset \fIcolorset\fP for the window
background and the foreground color of the buttons.  Please refer
to the man page of the FvwmTheme module for details about colorsets.

.IP "*FvwmTaskBar: IconFore \fIcolor\fP"
Specifies the color to use for the button names which represent iconified
windows.

.IP "*FvwmTaskBar: IconBack \fIcolor\fP"
Specifies the color to use for the buttons which represent iconified windows.

.IP "*FvwmTaskBar: IconColorset \fIcolorset\fP"
Tells the module to use colorset \fIcolorset\fP for the
buttons of iconified windows.  Please refer to the man page of
the FvwmTheme module for details about colorsets.

.IP "*FvwmTaskBar: FocusFore \fIcolor\fP"
Specifies the color to use for the button which represents the window
with the focus.  If not specified the color specified by *FvwmTaskBar: Fore or
*FvwmTaskBar: Colorset is used.

.IP "*FvwmTaskBar: FocusBack \fIcolor\fP"
Specifies the color to use for the button which represents the window
with the focus. If not specified the color specified by  *FvwmTaskBar: Back or
*FvwmTaskBar: Colorset is used. Note that the button which represents the window
with the focus is also highlighted.  See "*FvwmTaskBar: NoBrightFocus".

.IP "*FvwmTaskBar: FocusColorset \fIcolorset\fP"
Tells the module to use colorset \fIcolorset\fP for the button
which represents the window with the focus. Please refer to the man page of
the FvwmTheme module for details about colorsets.

.IP "*FvwmTaskBar: NoBrightFocus"
By default the button which represents the window with the focus is
highlighted. This option disables this feature.  \fINote:\fP you will
want this option if you use a pixmap (via FvwmTheme) for the background.

.IP "*FvwmTaskBar: TipsFore \fIcolor\fP"
Specifies the color to be used for the text in the tips windows.

.IP "*FvwmTaskBar: TipsBack \fIcolor\fP"
Specifies the background color for the tips windows.

.IP "*FvwmTaskBar: TipsColorset \fIcolorset\fP"
Tells the module to use colorset \fIcolorset\fP for the tips windows.
Please refer to the man page of the FvwmTheme module for details about
colorsets.

.IP "*FvwmTaskBar: AutoStick"
This option causes the taskbar to "stick" either to the top or bottom
of the screen, whichever is closest to the initial window placement. Any
further move operation is also subject to that behavior.

.IP "*FvwmTaskBar: AutoFocus"
This option causes the taskbar to raise a window if the cursor stays on a
button in taskbar and its tip is open.

.IP "*FvwmTaskBar: AutoHide [\fIpixels\fP]"
This option causes the taskbar to disappear leaving a narrow strip at the
bottom of the screen, and reappear only when the mouse is moved to that
strip.  This option automatically enables AutoStick.  The optional
\fIpixels\fP parameter specifies thickness of a strip (3 pixels by default).

.IP "*FvwmTaskBar: UseSkipList"
Tells FvwmTaskBar to not show the windows that are listed on a WindowListSkip
line in the configuration file.

.IP "*FvwmTaskBar: DeskOnly"
Tells FvwmTaskBar to show only windows that are on the current desktop.
When desktops are switched, the list of windows changes accordingly.

.IP "*FvwmTaskBar: PageOnly"
Tells FvwmTaskBar to show only windows that are on the same page
as the task bar.
When a window enters or leaves the page, the list of windows changes
accordingly.

.IP "*FvwmTaskBar: ScreenOnly"
Tells FvwmTaskBar to show only windows that are only on the same
Xinerama screen as the task bar.  When a window enters or leaves the
screen, the list of windows changes accordingly.

.IP "*FvwmTaskBar: UseIconNames"
Tells FvwmTaskBar to use the icon name of the window instead of the full
window name.  This is useful to keep the width of the buttons small.

.IP "*FvwmTaskBar: ShowTransients"
Tells FvwmTaskBar to show the application transient windows also. By default
they are not shown.

.IP "*FvwmTaskBar: Action \fIaction response\fP"
Tells FvwmTaskBar to do \fIresponse\fP when \fIaction\fP is done.  The
currently supported \fIaction\fPs are: Click1, Click2, Click3 and so on.
By default the module supports 5 mouse buttons, but it can be compiled
to support more.  The currently
supported \fIresponse\fPs are any fvwm built-in commands, including modules
and functions.  Warning: Use of the former syntax that allowed to use comma
separated lists of commands is strongly discouraged due to synchronization
problems with fvwm.  Please use complex fvwm functions instead (defined with
the AddToFunc command of fvwm).

In the \fIresponse\fP part, you can use a number of predefined
variables: \fI$left\fP, \fI$right\fP, \fI$top\fP and \fI$bottom\fP
are substituted by the left, right, top and bottom coordinates of
the button pressed. \fI$-left\fP, \fI$-right\fP, \fI$-top\fP and
\fI$-bottom\fP are substituted likewise, but the coordinates are
calculated from the bottom or the right edge of the screen instead
(for a button that is 5 pixels away from the right screen border,
$-right will be 5). \fI$width\fP and \fI$height\fP are replaced by
the width or height of the button.  All this is done regardless of
any quoting characters. To get a literal '$' use the string '$$'.

.IP "*FvwmTaskBar: Button Title \fItitle\fP, Icon \fIicon\fP, Action \fIaction\fP"
Tells FvwmTaskBar to put a shortcut minibutton in the taskbar that does
\fIaction\fP when clicked.  The icon can have a caption denoted by \fItitle\fP,
an icon denoted by \fIicon\fP, or a combination of the two.  The icons will
appear to the immediate right of the start button, and will appear in the
order that they are declared in the .fvwm2rc file.

To invoke different commands for different mouse clicks, use this syntax:

.nf
.sp
*FvwmTaskBar: Button Title \fItitle\fP, Icon \fIicon\fP, \\
              Action (Mouse 1) \fIaction1\fP, Action (Mouse 2) \fIaction2\fP
.sp
.fi

.IP "*FvwmTaskBar: ButtonWidth \fIwidth\fP"
Indicates the maximum width that window buttons should reach.
(the minimum is hard coded at 32).

.IP "*FvwmTaskBar: Pad \fIwidth\fP"
Specifies the space (in pixels) between the window buttons. If this option is
not specified, the default space is 3.

.IP "*FvwmTaskBar: WindowButtonsLeftMargin \fImargin\fP"
Specifies the space (in pixels) between the left side of the left-most window
button and the right side of the start button or right-most shortcut
minibutton.  If this option is not specified, the default margin is 4.

.IP "*FvwmTaskBar: WindowButtonsRightMargin \fImargin\fP"
Specifies the space (in pixels) between the right side of the right-most
window button and the left side of the clock and tip window.  If this option
is not specified, the default margin is 2.

.IP "*FvwmTaskBar: StartButtonRightMargin \fImargin\fP"
Specifies the space (in pixels) between the right side of the start button
and the left side of the left-most shortcut minibutton.  If this option is
not specified, the default margin is 0.

.IP "*FvwmTaskBar: 3DFvwm"
By default the buttons use a special (asymmetric) 3D look. This option enables
a more classical 3D look (Ie., a la fvwm).

.IP "*FvwmTaskBar: HighlightFocus"
If the mouse pointer is over the taskbar, the window under the current
button is active. This behavior is like the TVTWM Icon Manager or
FvwmIconMan. \fINote:\fP If you use this option combined with FollowMouse
focus style, you'll want the taskbar to be ClickToFocus.

.IP "*FvwmTaskBar: ShowTips"
Enables the tips windows (by default disabled).

.IP "*FvwmTaskBar: NoIconAction \fIaction\fP"
Tells FvwmTaskBar to do \fIaction\fP is when a NoIcon style window is
iconified or de-iconified. Relevant coordinates are appended to \fIaction\fP so
that the icon can be traced to an FvwmTaskBar button. An example action
is "*FvwmTaskBar: NoIconAction SendToModule FvwmAnimate animate". A blank or
null action turns this feature off.

.SH ""

The following options deal more specifically with the status indicators
displayed at the right of the taskbar.

.IP "*FvwmTaskBar: ClockFormat \fIformat-string\fP"
This option specifies the time format for the digital clock.
It is a \fIstrftime(3)\fP compatible format string.
By default it is "%R". There is a 24 character limit for string
expansion. The string depends of locale settings.

.IP "*FvwmTaskBar: DateFormat \fIformat-string\fP"
This option specifies the date and/or time format for clock tip.
It is a \fIstrftime(3)\fP compatible format string.
By default it is "%A, %B %d, %Y". There is 40 characters limit for
string expansion. The string depends of locale settings now.

.IP "*FvwmTaskBar: UpdateInterval \fIseconds\fP"
Specifies how often the clock display should be refreshed, so that times of
the form HH:MM:SS can be used. By default 60 seconds.

.IP "*FvwmTaskBar: BellVolume \fIvolume\fP"
This sets the volume of the bell when mail is detected.
It is a value between 0 (no bell) and 100 (maximum volume).
By default it is set to 20.

.IP "*FvwmTaskBar: MailBox \fIpath\fP"
This option instructs the module to look for mail at the specified place.
It is a full pathname to the user's mailbox.
By default it is \fI/var/spool/mail/$USER_LOGIN\fP.
A value of 'None' instructs the module not to have a mail indicator.

.IP "*FvwmTaskBar: MailDir"
By default format of the user's mailbox is mbox. If this option is
specified, the maildir format is used instead.

.IP "*FvwmTaskBar: MailCommand \fIcommand\fP"
Specifies a \fIfvwm\fP command to be executed when double-clicking
on the mail icon.

.IP "*FvwmTaskBar: MailCheck \fIseconds\fP"
Specifies the interval between checks for new mail. The default is
ten seconds. A value of zero or less switches mail checking off.

Note, this value is only relable when greater than the \fIUpdateInterval\fP
value. The mail check is done either on any redraw (like a focus change)
or every nearest factor of the \fIUpdateInterval\fP value.

.IP "*FvwmTaskBar: IgnoreOldMail"
If set, draw no bitmap if there is no new mail.

.SH ""
The following options deal with the Start button at the left of the taskbar:

.IP "*FvwmTaskBar: StartCommand \fIcommand\fP"
This option specifies a command to run when the start button is
pressed.  Some strings are replaced in the command when it is
executed like for the other buttons.  See
.B Action
for details.  If both,
.BR StartCommand " and " StartMenu
have been defined, the command is executed first and the menu is
opened afterwards.  The
.B StartCommand
can be used to exactly place a menu atop a button.

.nf
.sp
*FvwmTaskBar: StartCommand Popup StartMenu rectangle \\
        $widthx$height+$left+$top 0 -100m
.sp
.fi

To invoke different commands for different mouse clicks, use this syntax:

.nf
.sp
*FvwmTaskBar: StartCommand (Mouse 1) Popup Mouse1Menu
*FvwmTaskBar: StartCommand (Mouse 3) Popup Mouse3Menu
.sp
.fi

.IP "*FvwmTaskBar: StartName \fIstring\fP"
This option specifies the string displayed in the Start button.
('Start' by default). If the string is omitted no string is
displayed.

.IP "*FvwmTaskBar: StartMenu \fIstring\fP"
This option specifies the pop up menu to invoke when the start button is
pressed. ('StartMenu' by default). The module send a 'Popup StartMenu'
command to the fvwm window manager.

To invoke different menus for different mouse clicks, use this syntax:

.nf
.sp
*FvwmTaskBar: StartMenu (Mouse 1) Mouse1Menu
*FvwmTaskBar: StartMenu (Mouse 3) Mouse3Menu
.sp
.fi

.IP "*FvwmTaskBar: StartIcon \fIicon-name\fP"
This option specifies the name of the icon to display at the left of the Start
button.

.IP "*FvwmTaskBar: NoDefaultStartButton"
This option removes the default start button if no start button configuration
options are given. It is useful to remove the start button. Note that this is
the default if you use the Button configuration option.

.SH SAMPLE CONFIGURATION
The following are excerpts from a .fvwm2rc file which describe FvwmTaskBar
initialization commands:

.nf
.sp
#
# Start the taskbar on fvwm startup and restart
#

AddToFunc "StartFunction" "I" Module FvwmTaskBar

#
# For Click 1 action
#

AddToFunc DeiconifyRaiseAndFocus
+ I Iconify off
+ I Raise
+ I Focus

#
# Set the style for the taskbar window, keep always on top of another
# windows
#

Style "FvwmTaskBar" NoTitle,BorderWidth 4, HandleWidth 4,Sticky,\\
StaysOnTop,WindowListSkip,CirculateSkip

#------------------------------------ taskbar
*FvwmTaskBar: Back #c3c3c3
*FvwmTaskBar: Fore black
*FvwmTaskBar: TipsBack bisque
*FvwmTaskBar: TipsFore black
*FvwmTaskBar: Geometry +0-0
*FvwmTaskBar: Font -adobe-helvetica-medium-r-*-*-14-*-*-*-*-*-*-*
*FvwmTaskBar: SelFont -adobe-helvetica-bold-r-*-*-14-*-*-*-*-*-*-*
*FvwmTaskBar: StatusFont fixed

*FvwmTaskBar: Action Click1 DeiconifyRaiseAndFocus
*FvwmTaskBar: Action Click2 Iconify On
*FvwmTaskBar: Action Click3 Lower

*FvwmTaskBar: UseSkipList
*FvwmTaskBar: UseIconNames
*FvwmTaskBar: AutoStick
*FvwmTaskBar: ShowTips
*FvwmTaskBar: NoIconAction SendToModule FvwmAnimate animate

*FvwmTaskBar: ButtonWidth 180
*FvwmTaskBar: BellVolume 20
*FvwmTaskBar: MailBox /var/spool/mail/
*FvwmTaskBar: MailCommand Exec xterm -e mail
*FvwmTaskBar: ClockFormat %I:%M %p

*FvwmTaskBar: StartName Start
*FvwmTaskBar: StartMenu StartMenu
*FvwmTaskBar: StartIcon mini-exp.xpm

*FvwmTaskBar: Button Title Mozilla, Action exec exec /usr/local/mozilla/mozilla
*FvwmTaskBar: Button Icon mini.term.xpm, Action exec exec xterm
*FvwmTaskBar: Button Title Freeamp, Icon mini.cd.xpm, Action exec exec freeamp

.sp
.fi

.SH BUGS
There is a bug report that FvwmTaskBar doesn't work well with
auto hide turned on.

.SH AUTHOR
.IP "\fIDavid Barth\fP <barth@di.epfl.ch>"

.SH ACKNOWLEDGMENTS
These people have contributed to \fBFvwmTaskBar\fP:

.IP "\fIDanny Dulai\fP <nirva@ishiboo.com>"
.IP "\fIfvwm workers\fP <fvwm-workers@fvwm.org>"