Python X11 interface modules
============================

For building instructions, read Makefile.pre.in, but also see below.

The Doc subdirectory contains source for a document that lists all
functions, methods, and variables that are supported in the X11
modules that are optionally available in Python.  Together with this
file, it is the only documentation for the X11 modules.

The following extension modules (in C) exist:

	Xt: The X Toolkit Intrinsics (including widgets like Core, Shell etc.)
	Xlib: A few routines that directly interface to Xlib
	Xrm: Interface to X Resource Manager functions
	Xaw: The Athena widgets (if you have and want them)
	Xm: The Motif widgets and gadgets (if you have Motif)
	Mrm: The Motif Resource Manager
	Glx: SGI's GlxDraw widget (only on SGI systems)
	HTML: NCSA's widget for HTML (HyperText Markup Language).

In addition, these modules written in Python define some useful
symbolic constants or functions (their source is in the Lib
subdirectory):

	X: constants defined in <X11/X.h>
	Xcursorfont: constants defined in <X11/cursorfont.h>
	Xmd: constants defined in <Xm/Xm.h>
	Xtdefs: constants defined in <X11/Intrinsic.h>
	Xutil: constants from <X11/Xutil.h>
	xmmenus: a set of functions that simplify the use of Motif menus
	GLX: constants for the Glx module.

The Demo directory has several subdirectories containing examples and
tests; see the README file there.

The directory Generate contains the set of Python scripts that were
used to create some of the files here.

The file Mosaic-patches contains a shell archive which contains
patches for the libhtmlw directory of three different versions of NCSA
Mosaic.  These patches add support for a resource "visual" (class
"Visual") to the HTML widget when the source is compiled with the
added flag -DVISUAL.  The changes are backward compatible.  The
changes are necessary if you want to use the HTML widget with a
non-default visual.

Making dynamically loadable modules
-----------------------------------

With some trickery it is possible to make the X extension modules into
dynamically loadable modules.  Since some modules depend on others
(especially Xm calls functions in Xt), the modules cannot be made into
separate dynamically loadable modules.  Instead we have to resort to
trickery.

Make sure all modules are commented out in the Setup file, then add
the following lines to Setup (the second is split because of its
length, but it should be one line):

*noconfig*
allX Xlibmodule.o Xtmodule.o event.o XColor.o Xttypes.o Fontobject.o \
 GCobject.o Pixmapobject.o wclassobject.o widgetobject.o Xawmodule.o \
 Xmmodule.o Xmsupport.o xmevent.o Mrmmodule.o mrmhierarchyobject.o \
 Glxmodule.o Glxsupport.o HTMLmodule.o htmlevent.o -I$(LIBHTMLW) \
 $(LIBHTMLW)/libhtmlw.a -lMrm -lUil -lXm -lPW -lXaw -lXirisw -lgl \
 -lXext -lXmu -lXt -lX11 -DUSE_EDITRES

These lines work on Irix 5.X.  For other systems (especially Solaris)
some more -I and -L flags need to be added.  Basically all libraries
that are used for the individual modules should be present in the
right order.  Also, only object files for modules that are supported
on the platform should be present.  This means that the Glx object
files and corresponding libraries should not be present on any systems
other than SGI's.

After these changes, "make Makefile" and "make sharedmods".  If you
try to just "make" or "make python" the odds are that that will fail.
The setup scripts can't deal with Setup files without any non-shared
modules.

After "make sharedmods" there is a file allXmodule.so.  Make links to
this file for all of the constituent modules, i.e.:
	ln -s allXmodule.so Xlibmodule.so
	ln -s allXmodule.so Xtmodule.so
	ln -s allXmodule.so Xmmodule.so
	ln -s allXmodule.so Mrmmodule.so
	ln -s allXmodule.so Xawmodule.so
	ln -s allXmodule.so Glxmodule.so
	ln -s allXmodule.so HTMLmodule.so

That's it.  You can use a standard python and import these modules.
You only have to be sure that the Lib directory is in your PYTHON_PATH
(or sys.path).

I have heard that this will not work on SunOS 4.1.X.  There are two
different situations where you will get an error message from the
run-time loader:

1) loadable module A and loadable module B are both linked against
   shared library C.  You can dlopen A but when you try to dlopen
   B, ld.so complains

2) loadable module A and executable program E are both linked against
   shared library C.  When you try dlopen A, ld.so complains.

This can only be considered a bug in SunOS.  The only two options
available are: don't use dynamically loadable modules, or upgrade to
Solaris 2.X.  (This info came from Mitch Garnaat, Wilson Center for
Research & Technology, Xerox Corporation <garnaat@wrc.xerox.com>.)