<Someone> wishes to add a couple of new options to the wince port ("run fullscreen" and "do not use CE software keyboard").
The wincap field was full, so this adds a second field for
additional options.
.ds vr "NetHack 3.4
.ds f0 "\*(vr
.ds f1
-.ds f2 "June 29, 2003
+.ds f2 "July 16, 2003
.mt
A Guide to the Mazes of Menace
(Guidebook for NetHack)
NetHack should use this size font for the status window.
.lp font_size_text
NetHack should use this size font for text windows.
+.lp fullscreen
+NetHack should try and display on the entire screen rather than in a window.
.lp hilite_pet
Visually distinguish pets from similar animals (default off).
The behavior of this option depends on the type of windowing you use.
.lp scroll_margin
NetHack should scroll the display when the hero or cursor
is this number of cells away from the edge of the window.
+.lp softkeyboard
+Display an onscreen keyboard. Handhelds are most likely to support this option.
.lp splash_screen
NetHack should display an opening splash screen when it starts up (default yes).
.lp tiled_map
\begin{document}
%
% input file: guidebook.mn
-% $Revision: 1.66 $ $Date: 2003/06/06 03:49:35 $
+% $Revision: 1.67 $ $Date: 2003/06/30 02:08:55 $
%
%.ds h0 "
%.ds h1 %.ds h2 \%
%.au
\author{Eric S. Raymond\\
(Extensively edited and expanded for 3.4)}
-\date{June 29, 2003}
+\date{July 16, 2003}
\maketitle
\item[\ib{font\_size\_text}]
NetHack should use this size font for text windows.
%.lp
+\item[\ib{fullscreen}]
+NetHack should try and display on the entire screen rather than in a window.
+%.lp
\item[\ib{hilite\_pet}]
Visually distinguish pets from similar animals (default off).
The behavior of this option depends on the type of windowing you use.
NetHack should scroll the display when the hero or cursor
is this number of cells away from the edge of the window.
%.lp
+\item[\ib{softkeyboard}]
+Display an onscreen keyboard. Handhelds are most likely to support this option.
+%.lp
\item[\ib{splash\_screen}]
NetHack should display an opening splash screen when it starts up (default yes).
%.lp
The wincap preference settings all have their underlying values stored
in iflags fields. The names of the wincap related fields are all pre-
-fixed with wc_ to make it easy to identify them. Your window port can
-access the fields directly.
+fixed with wc_ or wc2_ to make it easy to identify them. Your window
+port can access the fields directly.
Your window port identifies what options it will react to and support
-by setting bits in the window_procs wincap mask. See section IX for
-details of where the wincap mask resides.
+by setting bits in the window_procs wincap mask and/or wincap2 mask.
+See section IX for details of where the wincap masks reside.
Two things control whether any preference setting appears in the
'O' command options menu during the game:
1. The option must be marked as being supported by having its
- bit set in the window_procs wincap mask.
+ bit set in the window_procs wincap or wincap2 mask.
2. The option must have its optflag field set to SET_IN_GAME in order
to be able to set the option, or marked DISP_IN_GAME if you just
want to reveal what the option is set to.
The default values for the optflag field for all the options are
hard-coded into the option in options.c. The default value for
-the options can be altered by calling
+the wc_ options can be altered by calling
set_wc_option_mod_status(optmask, status)
-specifying the option modification status to one of SET_IN_FILE,
+The default value for the wc2_ options can be altered by calling
+ set_wc2_option_mod_status(optmask, status)
+In each case, set the option modification status to one of SET_IN_FILE,
DISP_IN_GAME, or SET_IN_GAME.
-The setting of any wincap option is handled by the NetHack core option
-processing code. You do not have to provide a parser in your window
-port, nor should you set the values for the iflags.wc_* fields
-directly within the port code. The port code should honor whatever
-values were put there by the core when processing options, either
-in the config file, or by the 'O' command.
+The setting of any wincap or wincap2 option is handled by the NetHack
+core option processing code. You do not have to provide a parser in
+your window port, nor should you set the values for the
+iflags.wc_* and iflags.wc2_* fields directly within the port code.
+The port code should honor whatever values were put there by the core
+when processing options, either in the config file, or by the 'O' command.
You may be wondering what values your window port will find in the
-iflags.wc_* fields for options that the user has not specified
-in his/her config file. Put another way, how does you port code
+iflags.wc_* and iflags.wc2_* fields for options that the user has not
+specified in his/her config file. Put another way, how does you port code
tell if an option has not been set? The next paragraph explains that.
If the core does not set an option, it will still be initialized
to its default value. Those default values for the
-iflags.wc_* fields are:
+iflags.wc_* and iflags.wc_* fields are:
o All boolean fields are initialized to the starting
value specified for that option in the boolopt array in
that in your window-port code before using such a pointer, or
you'll end up triggering a nasty fault.
-Here are the wincap preference settings that your port can choose
+Here are the wincap and wincap2 preference settings that your port can choose
to support:
+ wincap
+--------------------+--------------------+--------------------+--------+
| | | iflags field | data |
| player option | bit in wincap mask | for value | type |
| mouse | WC_MOUSE_SUPPORT | wc_mouse_support |boolean |
+--------------------+--------------------+--------------------+--------+
+ wincap2
+ +--------------------+--------------------+--------------------+--------+
+ | | | iflags field | data |
+ | player option | bit in wincap mask | for value | type |
+ |--------------------+--------------------+--------------------+--------+
+ | fullscreen | WC2_FULLSCREEN | wc2_fullscreen |boolean |
+ | softkeyboard | WC2_SOFTKEYBOARD | wc2_softkeyboard |boolean |
+ +--------------------+--------------------+--------------------+--------+
+
align_message -- where to place message window (top, bottom, left, right)
align_status -- where to place status window (top, bottom, left, right).
ascii_map -- port should display an ascii map if it can.
font_size_text -- port should use this size font for text windows.
font_status -- port should use a font by this name for status window.
font_text -- port should use a font by this name for text windows.
+fullscreen -- port should try to use the whole screen.
hilite_pet -- port should mark pets in some special way on the map.
map_mode -- port should display the map in the manner specified.
player_selection
scroll_amount -- scroll this amount when scroll_margin is reached.
scroll_margin -- port should scroll the display when the hero or cursor
is this number of cells away from the edge of the window.
+softkeyboard -- handhelds should display an on-screen keyboard if possible.
splash_screen -- port should/should not display an opening splashscreen.
tiled_map -- port should display a tiled map if it can.
tile_width -- port should display tiles with this width or round to closest
Functions available for the window port to call:
set_wc_option_mod_status(optmask, status)
- -- Adjust the optflag field for a set of options to
+ -- Adjust the optflag field for a set of wincap options to
+ specify whether the port wants the option to appear
+ in the 'O' command options menu, The second parameter,
+ "status" can be set to SET_IN_FILE, DISP_IN_GAME,
+ or SET_IN_GAME (SET_IN_FILE implies that the option
+ is completely hidden during the game).
+
+set_wc2_option_mod_status(optmask, status)
+ -- Adjust the optflag field for a set of wincap2 options to
specify whether the port wants the option to appear
in the 'O' command options menu, The second parameter,
"status" can be set to SET_IN_FILE, DISP_IN_GAME,
Adding a new wincap option:
To add a new wincap option, please follow all these steps:
- 1. Add the option to the wincap preference settings table above.
+ 1. Add the option to the wincap preference settings table above. Since
+ wincap is full, your option will likely target wincap2 field.
2. Add the description to the paragraph below the chart.
- 3. Add the WC_ to the bit list in include/winprocs.h (if there is room).
- 4. Add the wc_ field(s) to the iflags structure in flag.h.
- 5. Add the name and value to wc_options[] in options.c
+ 3. Add the WC_ or WC2_ to the bit list in include/winprocs.h
+ (in wincap2 if there is no room in wincap).
+ 4. Add the wc_ or wc2_ field(s) to the iflags structure in flag.h.
+ 5. Add the name and value to wc_options[] or wc2_options[] in options.c
6. Add an appropriate parser to parseoptions() in options.c.
7. Add code to display current value to get_compopt_value() in options.c.
8. Document the option in Guidebook.mn and Guidebook.tex.
E char *FDECL(nh_getenv, (const char *));
E void FDECL(set_duplicate_opt_detection, (int));
E void FDECL(set_wc_option_mod_status, (unsigned long, int));
+E void FDECL(set_wc2_option_mod_status, (unsigned long, int));
E void FDECL(set_option_mod_status, (const char *,int));
/* ### pager.c ### */
in the message window */
boolean wc_eight_bit_input; /* allow eight bit input */
boolean wc_mouse_support; /* allow mouse support */
+ boolean wc2_fullscreen; /* run fullscreen */
+ boolean wc2_softkeyboard; /* use software keyboard */
boolean cmdassist; /* provide detailed assistance for some commands */
boolean clicklook; /* allow right-clicking for look */
struct window_procs {
const char *name;
unsigned long wincap; /* window port capability options supported */
+ unsigned long wincap2; /* additional window port capability options supported */
void FDECL((*win_init_nhwindows), (int *, char **));
void NDECL((*win_player_selection));
void NDECL((*win_askname));
#define WC_MOUSE_SUPPORT 0x80000000L /* 32 mouse support */
/* no free bits */
+#define WC2_FULLSCREEN 0x01L /* 01 mouse support */
+#define WC2_SOFTKEYBOARD 0x02L /* 02 software keyboard */
+ /* 30 free bits */
+
#define ALIGN_LEFT 1
#define ALIGN_RIGHT 2
#define ALIGN_TOP 3
#else
{"flush", (boolean *)0, FALSE, SET_IN_FILE},
#endif
+ {"fullscreen", &iflags.wc2_fullscreen, FALSE, SET_IN_FILE},
{"help", &flags.help, TRUE, SET_IN_GAME},
{"hilite_pet", &iflags.wc_hilite_pet, FALSE, SET_IN_GAME}, /*WC*/
#ifdef ASCIIGRAPH
{"showscore", (boolean *)0, FALSE, SET_IN_FILE},
#endif
{"silent", &flags.silent, TRUE, SET_IN_GAME},
+ {"softkeyboard", &iflags.wc2_softkeyboard, FALSE, SET_IN_FILE},
{"sortpack", &flags.sortpack, TRUE, SET_IN_GAME},
{"sound", &flags.soundok, TRUE, SET_IN_GAME},
{"sparkle", &flags.sparkle, TRUE, SET_IN_GAME},
STATIC_OVL int FDECL(wc_set_window_colors, (char *));
STATIC_OVL boolean FDECL(is_wc_option, (const char *));
STATIC_OVL boolean FDECL(wc_supported, (const char *));
+STATIC_OVL boolean FDECL(is_wc2_option, (const char *));
+STATIC_OVL boolean FDECL(wc2_supported, (const char *));
/* check whether a user-supplied option string is a proper leading
substring of a particular option name; option string might have
#endif
if (is_wc_option(boolopt[i].name) &&
!wc_supported(boolopt[i].name)) continue;
+ if (is_wc2_option(boolopt[i].name) &&
+ !wc2_supported(boolopt[i].name)) continue;
any.a_int = (pass == 0) ? 0 : i + 1;
if (!iflags.menu_tab_sep)
Sprintf(buf, "%s%-13s [%s]",
else if (is_wc_option(compopt[i].name) &&
!wc_supported(compopt[i].name))
continue;
+ else if (is_wc2_option(compopt[i].name) &&
+ !wc2_supported(compopt[i].name))
+ continue;
else
doset_add_menu(tmpwin, compopt[i].name,
(pass == DISP_IN_GAME) ? 0 : indexoffset);
Sprintf(buf, "%s%s", *boolopt[opt_indx].addr ? "!" : "",
boolopt[opt_indx].name);
parseoptions(buf, setinitial, fromfile);
- if (wc_supported(boolopt[opt_indx].name))
+ if (wc_supported(boolopt[opt_indx].name) ||
+ wc2_supported(boolopt[opt_indx].name))
preference_update(boolopt[opt_indx].name);
} else {
/* compound option */
/* pass the buck */
parseoptions(buf, setinitial, fromfile);
}
- if (wc_supported(compopt[opt_indx].name))
+ if (wc_supported(compopt[opt_indx].name) ||
+ wc2_supported(compopt[opt_indx].name))
preference_update(compopt[opt_indx].name);
}
}
{(char *)0, 0L}
};
+struct wc_Opt wc2_options[] = {
+ {"fullscreen", WC2_FULLSCREEN},
+ {"softkeyboard", WC2_SOFTKEYBOARD},
+ {(char *)0, 0L}
+};
+
/*
* If a port wants to change or ensure that the
{
int k = 0;
if (status < SET_IN_FILE || status > SET_IN_GAME) {
- impossible("set_option_mod_status: status out of range %d.",
+ impossible("set_wc_option_mod_status: status out of range %d.",
status);
return;
}
return FALSE;
}
+
+/*
+ * You can set several wc2_options in one call to
+ * set_wc2_option_mod_status() by setting
+ * the appropriate bits for each option that you
+ * are setting in the optmask argument
+ * prior to calling.
+ * example: set_wc2_option_mod_status(WC2_FULLSCREEN|WC2_SOFTKEYBOARD, SET_IN_FILE);
+ */
+
+void
+set_wc2_option_mod_status(optmask, status)
+unsigned long optmask;
+int status;
+{
+ int k = 0;
+ if (status < SET_IN_FILE || status > SET_IN_GAME) {
+ impossible("set_wc2_option_mod_status: status out of range %d.",
+ status);
+ return;
+ }
+ while (wc2_options[k].wc_name) {
+ if (optmask & wc2_options[k].wc_bit) {
+ set_option_mod_status(wc2_options[k].wc_name, status);
+ }
+ k++;
+ }
+}
+
+STATIC_OVL boolean
+is_wc2_option(optnam)
+const char *optnam;
+{
+ int k = 0;
+ while (wc2_options[k].wc_name) {
+ if (strcmp(wc2_options[k].wc_name, optnam) == 0)
+ return TRUE;
+ k++;
+ }
+ return FALSE;
+}
+
+STATIC_OVL boolean
+wc2_supported(optnam)
+const char *optnam;
+{
+ int k = 0;
+ while (wc2_options[k].wc_name) {
+ if (!strcmp(wc2_options[k].wc_name, optnam) &&
+ (windowprocs.wincap2 & wc2_options[k].wc_bit))
+ return TRUE;
+ k++;
+ }
+ return FALSE;
+}
+
+
STATIC_OVL void
wc_set_font_name(wtype, fontname)
int wtype;
{
"amii",
WC_COLOR|WC_HILITE_PET|WC_INVERSE,
+ 0L,
amii_init_nhwindows,
amii_player_selection,
amii_askname,
{
"amitile",
WC_COLOR|WC_HILITE_PET|WC_INVERSE,
+ 0L,
amii_init_nhwindows,
amii_player_selection,
amii_askname,
WC_LARGE_FONT | /* obsolete */
WC_FONT_MAP | WC_FONT_MENU | WC_FONT_MESSAGE | WC_FONT_STATUS | WC_FONT_TEXT |
WC_FONTSIZ_MAP | WC_FONTSIZ_MENU | WC_FONTSIZ_MESSAGE | WC_FONTSIZ_STATUS | WC_FONTSIZ_TEXT,
+ 0L,
mac_init_nhwindows,
mac_unimplemented, /* see macmenu.c:mac_askname() for player selection */
mac_askname,
WC_FONTSIZ_MESSAGE|WC_FONTSIZ_STATUS|WC_FONTSIZ_MENU|WC_FONTSIZ_TEXT|
WC_TILE_WIDTH|WC_TILE_HEIGHT|WC_TILE_FILE|WC_VARY_MSGCOUNT|
WC_WINDOWCOLORS|WC_PLAYER_SELECTION,
+ 0L,
mswin_init_nhwindows,
mswin_player_selection,
mswin_askname,
WC_ASCII_MAP|WC_TILED_MAP|
WC_FONT_MAP|WC_TILE_FILE|WC_TILE_WIDTH|WC_TILE_HEIGHT|
WC_PLAYER_SELECTION|WC_SPLASH_SCREEN,
+ 0L,
NetHackQtBind::qt_init_nhwindows,
NetHackQtBind::qt_player_selection,
NetHackQtBind::qt_askname,
struct window_procs X11_procs = {
"X11",
WC_COLOR|WC_HILITE_PET,
+ 0L,
X11_init_nhwindows,
X11_player_selection,
X11_askname,
WC_FONT_MESSAGE|WC_FONT_STATUS|WC_FONT_MENU|WC_FONT_TEXT|WC_FONT_MAP|
WC_FONTSIZ_MESSAGE|WC_FONTSIZ_STATUS|WC_FONTSIZ_MENU|WC_FONTSIZ_TEXT|WC_FONTSIZ_MAP|
WC_TILE_WIDTH|WC_TILE_HEIGHT|WC_TILE_FILE|WC_VARY_MSGCOUNT|WC_ASCII_MAP,
+ 0L,
Gem_init_nhwindows,
Gem_player_selection,
Gem_askname,
struct window_procs Gnome_procs = {
"Gnome",
WC_COLOR|WC_HILITE_PET|WC_INVERSE,
+ 0L,
gnome_init_nhwindows,
gnome_player_selection,
gnome_askname,
WC_MOUSE_SUPPORT|
#endif
WC_COLOR|WC_HILITE_PET|WC_INVERSE|WC_EIGHT_BIT_IN,
+ 0L,
tty_init_nhwindows,
tty_player_selection,
tty_askname,
WC_FONTSIZ_MESSAGE|WC_FONTSIZ_STATUS|WC_FONTSIZ_MENU|WC_FONTSIZ_TEXT|
WC_TILE_WIDTH|WC_TILE_HEIGHT|WC_TILE_FILE|WC_VARY_MSGCOUNT|
WC_WINDOWCOLORS|WC_PLAYER_SELECTION|WC_SPLASH_SCREEN|WC_POPUP_DIALOG,
+ 0L,
mswin_init_nhwindows,
mswin_player_selection,
mswin_askname,