1 NetHack 3.6 window.doc $NHDT-Date: 1433901374 2015/06/10 01:56:14 $ $NHDT-Branch: master $:$NHDT-Revision: 1.42 $
5 This file documents the support for various windowing systems in
6 NetHack. The support is through a standard interface, separating the
7 main NetHack code from window-system specific code. The implementation
8 supports multiple window systems in the same binary. Even if you only
9 wish to support one window-port on your port, you will need to follow
10 the instructions in Section IX to get a compilable binary.
12 Copyright 2003, David Cohrs
13 NetHack may be freely redistributed. See license for details.
16 I. Window Types and Terminology
17 II. Interface Specification
19 IV. WINCAP preferences support
20 V. New or respecified common, high level routines
24 IX. Implementation and Multi-window support
27 I. Window Types and Terminology
29 There are 4 basic window types, used to call create_nhwindow():
31 NHW_MESSAGE (top line)
32 NHW_MAP (main dungeon)
33 NHW_MENU (inventory or other "corner" windows)
34 NHW_TEXT (help/text, full screen paged window)
36 The tty window-port also uses NHW_BASE (the base display) internally.
38 (The genl_status_* routines use NHW_STATUS for backward compatibility
39 when displaying status information on the bottom lines. New code
40 should not use NHW_STATUS. NHW_STATUS will be phased out over time.)
42 NHW_MENU windows can be used for either menu or text display. Their
43 basic feature is that for the tty-port, if the window is small enough,
44 it appears in the corner of the tty display instead of overwriting
45 the whole screen. The first call to add information to the window
46 will decide if it is going to be used to display a menu or text.
47 If start_menu() is called, then it will be used as a menu. If
48 putstr() is called, it will be used as text. Once decided, there
49 is no turning back. For the tty-port, if the data is too large for
50 a single screen then the data is paged (with --more--) between pages.
51 Only NHW_MENU type windows can be used for menus.
53 NHW_TEXT windows are used to display a large amount of textual data.
54 This is the type of window one would use for displaying a help file,
55 for example. In the tty window-port, windows of type NHW_TEXT can
56 page using the DEF_PAGER, if DEF_PAGER is defined. There exists an
57 assumption that the font for text windows is monospaced. The help
58 files are all formatted accordingly.
60 "window" is always of type winid. This is currently implemented as an
61 integer, but doesn't necessarily have to be done that way. There are
62 a few fixed window names that are known throughout the code:
64 WIN_MESSAGE (top line)
65 WIN_MAP (main dungeon)
68 Other windows are created and destroyed as needed.
70 (The genl_status_* routines use WIN_STATUS for backward compatibility
71 when displaying status information on the bottom lines. New code
72 should not use WIN_STATUS, or assume its presence. NHW_STATUS will
73 be phased out over time.)
75 "Port" in this document refers to a CPU/OS/hardware platform (UNIX, MSDOS
76 TOS, etc.) "window-port" refers to the windowing platform. This is
77 orthogonal (e.g. UNIX might use either a tty window-port or an X11
81 II. Interface Specification
83 All functions below are void unless otherwise noted.
85 A. Low-level routines:
87 raw_print(str) -- Print directly to a screen, or otherwise guarantee that
88 the user sees str. raw_print() appends a newline to str.
89 It need not recognize ASCII control characters. This is
90 used during startup (before windowing system initialization
91 -- maybe this means only error startup messages are raw),
92 for error messages, and maybe other "msg" uses. E.g.
93 updating status for micros (i.e, "saving").
95 -- Like raw_print(), but prints in bold/standout (if possible).
97 -- Next output to window will start at (x,y), also moves
98 displayable cursor to (x,y). For backward compatibility,
99 1 <= x < cols, 0 <= y < rows, where cols and rows are
101 -- For variable sized windows, like the old status window, the
102 behavior when curs() is called outside the window's limits
103 is unspecified. The mac port wraps to 0, with the status
104 window being 2 lines high and 80 columns wide.
105 -- Still used by curs_on_u(), obsolete status updates,
106 screen locating (identify, teleport).
107 -- NHW_MESSAGE, NHW_MENU and NHW_TEXT windows do not
108 currently support curs in the tty window-port.
109 putstr(window, attr, str)
110 -- Print str on the window with the given attribute. Only
111 printable ASCII characters (040-0126) must be supported.
112 Multiple putstr()s are output on separate lines. Attributes
119 If a window-port does not support all of these, it may map
120 unsupported attributes to a supported one (e.g. map them
121 all to ATR_INVERSE). putstr() may compress spaces out of
122 str, break str, or truncate str, if necessary for the
123 display. Where putstr() breaks a line, it has to clear
125 -- putstr should be implemented such that if two putstr()s
126 are done consecutively the user will see the first and
127 then the second. In the tty port, pline() achieves this
128 by calling more() or displaying both on the same line.
129 putmixed(window, attr, str)
130 -- Print str on the window with the given attribute. In
131 addition to printable ASCII characters (040-0126),
132 sequences of encoded glyph values are supported.
133 The glyph encoding sequence is \GXXXXNNNN, where:
134 XXXX is a hexadecimal value. The value must match
135 the randomly generated value for the current
136 game in progress in order to be decoded.
137 The value for the game in progress is stored in
138 context.rndencode. This field minimizes
139 unintentional decoding of player-supplied strings
140 such as pet names, etc.
141 NNNN is a hexadecimal value representing the glyph.
142 If a window port does not yet support special handling of
143 the glyph value, it can use genl_putmixed (mapglyph.c)
144 which converts the encoded glyph into a character symbol.
146 Multiple putmixed()s are output on separate lines. Attributes
153 If a window-port does not support all of these, it may map
154 unsupported attributes to a supported one (e.g. map them
155 all to ATR_INVERSE). putmixed() may compress spaces out of
156 str, break str, or truncate str, if necessary for the
157 display. Where putmixed() breaks a line, it has to clear
159 -- putstr should be implemented such that if two putmixed()s
160 are done consecutively the user will see the first and
162 get_nh_event() -- Does window event processing (e.g. exposure events).
163 A noop for the tty and X window-ports.
164 int nhgetch() -- Returns a single character input from the user.
165 -- In the tty window-port, nhgetch() assumes that tgetch()
166 will be the routine the OS provides to read a character.
167 Returned character _must_ be non-zero and it must be
168 non meta-zero too (zero with the meta-bit set).
169 -- If platform uses it, should check program_state.done_hup
170 and immediately return ASCII 033 (escape) if it is.
171 This is required if the window-port supports SAFERHANGUP.
172 -- ASCII 033 must also be returned rather than EOF (applies
173 mainly to the tty window-port).
174 -- The program_state.done_hup flag can be set asynchronously
175 when SAFERHANGUP is defined and in that case, nhgetch()
176 needs to detect that the value of program_state.done_hup
177 changed and also return ASCII 033 in this case.
178 int nh_poskey(int *x, int *y, int *mod)
179 -- Returns a single character input from the user or a
180 positioning event (perhaps from a mouse). If the
181 return value is non-zero, a character was typed, else,
182 a position in the MAP window is returned in x, y and mod.
185 CLICK_1 /* mouse click type 1 */
186 CLICK_2 /* mouse click type 2 */
188 The different click types can map to whatever the
189 hardware supports. If no mouse is supported, this
190 routine always returns a non-zero character.
191 -- Otherwise follows the same behavior as nhgetch().
193 B. High-level routines:
195 print_glyph(window, x, y, glyph, bkglyph)
196 -- Print the glyph at (x,y) on the given window. Glyphs are
197 integers at the interface, mapped to whatever the window-
198 port wants (symbol, font, color, attributes, ...there's
199 a 1-1 map between glyphs and distinct things on the map).
200 -- bkglyph is a background glyph for potential use by some
201 graphical or tiled environments to allow the depiction
202 to fall against a background consistent with the grid
203 around x,y. If bkglyph is NO_GLYPH, then the parameter
204 should be ignored (do nothing with it).
206 char yn_function(const char *ques, const char *choices, char default)
207 -- Print a prompt made up of ques, choices and default.
208 Read a single character response that is contained in
209 choices or default. If choices is NULL, all possible
210 inputs are accepted and returned. This overrides
211 everything else. The choices are expected to be in
212 lower case. Entering ESC always maps to 'q', or 'n',
213 in that order, if present in choices, otherwise it maps
214 to default. Entering any other quit character (SPACE,
215 RETURN, NEWLINE) maps to default.
216 -- If the choices string contains ESC, then anything after
217 it is an acceptable response, but the ESC and whatever
218 follows is not included in the prompt.
219 -- If the choices string contains a '#' then accept a count.
220 Place this value in the global "yn_number" and return '#'.
221 -- This uses the top line in the tty window-port, other
222 ports might use a popup.
223 -- If choices is NULL, all possible inputs are accepted and
224 returned, preserving case (upper or lower.) This means that
225 if the calling function needs an exact match, it must handle
226 user input correctness itself.
227 -- ques should not be more than QBUFSZ-1 characters long.
228 getlin(const char *ques, char *input)
229 -- Prints ques as a prompt and reads a single line of text,
230 up to a newline. The string entered is returned without the
231 newline. ESC is used to cancel, in which case the string
232 "\033\000" is returned.
233 -- getlin() must call flush_screen(1) before doing anything.
234 -- This uses the top line in the tty window-port, other
235 ports might use a popup.
236 -- getlin() can assume the input buffer is at least BUFSZ
237 bytes in size and must truncate inputs to fit, including
239 int get_ext_cmd(void)
240 -- Get an extended command in a window-port specific way.
241 An index into extcmdlist[] is returned on a successful
242 selection, -1 otherwise.
244 -- Do a window-port specific player type selection. If
245 player_selection() offers a Quit option, it is its
246 responsibility to clean up and terminate the process.
247 You need to fill in pl_character[0].
248 display_file(str, boolean complain)
249 -- Display the file named str. Complain about missing files
250 iff complain is TRUE.
252 -- Indicate to the window port that the inventory has been
254 -- Merely calls display_inventory() for window-ports that
255 leave the window up, otherwise empty.
257 -- Display previous messages. Used by the ^P command.
258 -- On the tty-port this scrolls WIN_MESSAGE back one line.
260 update_positionbar(char *features)
261 -- Optional, POSITIONBAR must be defined. Provide some
262 additional information for use in a horizontal
263 position bar (most useful on clipped displays).
264 Features is a series of char pairs. The first char
265 in the pair is a symbol and the second char is the
266 column where it is currently located.
267 A '<' is used to mark an upstairs, a '>'
268 for a downstairs, and an '@' for the current player
269 location. A zero char marks the end of the list.
272 C. Window Utility Routines
274 init_nhwindows(int* argcp, char** argv)
275 -- Initialize the windows used by NetHack. This can also
276 create the standard windows listed at the top, but does
278 -- Any commandline arguments relevant to the windowport
279 should be interpreted, and *argcp and *argv should
280 be changed to remove those arguments.
281 -- When the message window is created, the variable
282 iflags.window_inited needs to be set to TRUE. Otherwise
283 all plines() will be done via raw_print().
284 ** Why not have init_nhwindows() create all of the "standard"
285 ** windows? Or at least all but WIN_INFO? -dean
287 -- Exits the window system. This should dismiss all windows,
288 except the "window" used for raw_print(). str is printed
290 window = create_nhwindow(type)
291 -- Create a window of type "type."
292 clear_nhwindow(window)
293 -- Clear the given window, when appropriate.
294 display_nhwindow(window, boolean blocking)
295 -- Display the window on the screen. If there is data
296 pending for output in that window, it should be sent.
297 If blocking is TRUE, display_nhwindow() will not
298 return until the data has been displayed on the screen,
299 and acknowledged by the user where appropriate.
300 -- All calls are blocking in the tty window-port.
301 -- Calling display_nhwindow(WIN_MESSAGE,???) will do a
302 --more--, if necessary, in the tty window-port.
303 destroy_nhwindow(window)
304 -- Destroy will dismiss the window if the window has not
305 already been dismissed.
307 -- Start using window as a menu. You must call start_menu()
308 before add_menu(). After calling start_menu() you may not
309 putstr() to the window. Only windows of type NHW_MENU may
311 add_menu(windid window, int glyph, const anything identifier,
312 char accelerator, char groupacc,
313 int attr, char *str, boolean preselected)
314 -- Add a text line str to the given menu window. If identifier
315 is 0, then the line cannot be selected (e.g. a title).
316 Otherwise, identifier is the value returned if the line is
317 selected. Accelerator is a keyboard key that can be used
318 to select the line. If the accelerator of a selectable
319 item is 0, the window system is free to select its own
320 accelerator. It is up to the window-port to make the
321 accelerator visible to the user (e.g. put "a - " in front
322 of str). The value attr is the same as in putstr().
323 Glyph is an optional glyph to accompany the line. If
324 window port cannot or does not want to display it, this
325 is OK. If there is no glyph applicable, then this
326 value will be NO_GLYPH.
327 -- All accelerators should be in the range [A-Za-z],
328 but there are a few exceptions such as the tty player
329 selection code which uses '*'.
330 -- It is expected that callers do not mix accelerator
331 choices. Either all selectable items have an accelerator
332 or let the window system pick them. Don't do both.
333 -- Groupacc is a group accelerator. It may be any character
334 outside of the standard accelerator (see above) or a
335 number. If 0, the item is unaffected by any group
336 accelerator. If this accelerator conflicts with
337 the menu command (or their user defined aliases), it loses.
338 The menu commands and aliases take care not to interfere
339 with the default object class symbols.
340 -- If you want this choice to be preselected when the
341 menu is displayed, set preselected to TRUE.
343 end_menu(window, prompt)
344 -- Stop adding entries to the menu and flushes the window
345 to the screen (brings to front?). Prompt is a prompt
346 to give the user. If prompt is NULL, no prompt will
348 ** This probably shouldn't flush the window any more (if
349 ** it ever did). That should be select_menu's job. -dean
350 int select_menu(windid window, int how, menu_item **selected)
351 -- Return the number of items selected; 0 if none were chosen,
352 -1 when explicitly cancelled. If items were selected, then
353 selected is filled in with an allocated array of menu_item
354 structures, one for each selected line. The caller must
355 free this array when done with it. The "count" field
356 of selected is a user supplied count. If the user did
357 not supply a count, then the count field is filled with
358 -1 (meaning all). A count of zero is equivalent to not
359 being selected and should not be in the list. If no items
360 were selected, then selected is NULL'ed out. How is the
361 mode of the menu. Three valid values are PICK_NONE,
362 PICK_ONE, and PICK_ANY, meaning: nothing is selectable,
363 only one thing is selectable, and any number valid items
364 may selected. If how is PICK_NONE, this function should
365 never return anything but 0 or -1.
366 -- You may call select_menu() on a window multiple times --
367 the menu is saved until start_menu() or destroy_nhwindow()
368 is called on the window.
369 -- Note that NHW_MENU windows need not have select_menu()
370 called for them. There is no way of knowing whether
371 select_menu() will be called for the window at
372 create_nhwindow() time.
373 char message_menu(char let, int how, const char *mesg)
374 -- tty-specific hack to allow single line context-sensitive
375 help to behave compatibly with multi-line help menus.
376 -- This should only be called when a prompt is active; it
377 sends `mesg' to the message window. For tty, it forces
378 a --More-- prompt and enables `let' as a viable keystroke
379 for dismissing that prompt, so that the original prompt
380 can be answered from the message line "help menu".
381 -- Return value is either `let', '\0' (no selection was made),
382 or '\033' (explicit cancellation was requested).
383 -- Interfaces which issue prompts and messages to separate
384 windows typically won't need this functionality, so can
385 substitute genl_message_menu (windows.c) instead.
387 D. Status Display Routines
389 status_init() -- core calls this to notify the window port that a status
390 display is required. The window port should perform
391 the necessary initialization in here, allocate memory, etc.
392 status_enablefield(int fldindex, char fldname, char fieldfmt, boolean enable)
393 -- notifies the window port which fields it is authorized to
395 -- This may be called at any time, and is used
396 to disable as well as enable fields, depending on the
397 value of the final argument (TRUE = enable).
398 -- fldindex could be one of the following from botl.h:
399 BL_TITLE, BL_STR, BL_DX, BL_CO, BL_IN, BL_WI, BL_CH,
400 BL_ALIGN, BL_SCORE, BL_CAP, BL_GOLD, BL_ENE, BL_ENEMAX,
401 BL_XP, BL_AC, BL_HD, BL_TIME, BL_HUNGER, BL_HP, BL_HPMAX,
402 BL_LEVELDESC, BL_EXP, BL_CONDITION
403 -- There are MAXBLSTATS status fields (from botl.h)
404 status_update(int fldindex, genericptr_t ptr, int chg, int percentage, int color, long *colormasks)
405 -- update the value of a status field.
406 -- the fldindex identifies which field is changing and
407 is an integer index value from botl.h
408 -- fldindex could be any one of the following from botl.h:
409 BL_TITLE, BL_STR, BL_DX, BL_CO, BL_IN, BL_WI, BL_CH,
410 BL_ALIGN, BL_SCORE, BL_CAP, BL_GOLD, BL_ENE, BL_ENEMAX,
411 BL_XP, BL_AC, BL_HD, BL_TIME, BL_HUNGER, BL_HP, BL_HPMAX,
412 BL_LEVELDESC, BL_EXP, BL_CONDITION
413 -- fldindex could also be BL_FLUSH (-1), which is not really
414 a field index, but is a special trigger to tell the
415 windowport that it should output all changes received
416 to this point. It marks the end of a bot() cycle.
417 -- fldindex could also be BL_RESET (-2), which is not really
418 a field index, but is a special advisory to to tell the
419 windowport that it should redisplay all its status fields,
420 even if no changes have been presented to it.
421 -- ptr is usually a "char *", unless fldindex is BL_CONDITION.
422 If fldindex is BL_CONDITION, then ptr is a long value with
423 any or none of the following bits set (from botl.h):
424 BL_MASK_STONE 0x00000001L
425 BL_MASK_SLIME 0x00000002L
426 BL_MASK_STRNGL 0x00000004L
427 BL_MASK_FOODPOIS 0x00000008L
428 BL_MASK_TERMILL 0x00000010L
429 BL_MASK_BLIND 0x00000020L
430 BL_MASK_DEAF 0x00000040L
431 BL_MASK_STUN 0x00000080L
432 BL_MASK_CONF 0x00000100L
433 BL_MASK_HALLU 0x00000200L
434 BL_MASK_LEV 0x00000400L
435 BL_MASK_FLY 0x00000800L
436 BL_MASK_RIDE 0x00001000L
437 -- The value passed for BL_GOLD includes a leading
438 symbol for GOLD "$:nnn". If the window port needs to use
439 the textual gold amount without the leading "$:" the port
440 will have to add 2 to the passed "ptr" for the BL_GOLD case.
441 -- color is an unsigned int.
442 int & 0x00FF = color CLR_*
443 int >> 8 = attribute (if any)
445 This contains the color and attribute that the field should
448 This is relevant for everything except BL_CONDITION fldindex.
449 If fldindex is BL_CONDITION, this parameter should be ignored,
450 as condition hilighting is done via the next colormasks
453 -- colormasks - pointer to cond_hilites[] array of colormasks.
455 Only relevant for BL_CONDITION fldindex. The window port
456 should ignore this parameter for other fldindex values.
458 Each condition bit must only ever appear in one of the
459 CLR_ array members, but can appear in multiple HL_ATTCLR_
460 offsets (because more than one attribute can co-exist).
462 For the user's chosen set of BL_MASK_ condition bits,
463 They are stored internally in the cond_hilites[] array,
464 at the array offset aligned to the color those condition
465 bits should display in.
467 For example, if the user has chosen to display strngl
468 and stone and termill in red and inverse,
470 BL_MASK_SLIME 0x00000002
471 BL_MASK_STRNGL 0x00000004
472 BL_MASK_TERMILL 0x00000010
474 The bitmask corresponding to those conditions is
475 0x00000016 (or 00010110 in binary) and the color
476 is at offset 1 (CLR_RED).
478 Here is how that is stored in the cond_hilites[] array:
480 +------+----------------------+--------------------+
482 |offset| macro for indexing | bitmask |
483 |------+----------------------+--------------------+
485 +------+----------------------+--------------------+
486 | 1 | CLR_RED | 00010110 |
487 +------+----------------------+--------------------+
489 +------+----------------------+--------------------+
491 +------+----------------------+--------------------+
493 +------+----------------------+--------------------+
494 | 5 | CLR_MAGENTA | |
495 +------+----------------------+--------------------+
497 +------+----------------------+--------------------+
499 +------+----------------------+--------------------+
501 +------+----------------------+--------------------+
503 +------+----------------------+--------------------+
504 | 10 | CLR_BRIGHT_GREEN | |
505 +------+----------------------+--------------------+
506 | 11 | CLR_BRIGHT_YELLOW | |
507 +------+----------------------+--------------------+
508 | 12 | CLR_BRIGHT_BLUE | |
509 +------+----------------------+--------------------+
510 | 13 | CLR_BRIGHT_MAGENTA | |
511 +------+----------------------+--------------------+
512 | 14 | CLR_BRIGHT_CYAN | |
513 +------+----------------------+--------------------+
515 +------+----------------------+--------------------+
516 | 16 | HL_ATTCLR_DIM | | CLR_MAX
517 +------+----------------------+--------------------+
518 | 17 | HL_ATTCLR_BLINK | |
519 +------+----------------------+--------------------+
520 | 18 | HL_ATTCLR_ULINE | |
521 +------+----------------------+--------------------+
522 | 19 | HL_ATTCLR_INVERSE | 00010110 |
523 +------+----------------------+--------------------+
524 | 20 | HL_ATTCLR_BOLD | |
525 +------+----------------------+--------------------+
526 | 21 | beyond array boundary | BL_ATTCLR_MAX
528 The window port can AND (&) the bits passed in the
529 ptr argument to status_update() with any non-zero
530 entries in the cond_hilites[] array to determine
531 the color and attributes for displaying the
532 condition on the screen for the user.
534 If the bit for a particular condition does not
535 appear in any of the cond_hilites[] array offsets,
536 that condition should be displayed in the default
537 color and attributes.
539 status_finish() -- called when it is time for the window port to tear down
540 the status display and free allocated memory, etc.
545 make_sound(???) -- To be determined later. THIS IS CURRENTLY UN-IMPLEMENTED.
546 nhbell() -- Beep at user. [This will exist at least until sounds are
547 redone, since sounds aren't attributable to windows anyway.]
548 mark_synch() -- Don't go beyond this point in I/O on any channel until
549 all channels are caught up to here. Can be an empty call
551 wait_synch() -- Wait until all pending output is complete (*flush*() for
553 -- May also deal with exposure events etc. so that the
554 display is OK when return from wait_synch().
555 delay_output() -- Causes a visible delay of 50ms in the output.
556 Conceptually, this is similar to wait_synch() followed
557 by a nap(50ms), but allows asynchronous operation.
558 askname() -- Ask the user for a player name.
559 cliparound(x, y)-- Make sure that the user is more-or-less centered on the
560 screen if the playing area is larger than the screen.
561 -- This function is only defined if CLIPPING is defined.
563 -- Initialize the number pad to the given state.
564 suspend_nhwindows(str)
565 -- Prepare the window to be suspended.
567 -- Restore the windows after being suspended.
568 can_suspend() -- Tell the core if the window system will allow the game
569 to be suspended now. If unconditionally yes or no, use
570 genl_can_suspend_yes() or genl_can_suspend_no().
572 start_screen() -- Only used on Unix tty ports, but must be declared for
573 completeness. Sets up the tty to work in full-screen
574 graphics mode. Look at win/tty/termcap.c for an
575 example. If your window-port does not need this function
576 just declare an empty function.
577 end_screen() -- Only used on Unix tty ports, but must be declared for
578 completeness. The complement of start_screen().
580 outrip(winid, int, time_t)
581 -- The tombstone code. If you want the traditional code use
582 genl_outrip for the value and check the #if in rip.c.
584 preference_update(preference)
585 -- The player has just changed one of the wincap preference
586 settings, and the NetHack core is notifying your window
587 port of that change. If your window-port is capable of
588 dynamically adjusting to the change then it should do so.
589 Your window-port will only be notified of a particular
590 change if it indicated that it wants to be by setting the
591 corresponding bit in the wincap mask.
594 -- This is used to preserve message history between games by
595 obtaining the messages from the window port so that the core
596 can put them into the savefile.
597 The routine is called repeatedly from the core save routine,
598 and the window port routine is expected to successively return
599 each message that it wants the game to store in the savefile,
600 starting with the oldest message first, finishing
601 with the most recent.
602 If init is TRUE, start over again from most recent message.
605 -- This is the counterpart to getmsghistory() for restores
606 used to reload the port's message recall buffer.
607 The routine is called repeatedly from the core restore
608 routine, starting with the oldest message first, and
609 finishing with the most recent one that it read from the savefile.
610 The window port routine is expected to load the message
611 recall buffers in such a way that the ordering remains correct.
612 The window port routine should make no assumptions about how
613 many messages are forthcoming, nor should it assume that
614 another message will follow this one, so it must be careful
615 to keep all pointers/indexes intact at the end of each call.
616 If the window port receives more messages that can fit in
617 its buffers, it is expected to scroll away the oldest from
618 its buffers, much like it would with new messages being
622 III. Global variables
624 The following global variables are defined in decl.c and must be used by
625 the window interface to the rest of NetHack.
627 char toplines[BUFSZ] Contains the last message printed to the WIN_MESSAGE
628 window, used by Norep().
629 winid WIN_MESSAGE, WIN_MAP, WIN_INVEN
630 The three standard windows.
631 There is also a window called WIN_STATUS that is used
632 only for backward compatibility in the genl_status_*
633 set of generic status display functions.
634 char *AE, *AS; Checked in options.c to see if we should load and
635 switch to DECGraphics symset. It is #ifdefed VMS and UNIX.
636 int LI, CO; Set in sys/unix/ioctl.c.
638 The following appears to be Unix specific. Other ports using the tty
639 window-port should also declare this variable in one of your sys/*.c files.
641 short ospeed; Set and declared in sys/unix/unixtty.c (don't
642 know about other sys files).
644 The following global variable is defined in options.c. It equates a
645 list of wincap option names with their associated bit-mask [see
646 section IV WINCAP preferences support]. The array is zero-terminated.
648 struct wc_Opt wc_options[];
649 One entry for each available WINCAP option.
650 Each entry has a wc_name field and a wc_bit
653 IV. WINCAP preferences support
655 Starting with NetHack 3.4.0, the window interface was enhanced to provide
656 a common way of setting window port user preferences from the config file,
657 and from the command line for some settings.
659 The wincap preference settings all have their underlying values stored
660 in iflags fields. The names of the wincap related fields are all pre-
661 fixed with wc_ or wc2_ to make it easy to identify them. Your window
662 port can access the fields directly.
664 Your window port identifies what options it will react to and support
665 by setting bits in the window_procs wincap mask and/or wincap2 mask.
666 Your window port can also fill in the color-availability table for
667 the window port, has_color[CLR_MAX] to flag the colors it supports
668 1 it does, or 0 it doesn't. [CLR_MAX is 16 as of 3.6.3.]
670 See section IX for details of where the wincap masks reside.
672 Two things control whether any preference setting appears in the
673 'O' command options menu during the game:
674 1. The option must be marked as being supported by having its
675 bit set in the window_procs wincap or wincap2 mask.
676 2. The option must have its optflag field set to SET_IN_GAME in order
677 to be able to set the option, or marked DISP_IN_GAME if you just
678 want to reveal what the option is set to.
679 Both conditions must be true to be able to see or set the option from
682 The default values for the optflag field for all the options are
683 hard-coded into the option in options.c. The default value for
684 the wc_ options can be altered by calling
685 set_wc_option_mod_status(optmask, status)
686 The default value for the wc2_ options can be altered by calling
687 set_wc2_option_mod_status(optmask, status)
688 In each case, set the option modification status to one of SET_IN_FILE,
689 DISP_IN_GAME, or SET_IN_GAME.
691 The setting of any wincap or wincap2 option is handled by the NetHack
692 core option processing code. You do not have to provide a parser in
693 your window port, nor should you set the values for the
694 iflags.wc_* and iflags.wc2_* fields directly within the port code.
695 The port code should honor whatever values were put there by the core
696 when processing options, either in the config file, or by the 'O' command.
698 You may be wondering what values your window port will find in the
699 iflags.wc_* and iflags.wc2_* fields for options that the user has not
700 specified in his/her config file. Put another way, how does your port code
701 tell if an option has not been set? The next paragraph explains that.
703 If the core does not set an option, it will still be initialized
704 to its default value. Those default values for the
705 iflags.wc_* and iflags.wc_* fields are:
707 o All boolean fields are initialized to the starting
708 value specified for that option in the boolopt array in
709 options.c. The window-port should respect that setting
710 unless it has a very good reason for not doing so.
711 o All int fields are initialized to zero. Zero is not a valid
712 setting for any of the int options, so if your port code
713 encounters a zero there, it can assume that the preference
714 option was not specified. In that case, the window-port code
715 should use a default setting that the port is comfortable with.
716 It should write the default setting back into the iflags.wc_*
717 field. That is the only time that your window-port could should
719 o All "char *" fields will be null pointers. Be sure to check for
720 that in your window-port code before using such a pointer, or
721 you'll end up triggering a nasty fault.
723 Here are the wincap and wincap2 preference settings that your port can choose
727 +--------------------+--------------------+--------------------+--------+
728 | | | iflags field | data |
729 | player option | bit in wincap mask | for value | type |
730 |--------------------+--------------------+--------------------+--------+
731 | align_message | WC_ALIGN_MESSAGE | wc_align_message |int |
732 | align_status | WC_ALIGN_STATUS | wc_align_status |int |
733 | ascii_map | WC_ASCII_MAP | wc_ascii_map |boolean |
734 | color | WC_COLOR | wc_color |boolean |
735 | eight_bit_tty | WC_EIGHT_BIT_IN | wc_eight_bit_input |boolean |
736 | font_map | WC_FONT_MAP | wc_font_map |char * |
737 | font_menu | WC_FONT_MENU | wc_font_menu |char * |
738 | font_message | WC_FONT_MESSAGE | wc_font_message |char * |
739 | font_status | WC_FONT_STATUS | wc_font_status |char * |
740 | font_text | WC_FONT_TEXT | wc_font_text |char * |
741 | font_size_map | WC_FONTSIZ_MAP | wc_fontsiz_map |int |
742 | font_size_menu | WC_FONTSIZ_MENU | wc_fontsiz_menu |int |
743 | font_size_message | WC_FONTSIZ_MESSAGE | wc_fontsiz_message |int |
744 | font_size_status | WC_FONTSIZ_STATUS | wc_fontsiz_status |int |
745 | font_size_text | WC_FONTSIZ_TEXT | wc_fontsiz_text |int |
746 | hilite_pet | WC_HILITE_PET | wc_hilite_pet |boolean |
747 | map_mode | WC_MAP_MODE | wc_map_mode |int |
748 | player_selection | WC_PLAYER_SELECTION| wc_player_selection|int |
749 | popup_dialog | WC_POPUP_DIALOG | wc_popup_dialog |boolean |
750 | preload_tiles | WC_PRELOAD_TILES | wc_preload_tiles |boolean |
751 | scroll_amount | WC_SCROLL_AMOUNT | wc_scroll_amount |int |
752 | scroll_margin | WC_SCROLL_MARGIN | wc_scroll_margin |int |
753 | splash_screen | WC_SPLASH_SCREEN | wc_splash_screen |boolean |
754 | tiled_map | WC_TILED_MAP | wc_tiled_map |boolean |
755 | tile_width | WC_TILE_WIDTH | wc_tile_width |int |
756 | tile_height | WC_TILE_HEIGHT | wc_tile_height |int |
757 | tile_file | WC_TILE_FILE | wc_tile_file |char * |
758 | use_inverse | WC_INVERSE | wc_inverse |boolean |
759 | vary_msgcount | WC_VARY_MSGCOUNT | wc_vary_msgcount |int |
760 | windowcolors | WC_WINDOWCOLORS | wc_foregrnd_menu |char * |
761 | | | wc_backgrnd_menu |char * |
762 | | | wc_foregrnd_message|char * |
763 | | | wc_backgrnd_message|char * |
764 | | | wc_foregrnd_status |char * |
765 | | | wc_backgrnd_status |char * |
766 | | | wc_foregrnd_text |char * |
767 | | | wc_backgrnd_text |char * |
768 | mouse | WC_MOUSE_SUPPORT | wc_mouse_support |boolean |
769 +--------------------+--------------------+--------------------+--------+
772 +--------------------+--------------------+--------------------+--------+
773 | | | iflags field | data |
774 | player option | bit in wincap mask | for value | type |
775 |--------------------+--------------------+--------------------+--------+
776 | fullscreen | WC2_FULLSCREEN | wc2_fullscreen |boolean |
777 | softkeyboard | WC2_SOFTKEYBOARD | wc2_softkeyboard |boolean |
778 | wraptext | WC2_WRAPTEXT | wc2_wraptext |boolean |
779 | selectsaved | WC2_SELECTSAVED | wc2_selectsaved |boolean |
780 | hitpointbar | WC2_HITPOINTBAR | wc2_hitpointbar |boolean |
781 | term_cols | WC2_TERM_COLS | wc2_term_cols |int |
782 | term_rows | WC2_TERM_ROWS | wc2_term_rows |int |
783 | windowborders | WC2_WINDOWBORDERS | wc2_windowborders |int |
784 +--------------------+--------------------+--------------------+--------+
786 more wincap2 for STATUS_HILITES support and control
787 +--------------------------------- +---------------------------+
788 | To inform the game engine | |
789 | that the window port is equipped | bit to set in wincap mask |
790 | to receive the following in its | |
791 | x_status_update() routine | |
792 |----------------------------------+---------------------------+
793 | BL_FLUSH to render buffered | WC2_FLUSH_STATUS |
794 | field changes now | |
795 |----------------------------------+---------------------------+
796 | BL_RESET to indicate that all | WC2_RESET_STATUS |
797 | fields should be redone | |
798 +----------------------------------+---------------------------+
800 align_message -- where to place message window (top, bottom, left, right)
801 align_status -- where to place status display (top, bottom, left, right).
802 ascii_map -- port should display an ascii map if it can.
803 color -- port should display color if it can.
804 eight_bit_tty -- port should allow eight bit input.
805 font_map -- port should use a font by this name for map window.
806 font_menu -- port should use a font by this name for menu windows.
807 font_message -- port should use a font by this name for message window.
808 font_size_map -- port should use this size font for the map window.
809 font_size_menu -- port should use this size font for menu windows.
811 -- port should use this size font for the message window.
812 font_size_status-- port should use this size font for the status display.
813 font_size_text -- port should use this size font for text windows.
814 font_status -- port should use a font by this name for status display.
815 font_text -- port should use a font by this name for text windows.
816 fullscreen -- port should try to use the whole screen.
817 hilite_pet -- port should mark pets in some special way on the map.
818 hitpointbar -- port should show a graphical bar representing hit points
819 map_mode -- port should display the map in the manner specified.
821 -- dialog or prompts for choosing character.
822 popup_dialog -- port should pop up dialog boxes for input.
823 preload_tiles -- port should preload tiles into memory.
824 scroll_amount -- scroll this amount when scroll_margin is reached.
825 scroll_margin -- port should scroll the display when the hero or cursor
826 is this number of cells away from the edge of the window.
827 selectsaved -- if port can display a menu of the user's saved games do so.
828 softkeyboard -- handhelds should display an on-screen keyboard if possible.
829 splash_screen -- port should/should not display an opening splashscreen.
830 term_cols -- Terminal should size itself to specified width, if possible.
831 term_rows -- Terminal should size itself to specified height, if possible.
832 tiled_map -- port should display a tiled map if it can.
833 tile_width -- port should display tiles with this width or round to closest
835 tile_height -- port should display tiles with this height or round to closest
837 tile_file -- open this alternative tile file. The file name is likely to be
838 window-port or platform specific.
839 use_inverse -- port should display inverse when NetHack asks for it.
840 vary_msgcount -- port should display this number of messages at a time in
842 windowborders -- port should display borders around main NetHack windows.
843 Can be set to (1) on, (2) off, or (3) auto.
845 -- port should use these colors for window foreground/background
847 menu fore/back message fore/back status fore/back text fore/back
848 wraptext -- port should wrap long lines of text if they don't fit in
849 the visible area of the window
850 mouse_support -- port should enable mouse support if possible
852 Whenever one of these settings is adjusted, the port is notified of a change
853 to the setting by calling the port's preference_update() routine. The port
854 is only notified if it has indicated that it supports that option by setting
855 the option's bit in the port's wincap mask. The port can choose to adjust
856 for the change to an option that it receives notification about, or ignore it.
857 The former approach is recommended. If you don't want to deal with a
858 user-initiated setting change, then the port should call
859 set_wc_option_mod_status(mask, SET_IN_FILE) to make the option invisible to
862 Functions available for the window port to call:
864 set_wc_option_mod_status(optmask, status)
865 -- Adjust the optflag field for a set of wincap options to
866 specify whether the port wants the option to appear
867 in the 'O' command options menu, The second parameter,
868 "status" can be set to SET_IN_FILE, DISP_IN_GAME,
869 or SET_IN_GAME (SET_IN_FILE implies that the option
870 is completely hidden during the game).
872 set_wc2_option_mod_status(optmask, status)
873 -- Adjust the optflag field for a set of wincap2 options to
874 specify whether the port wants the option to appear
875 in the 'O' command options menu, The second parameter,
876 "status" can be set to SET_IN_FILE, DISP_IN_GAME,
877 or SET_IN_GAME (SET_IN_FILE implies that the option
878 is completely hidden during the game).
880 set_option_mod_status(optnam, status)
881 -- Adjust the optflag field for one of the core options
882 that is not part of the wincap suite. A port might use
883 this to override the default initialization setting for
884 status specified in options.c. Note that you have to
885 specify the option by name and that you can only set
886 one option per call unlike set_wc_option_mod_status().
889 Adding a new wincap option:
891 To add a new wincap option, please follow all these steps:
892 1. Add the option to the wincap preference settings table above. Since
893 wincap is full, your option will likely target wincap2 field.
894 2. Add the description to the paragraph below the chart.
895 3. Add the WC_ or WC2_ to the bit list in include/winprocs.h
896 (in wincap2 if there is no room in wincap).
897 4. Add the wc_ or wc2_ field(s) to the iflags structure in flag.h.
898 5. Add the name and value to wc_options[] or wc2_options[] in options.c
899 6. Add an appropriate parser to parseoptions() in options.c.
900 7. Add code to display current value to get_compopt_value() in options.c.
901 8. Document the option in Guidebook.mn and Guidebook.tex.
902 9. Add the bit name to the OR'd values in your window port's winprocs struct
903 wincap mask if your port supports the option.
905 V. New or respecified common, high level routines
907 These are not part of the interface, but mentioned here for your information.
909 char display_inventory(lets, want_reply)
910 -- Calls a start_menu()/add_menu()/select_menu() sequence.
911 It returns the item selected, or '\0' if none is selected.
912 Returns '\033' if the menu was canceled.
914 -- Like raw_print(), but accepts arguments like printf(). This
915 routine processes the arguments and then calls raw_print().
916 -- The mac version #defines error raw_printf. I think this
917 is a reasonable thing to do for most ports.
919 -- Prints a string to WIN_MESSAGE using a printf() interface.
920 It has the variants You(), Your(), Norep(), and others
921 in pline.c which all use the same mechanism. pline()
922 requires the variable "char toplines[]" be defined; Every
923 putstr() on WIN_MESSAGE must copy str to toplines[] for use
924 by Norep() and pline(). If the window system is not active
925 (!iflags.window_inited) pline() uses raw_print().
929 These are not part of the interface. They may be called by your
930 window port routines to perform the desired task, instead of duplicating
931 the necessary code in each window port.
933 int mapglyph(int glyph, int *ochar, int *ocolor, unsigned *special,
934 int x, int y, unsigned mgflags)
935 -- Maps glyph at x,y to NetHack ascii character and color.
936 The return value is an index into the showsyms[] array, in
937 case a port wants to index into its own alternative
938 set of display symbols (such as a unicode set) instead of
941 If the glyph represents something special such as a pet,
942 that information is returned as set bits in "special.":
950 Usually called from the window port's print_glyph()
955 The following is the general order in which calls from main() should be made,
956 as they relate to the window system. The actual code may differ, but the
957 order of the calls should be the same.
960 choose_windows(DEFAULT_WINDOW_SYS) /* choose a default window system */
961 initoptions() /* read the resource file */
962 init_nhwindows() /* initialize the window system */
963 process_options(argc, argv) /* process command line options or equiv */
964 if(save file is present) {
965 display_gamewindows() /* create & display the game windows */
966 dorestore() /* restore old game; pline()s are OK */
968 player_selection() /* select a player type using a window */
969 display_gamewindows() /* create & display the game windows */
971 pline("Hello, welcome...");
973 Choose_windows() is a common routine, and calling it in main() is necessary
974 to initialize the function pointer table to _something_ so that calls to
975 raw_print() will not fail. Choose_windows() should be called almost
976 immediately upon entering main(). Look at unixmain.c for an example.
977 Choose_windows will call an (optional) ini_routine with a single argument
978 of WININIT to allow any needed setup. Because choose_windows() may be called
979 multiple times during argument and option processing, to handle the case where
980 ini_routines have side effects that need to be undone, the old ini_routine (if
981 any) will be called with an argument of WININIT_UNDO before the new
982 ini_routine (if any) is called (with WININIT).
984 Display_gamewindows() is a common routine that displays the two standard
985 game windows (WIN_MESSAGE, WIN_MAP), and the status display. It is normally
986 called just before the "Hello, welcome" message.
988 Process_options() is currently still unique to each port. There may be need
989 in the future to make it possible to replace this on a per window-port basis.
994 init_nhwindows() is expected to display a gee-whiz banner window, including
995 the Copyright message. It is recommended that the COPYRIGHT_BANNER_A,
996 COPYRIGHT_BANNER_B, COPYRIGHT_BANNER_C, and COPYRIGHT_BANNER_D macros from
997 patchlevel.h and date.h be used for constructing the Copyright message.
998 COPYRIGHT_BANNER_A is a quoted string that has the NetHack copyright declaration,
999 COPYRIGHT_BANNER_B is a quoted string that states who the copyright belongs to,
1000 COPYRIGHT_BANNER_C is a quoted string generated by makedefs that includes version
1001 and build information. and COPYRIGHT_BANNER_D simply says "See License for details."
1002 Be sure to #include "patchlevel.h" and date.h to define these macros. Using the
1003 macros will prevent having to update the Copyright information in each window-port
1004 prior to each release.
1006 Ports (MSDOS, TOS, MAC, etc) _may_ use window-port specific routines in
1007 their port specific files, _AT_THEIR_OWN_RISK_. Since "port" and
1008 "window-port" are orthogonal, you make your "port" code less portable by
1009 using "window-port" specific routines. Every effort should be made to
1010 use window-port interface routines, unless there is something port
1011 specific that is better suited (e.g. msmsg() for MSDOS).
1013 The tty window-port is contained in win/tty, the X window port is contained
1014 in win/X11. The files in these directories contain _only_ window port code,
1015 and may be replaced completely by other window ports.
1018 IX. Implementation and Multi-window support
1020 NetHack 3.2 and higher support multiple window systems in the same binary.
1021 When writing a new window-port, you need to follow the following guidelines:
1023 1) Pick a unique prefix to identify your window-port. For example, the tty
1024 window port uses "tty"; the X11 window-port uses "X11".
1025 2) When declaring your interface function, precede the function names with
1026 your unique prefix. E.g:
1028 void tty_init_nhwindows()
1030 /* code for initializing windows in the tty port */
1033 When calling window functions from within your port code, we suggest
1034 calling the prefixed version to avoid unnecessary overhead. However,
1035 you may safely call the non-prefixed version (e.g. putstr() rather than
1036 tty_putstr()) as long as you #include "hack.h". If you do not
1037 include hack.h and use the non-prefixed names, you will get compile
1038 or link-time errors.
1040 We also suggest declaring all functions and port-specific data with
1041 this prefix to avoid unexpected overlaps with other window-ports.
1042 The tty and X11 ports do not currently follow this suggestion, but do
1043 use separate non-overlapping convention for naming data and internal
1046 3) Declare a structure, "struct window_procs prefix_procs", (with your
1047 prefix instead of "prefix") and fill in names of all of your
1048 interface functions. The first entry in this structure is the name
1049 of your window-port, which should be the prefix. The second entry
1050 is the wincap mask that identifies what window port preference
1051 settings your port will react to and support. The other entries
1052 are the function addresses.
1054 Assuming that you followed the convention in (2), you can safely copy
1055 the structure definition from an existing window-port and just change
1056 the prefixes. That will guarantee that you get the order of your
1057 initializations correct (not all compilers will catch out-of-order
1058 function pointer declarations).
1060 4) Add a #define to config.h identifying your window-port in the
1061 "Windowing systems" section. Follow the "prefix_GRAPHICS" convention
1062 for your window-port.
1064 5) Add your prefix to the list of valid prefixes listed in the "Known
1065 systems are" comment.
1067 6) Edit makedefs.c and add a string for your windowing system to window_opts
1068 inside an #ifdef prefix_GRAPHICS.
1070 7) Edit windows.c and add an external reference to your prefix_procs inside
1071 an #ifdef prefix_GRAPHICS. Also add an entry to the win_choices
1072 structure for your window-port of the form:
1074 #ifdef prefix_GRAPHICS
1075 { &prefix_procs, prefix_init_function },
1078 The init_function is necessary for some compilers and systems to force
1079 correct linking. If your system does not need such massaging, you
1080 may put a null pointer here.
1082 You should declare prefix_procs and prefix_init_function as extern's
1083 in your win*.h file, and #include that file at the beginning of
1084 windows.c, also inside an #ifdef prefix_GRAPHICS. Some win*.h files
1085 are rather sensitive, and you might have to duplicate your
1086 prefix_procs and prefix_init_function's instead of including win*.h.
1087 The tty port includes wintty.h, the X11 port duplicates the declarations.
1089 8) If your port uses Makefile.src, add the .c and .o files and an
1090 appropriate comment in the section on "WINSRC" and "WINOBJ". See
1091 Makefile.src for the style to use. If you don't use Makefile.src,
1092 we suggest using a similar convention for the make-equivalent used
1093 on your system. Also add your new source and binaries to WINSRC and
1094 WINOBJ (if you want the NetHack binary to include them, that is).
1096 9) Look at your port's portmain.c (the file containing main()) and make
1097 sure that all of the calls match the requirements laid out in
1100 Now, proceed with compilation and installation as usual. Don't forget
1101 to edit Makefile.src (or its equivalent) and config.h to set the
1102 window-ports you want in your binary, the default window-port to use,
1103 and the .o's needed to build a valid game.
1105 One caveat. Unfortunately, if you incorrectly specify the
1106 DEFAULT_WINDOW_SYS, NetHack will dump core (or whatever) without
1107 printing any message, because raw_print() cannot function without first
1108 setting the window-port.
1113 WINCHAIN is an optional facility that allows the SYSCF_FILE to specify a
1114 series of processors that will see each call from the core to the window
1115 port (and the resulting return chain). Processors are specified one at a
1116 time from the start of the chain (the core end) towards the window port as:
1117 OPTIONS=windowchain:+PROC
1118 where PROC is the name of the processor to add to the chain. The '+' is
1119 required and is part of the name of the processor (this distinguishes
1120 processors from window ports; in addition the '-' character is reserved for
1121 WINCHAIN internals).
1123 If WINCHAIN is not compiled into the NetHack binary, there is no overhead.
1125 If WINCHAIN is compiled into the NetHack binary but not used, overhead is
1126 limited to one function call during game setup and a trivial amount of data.
1128 Note that raw_print* calls will not go through the chain until initialization
1129 is complete (when *main.c calls commit_windowchain()).
1131 The only processor currently available is '+trace' which is a debugging
1132 facility for window ports. See the code in win/chain/wc_trace.c for
1133 details on where to find the log file and how to write to it from other parts
1136 A processor may be specified more than once; this is expected to be most
1137 useful for surrounding a processor being developed with before and after