View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Brian Keck > xchar-0.2 > xtb


Annotate this POD

View/Report Bugs


xtb - xchar taskbar and char allocator


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


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:


It also uses the always supported hints:


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.


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:



    raise [-n] char
    lower char

    picture [index]

    autoraise [delay]


They are sent by for example:

    xtc restart
    xtc raise -n c

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

    xtb restarts itself with the same arguments (so -geometry and -l).
    Use this after you edit the configfile.
    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
    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.
    Refreshes the picture if any (see above).  This is useful if the
    picture fetching machinery is nondeterministic or has changed.
    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.


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:



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']  :

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']   :



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


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


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)


Brian Keck <>


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