Angband
Functions | Variables
ui-input.c File Reference

Some high-level UI functions, inkey() More...

#include "angband.h"
#include "cmds.h"
#include "game-event.h"
#include "game-input.h"
#include "game-world.h"
#include "init.h"
#include "obj-gear.h"
#include "obj-util.h"
#include "player-calcs.h"
#include "player-path.h"
#include "randname.h"
#include "savefile.h"
#include "target.h"
#include "ui-command.h"
#include "ui-context.h"
#include "ui-curse.h"
#include "ui-display.h"
#include "ui-help.h"
#include "ui-keymap.h"
#include "ui-knowledge.h"
#include "ui-map.h"
#include "ui-object.h"
#include "ui-output.h"
#include "ui-player.h"
#include "ui-prefs.h"
#include "ui-signals.h"
#include "ui-spell.h"
#include "ui-store.h"
#include "ui-target.h"

Functions

void flush (game_event_type unused, game_event_data *data, void *user)
 Flush all pending input. More...
 
static ui_event inkey_aux (int scan_cutoff)
 Helper function called only from "inkey()". More...
 
ui_event inkey_ex (void)
 Get a keypress from the user. More...
 
void anykey (void)
 Get a keypress or mouse click from the user and ignore it. More...
 
struct keypress inkey (void)
 Get a "keypress" from the user. More...
 
ui_event inkey_m (void)
 Get a "keypress" or a "mousepress" from the user. More...
 
static void msg_flush (int x)
 Hack – flush. More...
 
void display_message (game_event_type unused, game_event_data *data, void *user)
 Output a message to the top line of the screen. More...
 
void bell_message (game_event_type unused, game_event_data *data, void *user)
 Flush the output before displaying for emphasis. More...
 
void message_flush (game_event_type unused, game_event_data *data, void *user)
 Print the queued messages. More...
 
void clear_from (int row)
 Clear the bottom part of the screen. More...
 
bool askfor_aux_keypress (char *buf, size_t buflen, size_t *curs, size_t *len, struct keypress keypress, bool firsttime)
 The default "keypress handling function" for askfor_aux, this takes the given keypress, input buffer, length, etc, and does the appropriate action for each keypress, such as moving the cursor left or inserting a character. More...
 
bool askfor_aux (char *buf, size_t len, bool(*keypress_h)(char *, size_t, size_t *, size_t *, struct keypress, bool))
 Get some input at the cursor location. More...
 
static bool get_name_keypress (char *buf, size_t buflen, size_t *curs, size_t *len, struct keypress keypress, bool firsttime)
 A "keypress" handling function for askfor_aux, that handles the special case of '*' for a new random "name" and passes any other "keypress" through to the default "editing" handler. More...
 
bool get_character_name (char *buf, size_t buflen)
 Gets a name for the character, reacting to name changes. More...
 
bool textui_get_string (const char *prompt, char *buf, size_t len)
 Prompt for a string from the user. More...
 
int textui_get_quantity (const char *prompt, int max)
 Request a "quantity" from the user. More...
 
bool textui_get_check (const char *prompt)
 Verify something with the user. More...
 
char get_char (const char *prompt, const char *options, size_t len, char fallback)
 Ask the user to respond with a character. More...
 
static bool get_file_text (const char *suggested_name, char *path, size_t len)
 Text-native way of getting a filename. More...
 
bool textui_get_com (const char *prompt, char *command)
 Prompts for a keypress. More...
 
bool get_com_ex (const char *prompt, ui_event *command)
 
void pause_line (struct term *term)
 Pause for user response. More...
 
bool textui_get_rep_dir (int *dp, bool allow_5)
 Request a "movement" direction (1,2,3,4,6,7,8,9) from the user. More...
 
bool textui_get_aim_dir (int *dp)
 Get an "aiming direction" (1,2,3,4,6,7,8,9 or 5) from the user. More...
 
void textui_input_init (void)
 Initialise the UI hooks to give input asked for by the game. More...
 
static int textui_get_count (void)
 Get a command count, with the '0' key. More...
 
ui_event textui_get_command (int *count)
 Request a command from the user. More...
 
bool key_confirm_command (unsigned char c)
 Check no currently worn items are stopping the action 'c'. More...
 
bool textui_process_key (struct keypress kp, unsigned char *c, int count)
 Process a textui keypress. More...
 

Variables

static bool inkey_xtra
 
u32b inkey_scan
 
bool inkey_flag
 
struct keypressinkey_next = NULL
 Mega-Hack – special "inkey_next" pointer. More...
 
static bool keymap_auto_more
 See if more propmts will be skipped while in a keymap. More...
 
static int message_column = 0
 
bool msg_flag
 Player has pending message. More...
 
bool(* get_file )(const char *suggested_name, char *path, size_t len) = get_file_text
 Get a pathname to save a file to, given the suggested name. More...
 
static int dir_transitions [10][10]
 
static struct keypress request_command_buffer [256]
 Hack – special buffer to hold the action of the current keymap. More...
 

Detailed Description

Some high-level UI functions, inkey()

Copyright (c) 1997 Ben Harrison, James E. Wilson, Robert A. Koeneke

This work is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation, version 2, or

b) the "Angband licence": This software may be copied and distributed for educational, research, and not for profit purposes provided that this copyright and statement are included in all such copies. Other copyrights may also apply.

Function Documentation

void anykey ( void  )

Get a keypress or mouse click from the user and ignore it.

References EVENT_EMPTY, EVT_KBRD, EVT_MOUSE, inkey_ex(), and ui_event::type.

Referenced by death_info(), do_cmd_keylog(), do_cmd_view_map(), get_file_text(), msg_flush(), and pause_line().

bool askfor_aux ( char *  buf,
size_t  len,
bool(*)(char *, size_t, size_t *, size_t *, struct keypress, bool)  keypress_h 
)

Get some input at the cursor location.

The buffer is assumed to have been initialized to a default string. Note that this string is often "empty" (see below).

The default buffer is displayed in yellow until cleared, which happens on the first keypress, unless that keypress is Return.

Normal chars clear the default and append the char. Backspace clears the default or deletes the final char. Return accepts the current buffer contents and returns true. Escape clears the buffer and the window and returns false.

Note that 'len' refers to the size of the buffer. The maximum length of the input is 'len-1'.

'keypress_h' is a pointer to a function to handle keypresses, altering the input buffer, cursor position and suchlike as required. See 'askfor_aux_keypress' (the default handler if you supply NULL for 'keypress_h') for an example.

References askfor_aux_keypress(), keypress::code, COLOUR_WHITE, COLOUR_YELLOW, ESCAPE, inkey(), KEYPRESS_NULL, NULL, Term_erase(), Term_gotoxy(), Term_locate(), and Term_putstr().

Referenced by do_cmd_delay(), do_cmd_hp_warn(), do_cmd_lazymove_delay(), do_cmd_messages(), do_cmd_pref_file_hack(), do_cmd_wiz_effect(), get_character_name(), get_debug_command(), get_pref_path(), o_xtra_act(), rune_xtra_act(), show_file(), and textui_get_string().

bool askfor_aux_keypress ( char *  buf,
size_t  buflen,
size_t *  curs,
size_t *  len,
struct keypress keypress  ,
bool  firsttime 
)

The default "keypress handling function" for askfor_aux, this takes the given keypress, input buffer, length, etc, and does the appropriate action for each keypress, such as moving the cursor left or inserting a character.

It should return true when editing of the buffer is "complete" (e.g. on the press of RETURN).

References ARROW_LEFT, ARROW_RIGHT, bell(), keypress::code, ESCAPE, KC_BACKSPACE, KC_DELETE, and KC_ENTER.

Referenced by askfor_aux(), askfor_aux_numbers(), and get_name_keypress().

void bell_message ( game_event_type  unused,
game_event_data data,
void user 
)

Flush the output before displaying for emphasis.

References display_message(), PR_MESSAGE, player_upkeep::redraw, Term_fresh(), and player::upkeep.

Referenced by ui_enter_game(), and ui_leave_game().

void clear_from ( int  row)
void display_message ( game_event_type  unused,
game_event_data data,
void user 
)

Output a message to the top line of the screen.

Break long messages into multiple pieces (40-72 chars).

Allow multiple short messages to "share" the top line.

Prompt the user to make sure he has a chance to read them.

These messages are memorized for later reference (see above).

We could do a "Term_fresh()" to provide "flicker" if needed.

The global "msg_flag" variable can be cleared to tell us to "erase" any "pending" messages still on the screen, instead of using "msg_flush()". This should only be done when the user is known to have read the message.

We must be very careful about using the "msg("s", )" functions without explicitly calling the special "msg("s", NULL)" function, since this may result in the loss of information if the screen is cleared, or if anything is displayed on the top line.

Hack – Note that "msg("s", NULL)" will clear the top line even if no messages are pending.

References buf, character_generated, h, game_event_data::message, message_column, message_type_color(), msg, game_event_data::msg, msg_flag, msg_flush(), my_strcpy(), Term, Term_get_size(), Term_putstr(), type, game_event_data::type, void(), and w.

Referenced by bell_message(), combine_pack(), ui_enter_game(), and ui_leave_game().

void flush ( game_event_type  unused,
game_event_data data,
void user 
)

Flush all pending input.

Actually, remember the flush, using the "inkey_xtra" flag, and in the next call to "inkey()", perform the actual flushing, for efficiency, and correctness of the "inkey()" function.

References inkey_xtra.

Referenced by dice_parse_string(), ui_enter_game(), and ui_leave_game().

char get_char ( const char *  prompt,
const char *  options,
size_t  len,
char  fallback 
)

Ask the user to respond with a character.

Options is a constant string, e.g. "yns"; len is the length of the constant string, and fallback should be the default answer if the user hits escape or an invalid key.

Example: get_char("Study? ", "yns", 3, 'n') This prompts "Study? [yns]" and defaults to 'n'.

References keypress::code, EVENT_MESSAGE_FLUSH, event_signal(), inkey(), prt(), and strnfmt().

Referenced by do_cmd_save_screen().

bool get_character_name ( char *  buf,
size_t  buflen 
)

Gets a name for the character, reacting to name changes.

If sf is true, we change the savefile name depending on the character name.

References askfor_aux(), EVENT_MESSAGE_FLUSH, event_signal(), player::full_name, get_name_keypress(), my_strcpy(), and prt().

Referenced by do_cmd_change_name(), and get_name_command().

bool get_com_ex ( const char *  prompt,
ui_event command 
)
static bool get_file_text ( const char *  suggested_name,
char *  path,
size_t  len 
)
static

Text-native way of getting a filename.

References ANGBAND_DIR_USER, anykey(), file_exists(), format(), get_check(), get_string(), my_strcpy(), path_build(), and prt().

static bool get_name_keypress ( char *  buf,
size_t  buflen,
size_t *  curs,
size_t *  len,
struct keypress  keypress,
bool  firsttime 
)
static

A "keypress" handling function for askfor_aux, that handles the special case of '*' for a new random "name" and passes any other "keypress" through to the default "editing" handler.

References askfor_aux_keypress(), keypress::code, my_strcap(), name_sections, randname_make(), and RANDNAME_TOLKIEN.

Referenced by get_character_name().

struct keypress inkey ( void  )
static ui_event inkey_aux ( int  scan_cutoff)
static

Helper function called only from "inkey()".

References EVENT_EMPTY, SCAN_OFF, Term_inkey(), Term_xtra(), TERM_XTRA_DELAY, void(), and w.

Referenced by inkey_ex().

ui_event inkey_ex ( void  )

Get a keypress from the user.

This function recognizes a few "global parameters". These are variables which, if set to true before calling this function, will have an effect on this function, and which are always reset to false by this function before this function returns. Thus they function just like normal parameters, except that most calls to this function can ignore them.

If "inkey_xtra" is true, then all pending keypresses will be flushed. This is set by flush(), which doesn't actually flush anything itself but uses that flag to trigger delayed flushing.

If "inkey_scan" is true, then we will immediately return "zero" if no keypress is available, instead of waiting for a keypress.

If "inkey_flag" is true, then we are waiting for a command in the main map interface, and we shouldn't show a cursor.

If we are waiting for a keypress, and no keypress is ready, then we will refresh (once) the window which was active when this function was called.

Note that "back-quote" is automatically converted into "escape" for convenience on machines with no "escape" key.

If "angband_term[0]" is not active, we will make it active during this function, so that the various "main-xxx.c" files can assume that input is only requested (via "Term_inkey()") when "angband_term[0]" is active.

Mega-Hack – This function is used as the entry point for clearing the "signal_count" variable, and of the "character_saved" variable.

Mega-Hack – Note the use of "inkey_hack" to allow the "Borg" to steal control of the keyboard from the user.

References character_saved, keypress::code, ESCAPE, EVENT_EMPTY, EVT_NONE, inkey_aux(), inkey_flag, inkey_scan, inkey_xtra, ui_event::key, keymap_auto_more, NULL, OPT, SCAN_INSTANT, screen_save_depth, signal_count, target_sighted(), Term, Term_activate(), Term_flush(), Term_fresh(), Term_get_cursor(), Term_inkey(), term_screen, Term_set_cursor(), ui_event::type, and void().

Referenced by anykey(), check_for_player_interrupt(), display_knowledge(), do_cmd_change_name(), do_cmd_messages(), do_cmd_options_win(), do_cmd_wiz_features(), do_cmd_wiz_query(), inkey(), inkey_m(), menu_select(), see_floor_items(), textui_get_aim_dir(), textui_get_command(), and textui_get_rep_dir().

ui_event inkey_m ( void  )

Get a "keypress" or a "mousepress" from the user.

on return the event must be either a key press or a mouse press

References keypress::code, ESCAPE, EVENT_EMPTY, EVT_BUTTON, EVT_ESCAPE, EVT_KBRD, EVT_MOUSE, inkey_ex(), ui_event::key, keypress::mods, and ui_event::type.

Referenced by get_com_ex(), target_recall_loop_object(), target_set_interactive_aux(), and textui_get_check().

bool key_confirm_command ( unsigned char  c)
void message_flush ( game_event_type  unused,
game_event_data data,
void user 
)

Print the queued messages.

References message_column, msg_flag, msg_flush(), and Term.

Referenced by ui_enter_game(), and ui_leave_game().

static void msg_flush ( int  x)
static

Hack – flush.

References anykey(), COLOUR_L_BLUE, keymap_auto_more, OPT, Term_erase(), and Term_putstr().

Referenced by display_message(), and message_flush().

void pause_line ( struct term term)

Pause for user response.

This function is stupid. XXX XXX XXX

References anykey(), term::hgt, prt(), put_str(), Term, void(), and term::wid.

Referenced by display_winner(), main(), and splashscreen_note().

bool textui_get_aim_dir ( int dp)

Get an "aiming direction" (1,2,3,4,6,7,8,9 or 5) from the user.

Return true if a direction was chosen, otherwise return false.

The direction "5" is special, and means "use current target".

This function tracks and uses the "global direction", and uses that as the "desired direction", if it is set.

Note that "Force Target", if set, will pre-empt user interaction, if there is a usable target already set.

References bell(), mouseclick::button, keypress::code, EVT_KBRD, EVT_MOUSE, get_com_ex(), inkey_ex(), inkey_scan, ui_event::key, KEY_GRID_X, KEY_GRID_Y, player_options::lazymove_delay, ui_event::mouse, OPT, player::opts, p, target_dir(), TARGET_KILL, target_okay(), target_set_closest(), target_set_interactive(), and ui_event::type.

Referenced by textui_input_init().

bool textui_get_check ( const char *  prompt)

Verify something with the user.

The "prompt" should take the form "Query? "

Note that "[y/n]" is appended to the prompt.

References mouseclick::button, keypress::code, EVENT_MESSAGE_FLUSH, event_signal(), EVT_MOUSE, inkey_m(), ui_event::key, ui_event::mouse, prt(), strnfmt(), ui_event::type, and mouseclick::y.

Referenced by textui_input_init().

bool textui_get_com ( const char *  prompt,
char *  command 
)

Prompts for a keypress.

The "prompt" should take the form "Command: "

Warning - this function assumes that the entered command is an ASCII

character, and so should be used with great caution - NRM

Returns true unless the character is "Escape"

References keypress::code, get_com_ex(), and ui_event::key.

Referenced by textui_input_init().

ui_event textui_get_command ( int count)

Request a command from the user.

Note that "caret" ("^") is treated specially, and is used to allow manual input of control characters. This can be used on many machines to request repeated tunneling (Ctrl-H) and on the Macintosh to request "Control-Caret".

Note that "backslash" is treated specially, and is used to bypass any keymap entry for the following character. This is useful for macros.

References keypress::code, EVENT_EMPTY, EVT_BUTTON, EVT_KBRD, get_com(), get_com_ex(), inkey_ex(), inkey_flag, ui_event::key, keymap_find(), KEYMAP_MODE_ORIG, KEYMAP_MODE_ROGUE, KEYPRESS_NULL, KTRL, move_cursor_relative(), msg_flag, NULL, OPT, prt(), player::px, player::py, request_command_buffer, Term_set_cursor(), textui_get_count(), type, ui_event::type, and void().

Referenced by textui_process_command().

static int textui_get_count ( void  )
static

Get a command count, with the '0' key.

References bell(), keypress::code, D2I, ESCAPE, format(), inkey(), KC_BACKSPACE, KC_DELETE, KC_ENTER, keypress::mods, prt(), and Term_keypress().

Referenced by textui_get_command().

int textui_get_quantity ( const char *  prompt,
int  max 
)

Request a "quantity" from the user.

References get_string(), and strnfmt().

Referenced by textui_input_init().

bool textui_get_rep_dir ( int dp,
bool  allow_5 
)

Request a "movement" direction (1,2,3,4,6,7,8,9) from the user.

Return true if a direction was chosen, otherwise return false.

This function should be used for all "repeatable" commands, such as run, walk, open, close, bash, disarm, spike, tunnel, etc, as well as all commands which must reference a grid adjacent to the player, and which may not reference the grid under the player.

Directions "5" and "0" are illegal and will not be accepted.

This function tracks and uses the "global direction", and uses that as the "desired direction", if it is set.

References bell(), mouseclick::button, keypress::code, ESCAPE, EVENT_MESSAGE_FLUSH, event_signal(), EVT_KBRD, EVT_MOUSE, EVT_NONE, inkey_ex(), inkey_scan, ui_event::key, KEY_GRID_X, KEY_GRID_Y, player_options::lazymove_delay, loc(), ui_event::mouse, player::opts, pathfind_direction_to(), prt(), player::px, player::py, SCAN_INSTANT, SCAN_OFF, target_dir(), target_dir_allow(), and ui_event::type.

Referenced by textui_input_init().

bool textui_get_string ( const char *  prompt,
char *  buf,
size_t  len 
)

Prompt for a string from the user.

The "prompt" should take the form "Prompt: ".

See "askfor_aux" for some notes about "buf" and "len", and about the return value of this function.

References askfor_aux(), EVENT_MESSAGE_FLUSH, event_signal(), NULL, and prt().

Referenced by textui_input_init().

void textui_input_init ( void  )
bool textui_process_key ( struct keypress  kp,
unsigned char *  c,
int  count 
)

Process a textui keypress.

References keypress::code, and ESCAPE.

Referenced by textui_process_command().

Variable Documentation

int dir_transitions[10][10]
static
Initial value:
=
{
{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 },
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
{ 0, 0, 2, 0, 1, 0, 3, 0, 5, 0 },
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
{ 0, 0, 1, 0, 4, 0, 5, 0, 7, 0 },
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
{ 0, 0, 3, 0, 5, 0, 6, 0, 9, 0 },
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
{ 0, 0, 5, 0, 7, 0, 9, 0, 8, 0 },
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
}
bool(* get_file)(const char *suggested_name, char *path, size_t len) = get_file_text

Get a pathname to save a file to, given the suggested name.

Returns the result in "path".

Referenced by death_file(), do_cmd_change_name(), and do_cmd_save_screen_html().

bool inkey_flag

Referenced by inkey_ex(), and textui_get_command().

struct keypress* inkey_next = NULL

Mega-Hack – special "inkey_next" pointer.

XXX XXX XXX

This special pointer allows a sequence of keys to be "inserted" into the stream of keys returned by "inkey()". This key sequence cannot be bypassed by the Borg. We use it to implement keymaps.

u32b inkey_scan
bool inkey_xtra
static

Referenced by flush(), and inkey_ex().

bool keymap_auto_more
static

See if more propmts will be skipped while in a keymap.

Referenced by inkey_ex(), and msg_flush().

int message_column = 0
static

Referenced by display_message(), and message_flush().

bool msg_flag
struct keypress request_command_buffer[256]
static

Hack – special buffer to hold the action of the current keymap.

Referenced by textui_get_command().