Installing Slash'EM with a GTK 2.0 interface
--------------------------------------------

This document describes the installation of Slash'EM with a GTK 2.0 interface
on X11.  The GTK interface is another alternative to the Athena-widgets
interface found in ../X11.  You can download GTK+ from http://www.gtk.org/.
You need GTK+ 2.x to use this code.

The GTK interface comes from JNetHack version 1.1.5 and was written by
Issei Numata (issei@guru.gr.jp). JNetHack can be downloaded from
http://www.jnethack.org/.

The interface can be used in a number of different ways:

   1. As a conventional windowing interface. This has the lowest overhead
      and is therefore fastest. The disadvantage is that the interface
      will run in the same process as the game itself and since the Gtk+
      libraries cannot run with elevated privileges this means that the
      game must be installed without using any special privileges. On the
      MS-Windows platform this is the only supported configuration anyway
      and so there is no disadvantage. On UNIX platforms this requires
      choosing not to install the game with setuid or setgid permissions.
      See ../../sys/unix/Install.unx for details.

   2. As a proxified windowing interface. In this mode, the GTK interface
      is included in the game executable as normal but the interface will
      fork and run as a child of the game process when it is initialised.
      This means that the interface can drop any privileges that the game
      process may have and thus the Gtk+ libraries can be run without any
      problems. In many ways this is the best compromise on UNIX systems
      although the NhExt protocol that the game and GTK interface use to
      communicate does involve a significant overhead.

   3. As an external windowing interface. This is similar to the proxified
      mode but instead of including the GTK windowing interface in the
      game executable a seperate executable, gtkhack, is created. When
      gtkhack is run it connects to the game and communicates with it
      using the NhExt protocol. The advantage of this over proxified mode
      is that there is the potential for the game and the interface to
      run on seperate machines and the game executable is significantly
      smaller. If the GTK interface is only one of a number of different
      interfaces which will be used by players then this can remove an
      unneccessary overhead. The disadvantage is that installation and
      configuration is slightly more complex.

To use this code:

   1. follow the directions for the UNIX installation (in ../sys/unix)
      or for the MS-Windows installation (in ../sys/winnt) to create
      the Makefiles.

   2. ../../include/config.h

        define the following symbols (search for them):

	    [conventional]  GTK_GRAPHICS
	    [proxified]     PROXY_GRAPHICS, GTK_GRAPHICS and GTK_PROXY
	    [external]      PROXY_GRAPHICS and GTK_PROXY

	You can comment out TTY_GRAPHICS if you want to, or leave it
	in to support both interfaces (in which case be sure you have
	the right curses libraries etc. required for that interface).

	It is highly recommded that you leave TTY_GRAPHICS defined
	if PROXY_GRAPHICS is defined. In any event, PROXY_GRAPHICS
	must not be the only windowing interface supported.

	You may define X11_GRAPHICS and/or QT_GRAPHICS in addition to
	support multiple windowing ports (and tty as well, if you want)
	in the same executable if you so desire.

	Proxified and external modes require that PROXY_GRAPHICS is
	defined which will add support for plug-in windowing ports.
	This may also be defined in conventional mode to support
	plug-in interfaces as well as the GTK interface if so desired.

   3. for an external windowing interface, follow the directions in
      ../proxy/Install.pxy to build a game with support for plug-in
      window interfaces and to build the proxy library. Then build
      gtkhack, the external executable, by changing to this directory
      and typing:

	    [UNIX]		make -f Makefile.unx
	    [MS-Windows]	make -f Makefile.w32

      GtkHack relies on the game executable for tiles, but does need
      a couple of other support files:

	    credit.xpm		found in ../../dat
	    gtkrc		found in GTKRC (UNIX) or GTKRC.w32 (MS-Windows)

      Install the gtkhack executable and its support files somewhere
      suitable and then skip to step 6.

   4. ../../src/Makefile

	[UNIX]

	Add the following to WINSRC, WINOBJ, and WINLIB and compile:

	    [conventional]
		[WINSRC]    $(WINGTKSRC) $(PROXYUTLSRC)
		[WINOBJ]    $(WINGTKOBJ) $(PROXYUTLOBJ)
		[WINLIB]    $(WINGTKLIB)
	    [proxified]
		[WINSRC]    $(WINGTKSRC) $(WINPROXYSRC) $(PROXYUTLSRC) \
			    $(PROXYCOMSRC) $(PROXYCLNTSRC)
		[WINOBJ]    $(WINGTKOBJ) $(WINPROXYOBJ) $(PROXYUTLOBJ) \
			    $(PROXYCOMOBJ) $(PROXYCLNTOBJ)
		[WINLIB]    $(WINGTKLIB) $(WINPROXYLIB)

        This will give you an executable supporting GTK 2.0 and possibly
	plug-in windowing ports. To support tty windowing as well, add
	$(WINTTYSRC), $(WINTTYOBJ), and $(WINTTYLIB) to WINSRC, WINOBJ,
	and WINLIB respectively.

	To support multiple windowing ports, change the definitions of
	WINSRC, WINOBJ and WINLIB to include all the relevant variables.

	[MS-Windows]

	change the definition of USE_GTK and USE_PROXY as follows and
	compile:

	    [conventional]
		USE_GTK = Y
		USE_PROXY = N
	    [proxified]
		USE_GTK = N
		USE_PROXY = Y

	This will give you an executable supporting both tty windowing
	and GTK 2.0 and possibly plug-in windowing ports. Multiple
	windowing ports (apart from the above) are not supported under
	MS-Windows.

   5. [UNIX] ../../Makefile (the top-level makefile)

        change CNF_SHARE_DATND to include:
	
	    [conventional]    $(CNF_SHARE_GTKND)
	    [proxified]       $(CNF_SHARE_GTKND) and $(CNF_SHARE_GTKPROXYND)

	If you want to support the other windowing ports, include
	their $(CNF_SHARE_XXXND) variables also.

	CNF_SHARE_DATND should normally include all the various flavours
	of x11tiles to allow the user to select which tile set he/she
	would prefer at runtime. If you will always be using the same
	one however, you can remove the others.

   6. Follow all the instructions in ../../sys/unix/Install.unx or the
      appropriate documentation in ../../sys/winnt for the remainder of
      the installation process.

   7. Consider adding the lines below to your .slashemrc (or equivalent
      if you don't run UNIX), as they are likely to give the best interface
      for this window port:

        TILESET=name:Small tiles, file:x11tiles
	TILESET=name:Big tiles, file:x11bigtiles, transparent
	TILESET=name:Big 3D tiles, file:x11big3dtiles, transparent, pseudo3D
        OPTIONS=tiles:Big 3D tiles

      Set the tiles option to your preferred tile set. If not set, the
      GTK port will default to the first valid tile set found.

   8. Look at GAMEDIR/gtkrc (or FILE_AREA_SHARE/gtkrc if using file areas)
      and overide the styles in your local gtkrc (~/.gtkrc by default)
      if so desired.
