/ 
xchar-0.2
River stage zero No dependents
/ xtb

NAME

xtb - xchar taskbar and char allocator

SYNOPSIS

xtb [-geometry ...] [-r relief] [-w width] [-p] [-l logfile]

DESCRIPTION

Displays a vertical taskbar. That is, a tall thin window containing a list of X clients.

It requires that the window manager support some of the standard extended window manager hints (fvwm does, twm doesn't). Specifically, it requires:

_NET_CLIENT_LIST
_NET_ACTIVE_WINDOW

It also uses the always supported hints:

WM_CLASS
WM_ICON_NAME

Access to all these is through the module X11::Tops.

Each client's slot in the taskbar shows the client's 'character' followed by its icon name. The characters are assigned to clients via a perl function in the cfgfile $HOME/.xtb. The perl function argument is the client's instance name.

The character is fixed for the life of the client, but for best results the icon name contains information about the current state of the client (eg current directory, current mail folder, file or URL being viewed).

It normally sets its own instance name to 'xtb'. If it finds that a client with this name already exists, then it adds a number. If there's no other such instance, then it chooses xtb1. If there are instances of the form 'xtbN' then it chooses 'xtbM' where M is one more than the largest N.

It normally doesn't show itself in the list, but does if its own name is not xtb.

If .xtb contains a picture specification, then unless -p is given, the list is padded to the screen height by an image determined by a Unix command specified in the picture specification.

The possible relief values are, the 1st being the default:

raised sunken flat ridge solid groove

The default width is 170.

XTC

The taskbar can be controlled from the command line with xtc(1), whose main function is to send commands to the taskbar via the _XCHAR_COMMAND property on the taskbar window.

Commands currently known are:

restart
exit

left
right

raise [-n] char
lower char

picture [index]

autoraise [delay]

dump
DUMP

They are sent by for example:

xtc restart
xtc raise -n c

The first word (restart etc) can be abbreviated to 3 letters.

restart
xtb restarts itself with the same arguments (so -geometry and -l).
Use this after you edit the configfile.
exit
xtb exits, ceases, quits
left, right
If the ~/.xscreens entry for the current screen has an 'x' key, it
should list a sequence of numbers.  These are treated by xtb as
distances from the right side of the screen.  On these commands, xtb
aligns its right side to the next 'x' value, moving left or right
respectively.  

Normally the 'x' values are distances from the right side of client
geometries (elsewhere in ~/.xscreens) to the right edge of the
screen.  The reason for this is that the right side of text-based
clients is often less used than the left side, so is a less annoying
place for the taskbar.

Possibly these functions should be generalized and moved into xmv(1)
(which moves any window, not just the taskbar, but so far does not
allow relative moves).
raise, lower
These raise or lower the window with the specified character.  The
former also gives it the keyboard focus, unless -n is specified.

They are redundant really, xup(1) & xdn(1) doing the same.
picture
Refreshes the picture if any (see above).  This is useful if the
picture fetching machinery is nondeterministic or has changed.
autoraise
The taskbar automatically raises itself some time after being even
partly obscured.  The default time is 60 seconds, but can be changed
by this command.
DUMP, dump
For debugging.  Causes the taskbar to dump its internal state to
stdout, or to the logfile if xtb was started with -l.  DUMP is far
more verbose than dump.

CFGFILE

This is $HOME/.xtb. It is a perl fragment returning a hash reference.

Currently allowed keys & the type their allowed values are:

char     function
order    reference to an array of characters
picture  reference to an array of arrays

The 'char' function maps instance names to sequences of characters. The former is the usual X instance name (eg 'xterm' and 'firefox-bin'). A sequence is allowed because there may be several clients with the same instance name. Things are nicer if these clashes are avoided, such as by using 'xterm -name xterm/c' and mapping xterm/c to 'c'.

The 'order' array specifies the order in which clients are shown.

Each element of the picture array specifies a Unix command followed by its arguments. The command is called by xtb with the specified arguments supplemented by the size of the space available to the picture & the name of the file in which the command should place the image. The size is specified by xtb in the form '-170x400', & the name as /tmp/xtb (or /tmp/xtb1 or such). The command should return the image type on stdout. This can be any of the types handled by perl-tk, currently:

BMP GIF JPEG PNG PPM PGM XBM XPM

EXAMPLE CHAR FUNCTIONS

The argument is an instance name.

A simple example is:

char => sub {
    local $_ = shift;
    m-/(.)$-             ?  $1            :
    /gecko|firefox-bin/  ?  'f'           :
    /acroread/i          ?  'a'           :
    /xtb/                ?  '.'           :
    /./                  ?  ['A' .. 'Z']  :
    undef;
},

A more realistic example involves a bit more Perl:

my @reserved;
push @reserved, qw(x r s o h);
push @reserved, qw(a c e f g j k t y z , . - =);
my %reserved;
$reserved{$_} = 1 for @reserved;
my @spare;
for ('a' .. 'z') { push(@spare, $_) unless $reserved{$_}; }

char => sub {
  local $_ = shift;
  m-/(.)$-             ?  $1             :
  /acroread/i          ?  ['a', @spare]  :
  /xchat/              ?  ['c', @spare]  :
  /ethereal/           ?  ['e', @spare]  :
  /gecko|firefox-bin/  ?  ['f', @spare]  :
  /gv/i                ?  ['g', @spare]  :
  /sjphone/i           ?  ['j', @spare]  :
  /kaffeine/           ?  ['k', @spare]  :
  /TeXmacs/            ?  ['t', @spare]  :
  /skype/i             ?  ['y', @spare]  :
  /SWT/                ?  ['z', @spare]  : # azureus
  /xtb./               ?  [',', ';' ]    :
  /xtb/                ?  '.'            :
  /^$/                 ?  ['-', '=']     :
  /./                  ?  ['A' .. 'Z']   :
  undef;

},

EXAMPLE ORDER ARRAY

order => [
  qw(0 . , ; f g t p ), 'a' .. 'e', 1 .. 9, 'x' .. 'z', 'A' .. 'Z'
]

EXAMPLE PICTURE ARRAY

picture => [
  [qw(irand -m-^apod/- -y 4d -a)],
  [qw(irand -m-^apod/(galaxy|nebula)- -a)],
  [qw(irand -M-^apod/- -a)],
],

SEE ALSO

xchar(1), xtc(1), xup(1), xdn(1), screens(1), xterms(1)

mk.xtb(1), mk.xscreens(1), mk.xchar(1)

X11::Tops(3), X11::Screens(3), X11::XTerms(3)

AUTHOR

Brian Keck <bwkeck@gmail.com>

VERSION

$Source: /home/keck/gen/RCS/xtb,v $
$Revision: 4.23 $
$Date: 2007/07/07 07:51:55 $
xchar 0.2