Angband
Data Structures | Macros | Functions | Variables
ui-input.h File Reference

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

#include "cmd-core.h"
#include "game-event.h"
#include "ui-event.h"
#include "ui-term.h"

Go to the source code of this file.

Data Structures

struct  cmd_info
 Holds a generic command - if cmd is set to other than CMD_NULL it simply pushes that command to the game, otherwise the hook function will be called. More...
 
struct  command_list
 A categorised list of all the command lists. More...
 

Macros

#define SCAN_INSTANT   ((u32b) -1)
 
#define SCAN_OFF   0
 

Functions

void flush (game_event_type unused, game_event_data *data, void *user)
 Flush all pending input. 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...
 
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...
 
bool get_character_name (char *buf, size_t buflen)
 Gets a name for the character, reacting to name changes. More...
 
char get_char (const char *prompt, const char *options, size_t len, char fallback)
 Ask the user to respond with a character. More...
 
bool get_com_ex (const char *prompt, ui_event *command)
 
void pause_line (struct term *term)
 Pause for user response. More...
 
void textui_input_init (void)
 Initialise the UI hooks to give input asked for by the game. 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

struct cmd_info cmd_item []
 Here are lists of commands, stored in this format so that they can be easily maniuplated for e.g. More...
 
struct cmd_info cmd_action []
 General actions. More...
 
struct cmd_info cmd_item_manage []
 Item management commands. More...
 
struct cmd_info cmd_info []
 Information access commands. More...
 
struct cmd_info cmd_util []
 Utility/assorted commands. More...
 
struct cmd_info cmd_hidden []
 Commands that shouldn't be shown to the user. More...
 
struct command_list cmds_all []
 List of command lists. More...
 
struct keypressinkey_next
 Mega-Hack – special "inkey_next" pointer. More...
 
u32b inkey_scan
 
bool inkey_flag
 
u16b lazymove_delay
 
bool msg_flag
 Player has pending message. More...
 
bool(* get_file )(const char *suggested_name, char *path, size_t len)
 Get a pathname to save a file to, given the suggested name. 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.

Macro Definition Documentation

#define SCAN_INSTANT   ((u32b) -1)
#define SCAN_OFF   0

Referenced by inkey_aux(), and textui_get_rep_dir().

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 
)
struct keypress inkey ( void  )
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().

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().

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().

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

struct cmd_info cmd_action[]

General actions.

struct cmd_info cmd_hidden[]

Commands that shouldn't be shown to the user.

struct cmd_info cmd_info[]

Information access commands.

struct cmd_info cmd_item[]

Here are lists of commands, stored in this format so that they can be easily maniuplated for e.g.

help displays, or if a port wants to provide a native menu containing a command list.

Consider a two-paned layout for the command menus. XXX Item commands

struct cmd_info cmd_item_manage[]

Item management commands.

struct cmd_info cmd_util[]

Utility/assorted commands.

struct command_list cmds_all[]
bool(* get_file)(const char *suggested_name, char *path, size_t len)

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

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
u16b lazymove_delay
bool msg_flag