HELP CLX                                         John Williams, Dec 1990
                                                        Updated Feb 1995

CLX is a low-level interface from Common Lisp to the X Window System. It
was implemented by Texas Instruments Incorporated (and is copyrighted by
them - see below for full details). CLX version 5.02 (for X11R5) is
included with Poplog, in the "contrib" directory of unsupported public
domain software.

This file explains how to load the CLX module. For a tutorial discussion
of CLX and X windows, see TEACH * CLX (only accessible if the CLX module
has been loaded).


         CONTENTS - (Use <ENTER> g to access required sections)

  1   Loading CLX
  2   Authorising CLX to write to your display
  3   Some CLX Demo Programs
  4   Making a CLX saved Image
  5   Related Documentation
  6   Full CLX Copyright Notice


-----------------------------------------------------------------------
1  Loading CLX
-----------------------------------------------------------------------

To load CLX, you will first need to add the Lisp contrib directory to
the module search path. Do this with:

    (require :contrib)

You can then compile CLX with:

    (require :clx)

This will probably take a few minutes. You may see some warning messages
from the compiler: if so, ignore them.

Finally, to make the CLX facilities available without using package
qualifiers, do:

    (use-package :xlib)


-----------------------------------------------------------------------
2  Authorising CLX to write to your display
-----------------------------------------------------------------------

CLX will not be able to alter your display (screen) until it has been
authorised to do so. To do this, open a console window, and give the
Unix command:

    % xhost + <hostname>

where <hostname> is the name of the machine on which you are running
CLX. Please note that there is a security risk attached to this
procedure - anyone logged onto <hostname> can now potentially look and
tamper with what's displayed on your screen.

For more details on xhost, see MAN * XHOST.


-----------------------------------------------------------------------

3  Some CLX Demo Programs
-----------------------------------------------------------------------

A couple of simple demo programs are provided with CLX. The first,
HELLO-WORLD, creates a small window with the text "Hello World" inside.
First, load the demo by doing:

    (load "$popcontrib/lisp/clx/demo/hello.l")

and then run it with:

    (xlib::hello-world "")

Make the window disappear by moving the mouse cursor into the window and
clicking any button.

Another demo, JUST-SAY-LISP, creates a small pop-up menu listing various
programming languages. Load and run it with:

    (load "$popcontrib/lisp/clx/demo/menu.l")
    (xlib::just-say-lisp "")

To make the menu disappear, select (by clicking any mouse button), the
entry `Lisp'. If you select any of the other programming languages, the
menu is simply redrawn.

The file menu.l also defines a demo called POP-UP. Try the following:

    (xlib::pop-up "" '("Labour" "Conservative" "Liberal Democrat"
                        "Green" "Monster Raving Loony"))

This creates a medium size window (with no borders), with the text
"Press a button..." displayed at the top. When you press a button, a
pop-up menu appears listing the aforementioned UK political parties. If
you select one by pointing and clicking the mouse, the pop-up menu
disappears, and the text "You have selected" followed by the name of the
selected item is displayed at the bottom of the window. You can repeat
the selection procedure as many times as you like. To quit the demo,
interrupt by typing CTRL-C, and then type :A to the Lisp debugger
prompt.


-----------------------------------------------------------------------
4  Making a CLX saved Image
-----------------------------------------------------------------------

If you use CLX often, it's a good idea to create a saved image with CLX
already loaded into it. To do this, give the Unix command:

    % $popcontrib/lisp/clx/mkclx

This creates a saved image named clx.psv in the directory $poplocalbin,
which you can restore with:

    % clisp +clx

(For more information on saved images, see HELP * SAVELISP).


-----------------------------------------------------------------------
5  Related Documentation
-----------------------------------------------------------------------

TEACH * CLX
    Tutorial introduction to CLX and X Windows.
        (Only available if the CLX module has been loaded)

HELP * CONTRIB
    More information on "contributed" software.

$popcontrib/lisp/clx/src/*
    The CLX source files.

$popcontrib/lisp/clx/doc/CLX.Manual.tar.Z
    This contains the complete CLX manual (as PostScript files).
    For a listing of contents and instructions on how to unpack,
    see $popcontrib/lisp/clx/doc/READ.ME


-----------------------------------------------------------------------
6  Full CLX Copyright Notice
-----------------------------------------------------------------------

;;;          TEXAS INSTRUMENTS INCORPORATED
;;;               P.O. BOX 2909
;;;                AUSTIN, TEXAS 78769
;;;
;;; Portions Copyright (C) 1987 Texas Instruments Incorporated.
;;; Portions Copyright (C) 1988, 1989 Franz Inc, Berkeley, Ca.
;;;
;;; Permission is granted to any individual or institution to use, copy, modify,
;;; and distribute this software, provided that this complete copyright and
;;; permission notice is maintained, intact, in all copies and supporting
;;; documentation.
;;;
;;; Texas Instruments Incorporated provides this software "as is" without
;;; express or implied warranty.
;;;
;;; Franz Incorporated provides this software "as is" without express or
;;; implied warranty.



--- C.all/lisp/help/clx
--- Copyright University of Sussex 1995. All rights reserved.
