Zharf(1x)

NAME

Zharf - the AfterStep button panel module

SYNOPSIS

Zharf [-f config_file] [-v | --version] [-h | --help]

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

	Module		"I"	Zharf
	Wait		"I"	Zharf

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

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

% cat "~/GNUstep/Library/AfterStep/start/Modules/Zharf"
	Module "Zharf" Zharf
	MiniPixmap "mini-as.xpm"

To stop the Zharf module, a menu item can be used:

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

DESCRIPTION

The Zharf module is a free floating application loader/button panel similar to the Wharf that can execute programs or "Swallow" running programs, but also displays a label under the icon (if specified). Zharf could also be used as simply a text version of Wharf. Folders are not supported.

All mouse buttons are captured to initiate the command specified, however some swallowed apps might capure certain mouse buttons 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, Zharf will search for a configuration file which describes the button panel geometry, color, icons, and actions. This file will be the one specified by the -f option (if given). Else, the ~/GNUstep/Library/AfterStep/zharf file will be used if it exists. Else, /usr/share/afterstep/zharf will be used.

If the Zharf executable is linked to another name, ie 'ln -s Zharf OtherZharf', then another module called OtherZharf can be started, with a completely different set of configurations than Zharf, simply by adding configuration options with the keywords *OtherZharf. This way multiple Zharf programs can be used. Note that the symlinked module can not be called Zharf<something>, as aftrestep will pressume the standard Zharf binary.

INVOCATION

Zharf 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

Zharf reads the zharf file when it starts up and looks for it's configuration options:

*ZharfGeometry geometry: Specifies the Zharf window location and/or size. If the size is not specified, Zharf will auto-size itself in a reasonable manner. The geometry is a standard X11 window geometry specification.

*ZharfFont font: Specifies the font to be used for labeling the buttons.

*ZharfRows rows: Specifies the number of rows of buttons to be created. If unspecified, 2 rows will be used.

*ZharfColumns columns: Specifies the number of columns of buttons to be created. If unspecified, the number of columns will be set to the number of buttons requested, divided by the number of *ZharfRows rows. If both *ZharfRows rows and *ZharfRows columns are specified, but do not specify as many buttons as are defined, then the users columns specification will be ignored.

*ZharfFore color: Specifies the color for button label text and monochrome icons.

*ZharfBack color: Specifies the color for the buttons.

*Zharf[(WxH)] label icon command

If the optional (WxH) is specified, then this button will be W times the normal button width and H times the normal button height. NOTE: The entire Zharf will be resized to W if vertically priented; or H if vertically oriented.

The label field is what appears on the button bar, or below an icon; if an icon is used. If label is "-" then the button label will not be displayed.

The icon field specifies an X11 bitmap file, XPM, JPEG, or PNG color icon file to display on the button. This icon will be displayed over the ZharfBackColor and above the label. Transparent icons are allowed.

The command specifies an AfterStep built-in command (as described in the afterstep man page). If command is an AfterStep Exec command, then the button will remain pushed in until a window whose name or class matches the qouted portion of the command. This is intended to provide visual feedback to the user that the action requested will be performed. If the quoted portion contains no characters, then the button will pop out immediately. Note that user can continue pressing the button, and re-executing the command, even when it looks "pressed in."

The following Zharf commands are available:

Swallow "window-name" command: Causes Zharf 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.

FILES

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

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

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

$HOME/GNUstep/Library/AfterStep/base.[8|15|16|24|32]bpp: This file should be copied from the/usr/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 zharf file shipped contains many examples, refer to the CONFIGURATION OPTIONS section above for its configuration options.

To swallow the Pager module into the Zharf:

*Zharf(4x1) - - SwallowModule "Pager" Pager 0 3

This will captures the Pager into button that is 4 times the width of the other buttons. Since "-" is used for the button label and icon, the Pager will be resized to fit into the button's borders.

To have a button with a pixmap:

*Zharf Doc AfterStep3.xpm Exec "-" afterstepdoc &

Or with a bitmap and a label:

*Zharf Raise Up Raise

The "Up" is an X11 standard bitmap.

AUTHORS

Guylhem Aznar

Robert Nation
David Mihm <[email protected]> [Man page]