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.

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>.