NAME

xbmbrowser - view and manage X bitmap and X pixmap files.

SYNOPSIS

xbmbrowser [ -options... ] [ directory ]

DESCRIPTION

xbmbrowser will show you all the bitmaps or pixmaps in the directory if it is specified otherwise it will look in the current directory. Note that if the program can not change directory to the directory in the command line it will exit and print an error message.

Once started the User can change the directory being displayed by either

Editing the displayed current directory string on the main application window.
Selecting a directory from a popup menu, by pressing a mouse button over the displayed current directory string. This is the recommended method when you are moving around a directory tree that you know very well.
Clicking with the first (left-most) mouse button on a directory file symbol.
Or even through one of the user configurable popup menu actions (See below). This is usfull to define a specific directory that you wish to change to regularly.

This latest version of xbmbrowser will also display small symbols for all the other files and directories present in the displayed directory. These symbols can be turned of if desired either through command line options, resources, or interactivly within the program.

You can perform a many different operations on bitmap (or pixmap) file that is being displayed, or even any of the other files in the current directory. These operations include, Rename, Copy, Delete, Edit and Set it as the background root window pattern.

These operations are initialized from a default library configuration file "/usr/lib/X11/xbmbrowser/xbmbrowser.menu", or from the users own version of this file ".xbmbrowserrc" in the user's home directory.

OPTIONS

Xbmbrowser will take all the normal Xtoolkit options as well as the following command line options. All but the -cf option can also be turned on and off as and when required from an "Options" menu (middle button along the top of the main application window) or its default set via X resource.

-cf "file"

-config "file"

Load the menu configuration from the given file instead of either the users rc file ".xbmbrowserrc" or the library configuration file "/usr/lib/X11/xbmbrowser/xbmbrowser.menu".

-solid

This controls the two different styles in which xbmbrowser can display the icons. The first -solid option uses a solid background with the icons displayed in shaped windows. This option is generally only usful on color displays and is by default enabled if this is the case. You can override this automatic setting with the X resource below.

Resource: XbmBrowser.solid_bgnd: True

-stipple

This other option is just the oppisite of the -solid option above. Display a stipple (checker board grey pattern) as the background and display the icon images in boxed (un-shaped) windows. This option is the original default of xbmbrowser. It also produces a better display on monocrome displays and as such is automatically selected as the defult for such displays. You can override this automatic setting with the X resource below.

Resource: XbmBrowser.solid_bgnd: False

-(no)label

Display (or not) the filenames under the icon or symbols shown.

Resource: XbmBrowser.label_all: False

-(no)iconsonly

Only display (or not) the actual icons (bitmaps and pixmaps) found in the current directory. In other words do not display and file symbols for directories or other files found in the current directory. This option is provided to allow the user to turn of the display of a large number of file symbols that can appear at times, and return xbmbrowser back to the `older' version style.

Resource: XbmBrowser.icons_only: False

-(no)dir

Display (or not) directory symbols for any sub-directories found. The ".." directory symbol will also be removed.

Resource: XbmBrowser.show_dir: True

-(no)xpmbad

Display (or not) any pixmaps which failed to load properly. This Pixmaps usally couldn't be displayed as they were unable to allocate enough colors on the current display. To display these, try quiting some other applications, removing any root background image you may have on your display, or even delete or move other pixmaps in the current directory elsewhere.

Resource: XbmBrowser.show_xpmbad: True

-(no)other

Display (or not) the other files found in the current directory. As part of the attempt to load these files as icons for display, xbmbrowser has determined weather or not these files are either binary, plain text, or some other special file type. It will use an appropiate file symbol to show the user its findings. NOTE: Picture Image formats such as gif and jpeg will appear as binary files.

Resource: XbmBrowser.show_other: False

-(no)hidden

Include in the display (or not) the UNIX hidden (or `dot') files found in the directory. Note that this only allows these hidden files to be shown, other options (above) may or may not permit these files to be visible. EG: hidden directories will not be visible in the display if either hidden files or directories are not visible.

Resource: XbmBrowser.show_hidden: False

-R or -recursive

This option can slow xbmbrowser enormously. When it is turned on, initially by this command line option, or interactively through the "Options" menu, xbmbrowser will recursively scan and display all the files in the directories under the current directory. This directory search can take a very very long and could result in system limitations crashing the program. As such this option will be automatically turned off any time xbmbrowser successfully changes the current directory.

Resource: XbmBrowser.recursive: False

This option was provided at the request of Steve Kinzler to allow xbmbrowser to scan the directory tree structure of his ``picons'' collection (See SEE ALSO below).

OTHER X RESOURCES

Other than those associated with command line others the following resources are also available and usful in your .Xdefults or other resource control files.

XbmBrowser.shape_syms: True

Controls if the non-icon file symbols are to be displayed in a shaped window or as a boxed symbol. Note that by default this is initially set equal to the value of the XbmBrowser.solid_bgnd: (see -solid commandline option above) unless overridden by your own resource setting (IE: True on color displays False on monocrome).

XbmBrowser.label_syms: False

Label only the file symbols. The XbmBrowser.label_all: resource (see -(no)label commandline option above) can override this value if it is True.

XbmBrowser.sym_foreground: black

XbmBrowser.sym_background: wheat

The colors to display file symbols and their labels on the display.

XbmBrowser.icon_foreground: black

XbmBrowser.icon_background: white

The colors to display bitmap icons and their labels with.

XbmBrowser.icon_transparent: linen

This is the color used for the transparent (or `None') pixmap color when not using a solid background color (and shaped windows). It is also the color of the pixmaps label.

XbmBrowser.solid_background: grey

The the solid background color to use.

XbmBrowser.stipple_background: pale green

This is a very light color to use with the foreground color (usally black) when creating the background stipple pattern. This color is usally not used as the stipple pattern is normall used on monocrome display only.

ASIDE: The forground color of the stipple pattern currently is set to whatever the border color of the iconbox widget is set to. If you don't want it to be black you can change it with the resource XbmBrowserconbox.borderColor. In a future release you may be able to set this color and maybe the stripple pattern used, just like the other resources above.

Suggestion. Try setting the icon_background, icon_transparent, and solid_background all to the same color such as grey. This will make the background color of the bitmaps and pixmap labels the same as the solid background color, thus removing the square boxes around these items. This is more like a typical WWW client display.

Unfortunately if you do this, you will loose the visual information on the true bitmap sizes being used. You can temporarally regain this information however by switching to stripple (non-solid_background) mode which turns off shaped windows.

XbmBrowser*IconLabel.labelTop: True

This resource will cause xbmbrowser to place any and all Labels above the images displayed instead of below as is normal. This is not strictly a xbmbrowser resource but one for the unusal Widget it uses to handle the display of the Bitmaps and Pixmaps.

USER CONFIGURABLE MENUS

This version of xbmbrowser has a user definable menu of commands that can be executed for displayed bitmaps pixmaps and other files. There is a default library configuration file, usally located in "/usr/lib/X11/xbmbrowser/xbmbrowser.menu" (check with your system programmers) or you can have your own config file called ".xbmbrowserrc" in your home directory. I suggest that you copy the library file "/usr/lib/X11/xbmbrowser/xbmbrowser.menu.tut", which is a heavily commented version of the default library file, to your home directory as ".xbmbrowserrc" and then edit it to suit your needs.

Each line of this file consists of either :-

# comment line: A comment line which is completely ignored. Comments can appear at the end of any (non-continued) line.
menu "main"
menu "main" "Main Menu": Add any new menu elements (see below) to this menu. Only specific menus are allowed and will be titled using the optional second argument. The menus, if defined, will be poped up when the appropriate mouse button is pressed on a displayed icon ot file symbol. If the menu is not defined the program will `beep' the user. The following are the menus which the user may define:-

"main"

The menu which pops up when the "Main Menu" button when pressed. Generally this is used a menu of directories the user likes to visit. Warning no file is selected by the user when using this menu so some substitutions may be empty strings. (See Substitions below)

Note: this menu must be defined. If it isn't a warning message is printed and a default menu containing only a QUIT button is created.

"global"

A menu of global actions which will popup when either the first two mouse buttons are are pressed on a displayed icon or file symbol or any mouse button on the background of the icon area. If the pointer was not over a displayed icon or symbol, no filename, basename, or suffix will be defined. (See function `selected()' below)

NOTE: If button 1 (leftmost or select mouse button) is pressed on a directory symbol, the browser will automaticaly decend into that directory, instead of poping up the global menu.

"bitmap"

Display this menu on any displayed X bitmap with the right most (menu) mouse button.

"pixmap"

As "bitmap", but for any X pixmap (or pixmap which failed to load).

"directory"

Same again, but for directory symbols.

"other"

Again, for any other file symbol (text, binary..).

line

Just insert a line into the menu at this point.

item "Delete" confirm("Really delete %f?") \

exec("rm '%f'") rescan()

Insert a item into the current menu which will execute the sequence builtin functions (see below). As it is posible for a very long sequences to be required for some menu items, the menu lines can be continued onto the next line by `backslashing' (\) the return character at the end of the line.

Each function may or may-not require some quoted string arguments, with the quote being either single or double, allowing the other quote to be used freely with the argument.

Each argument can contain any number of macro substitutions which consist of a % character followed by a single letter. A percent character can be substituted with %%.

The following builtin functions can be called (in sequence) from a menu item :-

quit(): Exit xbmbrowser. Need I say more?
scan(): Completely scan the current directory (Again). (See rescan() below)
rescan(): Do a fast rescan of the current directory. Note that X pixmaps which failed to load will NOT be loaded by this command, to avoid slowing the rescan() in a directory of unloadable X pixmaps. This occurance is actually common on a directory of pixmaps which do not follow a standard color table.

: To attempt to load these Pixmaps use either a full scan(), touch the failed pixmap when more colors are available, or convert that pixmap to a common color table. Alturnatively, display the pixmap in a secondary image viewer (converting it if nessary).

chdir("dir"): Change directory to the given directory. If the directory change succeeds xbmbrowser will automatically do a full scan() of the new directory. If this fails, no scan() will be performed.
exec("command"): Execute the given bourne shell command. Any output by the command executed will be to the standard output (or error) of xbmbrowser, usally the users terminal.
confirm("prompt"): Ask the user to confirm action before continuing the next function. If the user presses ``cancal'' the current function sequence will be aborted.
input("prompt","initial"): Ask the user for some input, giving the user the "initial" string to start with. The result entered by the user will be returned in the substitution marco %i (see below). The ``cancal'' button will abort the current function sequence.
selected(): If the user pointer was NOT over an icon or symbol then abort the current sequence with a popup error. This function is not usful in anything but the "global" menu, as in the other menus an icon is either always or never selected.

The following are substition macros can be used within function arguments :-

%d: The current directory of the browser. Note that a the directory seperator '/' have been pre-added to this substition macro.
%f: The filename of the icon (or file) selected by the user.
%b: The basename (suffix removed) of the current filename.
%s: The suffix of the current filename EG: ".xbm"
%i: The users input of the last input() function (see above).
%h: The Users Home directory (do NOT use ~ in an argument for this). Note that a the directory seperator '/' have been pre-added to this substition macro.
%D: The Initial Startup Directory. This is either the directory XbmBrowser was started in or was given to it as an command line argument.
%%: Substitutes a percent character, just in case you really do need it.

NOTE: The full path of a selected file is %d%f. Also %b%s exactly the same as the %f substition.

WARNING: the substitution macros %f, %b and %s will be an empty string if the users pointer was not over a display icon or file symbol. See the function selected() above.

FILES

~/.xbmbrowserrc: User's own menu configuration file.
/usr/lib/X11/xbmbrowser/xbmbrowser.menu: Default library menu configuration file.
/usr/lib/X11/xbmbrowser/xbmbrowser.menu.tut: Verbose menu configuration file (with extra examples).

Note: Some of these files may be installed in different directories on your system, for example /usr/X11R6/lib/X11. If you are not sure, please contact your local system programmers.

AUTHORS

Original Programmer

Ashley Roll -- ash@cit.gu.edu.au ( upto version 3.4 )

Current Programmer & Original Idea for Program

Anthony Thyssen -- anthony@cit.gu.edu.au ( version 4.0 and later )