NAME

X11::Tops - handle top level X windows

WARNING

The high level part of the interface is currently (xchar 0.2) clumsy, and will probably be changed.

SYNOPSIS

  use X11::Tops;
  $xtops = X11::Tops->new;

  use X11::Tops;
  $X = X11::Protocol->new;
  $xtops = X11::Tops->new($X);

  $xtops->update;
  for $xtop (@{$xtops->sorted}) {
    print join("\t",
      $xtop->class, $xtop->instance, $xtop->title, $stop->icon
    ),
    "\n"
  }

  $xtop = $xtops->match('instance', qr/gecko/i);
  $xtop = $xtops->instance(qr/gecko/i);
  $xtop = $xtops->icon(qr/apod/i);

  $xtop->char('q');
  $xtop->char;

  @deleted = $xtops->update; # list of X ids

  $xtops->monitor_property_change;
  $xtop->monitor_property_change

DESCRIPTION

X11:Tops handles all the top level windows reported by the window manager via the root window _NET_CLIENT_LIST property. Most of the methods are general, but there's also support for the xchar(1) system (which is currently insufficiently separated from the general methods). It is built on top of the X11::Protocol module.

It's designed to handle long-lived programs that keep track of changes in the population of top level windows (such as xtb(1)) and short-lived programs that just want a snapshot (such as xup(1) and xmv(1)).

An X11::Tops object $xtops contains a set of X11::Top objects $xtop. The latter can be reached with several methods of the former:

    $xtops->sorted  returns a reference to an array of $xtop
    $xtops->byid    returns a hashref, each value an $xtop
    $xtops->bychar  returns a hashref, each value an $xtop

The construction of $xtops can take one or several steps, and can be partial or complete. As mentioned in the warning above, this is currently clumsy.

The following constructs it completely:

    $xtops = X11::Tops->new;
    $xtops->update;

This fetches all (toplevel) window ids and all their WM_CLASS properties, calculating a character for each & setting the _XCHAR_CHAR property on it accordingly.

The following also constructs it completely:

    $xtops = X11::Tops->new;
    $xtops->update_from_props;

the difference being that the per-window characters aren't computed as above but fetched from the _XCHAR_CHAR propertes.

The construction used by the update method above uses a hardwired algorithm for assigning characters to windows. The algorithm can instead be flexibly specified:

    $xtops = X11::Tops->new;
    $xtops->{char} = sub { $instance = shift; ...; return $char; };
    $xtops->update;

The sort method mentioned above uses a hardwired sort algorithm that can be over-ridden:

    $xtops = X11::Tops->new;
    $xtops->{char} = sub { $instance = shift; ...; return $char; };
    $xtops->update;
    $xtops->{order} = ['a' .. 'z', 0 .. 9, 'A' .. 'Z'];
    @xtops = $xtops->sort;

Partial construction, as for snapshotting, is typically:

    $xtops = X11::Tops->new->update_ids;
    for $xtop (values %{$xtops->byid}) { ... }

Both X11::Tops and X11::Top have class, instance, title & icon methods. They only get, not set. For X11::Tops there is a regex argument & the method returns an X11::Top object whose corresponding property matches the regex. For X11::Top there is no argument (other than the object) & the corresponding property is returned. Class & instance are handled separately even though they come from the same property (WM_CLASS). Values of class & instance are assumed not to change (so are cached).

The X11::Top method char gets or sets a (non-standard) property _XCHAR_CHAR. Normally the character name of a toplevel is derived from the instance name via $xtops->{char} as above.

OTHER X11::Xtops METHODS

X()

returns the associated X11::Protocol object

active()

returns the X id of the active window

stacking()

returns the array of X ids in stacking order (bottom first)

monitor_property_change()

asks for root PropertyChange events

OTHER X11::Xtop METHODS

command()

gets or sets the _XCHAR_COMMAND property

attributes()

X11::Protocol::GetWindowAttributes

raise()

raise_and_focus()

lower()

geometry()

frame_geometry()

wm_normal_hints()

parse_geometry()

requested_geometry()

move()

expand()

monitor_property_change()

asks for PropertyChange events

monitor_property_and_visibility_change()

asks for PropertyChange & VisibilityChange events

monitor_property_and_structure_change()

asks for PropertyChange & SubstructureNotifyMask events

AUTHOR

Brian Keck <bwkeck@gmail.com>

VERSION

 $Source: /home/keck/lib/perl/X11/RCS/Tops.pm,v $
 $Revision: 3.25 $
 $Date: 2007/07/07 07:52:11 $
 xchar 0.2

cpanm X11::Tops

perl -MCPAN -e shell
install X11::Tops