X11::Protocol, version 0.56

Copyright (C) 1997-2006 Stephen McCamant. All rights reserved. This
module is free software; you can redistribute and/or modify it under
the same terms as Perl itself. (As an exception, the file Keysyms.pm,
which is derived from a file in the standard X11 distribution, has
another, less restrictive copying policy, as do some of the extension
modules in the directory Protocol/Ext: see those files for details).

Module list information:123456789 123456789 123456789 123456789 12345
X11::Protocol	bdpO	Raw interface to X Window System servers
X11::Keysyms	bdpf	X11 key symbols (translation of keysymdef.h)
X11::Auth	bdpO	Read and handle X11 '.Xauthority' files

New in this version: 0.56
	- Fix infinite loop regression in robust_req in 0.54 caused by
	  handle_input change (found by Scott Smedley)

X11::Protocol and the related modules in this distribution are a rough
equivalent of Xlib (libX11.a, with a bit of Xau and Xext mixed in)
used for drawing windows on and otherwise manipulating X11 window
servers.

OTHER THINGS YOU NEED

* perl 5.002	  (not tested recently; recent versions have only been
                   tested with 5.6.1 and 5.8.*)

* an X11 server   (any version; it also doesn't have to be on the same
		   computer, but you must be able to connect to it
		   over a socket. For Win32 users, a free X server
                   is apparently available from
		   http://sources.redhat.com/win32-x11/ though the
                   author hasn't tried it)

* documentation about the X protocol (or at least Xlib, though its
interface is subtly different). O'Reilly has a good book, and the full
X distribution includes the definitive specification. As of this
writing, the latest version can be obtained from the X.org CVS
repository at:

http://cvs.freedesktop.org/*checkout*/xorg/xc/doc/hardcopy/XProtocol/proto.PS.gz

For Debian users, this is in the xspecs package.

Speaking of Debian, this module is also available as the Debian
package "libx11-protocol-perl"; thanks to tony mancill for maintaing
it.

	 *********************** NOTE ***********************

* This module's interface is admittedly a little cumbersome, but its low
level approach is intentional -- a higher-level interface, ideally more
object-oriented, easier to use, and plug-compatible with an XS Xlib
interface, would be a significant different project. (A project that
this author made an abortive start at, but is unlikely to finish any
time soon.)

* The interface has become stable, though mainly through the passage
of time rather than through extensive debugging. For better or worse,
it probably isn't going to change much in the future.

	 ****************************************************
BUILDING

Like any other module:
% perl Makefile.PL
% make
% make test
% make install

DOCUMENTATION

See the PODs at the end of each .pm file (converted into man pages by
the makefile) for detailed information.

EXAMPLES

test.pl is a good example of a complete program; it's also a
translation of an Xlib based program (in this case, `basicwin' from
O'Reilly & Associates's _Xlib Programming Manual_).

eg/anim.pl demonstrates buffered animation (needs IO::Select).

eg/full_test.pl uses just about every request in the protocol. You
might not want to run it, since it can do weird things to your
display, but it can show prototype calls if the documentation is
unclear.

eg/long-run.pl is a program that runs for a long time and allocates
many windows, as a stress-test of the resource-allocation code.

eg/random-win.pl demonstrates how to handle requests that might cause
errors, by picking random resource identifiers and trying to paint
over them with randomly-colored rectangles if they're windows.

eg/render-clock.pl uses the Render extension to draw an analog
clock. It's a bit spiffier that "xclock -render", in the author's
opinion, but falls short of fdclock.

eg/render-test.pl is like eg/full_test.pl, but just for the Render
extension.

eg/teletype.pl shows how it's possible to connect to more than one
server at once (needs IO::Select).

eg/widgets* are four examples that all do the same thing, with
different tools. They demonstrate all the techniques needed to
implement two simple custom widgets, a scroll bar and a progress
meter, with the different options available for X11 programming from
Perl:
 - widgets1.pl uses X11::Protocol directly.
 - widgets2.pl uses X11::Xlib from Ken Fox's X11-Motif
distribution. Unfortunately, even the latest alpha version of
X11-Motif I could find is missing interfaces for all the needed Xlib
structures, so the code has to play games with pack() to get some
calls to work. This may mean that the example may not work correctly
on platforms whose Xlib structures are laid out differently that the
author's Linux x86 box.
 - widgets3.pl is an example of how programming X11::Protocol would be
nicer with an object-oriented interface. It's a blatant ploy to get
someone else interested in picking up the half-finished library it
depends on, which is not included in this distribution (email me if
you're interested).
 - widgets.c is a C Xlib version of the same functionality, for
comparison.

eg/wintree.pl is a small utility that acts like a cross between
xlsclients, xwininfo, and pstree, showing the hierarchy of windows and
their parents. Takes a window ID, or by default starts at the
root. "-g" includes geometries, "-v" uses VT100 line drawing
characters. Beware that it hardcodes some assumptions about how
certain X servers encode resource IDs.


SEE ALSO

This is by no means the only way to put windows up on an X server from
Perl. 

* The most popular and portable windowing interface for Perl is
Perl/Tk, available as the Tk module from CPAN.

* The Motif widget set, as well as some support for other standard X
libraries, can be accessed using the X11::Motif modules, available
from CPAN. An alpha version is also available directly from the
author's homepage at http://www.vulpes.com/X11-Motif-1.2a8.tar.gz .

* Several other X widgets sets have Perl interfaces, incluing GTK (the
Gtk module), Qt (the PerlQt module), wxWindows (the Wx module) and Sx
(a simplified Athena wrapper, available with the similarly named
module).

* For testing or automating the operation of other programs, the
Xlib-based X11::GUITest module has more specialized support, including
for the XTEST extension, than X11::Protocol.

Send questions, bug reports, and feature requests to me, Stephen
McCamant <SMCCAM@cpan.org>.
