3 This file documents the support for various windowing systems in
4 NetHack. The support is through a standard interface, separating the
5 main NetHack code from window-system specific code. The implementation
6 supports multiple window systems in the same binary. Even if you only
7 wish to support one window-port on your port, you will need to follow
8 the instructions in Section IX to get a compilable binary.
11 I. Window Types and Terminology
12 II. Interface Specification
14 IV. WINCAP preferences support
15 V. New or respecified common, high level routines
19 IX. Implementation and Multi-window support
21 I. Window Types and Terminology
23 There are 5 basic window types, used to call create_nhwindow():
25 NHW_MESSAGE (top line)
26 NHW_STATUS (bottom lines)
27 NHW_MAP (main dungeon)
28 NHW_MENU (inventory or other "corner" windows)
29 NHW_TEXT (help/text, full screen paged window)
31 The tty window-port also uses NHW_BASE (the base display) internally.
33 NHW_MENU windows can be used for either menu or text display. Their
34 basic feature is that for the tty-port, if the window is small enough,
35 it appears in the corner of the tty display instead of overwriting
36 the whole screen. The first call to add information to the window
37 will decide if it is going to be used to display a menu or text.
38 If start_menu() is called, then it will be used as a menu. If
39 putstr() is called, it will be used as text. Once decided, there
40 is no turning back. For the tty-port, if the data is too large for
41 a single screen then the data is paged (with --more--) between pages.
42 Only NHW_MENU type windows can be used for menus.
44 NHW_TEXT windows are used to display a large amount of textual data.
45 This is the type of window one would use for displaying a help file,
46 for example. In the tty window-port, windows of type NHW_TEXT can
47 page using the DEF_PAGER, if DEF_PAGER is defined. There exists an
48 assumption that the font for text windows is monospaced. The help
49 files are all formatted accordingly.
51 "window" is always of type winid. This is currently implemented as an
52 integer, but doesn't necessarily have to be done that way. There are
53 a few fixed window names that are known throughout the code:
55 WIN_MESSAGE (top line)
56 WIN_STATUS (bottom lines)
57 WIN_MAP (main dungeon)
60 Other windows are created and destroyed as needed.
62 "Port" in this document refers to a CPU/OS/hardware platform (UNIX, MSDOS
63 TOS, etc.) "window-port" refers to the windowing platform. This is
64 orthogonal (e.g. UNIX might use either a tty window-port or an X11
68 II. Interface Specification
70 All functions below are void unless otherwise noted.
72 A. Low-level routines:
74 raw_print(str) -- Print directly to a screen, or otherwise guarantee that
75 the user sees str. raw_print() appends a newline to str.
76 It need not recognize ASCII control characters. This is
77 used during startup (before windowing system initialization
78 -- maybe this means only error startup messages are raw),
79 for error messages, and maybe other "msg" uses. E.g.
80 updating status for micros (i.e, "saving").
82 -- Like raw_print(), but prints in bold/standout (if possible).
84 -- Next output to window will start at (x,y), also moves
85 displayable cursor to (x,y). For backward compatibility,
86 1 <= x < cols, 0 <= y < rows, where cols and rows are
88 -- For variable sized windows, like the status window, the
89 behavior when curs() is called outside the window's limits
90 is unspecified. The mac port wraps to 0, with the status
91 window being 2 lines high and 80 columns wide.
92 -- Still used by curs_on_u(), status updates, screen locating
94 -- NHW_MESSAGE, NHW_MENU and NHW_TEXT windows do not
95 currently support curs in the tty window-port.
96 putstr(window, attr, str)
97 -- Print str on the window with the given attribute. Only
98 printable ASCII characters (040-0126) must be supported.
99 Multiple putstr()s are output on separate lines. Attributes
106 If a window-port does not support all of these, it may map
107 unsupported attributes to a supported one (e.g. map them
108 all to ATR_INVERSE). putstr() may compress spaces out of
109 str, break str, or truncate str, if necessary for the
110 display. Where putstr() breaks a line, it has to clear
112 -- putstr should be implemented such that if two putstr()s
113 are done consecutively the user will see the first and
114 then the second. In the tty port, pline() achieves this
115 by calling more() or displaying both on the same line.
116 get_nh_event() -- Does window event processing (e.g. exposure events).
117 A noop for the tty and X window-ports.
118 int nhgetch() -- Returns a single character input from the user.
119 -- In the tty window-port, nhgetch() assumes that tgetch()
120 will be the routine the OS provides to read a character.
121 Returned character _must_ be non-zero and it must be
122 non meta-zero too (zero with the meta-bit set).
123 int nh_poskey(int *x, int *y, int *mod)
124 -- Returns a single character input from the user or a
125 a positioning event (perhaps from a mouse). If the
126 return value is non-zero, a character was typed, else,
127 a position in the MAP window is returned in x, y and mod.
130 CLICK_1 /* mouse click type 1 */
131 CLICK_2 /* mouse click type 2 */
133 The different click types can map to whatever the
134 hardware supports. If no mouse is supported, this
135 routine always returns a non-zero character.
137 B. High-level routines:
139 print_glyph(window, x, y, glyph)
140 -- Print the glyph at (x,y) on the given window. Glyphs are
141 integers at the interface, mapped to whatever the window-
142 port wants (symbol, font, color, attributes, ...there's
143 a 1-1 map between glyphs and distinct things on the map).
144 char yn_function(const char *ques, const char *choices, char default)
145 -- Print a prompt made up of ques, choices and default.
146 Read a single character response that is contained in
147 choices or default. If choices is NULL, all possible
148 inputs are accepted and returned. This overrides
149 everything else. The choices are expected to be in
150 lower case. Entering ESC always maps to 'q', or 'n',
151 in that order, if present in choices, otherwise it maps
152 to default. Entering any other quit character (SPACE,
153 RETURN, NEWLINE) maps to default.
154 -- If the choices string contains ESC, then anything after
155 it is an acceptable response, but the ESC and whatever
156 follows is not included in the prompt.
157 -- If the choices string contains a '#' then accept a count.
158 Place this value in the global "yn_number" and return '#'.
159 -- This uses the top line in the tty window-port, other
160 ports might use a popup.
161 -- If choices is NULL, all possible inputs are accepted and
162 returned, preserving case (upper or lower.) This means that
163 if the calling function needs an exact match, it must handle
164 user input correctness itself.
165 getlin(const char *ques, char *input)
166 -- Prints ques as a prompt and reads a single line of text,
167 up to a newline. The string entered is returned without the
168 newline. ESC is used to cancel, in which case the string
169 "\033\000" is returned.
170 -- getlin() must call flush_screen(1) before doing anything.
171 -- This uses the top line in the tty window-port, other
172 ports might use a popup.
173 -- getlin() can assume the input buffer is at least BUFSZ
174 bytes in size and must truncate inputs to fit, including
176 int get_ext_cmd(void)
177 -- Get an extended command in a window-port specific way.
178 An index into extcmdlist[] is returned on a successful
179 selection, -1 otherwise.
181 -- Do a window-port specific player type selection. If
182 player_selection() offers a Quit option, it is its
183 responsibility to clean up and terminate the process.
184 You need to fill in pl_character[0].
185 display_file(str, boolean complain)
186 -- Display the file named str. Complain about missing files
187 iff complain is TRUE.
189 -- Indicate to the window port that the inventory has been
191 -- Merely calls display_inventory() for window-ports that
192 leave the window up, otherwise empty.
194 -- Display previous messages. Used by the ^P command.
195 -- On the tty-port this scrolls WIN_MESSAGE back one line.
197 update_positionbar(char *features)
198 -- Optional, POSITIONBAR must be defined. Provide some
199 additional information for use in a horizontal
200 position bar (most useful on clipped displays).
201 Features is a series of char pairs. The first char
202 in the pair is a symbol and the second char is the
203 column where it is currently located.
204 A '<' is used to mark an upstairs, a '>'
205 for a downstairs, and an '@' for the current player
206 location. A zero char marks the end of the list.
209 C. Window Utility Routines
211 init_nhwindows(int* argcp, char** argv)
212 -- Initialize the windows used by NetHack. This can also
213 create the standard windows listed at the top, but does
215 -- Any commandline arguments relevant to the windowport
216 should be interpreted, and *argcp and *argv should
217 be changed to remove those arguments.
218 -- When the message window is created, the variable
219 iflags.window_inited needs to be set to TRUE. Otherwise
220 all plines() will be done via raw_print().
221 ** Why not have init_nhwindows() create all of the "standard"
222 ** windows? Or at least all but WIN_INFO? -dean
224 -- Exits the window system. This should dismiss all windows,
225 except the "window" used for raw_print(). str is printed
227 window = create_nhwindow(type)
228 -- Create a window of type "type."
229 clear_nhwindow(window)
230 -- Clear the given window, when appropriate.
231 display_nhwindow(window, boolean blocking)
232 -- Display the window on the screen. If there is data
233 pending for output in that window, it should be sent.
234 If blocking is TRUE, display_nhwindow() will not
235 return until the data has been displayed on the screen,
236 and acknowledged by the user where appropriate.
237 -- All calls are blocking in the tty window-port.
238 -- Calling display_nhwindow(WIN_MESSAGE,???) will do a
239 --more--, if necessary, in the tty window-port.
240 destroy_nhwindow(window)
241 -- Destroy will dismiss the window if the window has not
242 already been dismissed.
244 -- Start using window as a menu. You must call start_menu()
245 before add_menu(). After calling start_menu() you may not
246 putstr() to the window. Only windows of type NHW_MENU may
248 add_menu(windid window, int glyph, const anything identifier,
249 char accelerator, char groupacc,
250 int attr, char *str, boolean preselected)
251 -- Add a text line str to the given menu window. If identifier
252 is 0, then the line cannot be selected (e.g. a title).
253 Otherwise, identifier is the value returned if the line is
254 selected. Accelerator is a keyboard key that can be used
255 to select the line. If the accelerator of a selectable
256 item is 0, the window system is free to select its own
257 accelerator. It is up to the window-port to make the
258 accelerator visible to the user (e.g. put "a - " in front
259 of str). The value attr is the same as in putstr().
260 Glyph is an optional glyph to accompany the line. If
261 window port cannot or does not want to display it, this
262 is OK. If there is no glyph applicable, then this
263 value will be NO_GLYPH.
264 -- All accelerators should be in the range [A-Za-z],
265 but there are a few exceptions such as the tty player
266 selection code which uses '*'.
267 -- It is expected that callers do not mix accelerator
268 choices. Either all selectable items have an accelerator
269 or let the window system pick them. Don't do both.
270 -- Groupacc is a group accelerator. It may be any character
271 outside of the standard accelerator (see above) or a
272 number. If 0, the item is unaffected by any group
273 accelerator. If this accelerator conflicts with
274 the menu command (or their user defined alises), it loses.
275 The menu commands and aliases take care not to interfere
276 with the default object class symbols.
277 -- If you want this choice to be preselected when the
278 menu is displayed, set preselected to TRUE.
280 end_menu(window, prompt)
281 -- Stop adding entries to the menu and flushes the window
282 to the screen (brings to front?). Prompt is a prompt
283 to give the user. If prompt is NULL, no prompt will
285 ** This probably shouldn't flush the window any more (if
286 ** it ever did). That should be select_menu's job. -dean
287 int select_menu(windid window, int how, menu_item **selected)
288 -- Return the number of items selected; 0 if none were chosen,
289 -1 when explicitly cancelled. If items were selected, then
290 selected is filled in with an allocated array of menu_item
291 structures, one for each selected line. The caller must
292 free this array when done with it. The "count" field
293 of selected is a user supplied count. If the user did
294 not supply a count, then the count field is filled with
295 -1 (meaning all). A count of zero is equivalent to not
296 being selected and should not be in the list. If no items
297 were selected, then selected is NULL'ed out. How is the
298 mode of the menu. Three valid values are PICK_NONE,
299 PICK_ONE, and PICK_ANY, meaning: nothing is selectable,
300 only one thing is selectable, and any number valid items
301 may selected. If how is PICK_NONE, this function should
302 never return anything but 0 or -1.
303 -- You may call select_menu() on a window multiple times --
304 the menu is saved until start_menu() or destroy_nhwindow()
305 is called on the window.
306 -- Note that NHW_MENU windows need not have select_menu()
307 called for them. There is no way of knowing whether
308 select_menu() will be called for the window at
309 create_nhwindow() time.
310 char message_menu(char let, int how, const char *mesg)
311 -- tty-specific hack to allow single line context-sensitive
312 help to behave compatibly with multi-line help menus.
313 -- This should only be called when a prompt is active; it
314 sends `mesg' to the message window. For tty, it forces
315 a --More-- prompt and enables `let' as a viable keystroke
316 for dismissing that prompt, so that the original prompt
317 can be answered from the message line "help menu".
318 -- Return value is either `let', '\0' (no selection was made),
319 or '\033' (explicit cancellation was requested).
320 -- Interfaces which issue prompts and messages to separate
321 windows typically won't need this functionality, so can
322 substitute genl_message_menu (windows.c) instead.
326 make_sound(???) -- To be determined later. THIS IS CURRENTLY UN-IMPLEMENTED.
327 nhbell() -- Beep at user. [This will exist at least until sounds are
328 redone, since sounds aren't attributable to windows anyway.]
329 mark_synch() -- Don't go beyond this point in I/O on any channel until
330 all channels are caught up to here. Can be an empty call
332 wait_synch() -- Wait until all pending output is complete (*flush*() for
334 -- May also deal with exposure events etc. so that the
335 display is OK when return from wait_synch().
336 delay_output() -- Causes a visible delay of 50ms in the output.
337 Conceptually, this is similar to wait_synch() followed
338 by a nap(50ms), but allows asynchronous operation.
339 askname() -- Ask the user for a player name.
340 cliparound(x, y)-- Make sure that the user is more-or-less centered on the
341 screen if the playing area is larger than the screen.
342 -- This function is only defined if CLIPPING is defined.
344 -- Initialize the number pad to the given state.
345 suspend_nhwindows(str)
346 -- Prepare the window to be suspended.
348 -- Restore the windows after being suspended.
350 start_screen() -- Only used on Unix tty ports, but must be declared for
351 completeness. Sets up the tty to work in full-screen
352 graphics mode. Look at win/tty/termcap.c for an
353 example. If your window-port does not need this function
354 just declare an empty function.
355 end_screen() -- Only used on Unix tty ports, but must be declared for
356 completeness. The complement of start_screen().
359 -- The tombstone code. If you want the traditional code use
360 genl_outrip for the value and check the #if in rip.c.
362 preference_update(preference)
363 -- The player has just changed one of the wincap preference
364 settings, and the NetHack core is notifying your window
365 port of that change. If your window-port is capable of
366 dynamically adjusting to the change then it should do so.
367 Your window-port will only be notified of a particular
368 change if it indicated that it wants to be by setting the
369 corresponding bit in the wincap mask.
371 III. Global variables
373 The following global variables are defined in decl.c and must be used by
374 the window interface to the rest of NetHack.
376 char toplines[BUFSZ] Contains the last message printed to the WIN_MESSAGE
377 window, used by Norep().
378 winid WIN_MESSAGE, WIN_MAP, WIN_STATUS, WIN_INVEN
379 The four standard windows.
380 char *AE, *AS; Checked in options.c to see if we should switch
381 to DEC_GRAPHICS. It is #ifdefed VMS and UNIX.
382 int LI, CO; Set in sys/unix/ioctl.c.
384 The following appears to be Unix specific. Other ports using the tty
385 window-port should also declare this variable in one of your sys/*.c files.
387 short ospeed; Set and declared in sys/unix/unixtty.c (don't
388 know about other sys files).
390 The following global variable is defined in options.c. It equates a
391 list of wincap option names with their associated bit-mask [see
392 section IV WINCAP preferences support]. The array is zero-terminated.
394 struct wc_Opt wc_options[];
395 One entry for each available WINCAP option.
396 Each entry has a wc_name field and a wc_bit
399 IV. WINCAP preferences support
401 Starting with NetHack 3.4.0, the window interface was enhanced to provide
402 a common way of setting window port user preferences from the config file,
403 and from the command line for some settings.
405 The wincap preference settings all have their underlying values stored
406 in iflags fields. The names of the wincap related fields are all pre-
407 fixed with wc_ or wc2_ to make it easy to identify them. Your window
408 port can access the fields directly.
410 Your window port identifies what options it will react to and support
411 by setting bits in the window_procs wincap mask and/or wincap2 mask.
412 See section IX for details of where the wincap masks reside.
414 Two things control whether any preference setting appears in the
415 'O' command options menu during the game:
416 1. The option must be marked as being supported by having its
417 bit set in the window_procs wincap or wincap2 mask.
418 2. The option must have its optflag field set to SET_IN_GAME in order
419 to be able to set the option, or marked DISP_IN_GAME if you just
420 want to reveal what the option is set to.
421 Both conditions must be true to be able to see or set the option from
424 The default values for the optflag field for all the options are
425 hard-coded into the option in options.c. The default value for
426 the wc_ options can be altered by calling
427 set_wc_option_mod_status(optmask, status)
428 The default value for the wc2_ options can be altered by calling
429 set_wc2_option_mod_status(optmask, status)
430 In each case, set the option modification status to one of SET_IN_FILE,
431 DISP_IN_GAME, or SET_IN_GAME.
433 The setting of any wincap or wincap2 option is handled by the NetHack
434 core option processing code. You do not have to provide a parser in
435 your window port, nor should you set the values for the
436 iflags.wc_* and iflags.wc2_* fields directly within the port code.
437 The port code should honor whatever values were put there by the core
438 when processing options, either in the config file, or by the 'O' command.
440 You may be wondering what values your window port will find in the
441 iflags.wc_* and iflags.wc2_* fields for options that the user has not
442 specified in his/her config file. Put another way, how does you port code
443 tell if an option has not been set? The next paragraph explains that.
445 If the core does not set an option, it will still be initialized
446 to its default value. Those default values for the
447 iflags.wc_* and iflags.wc_* fields are:
449 o All boolean fields are initialized to the starting
450 value specified for that option in the boolopt array in
451 options.c. The window-port should respect that setting
452 unless it has a very good reason for not doing so.
453 o All int fields are initialized to zero. Zero is not a valid
454 setting for any of the int options, so if your port code
455 encounters a zero there, it can assume that the preference
456 option was not specified. In that case, the window-port code
457 should use a default setting that the port is comfortable with.
458 It should write the default setting back into the iflags.wc_*
459 field. That is the only time that your window-port could should
461 o All "char *" fields will be null pointers. Be sure to check for
462 that in your window-port code before using such a pointer, or
463 you'll end up triggering a nasty fault.
465 Here are the wincap and wincap2 preference settings that your port can choose
469 +--------------------+--------------------+--------------------+--------+
470 | | | iflags field | data |
471 | player option | bit in wincap mask | for value | type |
472 |--------------------+--------------------+--------------------+--------+
473 | align_message | WC_ALIGN_MESSAGE | wc_align_message |int |
474 | align_status | WC_ALIGN_STATUS | wc_align_status |int |
475 | ascii_map | WC_ASCII_MAP | wc_ascii_map |boolean |
476 | color | WC_COLOR | wc_color |boolean |
477 | eight_bit_tty | WC_EIGHT_BIT_IN | wc_eight_bit_input |boolean |
478 | font_map | WC_FONT_MAP | wc_font_map |char * |
479 | font_menu | WC_FONT_MENU | wc_font_menu |char * |
480 | font_message | WC_FONT_MESSAGE | wc_font_message |char * |
481 | font_status | WC_FONT_STATUS | wc_font_status |char * |
482 | font_text | WC_FONT_TEXT | wc_font_text |char * |
483 | font_size_map | WC_FONTSIZ_MAP | wc_fontsiz_map |int |
484 | font_size_menu | WC_FONTSIZ_MENU | wc_fontsiz_menu |int |
485 | font_size_message | WC_FONTSIZ_MESSAGE | wc_fontsiz_message |int |
486 | font_size_status | WC_FONTSIZ_STATUS | wc_fontsiz_status |int |
487 | font_size_text | WC_FONTSIZ_TEXT | wc_fontsiz_text |int |
488 | hilite_pet | WC_HILITE_PET | wc_hilite_pet |boolean |
489 | map_mode | WC_MAP_MODE | wc_map_mode |int |
490 | player_selection | WC_PLAYER_SELECTION| wc_player_selection|int |
491 | popup_dialog | WC_POPUP_DIALOG | wc_popup_dialog |boolean |
492 | preload_tiles | WC_PRELOAD_TILES | wc_preload_tiles |boolean |
493 | scroll_amount | WC_SCROLL_AMOUNT | wc_scroll_amount |int |
494 | scroll_margin | WC_SCROLL_MARGIN | wc_scroll_margin |int |
495 | splash_screen | WC_SPLASH_SCREEN | wc_splash_screen |boolean |
496 | tiled_map | WC_TILED_MAP | wc_tiled_map |boolean |
497 | tile_width | WC_TILE_WIDTH | wc_tile_width |int |
498 | tile_height | WC_TILE_HEIGHT | wc_tile_height |int |
499 | tile_file | WC_TILE_FILE | wc_tile_file |char * |
500 | use_inverse | WC_INVERSE | wc_inverse |boolean |
501 | vary_msgcount | WC_VARY_MSGCOUNT | wc_vary_msgcount |int |
502 | windowcolors | WC_WINDOWCOLORS | wc_foregrnd_menu |char * |
503 | | | wc_backgrnd_menu |char * |
504 | | | wc_foregrnd_message|char * |
505 | | | wc_backgrnd_message|char * |
506 | | | wc_foregrnd_status |char * |
507 | | | wc_backgrnd_status |char * |
508 | | | wc_foregrnd_text |char * |
509 | | | wc_backgrnd_text |char * |
510 | mouse | WC_MOUSE_SUPPORT | wc_mouse_support |boolean |
511 +--------------------+--------------------+--------------------+--------+
514 +--------------------+--------------------+--------------------+--------+
515 | | | iflags field | data |
516 | player option | bit in wincap mask | for value | type |
517 |--------------------+--------------------+--------------------+--------+
518 | fullscreen | WC2_FULLSCREEN | wc2_fullscreen |boolean |
519 | softkeyboard | WC2_SOFTKEYBOARD | wc2_softkeyboard |boolean |
520 | wraptext | WC2_WRAPTEXT | wc2_wraptext |boolean |
521 +--------------------+--------------------+--------------------+--------+
523 align_message -- where to place message window (top, bottom, left, right)
524 align_status -- where to place status window (top, bottom, left, right).
525 ascii_map -- port should display an ascii map if it can.
526 color -- port should display color if it can.
527 eight_bit_tty -- port should allow eight bit input.
528 font_map -- port should use a font by this name for map window.
529 font_menu -- port should use a font by this name for menu windows.
530 font_message -- port should use a font by this name for message window.
531 font_size_map -- port should use this size font for the map window.
532 font_size_menu -- port should use this size font for menu windows.
534 -- port should use this size font for the message window.
535 font_size_status-- port should use this size font for the status window.
536 font_size_text -- port should use this size font for text windows.
537 font_status -- port should use a font by this name for status window.
538 font_text -- port should use a font by this name for text windows.
539 fullscreen -- port should try to use the whole screen.
540 hilite_pet -- port should mark pets in some special way on the map.
541 map_mode -- port should display the map in the manner specified.
543 -- dialog or prompts for choosing character.
544 popup_dialog -- port should pop up dialog boxes for input.
545 preload_tiles -- port should preload tiles into memory.
546 scroll_amount -- scroll this amount when scroll_margin is reached.
547 scroll_margin -- port should scroll the display when the hero or cursor
548 is this number of cells away from the edge of the window.
549 softkeyboard -- handhelds should display an on-screen keyboard if possible.
550 splash_screen -- port should/should not display an opening splashscreen.
551 tiled_map -- port should display a tiled map if it can.
552 tile_width -- port should display tiles with this width or round to closest
554 tile_height -- port should display tiles with this height or round to closest
556 tile_file -- open this alternative tile file. The file name is likely to be
557 window-port or platform specific.
558 use_inverse -- port should display inverse when NetHack asks for it.
559 vary_msgcount -- port should display this number of messages at a time in
562 -- port should use these colors for window foreground/background
564 menu fore/back message fore/back status fore/back text fore/back
565 wraptext -- port should wrap long lines of text if they don't fit in
566 the visible area of the window
567 mouse_support -- port should enable mouse support if possible
569 Whenever one of these settings is adjusted, the port is notified of a change
570 to the setting by calling the port's preference_update() routine. The port
571 is only notified if it has indicated that it supports that option by setting
572 the option's bit in the port's wincap mask. The port can choose to adjust
573 for the change to an option that it receives notification about, or ignore it.
574 The former approach is recommended. If you don't want to deal with a
575 user-initiated setting change, then the port should call
576 set_wc_option_mod_status(mask, SET_IN_FILE) to make the option invisible to
579 Functions available for the window port to call:
581 set_wc_option_mod_status(optmask, status)
582 -- Adjust the optflag field for a set of wincap options to
583 specify whether the port wants the option to appear
584 in the 'O' command options menu, The second parameter,
585 "status" can be set to SET_IN_FILE, DISP_IN_GAME,
586 or SET_IN_GAME (SET_IN_FILE implies that the option
587 is completely hidden during the game).
589 set_wc2_option_mod_status(optmask, status)
590 -- Adjust the optflag field for a set of wincap2 options to
591 specify whether the port wants the option to appear
592 in the 'O' command options menu, The second parameter,
593 "status" can be set to SET_IN_FILE, DISP_IN_GAME,
594 or SET_IN_GAME (SET_IN_FILE implies that the option
595 is completely hidden during the game).
597 set_option_mod_status(optnam, status)
598 -- Adjust the optflag field for one of the core options
599 that is not part of the wincap suite. A port might use
600 this to override the default initialization setting for
601 status specified in options.c. Note that you have to
602 specify the option by name and that you can only set
603 one option per call unlike set_wc_option_mod_status().
606 Adding a new wincap option:
608 To add a new wincap option, please follow all these steps:
609 1. Add the option to the wincap preference settings table above. Since
610 wincap is full, your option will likely target wincap2 field.
611 2. Add the description to the paragraph below the chart.
612 3. Add the WC_ or WC2_ to the bit list in include/winprocs.h
613 (in wincap2 if there is no room in wincap).
614 4. Add the wc_ or wc2_ field(s) to the iflags structure in flag.h.
615 5. Add the name and value to wc_options[] or wc2_options[] in options.c
616 6. Add an appropriate parser to parseoptions() in options.c.
617 7. Add code to display current value to get_compopt_value() in options.c.
618 8. Document the option in Guidebook.mn and Guidebook.tex.
619 9. Add the bit name to the OR'd values in your window port's winprocs struct
620 wincap mask if your port supports the option.
622 V. New or respecified common, high level routines
624 These are not part of the interface, but mentioned here for your information.
626 char display_inventory(lets, want_reply)
627 -- Calls a start_menu()/add_menu()/select_menu() sequence.
628 It returns the item selected, or '\0' if none is selected.
629 Returns '\033' if the menu was canceled.
631 -- Like raw_print(), but accepts arguments like printf(). This
632 routine processes the arguments and then calls raw_print().
633 -- The mac version #defines error raw_printf. I think this
634 is a reasonable thing to do for most ports.
636 -- Prints a string to WIN_MESSAGE using a printf() interface.
637 It has the variants You(), Your(), Norep(), and others
638 in pline.c which all use the same mechanism. pline()
639 requires the variable "char toplines[]" be defined; Every
640 putstr() on WIN_MESSAGE must copy str to toplines[] for use
641 by Norep() and pline(). If the window system is not active
642 (!iflags.window_inited) pline() uses raw_print().
646 These are not part of the interface. They may be called by your
647 window port routines to perform the desired task, instead of duplicating
648 the necessary code in each window port.
650 mapglyph(int glyph, int *ochar, int *ocolor, unsigned *special, int x, int y)
651 -- Maps glyph at x,y to NetHack ascii character and color.
652 If it represents something special such as a pet, that
653 information is returned as set bits in "special."
654 Usually called from the window port's print_glyph()
659 The following is the general order in which calls from main() should be made,
660 as they relate to the window system. The actual code may differ, but the
661 order of the calls should be the same.
664 choose_windows(DEFAULT_WINDOW_SYS) /* choose a default window system */
665 initoptions() /* read the resource file */
666 init_nhwindows() /* initialize the window system */
667 process_options(argc, argv) /* process command line options or equiv */
668 if(save file is present) {
669 display_gamewindows() /* create & display the game windows */
670 dorestore() /* restore old game; pline()s are OK */
672 player_selection() /* select a player type using a window */
673 display_gamewindows() /* create & display the game windows */
675 pline("Hello, welcome...");
677 Choose_windows() is a common routine, and calling it in main() is necessary
678 to initialize the function pointer table to _something_ so that calls to
679 raw_print() will not fail. Choose_windows() should be called almost
680 immediately upon entering main(). Look at unixmain.c for an example.
682 Display_gamewindows() is a common routine that displays the three standard
683 game windows (WIN_MESSAGE, WIN_MAP, and WIN_STATUS). It is normally called
684 just before the "Hello, welcome" message.
686 Process_options() is currently still unique to each port. There may be need
687 in the future to make it possible to replace this on a per window-port basis.
692 init_nhwindows() is expected to display a gee-whiz banner window, including
693 the Copyright message. It is recommended that the COPYRIGHT_BANNER_A,
694 COPYRIGHT_BANNER_B, and COPYRIGHT_BANNER_C macros from patchlevel.h be used
695 for constructing the Copyright message. COPYRIGHT_BANNER_A is a
696 quoted string that has the NetHack copyright declaration,
697 COPYRIGHT_BANNER_B is a quoted string that states who the copyright
698 belongs to, and COPYRIGHT_BANNER_C simply says "See License for
699 details." Be sure to #include "patchlevel.h" to define these macros.
700 Using the macros will prevent having to update the Copyright information
701 in each window-port prior to each release.
703 Ports (MSDOS, TOS, MAC, etc) _may_ use window-port specific routines in
704 their port specific files, _AT_THEIR_OWN_RISK_. Since "port" and
705 "window-port" are orthogonal, you make your "port" code less portable by
706 using "window-port" specific routines. Every effort should be made to
707 use window-port interface routines, unless there is something port
708 specific that is better suited (e.g. msmsg() for MSDOS).
710 The tty window-port is contained in win/tty, the X window port is contained
711 in win/X11. The files in these directories contain _only_ window port code,
712 and may be replaced completely by other window ports.
715 IX. Implementation and Multi-window support
717 NetHack 3.2 and higher support multiple window systems in the same binary.
718 When writing a new window-port, you need to follow the following guidelines:
720 1) Pick a unique prefix to identify your window-port. For example, the tty
721 window port uses "tty"; the X11 window-port uses "X11".
722 2) When declaring your interface function, precede the function names with
723 your unique prefix. E.g:
725 void tty_init_nhwindows()
727 /* code for initializing windows in the tty port */
730 When calling window functions from within your port code, we suggest
731 calling the prefixed version to avoid unnecessary overhead. However,
732 you may safely call the non-prefixed version (e.g. putstr() rather than
733 tty_putstr()) as long as you #include "hack.h". If you do not
734 include hack.h and use the non-prefixed names, you will get compile
737 We also suggest declaring all functions and port-specific data with
738 this prefix to avoid unexpected overlaps with other window-ports.
739 The tty and X11 ports do not currently follow this suggestion, but do
740 use separate non-overlapping convention for naming data and internal
743 3) Declare a structure, "struct window_procs prefix_procs", (with your
744 prefix instead of "prefix") and fill in names of all of your
745 interface functions. The first entry in this structure is the name
746 of your window-port, which should be the prefix. The second entry
747 is the wincap mask that identifies what window port preference
748 settings your port will react to and support. The other entries
749 are the function addresses.
751 Assuming that you followed the convention in (2), you can safely copy
752 the structure definition from an existing window-port and just change
753 the prefixes. That will guarantee that you get the order of your
754 initializations correct (not all compilers will catch out-of-order
755 function pointer declarations).
757 4) Add a #define to config.h identifying your window-port in the
758 "Windowing systems" section. Follow the "prefix_GRAPHICS" convention
759 for your window-port.
761 5) Add your prefix to the list of valid prefixes listed in the "Known
762 systems are" comment.
764 6) Edit makedefs.c and add a string for your windowing system to window_opts
765 inside an #ifdef prefix_GRAPHICS.
767 7) Edit windows.c and add an external reference to your prefix_procs inside
768 an #ifdef prefix_GRAPHICS. Also add an entry to the win_choices
769 structure for your window-port of the form:
771 #ifdef prefix_GRAPHICS
772 { &prefix_procs, prefix_init_function },
775 The init_function is necessary for some compilers and systems to force
776 correct linking. If your system does not need such massaging, you
777 may put a null pointer here.
779 You should declare prefix_procs and prefix_init_function as extern's
780 in your win*.h file, and #include that file at the beginning of
781 windows.c, also inside an #ifdef prefix_GRAPHICS. Some win*.h files
782 are rather sensitive, and you might have to duplicate your
783 prefix_procs and prefix_init_function's instead of including win*.h.
784 The tty port includes wintty.h, the X11 port duplicates the declarations.
786 8) If your port uses Makefile.src, add the .c and .o files and an
787 appropriate comment in the section on "WINSRC" and "WINOBJ". See
788 Makefile.src for the style to use. If you don't use Makefile.src,
789 we suggest using a similar convention for the make-equivalent used
790 on your system. Also add your new source and binaries to WINSRC and
791 WINOBJ (if you want the NetHack binary to include them, that is).
793 9) Look at your port's portmain.c (the file containing main()) and make
794 sure that all of the calls match the the requirements laid out in
797 Now, proceed with compilation and installation as usual. Don't forget
798 to edit Makefile.src (or its equivalent) and config.h to set the
799 window-ports you want in your binary, the default window-port to use,
800 and the .o's needed to build a valid game.
802 One caveat. Unfortunately, if you incorrectly specify the
803 DEFAULT_WINDOW_SYS, NetHack will dump core (or whatever) without
804 printing any message, because raw_print() cannot function without first
805 setting the window-port.