Wharf(1.8)

NAME
Wharf - the AfterStep "application dock" module

SYNOPSIS
Wharf [-f config_file] [-v | --version] [-h | --help]

Although Wharf can be run from the command line, it is normally spawned by afterstep in the autoexec file, in the following manner:

	Module		"I"	Wharf
	Wait		"I"	Wharf

Wait is used to allow Wharf to swallow the apps specified in the wharf file prior to afterstep starting other apps which use the same name.

or from within an afterstep menu file by 'Wharf':

% cat "~/GNUstep/Library/AfterStep/start/Modules/Wharf"
	Module "Wharf" Wharf
	MiniPixmap "mini-as.xpm"
To stop the Wharf module, a menu item can be used:

% cat "~/GNUstep/Library/AfterStep/start/Modules/Wharf_Stop"
	KillModuleByName "Stop Wharf" Wharf
	MiniPixmap "mini-as.xpm"

DESCRIPTION
The Wharf module is a free-floating application loader that can execute programs, "Swallow" running programs, and contain "Folders" of more applications, among other things. Pressing mouse button 1 on a button triggers either a "Folder" to open, or an application to run, while pressing mouse button 3 will cause the entire /fBWharf/fP to withdraw to the nearest corner in an iconized state. Some swallowed apps have mouse button 2 bound for its use.

OPTIONS

-f config_file
    Use config_file instead of the default configuration file.

-h | --help
    Print a usage message and exit successfully.

-v | --version
    Print version information and exit successfully.

INITIALIZATION
During initialization, Wharf will search for a configuration file which describes the button panel geometry, color, icons, and applications to use/swallow. This file will be the one specified by the -f option (if given). Else, the ~/GNUstep/Library/AfterStep/wharf file will be used if it exists. Else, /usr/local/share/afterstep/wharf will be used. If the Wharf executable is linked to another name, ie ln -s Wharf OtherWharf, then another module called OtherWharf can be started, with a completely different set of configurations than Wharf, simply by adding configuration options with the keywords *OtherWharf. This way multiple Wharf programs can be used. Note that the symlinked module can not be called Wharf<something>, as aftrestep will pressume the standard Wharf binary.

INVOCATION
Wharf can be invoked from the autoexec file or from a menu item as shown in the Synopsis section above. AfterStep will search through the directories specified in the ModulePath configuration in the base.#bpp (where # is your colordepth) to attempt to locate Wharf; as well as searching through the PixmapPath for the pixmaps & IconPath for the bitmaps supplied in the configuration options.

CONFIGURATION OPTIONS
Wharf reads the wharf file when it starts up and looks for it's configuration options:

MyStyle "*WharfTile"
    Specifies the style of the wharf button tiles, including background color, background pixmap (which may be transparent), and background gradient. This method of specifying the background is preferred over the BgColor, MaxColors, Pixmap, TextureColor, and TextureType options, although those (older) options do still work. See afterstep(1x) for details on the MyStyle format.

*WharfTextureType type
    Specifies the type of gradient fill or pixmap to be used on Wharf's buttons. Valid values for type are:
    0 - No texture - use WharfBgColor to set the desired color
    1 - Gradient from upper-left to lower right
    2 - Horizontal one way gradient from top to bottom
    3 - Horizontal cylindrical gradient from top/bottom to center
    4 - Vertical one way gradient from left to right
    5 - Vertical cylindrical gradient from left/right to center
    128 - User defined pixmap
    The default is the builtin Wharf texture pixmap.

*WharfTextureColor from to
    When used with a *WharfTextureType of 1 through 5, designates the ends of the color gradient's range to be used on Wharf's buttons.

*WharfPixmap pixmap
    Sets the pixmap file to be used as Wharf's button. To be used with *WharfTextureType 128. If the pixmap is transparent, Wharf will be transparent (shaped). The path need not be specified if the pixmap is in the PixmapPath specified in the base.#bpp file. Valid pixmaps are XPM, JPEG, or PNG.

*WharfBgColor color
    If *WharfTextureType 0 is specified, Wharf's buttons will be filled with color.

*WharfMaxColors number
    Specifies the maximum number of colors to use on a gradient fill.

*WharfAnimate
    If specified, the opening and closing of Folders will be animated, rather than simply drawn in one frame.

*WharfAnimateMain
    Designates that full-length Wharf withdraws will be animated.

*WharfAnimateDelay delay
    Specifies the delay in milliseconds that the animation will pause between each move when opening or closing a folder.

*WharfAnimateSteps steps
    Specifies the steps a Folder takes in animating while opening or closing. This translates into the Folder button moving <button-size>/steps pixels each step.

*WharfAnimateStepsMain steps
    Specifies the steps the main Wharf takes in iconification or de-iconification upon mouse button 3 being pressed. This translates into the main Wharf moving <button-size>/steps pixels each step.

*WharfBalloons
    Turns on the balloon feature. A "balloon" is displayed showing the name of the button the pointer is resting on in the Wharf. The balloon background and text are configured with the MyStyle "*WharfBalloon". See afterstep(1x) for more information on MyStyles.

*WharfBalloonBorderWidth number
    Sets the width of the balloon window's border. Defaults to 1.

*WharfBalloonBorderColor color
    Sets the color of the balloon window's border. Defaults to black.

*WharfBalloonDelay number
    Specifies the period in milliseconds to delay the appearance of the balloon.

*WharfBalloonYOffset number
    The balloon window is positioned to be horizontally centered against the Wharf window it is describing. The vertical position may be set as an offset. Negative offsets of -N are placed N pixels above the Wharf window, positive offsets of +N are placed N pixels below. Defaults to +2.

*WharfFullPush
    If specified, the entire Wharf button background will be offset down and to the right 2 pixels when pushed. Especially useful with *WharfNoBorder textures.

*WharfNoPush
    If specified, the entire Wharf button will not appear as if it is being pushed in.

*WharfNoBorder
    Denotes that beveled borders should not be drawn around the Wharf button. Useful with textures or pixmaps that include their own bevels.

*WharfWithdrawStyle style
    Specifies the circumstances under which button 3 should cause the Wharf to withdraw to a corner. If style is 0, button 3 will do nothing. If style is 1 (the default), a click on any button in the toplevel bar will cause Wharf to withdraw to the nearest corner. If style is 2, a click on either the first or the last button in the toplevel bar will cause the withdrawal. The undocumented NoWithdraw option, which does much the same thing, is deprecated - use WithdrawStyle instead.

*WharfForceSize
    If specified, will force pixmaps larger than 64x64 to the default size of 64x64. Pixmaps smaller than 64x64 are not supported. This has no effect on the icons used for applications.

*WharfRows rows
    Specifies the number of rows of buttons to be created. This will give your Wharf a horizontal layout, with the number of rows equal to the number specified in rows. If unspecified, the number of rows will be set to 1. If the rows are set to a number greater than 1, then there will be that number of rows with enough columns to satisfy the requested number of buttons. Only one of *WharfRows or *WharfColumns should be specified.

*WharfColumns columns
    Specifies the number of columns of buttons to be created. This will give your Wharf a vertical layout, with the number of columns equal to the number specificed in columns. If unspecified, the number of columns will be set to 1. If the columns are set to a number greater than 1, then there will be that number of columns with enough rows to satisfy the requested number of buttons. Only one of *WharfRows or *WharfColumns should be specified.

*WharfGeometry geometry
    Specifies the Wharf window location and/or size. If the size is not specified, Wharf will auto-size itself in a reasonable manner. The geometry is a standard X11 window geometry specification; see XParseGeometry(3x), and EXAMPLES (below) for further details.

*Wharf label-for-balloon icon command
    The label-for-balloon is what appears in the Balloons if balloons are used, otherwise this entry is still required. Multiple entries can refer to the same wharf button by using the same label-for-balloon. The icon field specifies an X11 bitmap file, XPM, JPEG, or PNG color icon file or a comma-delimited set of pixmaps containing the icon(s) to display on the button. These icon(s) will be displayed in front of the WharfTextureColor, WharfPixmap, or WharfBgColor, and behind any Swallowed windows. Transparent icons are allowed. The command specifies an AfterStep built-in command (as described in the afterstep man page) which should be executed when a button is pressed, or a Wharf command.

    The following Wharf commands are available:

    Swallow "window-name" command
        Causes Wharf to run command, capture the first window whose name or resource is window-name, and display it in the associated button. The application window will be shrunk to fit the size of the button.

    MaxSwallow "window-name" command
        Like Swallow, except the button will be resized to fit the application.

    SwallowModule "window-name" command
        Like Swallow, except the command is an AfterStep module.

    MaxSwallowModule "window-name" command
        Like MaxSwallow, except the command is an AfterStep module.

    DropExec "label" command %s %d
        Specifies a command to run when the associated button receives a Offix Drag & Drop event. %s (if present) will be replaced with the dropped data, and %d (if present) will be replaced with the data type. See EXAMPLES below for an example.

    Size width height
        Sets the size of the associated button, overriding any other size consideration. The Wharf button size depends on several things. The order of precedence is:
        1) Size definition
        2) MaxSwallow'd window size
        3) WharfPixmap size
        4) Use 64x64.

    Transient
        Specifies that this button will not perform any action, will not be pushable, and will not have an associated balloon.

    Folder "folder-name"
        Defines a slide-out folder inside the current folder. The following button definitions will be placed inside of the subfolder, until a *Wharf ~Folder line is encountered. See the EXAMPLES section below for an example. Folders may be nested.

FILES

/usr/local/share/afterstep/wharf
    The global configuration file for system wide defaults of all users.

$HOME/GNUstep/Library/AfterStep/wharf
    This file should be copied from the /usr/local/share/afterstep/wharf and edited to suit the user's specific requirements. This file, if exists, will override the system wide default file.

/usr/local/share/afterstep/base.[8|15|16|24|32]bpp
    Contains the IconPath & PixmapPath global settings for the Wharf.

$HOME/GNUstep/Library/AfterStep/base.[8|15|16|24|32]bpp
    This file should be copied from the/usr/local/share/afterstep/base.[8|15|16|24|32]bpp and edited to suit the user's specific requirements for the IconPath & PixmapPath settings of the Wharf.

EXAMPLES
The wharf file shipped contains many examples, refer to the CONFIGURATION OPTIONS section above for its configuration options. Wharf geometries are fundamentally an offset with a value of pixels from a specified corner of the screen, with format [+-]X[+-]Y. The + and - definitions for the offset specify which corner of the screen to place Wharf in. Here's a nifty picture to illustrate:
________________
|++          -+|
|              |
|              |
|              |
|+-          --|
----------------
For example, Geometry -5-5 would place Wharf in the lower right hand corner, 5 pixels left and 5 pixels up from the corner. To create slide-out folders in Wharf the following format must be used:
*Wharf files Folders.xpm,3_dots.xpm Folder
*Wharf xftp 3DRings.xpm	Exec "" xftp &
*Wharf xdir FolderDeposit.xpm Exec "" xdir &
*Wharf moxfm FilingCabinet.xpm Exec "" moxfm &
*Wharf ~Folder
The first line of this set tells Wharf that this button definition will be a folder. All of the button definitions between the Folder and the line with the definition of *Wharf ~Folder will appear on the "files" folder when it is exposed. To expose the "files" folder simply click on the Wharf button with the Folders.xpm icon showing. A button bar will appear perpendicular to your Wharf bar and toward the center of the screen. On this smaller bar will be the three icons that were configured between the Folder and ~Folder parts of the Wharf configuration. Folders may be nested.

Wharf supports the OffiX Drag and Drop standard. The following is an example of a DropExec line:
*Wharf trash Recyler.xpm DropExec "" rm %s
*Wharf trash - Restart "" afterstep
The button will restart AfterStep when pushed. If a file is dragged onto into it, rm will be called with %s being replaced by the dropped filename.

AUTHORS
Beat Christen <bchriste@iiic.ethz.ch>
Frank Fejes <frank@ssax.com>
Alfredo Kengi Kojima <kojima@inf.ufrgs.br>
Dan Weeks <dan@mango.sfasu.edu>
Bo Yang <eric@coeus.ucsd.edu>
Robert Nation
David Mihm <dmihm@swbell.net> [Man page]
Ethan Fischer <allanon@crystaltokyo.com>

SEE ALSO
afterstep(1), Pager(1), X(1), Zharf(1)