.\" Automatically generated by Pod::Man version 1.15
.\" Tue Aug 13 13:39:53 2002
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "BELT 1"
.TH BELT 1 "perl v5.6.1" "2002-08-13" "User Contributed Perl Documentation"
.UC
.SH "NAME"
belt \- Configurable buttonmenu for X
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
belt [ options ]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Belt is a configurable \*(L"belt\*(R" that pops out a row of buttons for easy
access to programs. It is inspired by the Macintosh version.
.SH "USAGE"
.IX Header "USAGE"
The belt is retracted as default. By clicking on the belt button the
belt pops out revealing buttons. The user can then click on the
buttons on the belt to start the desired programs. Depending upon how
it is configured the belt may hide back after starting the program
using a left-click. Right-clicking always retracts the belt after
starting the program.
.SH "OPTIONS"
.IX Header "OPTIONS"
You don not have to type out the entire name of the option, as long as
it is unique. A boolean value is either the string \fItrue\fR or
\&\fIfalse\fR.
.Ip "\*(--overrideredirect boolean" 4
.IX Item "overrideredirect boolean"
Should the overrideredirect directive be used for the main window.
.Ip "\*(--unpost boolean" 4
.IX Item "unpost boolean"
Should the belt retract when a program is started from the buttons.
.Ip "\*(--autopost boolean" 4
.IX Item "autopost boolean"
Should the belt extract the when mouse cursor is over the extract
button. The time the mouse cursor has to be over the button is
specified by the \-\-autopostdelay option.
.Ip "\*(--autopostdelay integer" 4
.IX Item "autopostdelay integer"
Specifies the delay from the mouse cursor enter the button area to the
belt is extracted. If the cursor leaves the button within this time
the belt is not extracted.
.Ip "\*(--autounpost boolean" 4
.IX Item "autounpost boolean"
Should the belt retract the when mouse cursor leaves the belt. The
time the mouse cursor has to be out of the belt area is specified by
the \-\-autounpostdelay option.
.Ip "\*(--autounpostdelay integer" 4
.IX Item "autounpostdelay integer"
Specifies the delay from the mouse cursor leaves the button area to
the belt is retracted. If the cursor enters the area again within this
time the belt is not retracted.
.Ip "\*(--bhactive boolean" 4
.IX Item "bhactive boolean"
Sets whether the balloonhelp is active or not. The balloonhelp
shows the associated name for each button if active.
.Ip "\*(--bhdelay milliseconds" 4
.IX Item "bhdelay milliseconds"
Sets the time in milliseconds before a balloonhelp popup is
displayed for a button.
.Ip "\*(--bhmaindelay milliseconds" 4
.IX Item "bhmaindelay milliseconds"
Sets the time in milliseconds before a balloonhelp popup is
displayed for the mainbutton.
.Ip "\*(--bhbackground color" 4
.IX Item "bhbackground color"
Sets the background color for the balloonhelp popups.
.Ip "\*(--bhfont fontname" 4
.IX Item "bhfont fontname"
Sets the font for the balloonhelp popups.
.Ip "\*(--maxicons integer" 4
.IX Item "maxicons integer"
Sets the maximum number of icons allowed on the belt. If the number
of icons exceed this amount, arrows will appear to allow scrolling.
.Ip "\*(--dynamic boolean" 4
.IX Item "dynamic boolean"
Sets whether the program is affected by the \s-1WMMENUPATH\s0 environment
variable when searching for program definitions.
.Ip "\*(--ontop boolean" 4
.IX Item "ontop boolean"
Sets whether the belt should be on top, ie. if it should be raised as
soon as it gets focus.
.Ip "\*(--placement placement" 4
.IX Item "placement placement"
The placement of the belt. Should be one of the corners and not a
size specification, just a placement specification (ie. +0\-0).
.Ip "\*(--direction string" 4
.IX Item "direction string"
Which direction should the belt extend. The string can be \fIright\fR,
\&\fIleft\fR, \fIup\fR or \fIdown\fR. The belt does not extend outside the 
screen which can lead to unintuitive packing order for the buttons if
placement and directions does not match.
.Ip "\*(--icondirectory directory" 4
.IX Item "icondirectory directory"
The directory where the icons used by belt is located. This is \fInot\fR
neccessarily the locations of the programicons. They can be located
here but also in one of the directories specified by the \-\-iconpath
switch or by setting an absolute path in the \fImenu.conf\fR file. The
directory specified in by this switch is searched before any
directories in the \-\-iconpath path.
.Ip "\*(--iconpath path" 4
.IX Item "iconpath path"
A path to search for the icons used by belt.
.Ip "\*(--iconsize size" 4
.IX Item "iconsize size"
The size of the icons. All icons (except for the arrows) are expected
to be square. This is a limit of the largest icon. The icons can be
of different sizes, but the same size is preferred. Icons larger than
iconsize will be cropped.
.Ip "\*(--configdirectory directory" 4
.IX Item "configdirectory directory"
The location of the userconfiguration files. The directory name should
have a trailing slash. The directory name is subject to a primitive
form of tilde expansion.
.Ip "\*(--configfile filename" 4
.IX Item "configfile filename"
The filename of the configurationfile you wish to use if you do not 
want to use the default one.
.Ip "\*(--menufile filename" 4
.IX Item "menufile filename"
The filename of the local menu configuration file to be used. This
can be used if you want multiple instances of belt. Filename should
be relative to the directory specified by configdirectory.
.Ip "\*(--extracticons" 4
.IX Item "extracticons"
Extracts the special (arrow)icons to the current directory. They
should be moved to the directory where the special icons are to be
stored.
.Ip "\*(--verbose" 4
.IX Item "verbose"
Show the configuration and add errormessages.
.Ip "\*(--help" 4
.IX Item "help"
Show this help.
.SH "X RESOURCES"
.IX Header "X RESOURCES"
These are the X resources that affect the appearance of belt and the
default values.
.Ip "" 4
Belt*autopost:         false
.Ip "" 4
Belt*autopostdelay:    300
.Ip "" 4
Belt*autounpost:       false
.Ip "" 4
Belt*autounpostdelay:  1500
.Ip "" 4
Belt*unpost:           false
.Ip "" 4
Belt*bhactive:         true
.Ip "" 4
Belt*bhdelay:          1500
.Ip "" 4
Belt*bhmaindelay:      5000
.Ip "" 4
Belt*bhbackground:     yellow
.Ip "" 4
Belt*bhfont:           fixed
.Ip "" 4
Belt*maxicons:         8
.Ip "" 4
Belt*dynamic:          true
.Ip "" 4
Belt*ontop:            true
.Ip "" 4
Belt*placement:        +0\-0
.Ip "" 4
Belt*direction:        right
.Ip "" 4
Belt*icondirectory:    /usr/local/belt/icons/
.Ip "" 4
Belt*iconpath:         /misc/graphics/icons/reduced/48x48
.Ip "" 4
Belt*iconsize:         48
.Ip "" 4
Belt*configdirectory:  ~/.beltconf/
.Ip "" 4
Belt*configfile:       \fIresources\fR
.Ip "" 4
Belt*menufile:         \fImenu.conf\fR
.PP
They correspond directly to a command line option.
.SH "THE CONFIG FILES"
.IX Header "THE CONFIG FILES"
There are primarily two types of files. Program settings is generally
xresources and thus can lie in \fI.Xdefaults\fR/\fI.Xresources\fR or in the
resources file in the users configuration directory.
.PP
Button definitions follow the dynamic-menu style as in use at the
Unix system at E.KTH.SE. The files should be called \fImenu.conf\fR and
reside in a directory found in the \s-1WMMENUPATH\s0 or in the users configuration 
directory for local settings. The name of the local button 
definitions file can be overridden by the menufile directive.
.PP
The format of the \fImenu.conf\fR\-file is:
.PP
.Vb 1
\&  module|cat|text|miniicon|applicationclass|icon|executable
.Ve
Where \fImodule\fR is the name of the module, \fIcat\fR is one of the predefined
the category, \fItext\fR is the label in the final menu, \fIminiicon\fR is a 
small icon for use in the window decoration, \fIapplicationclass\fR is the 
X Window System class for the application, \fIicon\fR is the path and icon 
associated with the application and \fIexecutable\fR is the path, file and 
switches needed to run the program. Only \fItext\fR, \fIicon\fR and 
\&\fIexecutable\fR is used by belt. For example the line:
.PP
.Vb 1
\&  ||XtermWide|||/usr/local/graphics/xterm.xpm|/bin/X11/xterm -132
.Ve
is sufficient for use with belt. One should however specify all fields
if applicable.
.PP
Icons can either be specified with a full path or a relative path. If
the path is relative first the icons is searched for in the
icondirectory and then in the directories specified by iconpath.
.PP
If the first character on the line is a # the line is considered to be
a comment.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The programs default settings has the lowest priority. The default settings
can be overridden by xresources in the X resource database (ie \fI.Xdefaults\fR or
\&\fI.Xresources\fR). These can in turn be overridden by resources specified in the
sers configuration file, usually \fI~/.beltconf/resources\fR.
Command line options always override any previous settings.
.SH "MULTIPLE INSTANCES"
.IX Header "MULTIPLE INSTANCES"
It is possible to start several instances of belt. You should probably 
have different placement specifiers and/or direction specifiers. Also
it might be a good idea to have different menufiles for the different 
instances as well as using the dynamic directive to turn off dynamic
buttons from all instances but one.
.SH "SMALLER/LARGER ICONS"
.IX Header "SMALLER/LARGER ICONS"
By default the icons should be 48x48, as indicated by iconsize. The 
only exception are the special arrowicons \fI[\s-1UDRL\s0][\s-1SH\s0].gif\fR which are
just one third as wide (default is 48x16). You can create your own
icons and use them instead. The problem is that when you use the 
dynamic menu you cannot change icons for those entries. You can only
change icons for icons for the local button definitions. Suppose 
that you have some icons that are 24x24 and the local button definition
file is called \fIsmallmenu.conf\fR and resides in your configuration directory.
Also you have made some small versions of the special icons with size
24x8 for the arrows and 24x24 for \fInoicon.gif\fR. Then you can start belt
with the command:
.PP
.Vb 2
\&  belt --iconsize=24 --menufile=smallmenu.conf 
\&       --iconpath=/home/staff/max/belt/SmallIcons/:/misc/icons/small
.Ve
.SH "EXITING"
.IX Header "EXITING"
To quit the application you can double-click on the button which posts the 
button bar using the right mouse button while holding down the Control key.
Yes, it is a bit awkward but that combo you should not press by mistake.
.SH "RESTARTING"
.IX Header "RESTARTING"
If you have edited the configuration files and wish to restart belt 
double-click on the button which posts the button bar using the middle
button while holding down the Control key. This effectively destroys 
the old button bar and exec a new one with the same arguments as the
original one was started with.
.SH "FILES"
.IX Header "FILES"
.Ip "\fI\s-1DS\s0.gif\fR" 4
.IX Item "DS.gif"
Solid arrow pointing down (48x16).
.Ip "\fI\s-1US\s0.gif\fR" 4
.IX Item "US.gif"
Solid arrow pointing up (48x16).
.Ip "\fI\s-1RS\s0.gif\fR" 4
.IX Item "RS.gif"
Solid arrow pointing right (16x48).
.Ip "\fI\s-1LS\s0.gif\fR" 4
.IX Item "LS.gif"
Solid arrow pointing left (16x48).
.Ip "\fI\s-1DH\s0.gif\fR" 4
.IX Item "DH.gif"
Hollow arrow pointing down (48x16).   
.Ip "\fI\s-1UH\s0.gif\fR" 4
.IX Item "UH.gif"
Hollow arrow pointing up (48x16).
.Ip "\fI\s-1RH\s0.gif\fR" 4
.IX Item "RH.gif"
Hollow arrow pointing right (16x48).
.Ip "\fI\s-1LH\s0.gif\fR" 4
.IX Item "LH.gif"
Hollow arrow pointing left (16x48).
.Ip "\fInoicon.gif\fR" 4
.IX Item "noicon.gif"
Icon used when no icon is found.
.Ip "\fImenu.conf\fR" 4
.IX Item "menu.conf"
Default name for local configuration file.
.Ip "\fIresources\fR" 4
.IX Item "resources"
Name for local resource settings file, overriding X resources.
.Ip "\fI.Xdefaults\fR or \fI.Xresources\fR" 4
.IX Item ".Xdefaults or .Xresources"
where the normal X resources are stored
.SH "AUTHOR"
.IX Header "AUTHOR"
This software is Copyright 1999, 2000, 2001, 2002 by Max
Zomborszki. Full licence can be found at the top of the code.
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
Larry Wall for creating Perl and everyone making great modules for Perl.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIPerl\fR\|(1), X(1X)
.SH "KNOWN PROBLEMS"
.IX Header "KNOWN PROBLEMS"
Lots of bugs. The autopost/autounpost features have not been tested
extensively and initial versions had obvious problems.
.SH "BUGS"
.IX Header "BUGS"
Send bug reports to max@e.kth.se