-NetHack 3.7 window.doc $NHDT-Date: 1596498145 2020/08/03 23:42:25 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.58 $
+NetHack 3.7 window.doc $NHDT-Date: 1615154657 2021/03/07 22:04:17 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.63 $
Introduction
(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.)
+ 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,
(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
+ 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
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,
+ -- 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.
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),
+ 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
+ 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
+ Multiple putmixed()s are output on separate lines.
+ Attributes can be one of
ATR_NONE (or 0)
ATR_ULINE
ATR_BOLD
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).
+ 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+ */
+ 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 */
+ unsigned glyphflags; /* more detail about the entity */
char yn_function(const char *ques, const char *choices, char default)
-- On the tty-port this scrolls WIN_MESSAGE back one line.
update_positionbar(char *features)
- -- Optional, POSITIONBAR must be defined. Provide some
+ -- 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
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
+ 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)
+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
+ 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_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)
+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_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
+ 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
+ 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.
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
+ 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_*
This contains the color and attribute that the field should
be displayed in.
- This is relevant for everything except BL_CONDITION fldindex.
- If fldindex is BL_CONDITION, this parameter should be ignored,
- as condition hilighting is done via the next colormasks
- parameter instead.
+ 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.
+------+----------------------+--------------------+
| 20 | HL_ATTCLR_BOLD | |
+------+----------------------+--------------------+
- | 21 | beyond array boundary | BL_ATTCLR_MAX
+ | 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
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
+ change if it indicated that it wants to be by setting the
corresponding bit in the wincap mask.
-getmsghistory(init)
+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.
+ 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
+ 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
+ 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
+ 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.
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.
+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
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
+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.
+ 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,
+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
+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.
+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
+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.
+See section IX for details of where the wincap masks reside.
-Two things control whether any preference setting appears in the
+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
+ 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.
+ 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.
+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
+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
+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,
+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.
+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
+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
+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 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.
+ 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
+ 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
| 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 |
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
+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.
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 itself to specified height, 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.
+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.
-- 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
+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
+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
+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
+ -- 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
+ -- 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
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
+ specify the option by name and that you can only set
one option per call unlike set_wc_option_mod_status().
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
+ 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
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
+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
the Copyright message. It is recommended that the COPYRIGHT_BANNER_A,
COPYRIGHT_BANNER_B, COPYRIGHT_BANNER_C, and COPYRIGHT_BANNER_D macros from
patchlevel.h and date.h be used for constructing the Copyright message.
-COPYRIGHT_BANNER_A is a quoted string that has the NetHack copyright declaration,
+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,
-COPYRIGHT_BANNER_C is a quoted string generated by makedefs 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.
+COPYRIGHT_BANNER_C is a quoted string generated by makedefs 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
projects / nethack / commitdiff