HELP X                                                 A.Sloman Oct 1990
                                         Updated: Adrian Howard Jul 1992

                         The POPLOG X Interface
                         ----------------------

This file is provided to enable users to get started using the POPLOG
interface to X. The file will probably be gradually improved, corrected
and extended.

NB: in order to access most of the documentation and program libraries
described below, it will be necessary first to give the POP-11 command

    uses popxlib

This can go into your init.p file if you regularly use X.

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

 -- Introduction
 -- Note for experienced programmers
 -- Pre-requisites
 -- VED in X
 -- Accessing the POPLOG/X libraries
 -- Finding what documentation is available
 -- Working through a simple POPLOG/X demonstration
 -- Other TEACH files
 -- Important HELP files
 -- Acknowledgement


-- Introduction -------------------------------------------------------

The POPLOG interface to X provides a great many facilities for
interacting with graphical windows and other objects, reacting either
synchronously or asynchronously with events in those windows, and
building higher level tools on the primitives provided.

It can be used on a workstation running X , or on an X terminal
connected to a suitable computer. You can also log through from a
workstation running X to another computer (e.g. bigger and faster) and
run your POPLOG/X programs there, driving graphical processes on your
workstation via the network connection. Most of the facilities are
design for X version 11 Release 4, or later. It may be possible to use
older versions of X, with certain restrictions. There are also
restrictions on some machines, where suppliers do not provide full
dynamically loadable versions of the X libraries.

The basic POPLOG interface to X is implemented via POP-11, and the
procedures provided can be invoked from other POPLOG languages via
POP-11. It is intended that libraries tailored to the different
languages will be added in due course.

For LISP users CLX is already available as part of the $popcontrib
library -- See HELP * CONTRIB and the LISP HELP *CLX. However CLX
provides a far more primitive interface to X than that described here.

A preliminary set of utilities for driving X from Prolog is also
available in the files in $popcontrib/x/prolog/xpw.

Although there are interfaces and tools for expert X programmers, POPLOG
also now provides a basic collection of useful facilities that enable a
wide variety of applications.

The rest of this file tells you how you can get started.


-- Note for experienced programmers -----------------------------------

Beginners can skip this section.

Sophisticated programmers who develop their own widget sets can link
them into POPLOG using the mechanisms described in REF *XptWidgetSet.

POPLOG supports the OLIT, Motif, Athena, and POPLOG widget sets.

For advanced POPLOG X programming it is recommended that you read
standard manuals on X. POPLOG provides interface facilities at the XLIB
and XTOOLKIT level as well as facilities for linking in widget sets.

The POPLOG Widget Set, which provides graphical and text manipulation
facilities, is described in HELP * Xpw, and related files referred to
therein.

Sophisticated programmers will need to read all the files in the
POPLOG/X REF and HELP directories, listed in

    HELP *XPOPINDEX
    REF  *XPOPINDEX

and may also need to look at the library files in the X subtree of
POPLOG, i.e. $usepop/pop/x/*, in order to see how things are done.

REF * SYSTEM explains some of the startup mechanisms. Search for mention
of
    %x
        An optional "command-line" flag used when starting up POPLOG, to
        indicate that X facilities are to be used.

    popunderx
        Set non-false (normally a list, possibly empty) if the "%x" flag
        is used.

    sysxsetup
        A user-definable procedure used to open a connection to the X
        server. See *SYSXSETUP for details.

Most of the rest of this file is for relatively naive users.


-- Pre-requisites -----------------------------------------------------

It is assumed that you are using POPLOG Version 14.1 or later and that
you have access to a server running X, version 11 Release 4 or later.
Some aspects of POPLOG/X may not work on Release 3 as it has been
assumed that Release 4 will be standard soon after POPLOG/X is made
available.

If you wish to become a serious POPLOG/X programmer you will need to
study X and whatever facilities your server provides that are built on
top of it, e.g. which window managers are available.

However, there are a number of basic capabilities that can be learnt
simply by playing with some of the facilities described here.


-- VED in X -----------------------------------------------------------

There is a full X based VED editor available from POPLOG version 14.1.
See HELP *XVED for details.

VED can  also be  used in  an  ordinary "xterm"  window, i.e.  a  window
containing a VT100 terminal emulator, or something similar. (See  HELP *
VEDXTERM for xterm, HELP * VEDDXTERM for dxterm). In that case, VED will
work as if it were communicating with a VDU of the appropriate type. You
may have trouble getting all the function keys to work, and for that you
have to  set up  your X  environment  properly in  such files  as  .xrdb
.xstart .Xdefaults, or whatever. If in doubt consult your system manager
or the supplier of your workstation or Xterminal.

See also
    HELP * VEDXTERM,
    HELP * VEDDXTERM,
    REF * VEDTERMINALS,
    HELP * TERMINAL,
    HELP * INITIAL


-- Accessing the POPLOG/X libraries -----------------------------------

When you start up Pop11 or Prolog or Lisp or ML you will get an
executable image that contains a core of the POPLOG-X interface
facilities. However, making use of them will require loading additional
libraries. Some of these may take some time to load, and therefore you
may find it most convenient to create saved images containing them so
that you don't have to recompile them whenever you log in.
Alternatively, your local POPLOG system administrator may have provided
saved images with pre-compiled X facilities.
    (See HELP * SYSSAVE, REF * SYSTEM)

In order to be able to access the program and documentation libraries
described in this file, you should put into your init.p file the
following command

    uses popxlib

This will extend various search lists so that LIB, TEACH, HELP, USES and
similar commands will find relevant items in POPLOG/X libraries.

It is probably also a good idea to increase the value of the variable
-popmemlim- to at least 350000 words, i.e. put in your init.p file:

    350000 -> popmemlim;

This will enable you to load a considerable number of POPLOG/X libraries
without bumping into the "MEMORY LIMIT EXCEEDED" error message. Use a
larger number if you get that message. This may be required if you will
also be compiling large programs of your own. Too large a number can
cause your machine to spend too much time paging. See HELP * POPMEMLIM


-- Finding what documentation is available ----------------------------

If you wish to learn more about what documentation is available for X
generally, you should read DOC *XBIBLIOGRAPHY, by doing:

    uses popxlib;
    doc xbibliography

Apart from this file (HELP X) there is another very important overview
file REF * X, which is in the main POPLOG REF directory, unlike the
other REF files specifically concerned with X, which are in the X
subtree of POPLOG. (See the section on the POPLOG directory tree in
DOC * SYSSPEC).

To see the indexes for HELP, REF, TEACH and DOC files, look at:

    DOC * XPOPINDEX
    REF * XPOPINDEX
    HELP * XPOPINDEX
    TEACH * XPOPINDEX

There are a few POPLOG/X HELP files, e.g. this one, that are not in the
X libraries, but in the main POPLOG library, so that they can be found
easily. These are

    HELP * X
        This file

    HELP * XNEWS
        Reports on changes to POPLOG/X
        This is well worth scanning to see if something relevant
        has been added that has not been included in this file.

    HELP *XVED
        An overview of the POPLOG XVed editor.

    HELP *POPLOG_UI
        An overview of the POPLOG X User Interface for Motif
        and OPEN LOOK.

    LIB  * POPXLIB
        This must be run before you can access the POPLOG/X files
        that are not in the main library. Some of the libraries also
        require LIB * XLIB.

    LIB  * POPXDEMO
        This must be run before you can access the demonstration
        files provided in $usepop/pop/x/pop/demo (as required for
        TEACH * OPENLOOK).

    LIB * POPXVED
        Adds POPXLIB to the search lists, and then adds XVED libraries
        and files to the search lists.


-- Working through a simple POPLOG/X demonstration --------------------

If you have never used the X Toolkit before, you should do:

    pop11

    uses popxlib

    teach xtoolkit

This tutorial gives you an in-depth example-ridden tutorial of the X
toolkit.

In order to get a feel for some of the graphical facilities packaged up
into a convenient user interface do

    pop11

    uses popxlib

    teach rc_graphic

and work through the examples.

Once you have done that, and if you have OLIT or Motif widget available,
you might want to try:

    teach propsheet ;;; for Motif or OLIT users

After that reading REF files listed in REF * XPOPINDEX will introduce
you to the more basic and general facilities that were used to implement
the LIB * RC_GRAPHIC package

Look at TEACH * XPOPINDEX to see whether any additional TEACH files have
become available.


-- Other TEACH files --------------------------------------------------

    TEACH * Xpw
        This file contains some sample code to illustrate how to create
        and use the graphics facilities provided by the POPLOG Widget
        Set.

    TEACH * RC_GRAPHIC
        A "higher level" set of facilities. This teach file is described
        above.

    TEACH * RC_GRAPHPLOT
        This file, an extension of TEACH RC_GRAPHIC, shows how to use a
        set of library facilities for drawing graphs of various kinds.

    TEACH * ATHENA
        A tutorial to demonstrate the creation and manipulation of some
        widgets from the Athena widget set.

    TEACH * MOTIF
        A tutorial to demonstrate the creation and manipulation of some
        widgets from the Motif widget set.

    TEACH * XmDemos
        Describes the demonstration libraries available in POPLOG for
        the Motif widget set.

    TEACH * OPENLOOK
        A tutorial to demonstrate the creation and manipulation of some
        widgets from the Open Look widget set.

    TEACH * XolDemos
        Describes the demonstration libraries available in POPLOG for
        the OLIT widget set.

    TEACH * XTOOLKIT
        Some general information about using the X toolkit and widgets.
        It also introduces the toolkit event handling and timer
        facilities.

    TEACH * PROPSHEET
        High level tool for building Motif and OLIT dialog boxes.


-- Important HELP files -----------------------------------------------

    HELP * Xpw
        Provides an overview of the POPLOG Widget Set.

    HELP * XtN
        A macro for managing string constants used by the X toolkit

    HELP * ATHENA
        Describes the POPLOG interface to the Athena Widget Set.

    HELP * MOTIF
        Describes the POPLOG interface to the Motif Widget Set.

    HELP * OPENLOOK
        Describes the POPLOG interface to the OLIT Widget Set.

    HELP * XCOLOURS
        A list of all of the named colours contained in the X
        colour database.

    HELP * XLIB
        Describes the POP-11 interface to the Xlib layer of the X
        system.

    HELP * RC_GRAPHIC  HELP * RC_GRAPHPLOT
        These two describe the "relative coordinates" graphic facilities

-- Acknowledgement ----------------------------------------------------

The POPLOG X interface was a developed by a team based at Sussex
University. Its members included Roger Evans, Ian Rogers, Jonathan
Meyer, John Gibson, Adrian Howard, Robert Duncan, Simon Nichols and
Andreas  Schoter. Tom Khabaza helped with management of the work  and
also contributed software and documentation. Jason Handby helped
document the POPLOG X toolkit interface. The RC_GRAPHIC package was
designed and implemented by Aaron Sloman  using ideas developed jointly
with David Hogg and David Young.


--- C.all/help/x
--- Copyright University of Sussex 1991. All rights reserved. ----------
