/----------------------------------------\
            <      util.pkg functions helper file      >
             \----------------------------------------/

----------------------------------------------------------------------

=== bst ===

Declaration
    s32b bst(s32b what, s32b t);

File
    util.c

Comment
/*
 * Break scalar time
 */

Description
Return the minute, hour, day, or year for turn "t". One turn takes 7.5
seconds.

Parameters
> "what" is the unit to be returned and must be one of
  MINUTE (number of turns per minute, which is 8)
  HOUR   (number of turns per hour, which is 480)
  DAY    (number of turns per day, which is 11,520)
  YEAR   (number of turns per year, which is 4,204,800)
> "t" is the number of turns.

----------------------------------------------------------------------

=== path_build ===

Declaration
    errr path_build(char *buf, int max, cptr path, cptr file);

File
    util.c

Comment
/*
* Create a new path by appending a file (or directory) to a path
*
* This requires no special processing on simple machines, except
* for verifying the size of the filename, but note the ability to
* bypass the given "path" with certain special file-names.
*
* Note that the "file" may actually be a "sub-path", including
* a path and a file.
*
* Note that this function yields a path which must be "parsed"
* using the "parse" function above.
*/

Description
Append file "file" to path "path" and return the result in "buf". The
length of "buf" is a maximum of "max" characters. If "file" starts
with '~' then return "file". If "file" starts with the path separator
and the path separator is not blank then return "file". If there is no
path then return "file". Otherwise return "path" + path separator +
"file". The path separator is defined in "H-config.h".

Parameters
> "buf" contains the new path.
> "max" is the maximum number of characters allowed in "buf".
> "path" is the original path.
> "file" is the original file.

----------------------------------------------------------------------

=== move_cursor ===

Declaration
    void move_cursor(int row, int col);

File
    util.c

Comment
/*
* Move the cursor
*/

Description
Move the cursor to row "row" and column "col".

Parameters
> "row" is the row the cursor is to be moved to.
> "col" is the column the cursor is to be moved to.

----------------------------------------------------------------------

=== inkey ===

Declaration
    char inkey(void);

File
    util.c

Comment
/*
* Get a keypress from the user.
*
* This function recognises 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,
* and any macro processing in progress will be aborted.  This flag is
* set by the "flush()" function, which does not actually flush anything
* itself, but rather, triggers delayed input flushing via "inkey_xtra".
*
* If "inkey_scan" is TRUE, then we will immediately return "zero" if no
* keypress is available, instead of waiting for a keypress.
*
* If "inkey_base" is TRUE, then all macro processing will be bypassed.
* If "inkey_base" and "inkey_scan" are both TRUE, then this function will
* not return immediately, but will wait for a keypress for as long as the
* normal macro matching code would, allowing the direct entry of macro
* triggers.  The "inkey_base" flag is extremely dangerous!
*
* If "inkey_flag" is TRUE, then we will assume that we are waiting for a
* normal command, and we will only show the cursor if "hilite_player" is
* TRUE (or if the player is in a store), instead of always showing the
* cursor.  The various "main-xxx.c" files should avoid saving the game
* in response to a "menu item" request unless "inkey_flag" is TRUE, to
* prevent savefile corruption.
*
* 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.  This is done after the
* macro matching, so the user can still make a macro for "backquote".
*
* Note the special handling of "ascii 30" (ctrl-caret, aka ctrl-shift-six)
* and "ascii 31" (ctrl-underscore, aka ctrl-shift-minus), which are used to
* provide support for simple keyboard "macros".  These keys are so strange
* that their loss as normal keys will probably be noticed by nobody.  The
* "ascii 30" key is used to indicate the "end" of a macro action, which
* allows recursive macros to be avoided.  The "ascii 31" key is used by
* some of the "main-xxx.c" files to introduce macro trigger sequences.
*
* Hack -- we use "ascii 29" (ctrl-right-bracket) as a special "magic" key,
* which can be used to give a variety of "sub-commands" which can be used
* any time.  These sub-commands could include commands to take a picture of
* the current screen, to start/stop recording a macro action, etc.
*
* 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.
*
* Hack -- Note the use of "inkey_next" to allow "keymaps" to be processed.
*
* Mega-Hack -- Note the use of "inkey_hack" to allow the "Borg" to steal
* control of the keyboard from the user.
*/

Description
Get a keypress from the user.

----------------------------------------------------------------------

=== cmsg_print ===

Declaration
    void cmsg_print(byte color, cptr msg);

File
    util.c

Comment
/*
* 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 memorised for later reference (see above).
*
* We could do "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.
*
* XXX XXX XXX Note that we must be very careful about using the
* "msg_print()" functions without explicitly calling the special
* "msg_print(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.
*
* XXX XXX XXX Note that "msg_print(NULL)" will clear the top line
* even if no messages are pending.  This is probably a hack.
*/

Description
In color "color", output message "msg" to the top line of the screen.
If the message is blank or has more than 1000 characters, nothing is
printed. Long messages are split after the 40th character and before
the 72nd character.

Parameters
> "color" is the color of the message.
  colors
> "msg" is the message.

----------------------------------------------------------------------

=== msg_print ===

Declaration
    void msg_print(cptr msg);

File
    util.c

Comment
/* Hack -- for compatibility and easy sake */

Description
Print message "msg" in white (see cmsg_print() above).

Parameters
> "msg" is the message.

----------------------------------------------------------------------

=== screen_save ===

Declaration
    void screen_save(void);

File
    util.c

Comment
/*
 * Save the screen, and increase the "icky" depth.
 *
 * This function must match exactly one call to "screen_load()".
 */

Description
Save a screen shot.

----------------------------------------------------------------------

=== screen_load ===

Declaration
    void screen_load(void);

File
    util.c

Comment
/*
 * Load the screen, and decrease the "icky" depth.
 *
 * This function must match exactly one call to "screen_save()".
 */

Description
Load a previously saved screen shot.

----------------------------------------------------------------------

=== c_put_str ===

Declaration
    void c_put_str(byte attr, cptr str, int row, int col);

File
    util.c

Comment
/*
* Display a string on the screen using an attribute.
*
* At the given location, using the given attribute, if allowed,
* add the given string.  Do not clear the line.
*/

Description
Put string "str" at row "row" and column "col" with attribute "attr".

Parameters
> "attr" is the color of the message.
  colors
> "msg" is the message.
> "row" is the row the message is to be printed at.
> "col" is the column the message is to be printed at.

----------------------------------------------------------------------

=== c_prt ===

Declaration
    void c_prt(byte attr, cptr str, int row, int col);

File
    util.c

Comment
/*
* Display a string on the screen using an attribute, and clear
* to the end of the line.
*/

Description
Clear row "row" from column "col". Put string "str" at "row", "col"
with attribute "attr".

Parameters
> "attr" is the color of the message.
  colors
> "msg" is the message.
> "row" is the row the message is to be printed at.
> "col" is the column the message is to be printed at.

----------------------------------------------------------------------

=== clear_from ===

Declaration
    void clear_from(int row);

File
    util.c

Comment
/*
* Clear part of the screen
*/

Description
Clear the screen from row "row" onwards.

Parameters
> "row" is the first row of the screen to be cleared.

----------------------------------------------------------------------

=== askfor_aux ===

Declaration
    bool askfor_aux(char *buf, int len);

File
    util.c

Comment
/*
* Get some input at the cursor location.
* Assume the buffer is initialized to a default string.
* Note that this string is often "empty" (see below).
* The default buffer is displayed in yellow until cleared.
* Pressing RETURN right away accepts the default entry.
* Normal chars clear the default and append the char.
* Backspace clears the default or deletes the final char.
* ESCAPE clears the buffer and the window and returns FALSE.
* RETURN accepts the current buffer contents and returns TRUE.
*/

Description
Get string "buf" from the screen. "buf" is to be no more than "len"
bytes. The string starts at the current cursor position. The length
can not exceed the number of bytes from the cursor to the end of the
line. Accept user input until the escape or return key is pressed.

Parameters
> "buf" is the string returned from the screen.
> "len" is the length of the string. If it is <1 it is forced to 1.

----------------------------------------------------------------------

=== get_string ===

Declaration
    bool get_string(cptr prompt, char *buf, int len);

File
    util.c

Comment
/*
* Get a string from the user
*
* The "prompt" should take the form "Prompt: "
*
* Note that the initial contents of the string is used as
* the default response, so be sure to "clear" it if needed.
*
* We clear the input, and return FALSE, on "ESCAPE".
*/

Description
Print prompt "prompt" at the top-left corner of the screen and return
response "buf" which will have a maximum length "length". If ESCAPE
is entered, the function returns FALSE, otherwise it returns TRUE.

Parameters
> "prompt" is the prompt for input.
> "buf" is the returned response.
> "len" is the maximum length of the string.

----------------------------------------------------------------------

=== get_check ===

Declaration
    bool get_check(cptr prompt);

File
    util.c

Comment
/*
* Verify something with the user
*
* The "prompt" should take the form "Query? "
*
* Note that "[y/n]" is appended to the prompt.
*/

Description
Ask the user question "prompt" which requires a yes/no answer. The
prompt appears in the top-left corner of the screen. A response of
'Y' (either case) returns TRUE. A response of 'N' (either case) or
ESCAPE returns FALSE.

Parameters
> "prompt" is the question asked. It has a maximum length of 70
  characters.

----------------------------------------------------------------------

=== get_com_lua ===

Declaration
    bool get_com_lua @ get_com(cptr promtp, int *com);

File
    util.c

Comment
/*
* Prompts for a keypress
*
* The "prompt" should take the form "Command: "
*
* Returns TRUE unless the character is "Escape"
*/

Description
Ask the user for command "prompt" and return the key press "com". A
response of ESCAPE returns FALSE. All other responses return TRUE.

Parameters
> "prompt" is the prompt for the key press.
> "com" is the returned key press.

----------------------------------------------------------------------

=== get_quantity ===

Declaration
    s32b get_quantity(cptr prompt, s32b max);

File
    util.c

Comment
/*
* Request a "quantity" from the user
*
* Hack -- allow "command_arg" to specify a quantity
*/

Description
Ask the user for quantity "prompt" of maximum value "max" and return
a quantity. If the user quantity is higher than the maximum then the
maximum is returned. If the response is a letter then the maximum is
returned. If the user quantity is negative then zero is returned.

Parameters
> "prompt" is the prompt for a quantity.
> "max" is the maximum value allowed.

----------------------------------------------------------------------

=== test_monster_name ===

Declaration
    int test_monster_name(cptr name);

File
    util.c

Comment
/*
 * Given monster name as string, return the index in r_info array. Name
 * must exactly match (look out for commas and the like!), or else 0 is 
 * returned. Case doesn't matter. -GSN-
 */

Description
Return the monster index for monster with name "name". If no match is
found then zero is returned.

Parameters
> "name" is the monster name.

----------------------------------------------------------------------

=== test_item_name ===

Declaration
    int test_item_name(cptr name);

File
    util.c

Comment
/*
 * Given item name as string, return the index in k_info array. Name
 * must exactly match (look out for commas and the like!), or else 0 is 
 * returned. Case doesn't matter. -DG-
 */

Description
Return the item index for item with name "name". If no match is found
then zero is returned.

Parameters
> "name" is the item name.

----------------------------------------------------------------------

=== luck ===

Declaration
    int luck(int min, int max);

File
    xtra1.c

Comment
/*
 * Return a luck number between a certain range
 */

Description
Return a number for luck between minimum "min" and maximum "max". The
value begins with the player's current luck. The value is forced to
be between -30 and +30. 30 is added to give a value between 0 and 60.
The value is multiplied by the range (maximum - minimum) and divided
by 60. The value is increased by the minimum. The value is returned.

For example, if the player's current luck is 15, the minimum is -10,
and the maximum is 10 (range 20), then the value returned is
(45 * 20) / 60 which is 900 / 60 which is 15 + the minimum -10 gives
a returned value of 5.

Parameters
> "min" is the minimum luck.
> "max" is the maximum luck. Beware: this should be greater than the
  minimum but it is not checked!

----------------------------------------------------------------------

=== get_player_race_name ===

Declaration
    cptr get_player_race_name(int pr, int ps);

File
    util.c

Comment
(none)

Description
Return the name for player race "pr" and player sub-race "ps".

Parameters
> "pr" is the index for player race.
> "ps" is the index for player sub-race.

----------------------------------------------------------------------

=== quit ===

Declaration
    void quit(cptr str);

File
    z-util.c

Comment
/*
 * Exit (ala "exit()").  If 'str' is NULL, do "exit(0)".
 * If 'str' begins with "+" or "-", do "exit(atoi(str))".
 * Otherwise, plog() 'str' and exit with an error code of -1.
 * But always use 'quit_aux', if set, before anything else.
 */

Description
Quit the game. If "str" is a string then write the string to the
error file or screen. If "str" is a number then exit with the
number as the exit code.

Parameters
> "str" is an error message or exit code.

----------------------------------------------------------------------

=== dump_hooks ===

Declaration
    void dump_hooks();

File
    plots.c

Comment
(none)

Description
Print the name and type (C or Lua) of hooks in the hook list.

----------------------------------------------------------------------

=== add_hook_script ===

Declaration
    void add_hook_script(int h_idx, char *script, cptr name);

File
    plots.c

Comment
(none)

Description
To hook list with index "h_idx", add a script with script file
"script" and name "name" as a Lua hook if a hook with that name
does not already exist.

Parameters
> "h_idx" is the index of the hook list in the array of hook lists.
> "script" is the name of the script file.
> "name" is the name of the hook to be added.

----------------------------------------------------------------------

=== del_hook_name ===

Declaration
    void del_hook_name(int h_idx, cptr name);

File
    plots.c

Comment
(none)

Description
Search hook list with index "h_idx" and remove the hook with name
"name".

Parameters
> "h_idx" is the index of the hook list in the array of hook lists.
> "name" is the name of the hook to be removed.

----------------------------------------------------------------------

=== pern_dofile ===

Declaration
    bool pern_dofile(char *file);

File
    script.c

Comment
(none)

Description
Parse the Lua script file "file".

Parameters
> "file" is the Lua script file to be parsed.

----------------------------------------------------------------------

=== intMod ===

Declaration
    s32b intMod(s32b a, s32b b);

File
    script.c

Comment
(none)

Description
Return the result of operation "a" mod  "b" (a % b).

Parameters
> "a" is a number.
> "b" is a number.

----------------------------------------------------------------------

=== intAnd ===

Declaration
    s32b intAnd(s32b a, s32b b);

File
    script.c

Comment
(none)

Description
Return the result of bitwise operation "a" AND "b" (a & b).

Parameters
> "a" is a number.
> "b" is a number.

----------------------------------------------------------------------

=== intOr ===

Declaration
    s32b intOr(s32b a, s32b b);

File
    script.c

Comment
(none)

Description
Return the result of bitwise operation "a" OR "b" (a | b).

Parameters
> "a" is a number.
> "b" is a number.

----------------------------------------------------------------------

=== intXor ===

Declaration
    s32b intXor(s32b a, s32b b);

File
    script.c

Comment
(none)

Description
Return the result of bitwise operation "a" XOR "b" (a ^ b).

Parameters
> "a" is a number.
> "b" is a number.

----------------------------------------------------------------------

=== intShiftl ===

Declaration
    s32b intShiftl(s32b a, s32b b);

File
    script.c

Comment
(none)

Description
Return the result of bitwise operation "a" << "b".

Parameters
> "a" is a number.
> "b" is a number.

----------------------------------------------------------------------

=== intShiftr ===

Declaration
    s32b intShiftr(s32b a, s32b b);

File
    script.c

Comment
(none)

Description
Return the result of bitwise operation "a" >> "b".

Parameters
> "a" is a number.
> "b" is a number.

----------------------------------------------------------------------

=== intBitNot ===

Declaration
    s32b intBitNot(s32b b);

File
    script.c

Comment
(none)

Description
Return the result of bitwise operation NOT "b" (~ b).

Parameters
> "b" is a number.

----------------------------------------------------------------------

=== register_savefile ===

Declaration
    void register_savefile(int num);

File
    loadsave.c

Comment
/*
 * Add num slots to the savefile
 */

Description
Add "num" slots to the save file.

Parameters
> "num" is the number of slots to add to the savefile. If num is <0
  then "num" is forced to zero.

----------------------------------------------------------------------

=== save_number_key ===

Declaration
    void save_number_key(char *key, s32b val);

File
    util.c

Comment
(none)

Description
Save the length of key "key", the key itself, and the value "val" as
bytes in the savefile.

Parameters
> "key" is the key string for the value.
> "val" is the value to be saved.

----------------------------------------------------------------------



Back to the lua help index .


                                                     This file by Chris Hadgis