1Introduction 2 3This file documents the support for various windowing systems in 4NetHack. The support is through a standard interface, separating the 5main NetHack code from window-system specific code. The implementation 6supports multiple window systems in the same binary. Even if you only 7wish to support one window-port on your port, you will need to follow 8the instructions in Section IX to get a compilable binary. 9 10Contents: 11 I. Window Types and Terminology 12 II. Interface Specification 13 III. Global variables 14 IV. WINCAP preferences support 15 V. New or respecified common, high level routines 16 VI. Helper routines 17 VII. Game startup 18 VIII. Conventions 19 IX. Implementation and Multi-window support 20 21I. Window Types and Terminology 22 23There are 5 basic window types, used to call create_nhwindow(): 24 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) 30 31The tty window-port also uses NHW_BASE (the base display) internally. 32 33NHW_MENU windows can be used for either menu or text display. Their 34basic feature is that for the tty-port, if the window is small enough, 35it appears in the corner of the tty display instead of overwriting 36the whole screen. The first call to add information to the window 37will decide if it is going to be used to display a menu or text. 38If start_menu() is called, then it will be used as a menu. If 39putstr() is called, it will be used as text. Once decided, there 40is no turning back. For the tty-port, if the data is too large for 41a single screen then the data is paged (with --more--) between pages. 42Only NHW_MENU type windows can be used for menus. 43 44NHW_TEXT windows are used to display a large amount of textual data. 45This is the type of window one would use for displaying a help file, 46for example. In the tty window-port, windows of type NHW_TEXT can 47page using the DEF_PAGER, if DEF_PAGER is defined. There exists an 48assumption that the font for text windows is monospaced. The help 49files are all formatted accordingly. 50 51"window" is always of type winid. This is currently implemented as an 52integer, but doesn't necessarily have to be done that way. There are 53a few fixed window names that are known throughout the code: 54 55 WIN_MESSAGE (top line) 56 WIN_STATUS (bottom lines) 57 WIN_MAP (main dungeon) 58 WIN_INVEN (inventory) 59 60Other windows are created and destroyed as needed. 61 62"Port" in this document refers to a CPU/OS/hardware platform (UNIX, MSDOS 63TOS, etc.) "window-port" refers to the windowing platform. This is 64orthogonal (e.g. UNIX might use either a tty window-port or an X11 65window-port). 66 67 68II. Interface Specification 69 70All functions below are void unless otherwise noted. 71 72A. Low-level routines: 73 74raw_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"). 81raw_print_bold(str) 82 -- Like raw_print(), but prints in bold/standout (if possible). 83curs(window, x, y) 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 87 the size of window. 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 93 (identify, teleport). 94 -- NHW_MESSAGE, NHW_MENU and NHW_TEXT windows do not 95 currently support curs in the tty window-port. 96putstr(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 100 can be one of 101 ATR_NONE (or 0) 102 ATR_ULINE 103 ATR_BOLD 104 ATR_BLINK 105 ATR_INVERSE 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 111 to end-of-line. 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. 116get_nh_event() -- Does window event processing (e.g. exposure events). 117 A noop for the tty and X window-ports. 118int 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). 123int 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. 128 mod may be one of 129 130 CLICK_1 /* mouse click type 1 */ 131 CLICK_2 /* mouse click type 2 */ 132 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. 136 137B. High-level routines: 138 139print_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). 144char 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. 165getlin(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 175 the nul character. 176int 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. 180player_selection() 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]. 185display_file(str, boolean complain) 186 -- Display the file named str. Complain about missing files 187 iff complain is TRUE. 188update_inventory() 189 -- Indicate to the window port that the inventory has been 190 changed. 191 -- Merely calls display_inventory() for window-ports that 192 leave the window up, otherwise empty. 193doprev_message() 194 -- Display previous messages. Used by the ^P command. 195 -- On the tty-port this scrolls WIN_MESSAGE back one line. 196 197update_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. 207 208 209C. Window Utility Routines 210 211init_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 214 not display them. 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 223exit_nhwindows(str) 224 -- Exits the window system. This should dismiss all windows, 225 except the "window" used for raw_print(). str is printed 226 if possible. 227window = create_nhwindow(type) 228 -- Create a window of type "type." 229clear_nhwindow(window) 230 -- Clear the given window, when appropriate. 231display_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. 240destroy_nhwindow(window) 241 -- Destroy will dismiss the window if the window has not 242 already been dismissed. 243start_menu(window) 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 247 be used for menus. 248add_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. 279 280end_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 284 be printed. 285 ** This probably shouldn't flush the window any more (if 286 ** it ever did). That should be select_menu's job. -dean 287int 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. 310char 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. 323 324D. Misc. Routines 325 326make_sound(???) -- To be determined later. THIS IS CURRENTLY UN-IMPLEMENTED. 327nhbell() -- Beep at user. [This will exist at least until sounds are 328 redone, since sounds aren't attributable to windows anyway.] 329mark_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 331 for the moment 332wait_synch() -- Wait until all pending output is complete (*flush*() for 333 streams goes here). 334 -- May also deal with exposure events etc. so that the 335 display is OK when return from wait_synch(). 336delay_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. 339askname() -- Ask the user for a player name. 340cliparound(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. 343number_pad(state) 344 -- Initialize the number pad to the given state. 345suspend_nhwindows(str) 346 -- Prepare the window to be suspended. 347resume_nhwindows() 348 -- Restore the windows after being suspended. 349 350start_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. 355end_screen() -- Only used on Unix tty ports, but must be declared for 356 completeness. The complement of start_screen(). 357 358outrip(winid, int) 359 -- The tombstone code. If you want the traditional code use 360 genl_outrip for the value and check the #if in rip.c. 361 362preference_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. 370 371III. Global variables 372 373The following global variables are defined in decl.c and must be used by 374the window interface to the rest of NetHack. 375 376char toplines[BUFSZ] Contains the last message printed to the WIN_MESSAGE 377 window, used by Norep(). 378winid WIN_MESSAGE, WIN_MAP, WIN_STATUS, WIN_INVEN 379 The four standard windows. 380char *AE, *AS; Checked in options.c to see if we should switch 381 to DEC_GRAPHICS. It is #ifdefed VMS and UNIX. 382int LI, CO; Set in sys/unix/ioctl.c. 383 384The following appears to be Unix specific. Other ports using the tty 385window-port should also declare this variable in one of your sys/*.c files. 386 387short ospeed; Set and declared in sys/unix/unixtty.c (don't 388 know about other sys files). 389 390The following global variable is defined in options.c. It equates a 391list of wincap option names with their associated bit-mask [see 392section IV WINCAP preferences support]. The array is zero-terminated. 393 394struct wc_Opt wc_options[]; 395 One entry for each available WINCAP option. 396 Each entry has a wc_name field and a wc_bit 397 field. 398 399IV. WINCAP preferences support 400 401Starting with NetHack 3.4.0, the window interface was enhanced to provide 402a common way of setting window port user preferences from the config file, 403and from the command line for some settings. 404 405The wincap preference settings all have their underlying values stored 406in iflags fields. The names of the wincap related fields are all pre- 407fixed with wc_ or wc2_ to make it easy to identify them. Your window 408port can access the fields directly. 409 410Your window port identifies what options it will react to and support 411by setting bits in the window_procs wincap mask and/or wincap2 mask. 412See section IX for details of where the wincap masks reside. 413 414Two 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. 421Both conditions must be true to be able to see or set the option from 422within NetHack. 423 424The default values for the optflag field for all the options are 425hard-coded into the option in options.c. The default value for 426the wc_ options can be altered by calling 427 set_wc_option_mod_status(optmask, status) 428The default value for the wc2_ options can be altered by calling 429 set_wc2_option_mod_status(optmask, status) 430In each case, set the option modification status to one of SET_IN_FILE, 431DISP_IN_GAME, or SET_IN_GAME. 432 433The setting of any wincap or wincap2 option is handled by the NetHack 434core option processing code. You do not have to provide a parser in 435your window port, nor should you set the values for the 436iflags.wc_* and iflags.wc2_* fields directly within the port code. 437The port code should honor whatever values were put there by the core 438when processing options, either in the config file, or by the 'O' command. 439 440You may be wondering what values your window port will find in the 441iflags.wc_* and iflags.wc2_* fields for options that the user has not 442specified in his/her config file. Put another way, how does you port code 443tell if an option has not been set? The next paragraph explains that. 444 445If the core does not set an option, it will still be initialized 446to its default value. Those default values for the 447iflags.wc_* and iflags.wc_* fields are: 448 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 460 update those fields. 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. 464 465Here are the wincap and wincap2 preference settings that your port can choose 466to support: 467 468 wincap 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 +--------------------+--------------------+--------------------+--------+ 512 513 wincap2 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 +--------------------+--------------------+--------------------+--------+ 522 523align_message -- where to place message window (top, bottom, left, right) 524align_status -- where to place status window (top, bottom, left, right). 525ascii_map -- port should display an ascii map if it can. 526color -- port should display color if it can. 527eight_bit_tty -- port should allow eight bit input. 528font_map -- port should use a font by this name for map window. 529font_menu -- port should use a font by this name for menu windows. 530font_message -- port should use a font by this name for message window. 531font_size_map -- port should use this size font for the map window. 532font_size_menu -- port should use this size font for menu windows. 533font_size_message 534 -- port should use this size font for the message window. 535font_size_status-- port should use this size font for the status window. 536font_size_text -- port should use this size font for text windows. 537font_status -- port should use a font by this name for status window. 538font_text -- port should use a font by this name for text windows. 539fullscreen -- port should try to use the whole screen. 540hilite_pet -- port should mark pets in some special way on the map. 541map_mode -- port should display the map in the manner specified. 542player_selection 543 -- dialog or prompts for choosing character. 544popup_dialog -- port should pop up dialog boxes for input. 545preload_tiles -- port should preload tiles into memory. 546scroll_amount -- scroll this amount when scroll_margin is reached. 547scroll_margin -- port should scroll the display when the hero or cursor 548 is this number of cells away from the edge of the window. 549softkeyboard -- handhelds should display an on-screen keyboard if possible. 550splash_screen -- port should/should not display an opening splashscreen. 551tiled_map -- port should display a tiled map if it can. 552tile_width -- port should display tiles with this width or round to closest 553 if it can. 554tile_height -- port should display tiles with this height or round to closest 555 if it can. 556tile_file -- open this alternative tile file. The file name is likely to be 557 window-port or platform specific. 558use_inverse -- port should display inverse when NetHack asks for it. 559vary_msgcount -- port should display this number of messages at a time in 560 the message window. 561windowcolors 562 -- port should use these colors for window foreground/background 563 colors. Syntax: 564 menu fore/back message fore/back status fore/back text fore/back 565wraptext -- port should wrap long lines of text if they don't fit in 566 the visible area of the window 567mouse_support -- port should enable mouse support if possible 568 569Whenever one of these settings is adjusted, the port is notified of a change 570to the setting by calling the port's preference_update() routine. The port 571is only notified if it has indicated that it supports that option by setting 572the option's bit in the port's wincap mask. The port can choose to adjust 573for the change to an option that it receives notification about, or ignore it. 574The former approach is recommended. If you don't want to deal with a 575user-initiated setting change, then the port should call 576set_wc_option_mod_status(mask, SET_IN_FILE) to make the option invisible to 577the user. 578 579Functions available for the window port to call: 580 581set_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). 588 589set_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). 596 597set_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(). 604 605 606Adding a new wincap option: 607 608To 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. 621 622V. New or respecified common, high level routines 623 624These are not part of the interface, but mentioned here for your information. 625 626char 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. 630raw_printf(str, ...) 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. 635pline(str, ...) 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(). 643 644VI. Helper Routines 645 646These are not part of the interface. They may be called by your 647window port routines to perform the desired task, instead of duplicating 648the necessary code in each window port. 649 650mapglyph(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() 655 routine. 656 657VII. Game startup 658 659The following is the general order in which calls from main() should be made, 660as they relate to the window system. The actual code may differ, but the 661order of the calls should be the same. 662 663 664choose_windows(DEFAULT_WINDOW_SYS) /* choose a default window system */ 665initoptions() /* read the resource file */ 666init_nhwindows() /* initialize the window system */ 667process_options(argc, argv) /* process command line options or equiv */ 668if(save file is present) { 669 display_gamewindows() /* create & display the game windows */ 670 dorestore() /* restore old game; pline()s are OK */ 671} else { 672 player_selection() /* select a player type using a window */ 673 display_gamewindows() /* create & display the game windows */ 674} 675pline("Hello, welcome..."); 676 677Choose_windows() is a common routine, and calling it in main() is necessary 678to initialize the function pointer table to _something_ so that calls to 679raw_print() will not fail. Choose_windows() should be called almost 680immediately upon entering main(). Look at unixmain.c for an example. 681 682Display_gamewindows() is a common routine that displays the three standard 683game windows (WIN_MESSAGE, WIN_MAP, and WIN_STATUS). It is normally called 684just before the "Hello, welcome" message. 685 686Process_options() is currently still unique to each port. There may be need 687in the future to make it possible to replace this on a per window-port basis. 688 689 690VIII. Conventions 691 692init_nhwindows() is expected to display a gee-whiz banner window, including 693the Copyright message. It is recommended that the COPYRIGHT_BANNER_A, 694COPYRIGHT_BANNER_B, and COPYRIGHT_BANNER_C macros from patchlevel.h be used 695for constructing the Copyright message. COPYRIGHT_BANNER_A is a 696quoted string that has the NetHack copyright declaration, 697COPYRIGHT_BANNER_B is a quoted string that states who the copyright 698belongs to, and COPYRIGHT_BANNER_C simply says "See License for 699details." Be sure to #include "patchlevel.h" to define these macros. 700Using the macros will prevent having to update the Copyright information 701in each window-port prior to each release. 702 703Ports (MSDOS, TOS, MAC, etc) _may_ use window-port specific routines in 704their port specific files, _AT_THEIR_OWN_RISK_. Since "port" and 705"window-port" are orthogonal, you make your "port" code less portable by 706using "window-port" specific routines. Every effort should be made to 707use window-port interface routines, unless there is something port 708specific that is better suited (e.g. msmsg() for MSDOS). 709 710The tty window-port is contained in win/tty, the X window port is contained 711in win/X11. The files in these directories contain _only_ window port code, 712and may be replaced completely by other window ports. 713 714 715IX. Implementation and Multi-window support 716 717NetHack 3.2 and higher support multiple window systems in the same binary. 718When writing a new window-port, you need to follow the following guidelines: 719 7201) Pick a unique prefix to identify your window-port. For example, the tty 721 window port uses "tty"; the X11 window-port uses "X11". 7222) When declaring your interface function, precede the function names with 723 your unique prefix. E.g: 724 725 void tty_init_nhwindows() 726 { 727 /* code for initializing windows in the tty port */ 728 } 729 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 735 or link-time errors. 736 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 741 functions. 742 7433) 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. 750 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). 756 7574) 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. 760 7615) Add your prefix to the list of valid prefixes listed in the "Known 762 systems are" comment. 763 7646) Edit makedefs.c and add a string for your windowing system to window_opts 765 inside an #ifdef prefix_GRAPHICS. 766 7677) 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: 770 771 #ifdef prefix_GRAPHICS 772 { &prefix_procs, prefix_init_function }, 773 #endif 774 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. 778 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. 785 7868) 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). 792 7939) 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 795 Section VII. 796 797Now, proceed with compilation and installation as usual. Don't forget 798to edit Makefile.src (or its equivalent) and config.h to set the 799window-ports you want in your binary, the default window-port to use, 800and the .o's needed to build a valid game. 801 802One caveat. Unfortunately, if you incorrectly specify the 803DEFAULT_WINDOW_SYS, NetHack will dump core (or whatever) without 804printing any message, because raw_print() cannot function without first 805setting the window-port. 806