--- /dev/null
+NetHack 3.7 window.txt $NHDT-Date: 1643491505 2022/01/29 21:25:05 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.0 $
+
+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.
+
+"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, 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.
+ -- 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.]
+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) {
+ display_gamewindows() /* create & display the game windows */
+ dorestore() /* restore old game; pline()s are OK */
+} else {
+ player_selection() /* select a player type using a window */
+ display_gamewindows() /* create & display the game windows */
+}
+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).
+
+Display_gamewindows() is a common routine that displays the two standard
+game windows (WIN_MESSAGE, WIN_MAP), 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" 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.
projects / nethack / commitdiff