BELT-1.21(1)

NAME
belt - Configurable buttonmenu for X

SYNOPSIS
belt [ options ]

DESCRIPTION
Belt is a configurable "belt" that pops out a row of buttons for easy access to programs. It is inspired by the Macintosh version.

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.

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 true or false.

--overrideredirect boolean
    Should the overrideredirect directive be used for the main window.

--unpost boolean
    Should the belt retract when a program is started from the buttons.

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

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

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

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

--bhactive boolean
    Sets whether the balloonhelp is active or not. The balloonhelp shows the associated name for each button if active.

--bhdelay milliseconds
    Sets the time in milliseconds before a balloonhelp popup is displayed for a button.

--bhmaindelay milliseconds
    Sets the time in milliseconds before a balloonhelp popup is displayed for the mainbutton.

--bhbackground color
    Sets the background color for the balloonhelp popups.

--bhfont fontname
    Sets the font for the balloonhelp popups.

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

--dynamic boolean
    Sets whether the program is affected by the WMMENUPATH environment variable when searching for program definitions.

--ontop boolean
    Sets whether the belt should be on top, ie. if it should be raised as soon as it gets focus.

--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).

--direction string
    Which direction should the belt extend. The string can be right, left, up or down. 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.

--icondirectory directory
    The directory where the icons used by belt is located. This is not 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 menu.conf file. The directory specified in by this switch is searched before any directories in the --iconpath path.

--iconpath path
    A path to search for the icons used by belt.

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

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

--configfile filename
    The filename of the configurationfile you wish to use if you do not want to use the default one.

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

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

--verbose
    Show the configuration and add errormessages.

--help
    Show this help.

X RESOURCES
These are the X resources that affect the appearance of belt and the default values.

•   Belt*autopost: false

•   Belt*autopostdelay: 300

•   Belt*autounpost: false

•   Belt*autounpostdelay: 1500

•   Belt*unpost: false

•   Belt*bhactive: true

•   Belt*bhdelay: 1500

•   Belt*bhmaindelay: 5000

•   Belt*bhbackground: yellow

•   Belt*bhfont: fixed

•   Belt*maxicons: 8

•   Belt*dynamic: true

•   Belt*ontop: true

•   Belt*placement: +0-0

•   Belt*direction: right

•   Belt*icondirectory: /usr/local/share/belt/icons/

•   Belt*iconpath: /misc/graphics/icons/reduced/48x48

•   Belt*iconsize: 48

•   Belt*configdirectory: ~/.beltconf/

•   Belt*configfile: resources

•   Belt*menufile: menu.conf

They correspond directly to a command line option.

THE CONFIG FILES
There are primarily two types of files. Program settings is generally xresources and thus can lie in .Xdefaults/.Xresources or in the resources file in the users configuration directory.

Button definitions follow the dynamic-menu style as in use at the Unix system at E.KTH.SE. The files should be called menu.conf and reside in a directory found in the WMMENUPATH or in the users configuration directory for local settings. The name of the local button definitions file can be overridden by the menufile directive.

The format of the menu.conf-file is:

  module|cat|text|miniicon|applicationclass|icon|executable

Where module is the name of the module, cat is one of the predefined the category, text is the label in the final menu, miniicon is a small icon for use in the window decoration, applicationclass is the X Window System class for the application, icon is the path and icon associated with the application and executable is the path, file and switches needed to run the program. Only text, icon and executable is used by belt. For example the line:

  ||XtermWide|||/usr/local/graphics/xterm.xpm|/bin/X11/xterm -132

is sufficient for use with belt. One should however specify all fields if applicable.

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.

If the first character on the line is a # the line is considered to be a comment.

CONFIGURATION
The programs default settings has the lowest priority. The default settings can be overridden by xresources in the X resource database (ie .Xdefaults or .Xresources). These can in turn be overridden by resources specified in the sers configuration file, usually ~/.beltconf/resources. Command line options always override any previous settings.

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.

SMALLER/LARGER ICONS
By default the icons should be 48x48, as indicated by iconsize. The only exception are the special arrowicons [UDRL][SH].gif 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 smallmenu.conf 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 noicon.gif. Then you can start belt with the command:

  belt --iconsize=24 --menufile=smallmenu.conf
       --iconpath=/home/staff/max/belt/SmallIcons/:/misc/icons/small

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.

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.

FILES

DS.gif
    Solid arrow pointing down (48x16).

US.gif
    Solid arrow pointing up (48x16).

RS.gif
    Solid arrow pointing right (16x48).

LS.gif
    Solid arrow pointing left (16x48).

DH.gif
    Hollow arrow pointing down (48x16).

UH.gif
    Hollow arrow pointing up (48x16).

RH.gif
    Hollow arrow pointing right (16x48).

LH.gif
    Hollow arrow pointing left (16x48).

noicon.gif
    Icon used when no icon is found.

menu.conf
    Default name for local configuration file.

resources
    Name for local resource settings file, overriding X resources.

.Xdefaults or .Xresources
    where the normal X resources are stored

AUTHOR
This software is Copyright 1999, 2000, 2001, 2002 by Max Zomborszki. Full licence can be found at the top of the code.

ACKNOWLEDGMENTS
Larry Wall for creating Perl and everyone making great modules for Perl.

SEE ALSO
Perl(1), X(1X)

KNOWN PROBLEMS
Lots of bugs. The autopost/autounpost features have not been tested extensively and initial versions had obvious problems.

BUGS
Send bug reports to max@e.kth.se