Wharf 1.8 Feb 7 2000 Wharf
Wharf the AfterStep "application dock" module
`Wharf` -f config_file -v --version -h --help AlthoughWharfcanberunfromthecommandline,itisnormallyspawnedbyafterstepintheautoexecfile,inthefollowingmanner:Module"I"WharfWait"I"WharfWaitisusedtoallowWharftoswallowtheappsspecifiedinthewharffilepriortoafterstepstartingotherappswhichusethesamename.orfromwithinanafterstepmenufileby'Wharf':%cat"~/GNUstep/Library/AfterStep/start/Modules/Wharf"Module"Wharf"WharfMiniPixmap"mini-as.xpm"
TostoptheWharfmodule,amenuitemcanbeused:%cat"~/GNUstep/Library/AfterStep/start/Modules/Wharf_Stop"KillModuleByName"StopWharf"WharfMiniPixmap"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