NetHack 3.7  window.txt	$NHDT-Date: 1666390558 2022/10/21 22:15:58 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.70 $

Introduction

This file documents the support for various windowing systems in
NetHack.  The support is through a standard interface, separating the
main NetHack code from window-system specific code.  The implementation
supports multiple window systems in the same binary.  Even if you only
wish to support one window-port on your port, you will need to follow
the instructions in Section IX to get a compilable binary.

Copyright 2003, David Cohrs
NetHack may be freely redistributed.  See license for details.

Contents:
	I.    Window Types and Terminology
	II.   Interface Specification
	III.  Global variables
	IV.   WINCAP preferences support
	V.    New or respecified common, high level routines
	VI.   Game startup
	VII.  Conventions
	VIII. Implementation and Multi-window support
	IX.   WINCHAIN

I.  Window Types and Terminology

There are 4 basic window types, used to call create_nhwindow():

	NHW_MESSAGE	(top line)
	NHW_MAP		(main dungeon)
	NHW_MENU	(inventory or other "corner" windows)
	NHW_TEXT	(help/text, full screen paged window)

The tty window-port also uses NHW_BASE (the base display) internally.

(The genl_status_* routines use NHW_STATUS for backward compatibility
 when displaying status information on the bottom lines.  New code
 should not use NHW_STATUS.  NHW_STATUS will be phased out over time.)

NHW_MENU windows can be used for either menu or text display.  Their
basic feature is that for the tty-port, if the window is small enough,
it appears in the corner of the tty display instead of overwriting
the whole screen.  The first call to add information to the window
will decide if it is going to be used to display a menu or text.
If start_menu() is called, then it will be used as a menu.  If
putstr() is called, it will be used as text.  Once decided, there
is no turning back.  For the tty-port, if the data is too large for
a single screen then the data is paged (with --more--) between pages.
Only NHW_MENU type windows can be used for menus.

NHW_TEXT windows are used to display a large amount of textual data.
This is the type of window one would use for displaying a help file,
for example.  In the tty window-port, windows of type NHW_TEXT can
page using the DEF_PAGER, if DEF_PAGER is defined.  There exists an
assumption that the font for text windows is monospaced.  The help
files are all formatted accordingly.

NHW_MAP is a persistent window which uses tty-style character cell
column and row as x,y coordinates (even for tiled map).  The y or row
coordinate runs from 0 through ROWNO-1 inclusive, with 0 at the top
and +(ROWNO-1) at the bottom.  The x or column coordinate runs from
_1_ through COLNO-1, left to right.  Column 0 is used by the core
for internal bookkeeping and not drawn on the screen.  Most levels
leave some rows and/or columns unused but the core still passes data
(typically 'unexplored' or 'solid stone') for them and those should
be rendered to the screen.  The exception is map column 0.  The map
window does not need to include room for that; if it does, that column
should be drawn as <space> for text map or the tile specified for
GLYPH_NOTHING for tiled map.

"window" is always of type winid.  This is currently implemented as an
integer, but doesn't necessarily have to be done that way.  There are
a few fixed window names that are known throughout the code:

	WIN_MESSAGE	(top line)
	WIN_MAP		(main dungeon)
	WIN_INVEN	(inventory)

Other windows are created and destroyed as needed.

(The genl_status_* routines use WIN_STATUS for backward compatibility
 when displaying status information on the bottom lines.  New code
 should not use WIN_STATUS, or assume its presence. NHW_STATUS will
 be phased out over time.)

"Port" in this document refers to a CPU/OS/hardware platform (UNIX, MSDOS
TOS, etc.)  "window-port" refers to the windowing platform.  This is
orthogonal (e.g.  UNIX might use either a tty window-port or an X11
window-port).


II.  Interface Specification

All functions below are void unless otherwise noted.

A.  Low-level routines:

raw_print(str)	-- Print directly to a screen, or otherwise guarantee that
		   the user sees str.  raw_print() appends a newline to str.
		   It need not recognize ASCII control characters.  This is
		   used during startup (before windowing system initialization
		   -- maybe this means only error startup messages are raw),
		   for error messages, and maybe other "msg" uses.  E.g.
		   updating status for micros (i.e, "saving").
raw_print_bold(str)
		-- Like raw_print(), but prints in bold/standout (if possible).
curs(window, x, y)
		-- Next output to window will start at (x,y), also moves
		   displayable cursor to (x,y).  For backward compatibility,
		   1 <= x < cols, 0 <= y < rows, where cols and rows are
		   the size of window.
		-- For variable sized windows, like the old status window, the
		   behavior when curs() is called outside the window's limits
		   is unspecified. The mac port wraps to 0, with the status
		   window being 2 lines high and 80 columns wide.
		-- Still used by curs_on_u(), obsolete status updates,
		   screen locating (identify, teleport).
		-- NHW_MESSAGE, NHW_MENU and NHW_TEXT windows do not
		   currently support curs in the tty window-port.
putstr(window, attr, str)
		-- Print str on the window with the given attribute.  Only
		   printable ASCII characters (040-0126) must be supported.
		   Multiple putstr()s are output on separate lines.  Attributes
		   can be one of
			ATR_NONE (or 0)
			ATR_ULINE
			ATR_BOLD
			ATR_BLINK
			ATR_INVERSE
		   If a window-port does not support all of these, it may map
		   unsupported attributes to a supported one (e.g. map them
		   all to ATR_INVERSE).  putstr() may compress spaces out of
		   str, break str, or truncate str, if necessary for the
		   display.  Where putstr() breaks a line, it has to clear
		   to end-of-line.
		-- putstr should be implemented such that if two putstr()s
		   are done consecutively the user will see the first and
		   then the second.  In the tty port, pline() achieves this
		   by calling more() or displaying both on the same line.
putmixed(window, attr, str)
		-- Print str on the window with the given attribute.  In
		   addition to printable ASCII characters (040-0126),
		   sequences of encoded glyph values are supported.
		   The glyph encoding sequence is \GXXXXNNNN, where:
			XXXX is a hexadecimal value. The value must match
			     the randomly generated value for the current
			     game in progress in order to be decoded.
			     The value for the game in progress is stored in
			     context.rndencode.  This field minimizes
			     unintentional decoding of player-supplied strings
			     such as pet names, etc.
			NNNN is a hexadecimal value representing the glyph.
		   If a window port does not yet support special handling of
		   the glyph value, it can use genl_putmixed (windows.c)
		   which converts the encoded glyph into a character symbol.

		   Multiple putmixed()s are output on separate lines.
		   Attributes can be one of
			ATR_NONE (or 0)
			ATR_ULINE
			ATR_BOLD
			ATR_BLINK
			ATR_INVERSE
		   If a window-port does not support all of these, it may map
		   unsupported attributes to a supported one (e.g. map them
		   all to ATR_INVERSE).  putmixed() may compress spaces out of
		   str, break str, or truncate str, if necessary for the
		   display.  Where putmixed() breaks a line, it has to clear
		   to end-of-line.
		-- putstr should be implemented such that if two putmixed()s
		   are done consecutively the user will see the first and
		   then the second.
get_nh_event()	-- Does window event processing (e.g. exposure events).
		   A noop for the tty and X window-ports.
int nhgetch()	-- Returns a single character input from the user.
		-- In the tty window-port, nhgetch() assumes that tgetch()
		   will be the routine the OS provides to read a character.
		   Returned character _must_ be non-zero and it must be
                   non meta-zero too (zero with the meta-bit set).
		-- If platform uses it, should check program_state.done_hup
		   and immediately return ASCII 033 (escape) if it is.
		   This is required if the window-port supports SAFERHANGUP.
		-- ASCII 033 must also be returned rather than EOF (applies
		   mainly to the tty window-port).
		-- The program_state.done_hup flag can be set asynchronously
		   when SAFERHANGUP is defined and in that case, nhgetch()
		   needs to detect that the value of program_state.done_hup
		   changed and also return ASCII 033 in this case.
int nh_poskey(int *x, int *y, int *mod)
		-- Returns a single character input from the user or a
		   positioning event (perhaps from a mouse).  If the
		   return value is non-zero, a character was typed, else,
		   a position in the MAP window is returned in x, y and mod.
		   mod may be one of

			CLICK_1		/* mouse click type 1 */
			CLICK_2		/* mouse click type 2 */

		   The different click types can map to whatever the
		   hardware supports.  If no mouse is supported, this
		   routine always returns a non-zero character.
		-- Otherwise follows the same behavior as nhgetch().

B.  High-level routines:

print_glyph(window, x, y, glyphinfo, bkglyphinfo)
		-- Print a glyph found within the glyphinfo at (x,y) on the
                   given window. The glyphs within the glyph_info struct are
                   integers and can be mapped to whatever the window-
		   port wants (symbol, font, color, attributes, ...there's
		   a 1-1 map between glyphs and distinct things on the map).
		-- bkglyphinfo contains a background glyph for potential use
		   by some graphical or tiled environments to allow the
		   depiction to fall against a background consistent with the
		   grid around x,y.  If bkglyphinfo->glyph is NO_GLYPH, then
		   the parameter should be ignored (do nothing with it).
                -- glyph_info struct fields:
                    int glyph;    /* the display entity */
                    int color;    /* color for window ports not using a tile */
                    int ttychar;  /* the character mapping for the original tty
                                   * interface. Most or all window ports wanted
                                   * and used this for various things so it is
                                   * provided in 3.7+ */
                    short int symidx;    /* offset into syms array */
                    unsigned glyphflags; /* more detail about the entity */


char yn_function(const char *ques, const char *choices, char default)
		-- Print a prompt made up of ques, choices and default.
		   Read a single character response that is contained in
		   choices or default.  If choices is NULL, all possible
		   inputs are accepted and returned.  This overrides
		   everything else.  The choices are expected to be in
		   lower case.  Entering ESC always maps to 'q', or 'n',
		   in that order, if present in choices, otherwise it maps
		   to default.  Entering any other quit character (SPACE,
		   RETURN, NEWLINE) maps to default.
		-- If the choices string contains ESC, then anything after
		   it is an acceptable response, but the ESC and whatever
		   follows is not included in the prompt.
		-- If the choices string contains a '#' then accept a count.
		   Place this value in the global "yn_number" and return '#'.
		-- This uses the top line in the tty window-port, other
		   ports might use a popup.
		-- If choices is NULL, all possible inputs are accepted and
		   returned, preserving case (upper or lower.) This means that
		   if the calling function needs an exact match, it must handle
		   user input correctness itself.
		-- ques should not be more than QBUFSZ-1 characters long.
getlin(const char *ques, char *input)
		-- Prints ques as a prompt and reads a single line of text,
		   up to a newline.  The string entered is returned without the
		   newline.  ESC is used to cancel, in which case the string
		   "\033\000" is returned.
		-- getlin() must call flush_screen(1) before doing anything.
		-- This uses the top line in the tty window-port, other
		   ports might use a popup.
		-- getlin() can assume the input buffer is at least BUFSZ
		   bytes in size and must truncate inputs to fit, including
		   the nul character.
int get_ext_cmd(void)
		-- Get an extended command in a window-port specific way.
		   An index into extcmdlist[] is returned on a successful
		   selection, -1 otherwise.
player_selection()
		-- Do a window-port specific player type selection.  If
		   player_selection() offers a Quit option, it is its
		   responsibility to clean up and terminate the process.
		   You need to fill in pl_character[0].
display_file(str, boolean complain)
		-- Display the file named str.  Complain about missing files
		   iff complain is TRUE.
update_inventory(arg)
		-- For an argument of 0:
		   -- Indicate to the window port that the inventory has
		      been changed.
		   -- Merely calls display_inventory() for window-ports
		      that leave the window up, otherwise empty.
		-- or for a non-zero argument:
		   -- Prompts the user for a menu scrolling action and
		      executes that.
		   -- May repeat until user finishes (typically by using
		      <return> or <esc> but interface may use other means).
doprev_message()
		-- Display previous messages.  Used by the ^P command.
		-- On the tty-port this scrolls WIN_MESSAGE back one line.

update_positionbar(char *features)
		-- Optional, POSITIONBAR must be defined. Provide some
		   additional information for use in a horizontal
		   position bar (most useful on clipped displays).
		   Features is a series of char pairs.  The first char
		   in the pair is a symbol and the second char is the
		   column where it is currently located.
		   A '<' is used to mark an upstairs, a '>'
		   for a downstairs, and an '@' for the current player
		   location. A zero char marks the end of the list.
			

C.  Window Utility Routines

init_nhwindows(int* argcp, char** argv)
		-- Initialize the windows used by NetHack.  This can also
		   create the standard windows listed at the top, but does
		   not display them.
		-- Any commandline arguments relevant to the windowport
		   should be interpreted, and *argcp and *argv should
		   be changed to remove those arguments.
		-- When the message window is created, the variable
		   iflags.window_inited needs to be set to TRUE.  Otherwise
		   all plines() will be done via raw_print().
		** Why not have init_nhwindows() create all of the "standard"
		** windows?  Or at least all but WIN_INFO?	-dean
exit_nhwindows(str)
		-- Exits the window system.  This should dismiss all windows,
		   except the "window" used for raw_print().  str is printed
		   if possible.
window = create_nhwindow(type)
		-- Create a window of type "type."
clear_nhwindow(window)
		-- Clear the given window, when appropriate.
display_nhwindow(window, boolean blocking)
		-- Display the window on the screen.  If there is data
		   pending for output in that window, it should be sent.
		   If blocking is TRUE, display_nhwindow() will not
		   return until the data has been displayed on the screen,
		   and acknowledged by the user where appropriate.
		-- All calls are blocking in the tty window-port.
		-- Calling display_nhwindow(WIN_MESSAGE,???) will do a
		   --more--, if necessary, in the tty window-port.
destroy_nhwindow(window)
		-- Destroy will dismiss the window if the window has not
		   already been dismissed.
start_menu(window, unsigned long mbehavior)
		-- Start using window as a menu.  You must call start_menu()
		   before add_menu().  After calling start_menu() you may not
		   putstr() to the window.  Only windows of type NHW_MENU may
		   be used for menus.
		-- mbehavior allows flags to be passed to alter the appearance
                   and/or behavior of the menu.
add_menu(windid window, glyphinfo, const anything identifier, char accelerator,
                                char groupacc, int attr, int clr, char *str,
                                unsigned itemflags)
		-- Add a text line str to the given menu window.  If identifier
		   is 0, then the line cannot be selected (e.g. a title).
		   Otherwise, identifier is the value returned if the line is
		   selected.  Accelerator is a keyboard key that can be used
		   to select the line.  If the accelerator of a selectable
		   item is 0, the window system is free to select its own
		   accelerator.  It is up to the window-port to make the
		   accelerator visible to the user (e.g. put "a - " in front
		   of str).  The value attr is the same as in putstr().
		-- glyphinfo (glyph_info type) may optionally contain a glyph
                   to accompany the line. If a window port cannot
                   or does not want to display it, this is OK.  If there is no
                   glyph provided, then the value of glyphinfo->glyph will
                   be NO_GLYPH.
		-- All accelerators should be in the range [A-Za-z],
		   but there are a few exceptions such as the tty player
		   selection code which uses '*'.
	        -- It is expected that callers do not mix accelerator
		   choices.  Either all selectable items have an accelerator
		   or let the window system pick them.  Don't do both.
		-- Groupacc is a group accelerator.  It may be any character
		   outside of the standard accelerator (see above) or a
		   number.  If 0, the item is unaffected by any group
		   accelerator.  If this accelerator conflicts with
		   the menu command (or their user defined aliases), it loses.
		   The menu commands and aliases take care not to interfere
		   with the default object class symbols.
                -- attr attributes can be one of
			ATR_NONE (or 0)
			ATR_ULINE
			ATR_BOLD
			ATR_BLINK
			ATR_INVERSE
		   If a window-port does not support all of these, it may map
		   unsupported attributes to a supported one (e.g. map them
		   all to ATR_INVERSE).
                -- clr color will hold a color value including 24-bit
                   true color values. To do that, and make it
                   distinguishable on the windowport side of things, the
                   windowport needs to treat it as follows:
                      0      = not used, just ignore the clr value.
                      1-16   = indicates a normal NetHack color value from
                               0 - 15, so subtract 1 to get the NetHack
                               color value.
                      17...  = indicates a 24-bit RGB color value, so
                               subtract 17 to get the actual 24-bit
                               color value.
                   When placing the values into this parameter, the core
                   will add 1 to a NetHack color value, and add 17 to a
                   24-bit RGB color value. 
                -- str is a pointer to the menu item text.
		-- itemflags on this item (such as MENU_ITEMFLAGS_SELECTED etc.).

end_menu(window, prompt)
		-- Stop adding entries to the menu and flushes the window
		   to the screen (brings to front?).  Prompt is a prompt
		   to give the user.  If prompt is NULL, no prompt will
		   be printed.
		** This probably shouldn't flush the window any more (if
		** it ever did).  That should be select_menu's job.  -dean
int select_menu(windid window, int how, menu_item **selected)
		-- Return the number of items selected; 0 if none were chosen,
		   -1 when explicitly cancelled.  If items were selected, then
		   selected is filled in with an allocated array of menu_item
		   structures, one for each selected line.  The caller must
		   free this array when done with it.  The "count" field
		   of selected is a user supplied count.  If the user did
		   not supply a count, then the count field is filled with
		   -1 (meaning all).  A count of zero is equivalent to not
		   being selected and should not be in the list.  If no items
		   were selected, then selected is NULL'ed out.  How is the
		   mode of the menu.  Three valid values are PICK_NONE,
		   PICK_ONE, and PICK_ANY, meaning: nothing is selectable,
		   only one thing is selectable, and any number valid items
		   may selected.  If how is PICK_NONE, this function should
		   never return anything but 0 or -1.
		-- You may call select_menu() on a window multiple times --
		   the menu is saved until start_menu() or destroy_nhwindow()
		   is called on the window.
		-- Note that NHW_MENU windows need not have select_menu()
		   called for them. There is no way of knowing whether
		   select_menu() will be called for the window at
		   create_nhwindow() time.
char message_menu(char let, int how, const char *mesg)
		-- tty-specific hack to allow single line context-sensitive
		   help to behave compatibly with multi-line help menus.
		-- This should only be called when a prompt is active; it
		   sends `mesg' to the message window.  For tty, it forces
		   a --More-- prompt and enables `let' as a viable keystroke
		   for dismissing that prompt, so that the original prompt
		   can be answered from the message line "help menu".
		-- Return value is either `let', '\0' (no selection was made),
		   or '\033' (explicit cancellation was requested).
		-- Interfaces which issue prompts and messages to separate
		   windows typically won't need this functionality, so can
		   substitute genl_message_menu (windows.c) instead.

D.  Status Display Routines

status_init()   -- core calls this to notify the window port that a status
		   display is required. The window port should perform
		   the necessary initialization in here, allocate memory, etc.
status_enablefield(int fldindex, char fldname, char fieldfmt, boolean enable)
                -- notifies the window port which fields it is authorized to
		   display.
		-- This may be called at any time, and is used
		   to disable as well as enable fields, depending on the
		   value of the final argument (TRUE = enable).
		-- fldindex could be one of the following from botl.h:
		   BL_TITLE, BL_STR, BL_DX, BL_CO, BL_IN, BL_WI, BL_CH,
		   BL_ALIGN, BL_SCORE, BL_CAP, BL_GOLD, BL_ENE, BL_ENEMAX,
		   BL_XP, BL_AC, BL_HD, BL_TIME, BL_HUNGER, BL_HP, BL_HPMAX,
		   BL_LEVELDESC, BL_EXP, BL_CONDITION
		-- There are MAXBLSTATS status fields (from botl.h)
status_update(int fldindex, genericptr_t ptr, int chg, int percentage, \
              int color, long *colormasks)
		-- update the value of a status field.
		-- the fldindex identifies which field is changing and
		   is an integer index value from botl.h
		-- fldindex could be any one of the following from botl.h:
		   BL_TITLE, BL_STR, BL_DX, BL_CO, BL_IN, BL_WI, BL_CH,
		   BL_ALIGN, BL_SCORE, BL_CAP, BL_GOLD, BL_ENE, BL_ENEMAX,
		   BL_XP, BL_AC, BL_HD, BL_TIME, BL_HUNGER, BL_HP, BL_HPMAX,
		   BL_LEVELDESC, BL_EXP, BL_CONDITION
		-- fldindex could also be BL_FLUSH (-1), which is not really
		   a field index, but is a special trigger to tell the
		   windowport that it should output all changes received
                   to this point. It marks the end of a bot() cycle.
		-- fldindex could also be BL_RESET (-2), which is not really
		   a field index, but is a special advisory to to tell the
		   windowport that it should redisplay all its status fields,
		   even if no changes have been presented to it.
		-- ptr is usually a "char *", unless fldindex is BL_CONDITION.
		   If fldindex is BL_CONDITION, then ptr is a long value with
		   any or none of the following bits set (from botl.h):
                        BL_MASK_BAREH        0x00000001L
                        BL_MASK_BLIND        0x00000002L
                        BL_MASK_BUSY         0x00000004L
                        BL_MASK_CONF         0x00000008L
                        BL_MASK_DEAF         0x00000010L
                        BL_MASK_ELF_IRON     0x00000020L
                        BL_MASK_FLY          0x00000040L
                        BL_MASK_FOODPOIS     0x00000080L
                        BL_MASK_GLOWHANDS    0x00000100L
                        BL_MASK_GRAB         0x00000200L
                        BL_MASK_HALLU        0x00000400L
                        BL_MASK_HELD         0x00000800L
                        BL_MASK_ICY          0x00001000L
                        BL_MASK_INLAVA       0x00002000L
                        BL_MASK_LEV          0x00004000L
                        BL_MASK_PARLYZ       0x00008000L
                        BL_MASK_RIDE         0x00010000L
                        BL_MASK_SLEEPING     0x00020000L
                        BL_MASK_SLIME        0x00040000L
                        BL_MASK_SLIPPERY     0x00080000L
                        BL_MASK_STONE        0x00100000L
                        BL_MASK_STRNGL       0x00200000L
                        BL_MASK_STUN         0x00400000L
                        BL_MASK_SUBMERGED    0x00800000L
                        BL_MASK_TERMILL      0x01000000L
                        BL_MASK_TETHERED     0x02000000L
                        BL_MASK_TRAPPED      0x04000000L
                        BL_MASK_UNCONSC      0x08000000L
                        BL_MASK_WOUNDEDL     0x10000000L
                        BL_MASK_HOLDING      0x20000000L
		-- The value passed for BL_GOLD includes a leading
		   symbol for GOLD "$:nnn". If the window port needs to use
		   the textual gold amount without the leading "$:" the port
		   will have to add 2 to the passed "ptr" for the BL_GOLD case.
                -- color is an unsigned int.
                   int & 0x00FF = color CLR_*
                   int >> 8 = attribute (if any)

                   This contains the color and attribute that the field should
                   be displayed in.

                   This is relevant for everything except BL_CONDITION.
                   If fldindex is BL_CONDITION, this parameter should be
                   ignored, as condition hilighting is done via the next
                   colormasks parameter instead.

                -- colormasks - pointer to cond_hilites[] array of colormasks.
                   Only relevant for BL_CONDITION fldindex. The window port
                   should ignore this parameter for other fldindex values.

                   Each condition bit must only ever appear in one of the
                   CLR_ array members, but can appear in multiple HL_ATTCLR_
                   offsets (because more than one attribute can co-exist).

                   For the user's chosen set of BL_MASK_ condition bits,
                   They are stored internally in the cond_hilites[] array,
                   at the array offset aligned to the color those condition
                   bits should display in.

                   For example, if the user has chosen to display strngl
                   and stone and termill in red and inverse,

                        BL_MASK_SLIME           0x00000002
                        BL_MASK_STRNGL          0x00000004
                        BL_MASK_TERMILL         0x00000010

                   The bitmask corresponding to those conditions is
                   0x00000016 (or 00010110 in binary) and the color
                   is at offset 1 (CLR_RED).

                   Here is how that is stored in the cond_hilites[] array:

                   +------+----------------------+--------------------+
                   |array |                      |                    |
                   |offset| macro for indexing   |   bitmask          |
                   |------+----------------------+--------------------+
                   |   0  |   CLR_BLACK          |                    |
                   +------+----------------------+--------------------+
                   |   1  |   CLR_RED            |   00010110         |
                   +------+----------------------+--------------------+
                   |   2  |   CLR_GREEN          |                    |
                   +------+----------------------+--------------------+
                   |   3  |   CLR_BROWN          |                    |
                   +------+----------------------+--------------------+
                   |   4  |   CLR_BLUE           |                    |
                   +------+----------------------+--------------------+
                   |   5  |   CLR_MAGENTA        |                    |
                   +------+----------------------+--------------------+
                   |   6  |   CLR_CYAN           |                    |
                   +------+----------------------+--------------------+
                   |   7  |   CLR_GRAY           |                    |
                   +------+----------------------+--------------------+
                   |   8  |   NO_COLOR           |                    |
                   +------+----------------------+--------------------+
                   |   9  |   CLR_ORANGE         |                    |
                   +------+----------------------+--------------------+
                   |  10  |   CLR_BRIGHT_GREEN   |                    |
                   +------+----------------------+--------------------+
                   |  11  |   CLR_BRIGHT_YELLOW  |                    |
                   +------+----------------------+--------------------+
                   |  12  |   CLR_BRIGHT_BLUE    |                    |
                   +------+----------------------+--------------------+
                   |  13  |   CLR_BRIGHT_MAGENTA |                    |
                   +------+----------------------+--------------------+
                   |  14  |   CLR_BRIGHT_CYAN    |                    |
                   +------+----------------------+--------------------+
                   |  15  |   CLR_WHITE          |                    |
                   +------+----------------------+--------------------+
                   |  16  |   HL_ATTCLR_DIM      |                    | CLR_MAX
                   +------+----------------------+--------------------+
                   |  17  |   HL_ATTCLR_BLINK    |                    |
                   +------+----------------------+--------------------+
                   |  18  |   HL_ATTCLR_ULINE    |                    |
                   +------+----------------------+--------------------+
                   |  19  |   HL_ATTCLR_INVERSE  |   00010110         |
                   +------+----------------------+--------------------+
                   |  20  |   HL_ATTCLR_BOLD     |                    |
                   +------+----------------------+--------------------+
                   |  21  | beyond array boundary|              | BL_ATTCLR_MAX

                   The window port can AND (&) the bits passed in the
                   ptr argument to status_update() with any non-zero
                   entries in the cond_hilites[] array to determine
                   the color and attributes for displaying the
                   condition on the screen for the user.

                   If the bit for a particular condition does not
                   appear in any of the cond_hilites[] array offsets,
                   that condition should be displayed in the default
                   color and attributes.

status_finish() -- called when it is time for the window port to tear down
		   the status display and free allocated memory, etc.


E.  Misc. Routines

make_sound(???) -- To be determined later.  THIS IS CURRENTLY UN-IMPLEMENTED.
nhbell()	-- Beep at user.  [This will exist at least until sounds are
		   redone, since sounds aren't attributable to windows anyway.]
                   Implementation should respect the flags.silent setting just
                   like the tty window-port does in tty_nhbell().
mark_synch()	-- Don't go beyond this point in I/O on any channel until
		   all channels are caught up to here.  Can be an empty call
		   for the moment
wait_synch()	-- Wait until all pending output is complete (*flush*() for
		   streams goes here).
		-- May also deal with exposure events etc. so that the
		   display is OK when return from wait_synch().
delay_output()	-- Causes a visible delay of 50ms in the output.
		   Conceptually, this is similar to wait_synch() followed
		   by a nap(50ms), but allows asynchronous operation.
askname()	-- Ask the user for a player name.
cliparound(x, y)-- Make sure that the user is more-or-less centered on the
		   screen if the playing area is larger than the screen.
		-- This function is only defined if CLIPPING is defined.
number_pad(state)
		-- Initialize the number pad to the given state.
suspend_nhwindows(str)
		-- Prepare the window to be suspended.
resume_nhwindows()
		-- Restore the windows after being suspended.
can_suspend()   -- Tell the core if the window system will allow the game
                   to be suspended now.  If unconditionally yes or no, use
		   genl_can_suspend_yes() or genl_can_suspend_no().

start_screen()	-- Only used on Unix tty ports, but must be declared for
		   completeness.  Sets up the tty to work in full-screen
		   graphics mode.  Look at win/tty/termcap.c for an
		   example.  If your window-port does not need this function
		   just declare an empty function.
end_screen()	-- Only used on Unix tty ports, but must be declared for
		   completeness.  The complement of start_screen().

outrip(winid, int, time_t)
		-- The tombstone code.  If you want the traditional code use
		   genl_outrip for the value and check the #if in rip.c.

preference_update(preference)
		-- The player has just changed one of the wincap preference
		   settings, and the NetHack core is notifying your window
		   port of that change.  If your window-port is capable of
		   dynamically adjusting to the change then it should do so.
		   Your window-port will only be notified of a particular
		   change if it indicated that it wants to be by setting the
		   corresponding bit in the wincap mask.

getmsghistory(init)
		-- This is used to preserve message history between games by
		   obtaining the messages from the window port so that the
		   core can put them into the savefile.
		   The routine is called repeatedly from the core save routine,
		   and the window port routine is expected to successively
		   return each message that it wants the game to store in the
		   savefile,  starting with the oldest message first, finishing
		   with the most recent.
		   If init is TRUE, start over again from most recent message.

putmsghistory(msg)
		-- This is the counterpart to getmsghistory() for restores
		   used to reload the port's message recall buffer.
		   The routine is called repeatedly from the core restore
		   routine, starting with the oldest message first, and
		   finishing with the most recent one that it read from the
		   savefile.  The window port routine is expected to load the
		   message recall buffers in such a way that the ordering
		   remains correct.  The window port routine should make no
		   assumptions about how
		   many messages are forthcoming, nor should it assume that
		   another message will follow this one, so it must be careful
		   to keep all pointers/indexes intact at the end of each call.
		   If the window port receives more messages that can fit in
		   its buffers, it is expected to scroll away the oldest from
		   its buffers, much like it would with new messages being
		   produced.


III.  Global variables

The following global variables are defined in decl.c and must be used by
the window interface to the rest of NetHack.

char toplines[BUFSZ]	Contains the last message printed to the WIN_MESSAGE
			window, used by Norep().
winid WIN_MESSAGE, WIN_MAP, WIN_INVEN
			The three standard windows.
			There is also a window called WIN_STATUS that is used
			only for backward compatibility in the genl_status_*
			set of generic status display functions.
char *AE, *AS;		Checked in options.c to see if we should load and
			switch to DECGraphics symset.  It is #ifdefed VMS
			and UNIX.
int LI, CO;		Set in sys/unix/ioctl.c.

The following appears to be Unix specific.  Other ports using the tty
window-port should also declare this variable in one of your sys/*.c files.

short ospeed;		Set and declared in sys/unix/unixtty.c (don't
			know about other sys files).

The following global variable is defined in options.c. It equates a
list of wincap option names with their associated bit-mask [see
section IV WINCAP preferences support].  The array is zero-terminated.

struct wc_Opt wc_options[];
			One entry for each available WINCAP option.
			Each entry has a wc_name field and a wc_bit
			field.

IV. WINCAP preferences support

Starting with NetHack 3.4.0, the window interface was enhanced to provide
a common way of setting window port user preferences from the config file,
and from the command line for some settings.

The wincap preference settings all have their underlying values stored
in iflags fields.  The names of the wincap related fields are all pre-
fixed with wc_ or wc2_ to make it easy to identify them.  Your window
port can access the fields directly.

Your window port identifies what options it will react to and support
by setting bits in the window_procs wincap mask and/or wincap2 mask.
Your window port can also fill in the color-availability table for
the window port, has_color[CLR_MAX] to flag the colors it supports
1 it does, or 0 it doesn't. [CLR_MAX is 16 as of 3.6.3.]

See section IX for details of where the wincap masks reside.

Two things control whether any preference setting appears in the
'O' command options menu during the game:
 1. The option must be marked as being supported by having its
    bit set in the window_procs wincap or wincap2 mask.
 2. The option must have its optflag field set to set_in_game in order
    to be able to set the option, or marked set_gameview if you just
    want to reveal what the option is set to.
Both conditions must be true to be able to see or set the option from
within NetHack.

The default values for the optflag field for all the options are
hard-coded into the option in options.c.  The default value for
the wc_ options can be altered by calling
	set_wc_option_mod_status(optmask, status)
The default value for the wc2_ options can be altered by calling
	set_wc2_option_mod_status(optmask, status)
In each case, set the option modification status to one of set_in_config,
set_gameview, or set_in_game.

The setting of any wincap or wincap2 option is handled by the NetHack
core option processing code. You do not have to provide a parser in
your window port, nor should you set the values for the
iflags.wc_* and iflags.wc2_* fields directly within the port code.
The port code should honor whatever values were put there by the core
when processing options, either in the config file, or by the 'O' command.

You may be wondering what values your window port will find in the
iflags.wc_* and iflags.wc2_* fields for options that the user has not
specified in his/her config file. Put another way, how does your port code
tell if an option has not been set? The next paragraph explains that.

If the core does not set an option, it will still be initialized
to its default value. Those default values for the
iflags.wc_* and iflags.wc_* fields are:

 o All boolean fields are initialized to the starting
   value specified for that option in the boolopt array in
   options.c.  The window-port should respect that setting
   unless it has a very good reason for not doing so.
 o All int fields are initialized to zero. Zero is not a valid
   setting for any of the int options, so if your port code
   encounters a zero there, it can assume that the preference
   option was not specified.  In that case, the window-port code
   should use a default setting that the port is comfortable with.
   It should write the default setting back into the iflags.wc_*
   field.  That is the only time that your window-port could should
   update those fields.
 o All "char *" fields will be null pointers. Be sure to check for
   that in your window-port code before using such a pointer, or
   you'll end up triggering a nasty fault.

Here are the wincap and wincap2 preference settings that your port can choose
to support:

  wincap
  +--------------------+--------------------+--------------------+--------+
  |                    |                    | iflags field       | data   |
  | player option      | bit in wincap mask |   for value        | type   |
  |--------------------+--------------------+--------------------+--------+
  |  align_message     | WC_ALIGN_MESSAGE   | wc_align_message   |int     |
  |  align_status      | WC_ALIGN_STATUS    | wc_align_status    |int     |
  |  ascii_map         | WC_ASCII_MAP       | wc_ascii_map       |boolean |
  |  color             | WC_COLOR           | wc_color           |boolean |
  |  eight_bit_tty     | WC_EIGHT_BIT_IN    | wc_eight_bit_input |boolean |
  |  font_map          | WC_FONT_MAP        | wc_font_map        |char *  |
  |  font_menu         | WC_FONT_MENU       | wc_font_menu       |char *  |
  |  font_message      | WC_FONT_MESSAGE    | wc_font_message    |char *  |
  |  font_status       | WC_FONT_STATUS     | wc_font_status     |char *  |
  |  font_text         | WC_FONT_TEXT       | wc_font_text       |char *  |
  |  font_size_map     | WC_FONTSIZ_MAP     | wc_fontsiz_map     |int     |
  |  font_size_menu    | WC_FONTSIZ_MENU    | wc_fontsiz_menu    |int     |
  |  font_size_message | WC_FONTSIZ_MESSAGE | wc_fontsiz_message |int     |
  |  font_size_status  | WC_FONTSIZ_STATUS  | wc_fontsiz_status  |int     |
  |  font_size_text    | WC_FONTSIZ_TEXT    | wc_fontsiz_text    |int     |
  |  hilite_pet        | WC_HILITE_PET      | wc_hilite_pet      |boolean |
  |  map_mode          | WC_MAP_MODE        | wc_map_mode        |int     |
  |  perm_invent       | WC_PERM_INVENT     | wc_perm_invent     |boolean |
  |  player_selection  | WC_PLAYER_SELECTION| wc_player_selection|int     |
  |  popup_dialog      | WC_POPUP_DIALOG    | wc_popup_dialog    |boolean |
  |  preload_tiles     | WC_PRELOAD_TILES   | wc_preload_tiles   |boolean |
  |  scroll_amount     | WC_SCROLL_AMOUNT   | wc_scroll_amount   |int     |
  |  scroll_margin     | WC_SCROLL_MARGIN   | wc_scroll_margin   |int     |
  |  splash_screen     | WC_SPLASH_SCREEN   | wc_splash_screen   |boolean |
  |  tiled_map         | WC_TILED_MAP       | wc_tiled_map       |boolean |
  |  tile_width        | WC_TILE_WIDTH      | wc_tile_width      |int     |
  |  tile_height       | WC_TILE_HEIGHT     | wc_tile_height     |int     |
  |  tile_file         | WC_TILE_FILE       | wc_tile_file       |char *  |
  |  use_inverse       | WC_INVERSE         | wc_inverse         |boolean |
  |  vary_msgcount     | WC_VARY_MSGCOUNT   | wc_vary_msgcount   |int     |
  |  windowcolors      | WC_WINDOWCOLORS    | wc_foregrnd_menu   |char *  |
  |                    |                    | wc_backgrnd_menu   |char *  |
  |                    |                    | wc_foregrnd_message|char *  |
  |                    |                    | wc_backgrnd_message|char *  |
  |                    |                    | wc_foregrnd_status |char *  |
  |                    |                    | wc_backgrnd_status |char *  |
  |                    |                    | wc_foregrnd_text   |char *  |
  |                    |                    | wc_backgrnd_text   |char *  |
  |  mouse             | WC_MOUSE_SUPPORT   | wc_mouse_support   |boolean |
  +--------------------+--------------------+--------------------+--------+

  wincap2
  +--------------------+--------------------+--------------------+--------+
  |                    |                    | iflags field       | data   |
  | player option      | bit in wincap mask |   for value        | type   |
  |--------------------+--------------------+--------------------+--------+
  |  fullscreen        | WC2_FULLSCREEN     | wc2_fullscreen     |boolean |
  |  guicolor          | WC2_GUICOLOR       | wc2_guicolor       |boolean |
  |  hilite_status     | WC2_HILITE_STATUS  | wc2_hilite_status  |strings |
  |  hitpointbar       | WC2_HITPOINTBAR    | wc2_hitpointbar    |boolean |
  |  menu_shift_left   | WC2_MENU_SHIFT     |  n/a               |char    |
  |  menu_shift_right  | WC2_MENU_SHIFT     |  n/a               |char    |
  |  petattr           | WC2_PETATTR        | wc2_petattr        |int     |
  |  selectsaved       | WC2_SELECTSAVED    | wc2_selectsaved    |boolean |
  |  softkeyboard      | WC2_SOFTKEYBOARD   | wc2_softkeyboard   |boolean |
  |  statuslines       | WC2_STATUSLINES    | wc2_statuslines    |int     |
  |  term_cols         | WC2_TERM_SIZE      | wc2_term_cols      |int     |
  |  term_rows         | WC2_TERM_SIZE      | wc2_term_rows      |int     |
  |  use_darkgray      | WC2_DARKGRAY       | wc2_darkgray       |boolean |
  |  windowborders     | WC2_WINDOWBORDERS  | wc2_windowborders  |int     |
  |  wraptext          | WC2_WRAPTEXT       | wc2_wraptext       |boolean |
  +--------------------+--------------------+--------------------+--------+

  more wincap2 for STATUS_HILITES support and control
  +--------------------------------- +---------------------------+
  | To inform the game engine        |                           |
  | that the window port is equipped | bit to set in wincap mask |
  | to receive the following in its  |                           |
  | x_status_update() routine        |                           |
  |----------------------------------+---------------------------+
  | BL_FLUSH to render buffered      | WC2_FLUSH_STATUS          |
  |          field changes now       |                           |
  |----------------------------------+---------------------------+
  | BL_RESET to indicate that all    | WC2_RESET_STATUS          |
  |          fields should be redone |                           |
  +----------------------------------+---------------------------+

  additional wincap2 flag bits for supported putstr() attributes
  +----------------------------------+---------------------------+
  |  avoid putting message into      | WC2_SUPPRESS_HIST         |
  |          recall history          |                           |
  |  draw extra attention to message | WC2_URGENT_MESG           |
  +----------------------------------+---------------------------+

align_message	-- where to place message window (top, bottom, left, right)
align_status	-- where to place status display (top, bottom, left, right).
ascii_map	-- port should display an ascii map if it can.
color		-- port should display color if it can.
eight_bit_tty	-- port should allow eight bit input.
font_map	-- port should use a font by this name for map window.
font_menu	-- port should use a font by this name for menu windows.
font_message	-- port should use a font by this name for message window.
font_size_map	-- port should use this size font for the map window.
font_size_menu	-- port should use this size font for menu windows.
font_size_message
		-- port should use this size font for the message window.
font_size_status-- port should use this size font for the status display.
font_size_text	-- port should use this size font for text windows.
font_status	-- port should use a font by this name for status display.
font_text	-- port should use a font by this name for text windows.
fullscreen      -- port should try to use the whole screen.
hilite_pet	-- port should mark pets in some special way on the map.
hitpointbar	-- port should show a graphical bar representing hit points
map_mode	-- port should display the map in the manner specified.
player_selection
		-- dialog or prompts for choosing character.
popup_dialog	-- port should pop up dialog boxes for input.
preload_tiles	-- port should preload tiles into memory.
scroll_amount   -- scroll this amount when scroll_margin is reached.
scroll_margin	-- port should scroll the display when the hero or cursor
		   is this number of cells away from the edge of the window.
selectsaved     -- if port can display a menu of the user's saved games do so.
softkeyboard    -- handhelds should display an on-screen keyboard if possible.
splash_screen   -- port should/should not display an opening splashscreen.
term_cols       -- Terminal should size itself to specified width, if possible.
term_rows       -- Terminal should size to specified height, if possible.
tiled_map	-- port should display a tiled map if it can.
tile_width	-- port should display tiles with this width or round to
		   closest if it can.
tile_height	-- port should display tiles with this height or round to
		   closest if it can.
tile_file	-- open this alternative tile file.  The file name is likely to
		   be window-port or platform specific.
use_inverse	-- port should display inverse when NetHack asks for it.
vary_msgcount	-- port should display this number of messages at a time in
		   the message window.
windowborders   -- port should display borders around main NetHack windows.
                Can be set to (1) on, (2) off, or (3) auto.
windowcolors
		-- port should use these colors for window foreground/background
		   colors.  Syntax:
		     menu fore/back message fore/back status fore/back text fore/back
wraptext	-- port should wrap long lines of text if they don't fit in
		   the visible area of the window
mouse_support	-- port should enable mouse support if possible

Whenever one of these settings is adjusted, the port is notified of a change
to the setting by calling the port's preference_update() routine. The port
is only notified if it has indicated that it supports that option by setting
the option's bit in the port's wincap mask.  The port can choose to adjust
for the change to an option that it receives notification about, or ignore it.
The former approach is recommended.  If you don't want to deal with a
user-initiated setting change, then the port should call
set_wc_option_mod_status(mask, set_in_config) to make the option invisible to
the user.

Functions available for the window port to call:

set_wc_option_mod_status(optmask, status)
		-- Adjust the optflag field for a set of wincap options to
		   specify whether the port wants the option to appear
		   in the 'O' command options menu, The second parameter,
		   "status" can be set to set_in_config, set_gameview,
		   or set_in_game (set_in_config implies that the option
		   is completely hidden during the game).

set_wc2_option_mod_status(optmask, status)
		-- Adjust the optflag field for a set of wincap2 options to
		   specify whether the port wants the option to appear
		   in the 'O' command options menu, The second parameter,
		   "status" can be set to set_in_config, set_gameview,
		   or set_in_game (set_in_config implies that the option
		   is completely hidden during the game).

set_option_mod_status(optnam, status)
		-- Adjust the optflag field for one of the core options
		   that is not part of the wincap suite.  A port might use
		   this to override the default initialization setting for
		   status specified in options.c.  Note that you have to
		   specify the option by name and that you can only set
		   one option per call unlike set_wc_option_mod_status().


Adding a new wincap option:

To add a new wincap option, please follow all these steps:
	1. Add the option to the wincap preference settings table above. Since
	   wincap is full, your option will likely target wincap2 field.
	2. Add the description to the paragraph below the chart.
	3. Add the WC_ or WC2_ to the bit list in include/winprocs.h
	   (in wincap2 if there is no room in wincap).
	4. Add the wc_ or wc2_ field(s) to the iflags structure in flag.h.
	5. Add the name and value to wc_options[] or wc2_options[] in options.c
	6. Add an appropriate parser to parseoptions() in options.c.
	7. Add code to display current value to get_compopt_value() in options.c.
	8. Document the option in Guidebook.mn and Guidebook.tex.
	9. Add the bit name to the OR'd values in your window port's winprocs struct
	   wincap mask if your port supports the option.

V.  New or respecified common, high level routines

These are not part of the interface, but mentioned here for your information.

char display_inventory(lets, want_reply)
		-- Calls a start_menu()/add_menu()/select_menu() sequence.
		   It returns the item selected, or '\0' if none is selected.
		   Returns '\033' if the menu was canceled.
raw_printf(str, ...)
		-- Like raw_print(), but accepts arguments like printf().  This
		   routine processes the arguments and then calls raw_print().
		-- The mac version #defines error raw_printf.  I think this
		   is a reasonable thing to do for most ports.
pline(str, ...)
		-- Prints a string to WIN_MESSAGE using a printf() interface.
		   It has the variants You(), Your(), Norep(), and others
		   in pline.c which all use the same mechanism.  pline()
		   requires the variable "char toplines[]" be defined; Every
		   putstr() on WIN_MESSAGE must copy str to toplines[] for use
		   by Norep() and pline().  If the window system is not active
		   (!iflags.window_inited) pline() uses raw_print().

VI.  Game startup

The following is the general order in which calls from main() should be made,
as they relate to the window system.  The actual code may differ, but the
order of the calls should be the same.


choose_windows(DEFAULT_WINDOW_SYS) /* choose a default window system */
initoptions()			   /* read the resource file */
init_nhwindows()		   /* initialize the window system */
process_options(argc, argv)	   /* process command line options or equiv */
if(save file is present) {
  init_sound_and_display_gamewindows() /* init sound, create & display */
  dorestore()			   /* restore old game; pline()s are OK */
} else {
  player_selection()		   /* select a player type using a window */
  init_sound_and_display_gamewindows() /* init sound, create & display  */
}
pline("Hello, welcome...");

Choose_windows() is a common routine, and calling it in main() is necessary
to initialize the function pointer table to _something_ so that calls to
raw_print() will not fail.  Choose_windows() should be called almost
immediately upon entering main().  Look at unixmain.c for an example.
Choose_windows will call an (optional) ini_routine with a single argument
of WININIT to allow any needed setup.  Because choose_windows() may be called
multiple times during argument and option processing, to handle the case where
ini_routines have side effects that need to be undone, the old ini_routine (if
any) will be called with an argument of WININIT_UNDO before the new
ini_routine (if any) is called (with WININIT).

Init_sound_and_display_gamewindows() is a common routine that initializes
the soundlib, then displays the standard game windows (WIN_MESSAGE, WIN_MAP,
etc.), and the status display. It is normally called just before the
"Hello, welcome" message.

Process_options() is currently still unique to each port.  There may be need
in the future to make it possible to replace this on a per window-port basis.


VII.  Conventions

init_nhwindows() is expected to display a gee-whiz banner window, including
the Copyright message.  It is recommended that the COPYRIGHT_BANNER_A macro
from patchlevel.h, COPYRIGHT_BANNER_B from patchlevel.h, 
nomakedefs.copyright_banner_c internal global variable, and
COPYRIGHT_BANNER_D macros from patchlevel.h be used for constructing the
Copyright message.
COPYRIGHT_BANNER_A is a quoted string that has NetHack copyright declaration,
COPYRIGHT_BANNER_B is a quoted string that states who the copyright belongs to,
nomakedefs.copyright_banner_c is a quoted string produced at runtime that
includes version and build information, and
COPYRIGHT_BANNER_D simply says "See License for details."
Be sure to #include "patchlevel.h" and date.h to define these macros.  Using
the macros will prevent having to update the Copyright information in each
window-port prior to each release.

Ports (MSDOS, TOS, MAC, etc) _may_ use window-port specific routines in
their port specific files, _AT_THEIR_OWN_RISK_.  Since "port" and
"window-port" are orthogonal, you make your "port" code less portable by
using "window-port" specific routines.  Every effort should be made to
use window-port interface routines, unless there is something port
specific that is better suited (e.g. msmsg() for MSDOS).

The tty window-port is contained in win/tty, the X window port is contained
in win/X11.  The files in these directories contain _only_ window port code,
and may be replaced completely by other window ports.


VIII.  Implementation and Multi-window support

NetHack 3.2 and higher support multiple window systems in the same binary.
When writing a new window-port, you need to follow the following guidelines:

1) Pick a unique prefix to identify your window-port.  For example, the tty
   window port uses "tty"; the X11 window-port uses "X11".
2) When declaring your interface function, precede the function names with
   your unique prefix.  E.g:

	void tty_init_nhwindows()
	{
		/* code for initializing windows in the tty port */
	}

   When calling window functions from within your port code, we suggest
   calling the prefixed version to avoid unnecessary overhead.  However,
   you may safely call the non-prefixed version (e.g. putstr() rather than
   tty_putstr()) as long as you #include "hack.h".  If you do not
   include hack.h and use the non-prefixed names, you will get compile
   or link-time errors.

   We also suggest declaring all functions and port-specific data with
   this prefix to avoid unexpected overlaps with other window-ports.
   The tty and X11 ports do not currently follow this suggestion, but do
   use separate non-overlapping convention for naming data and internal
   functions.

3) Declare a structure, "struct window_procs prefix_procs", (with your
   prefix instead of "prefix") and fill in names of all of your
   interface functions.  The first entry in this structure is the name
   of your window-port, which should be the prefix.  The second entry
   is the wincap mask that identifies what window port preference
   settings your port will react to and support.  The other entries
   are the function addresses.

   Assuming that you followed the convention in (2), you can safely copy
   the structure definition from an existing window-port and just change
   the prefixes.  That will guarantee that you get the order of your
   initializations correct (not all compilers will catch out-of-order
   function pointer declarations).

4) Add a #define to config.h identifying your window-port in the
   "Windowing systems" section.  Follow the "prefix_GRAPHICS" convention
   for your window-port.

5) Add your prefix to the list of valid prefixes listed in the "Known
   systems are" comment.

6) Edit makedefs.c and add a string for your windowing system to window_opts
   inside an #ifdef prefix_GRAPHICS.

7) Edit windows.c and add an external reference to your prefix_procs inside
   an #ifdef prefix_GRAPHICS.  Also add an entry to the win_choices
   structure for your window-port of the form:

    #ifdef prefix_GRAPHICS
	{ &prefix_procs, prefix_init_function },
    #endif

   The init_function is necessary for some compilers and systems to force
   correct linking.  If your system does not need such massaging, you
   may put a null pointer here.

   You should declare prefix_procs and prefix_init_function as extern's
   in your win*.h file, and #include that file at the beginning of
   windows.c, also inside an #ifdef prefix_GRAPHICS.  Some win*.h files
   are rather sensitive, and you might have to duplicate your
   prefix_procs and prefix_init_function's instead of including win*.h.
   The tty port includes wintty.h, the X11 port duplicates the declarations.

8) If your port uses Makefile.src, add the .c and .o files and an
   appropriate comment in the section on "WINSRC" and "WINOBJ".  See
   Makefile.src for the style to use.  If you don't use Makefile.src,
   we suggest using a similar convention for the make-equivalent used
   on your system.  Also add your new source and binaries to WINSRC and
   WINOBJ (if you want the NetHack binary to include them, that is).

9) Look at your port's portmain.c (the file containing main()) and make
   sure that all of the calls match the requirements laid out in
   Section VII.

Now, proceed with compilation and installation as usual.  Don't forget
to edit Makefile.src (or its equivalent) and config.h to set the
window-ports you want in your binary, the default window-port to use,
and the .o's needed to build a valid game.

One caveat.  Unfortunately, if you incorrectly specify the
DEFAULT_WINDOW_SYS, NetHack will dump core (or whatever) without
printing any message, because raw_print() cannot function without first
setting the window-port.


IX. WINCHAIN

WINCHAIN is an optional facility that allows the SYSCF_FILE to specify a
series of processors that will see each call from the core to the window
port (and the resulting return chain).  Processors are specified one at a
time from the start of the chain (the core end) towards the window port as:
    OPTIONS=windowchain:+PROC
where PROC is the name of the processor to add to the chain.  The '+' is
required and is part of the name of the processor (this distinguishes
processors from window ports; in addition the '-' character is reserved for
WINCHAIN internals).

If WINCHAIN is not compiled into the NetHack binary, there is no overhead.

If WINCHAIN is compiled into the NetHack binary but not used, overhead is
limited to one function call during game setup and a trivial amount of data.

Note that raw_print* calls will not go through the chain until initialization
is complete (when *main.c calls commit_windowchain()).

The only processor currently available is '+trace' which is a debugging
facility for window ports.  See the code in win/chain/wc_trace.c for
details on where to find the log file and how to write to it from other parts
of the code.

A processor may be specified more than once; this is expected to be most
useful for surrounding a processor being developed with before and after
calls to +trace.
