# lib_ui function library

Dependencies:

## Description

Functions to patch the Enhanced-Edition user interface.

These functions mostly work like this. An object in the current file (normally ui.menu, but sometimes a ui object extracted from ui.menu) is located by (i) the object type (e.g., 'menu'), a field in the object used to identify it (e.g., 'name' - this is the default value), and a value of that field (e.g., 'CHARGEN_CLASS'). The function then goes through the UI until it finds the (hopefully unique) object matching that description. The object is pulled out of ui.menu and patched; then it's substituted back in.

Technically this library depends on lib_anon (since it permits anonymous functions) and lib_sfo (since it uses sfo_path) but if you don't use either feature, it's self-contained.

For legacy reasons, the naming convention here uses UI_ rather than ui_ as a function prefix.

## Public functions

UI_add_function(function:s, location:s, locbase:s, path:s)=() patch

Adds the contents of the file 'function' (optionally located at the SFO location given by location/locbase/path) immediately before the first function definition in the current file. (Use to add functions to UI.menu - but 99% of the time it's better to define them in your own custom lua file.)

UI_add_string(tra_entry:i, string_id:s, string:s)=() action

Add a string to the lua string file appropriate for the current game language (e.g., L_EN_US.lua if you're playing in English). 'string_id' is the lua string ID for the string; you can specify the string either via the INT_VAR tra_entry (an entry in your current .tra file) or directly as the STR_VAR 'string'.)

UI_add_string_array(array:a)=() dimorphic

Given a k=>v array 'array' with entries like MY_TEXT_STRING=>1234, go through each entry, and for each, get the string with tra ref 1234 in the current tra file and set TEXT_STRING equal to it in the current EE language file (e.g., l_en_us.lua).

Exits with a warning if not on EE.

UI_alter_function(function:s, patch:f)=() patch

Find the lua function 'function' in the current file. Extract it, apply the patch function 'patch' to it (you can use the anonymous function construct) and put it back.

Note that the heuristic used to find the function is fairly crude: it assumes that the function finishes at the first 'end' that starts a new line. (This matches most, but not quite all, functions in ui.menu.)

UI_alter_object(silent:i, object:s, object_type:s, object_name_field:s="name", patch:f)=() patch

Apply the patch function 'patch' to the matched ui object in the current file, and substitute the result back in. You can use the anonymous function construct.

UI_analyze_object(object:s, object_type:s, object_name_field:s="name", patch:f)=(patch_output:a) patch

Apply the patch function 'patch' to the matched ui object in the current file. 'patch' should return an array called 'patch_output, which is in turn returned by UI_analyze object return 'patch_output' The actual result of the patch is discarded (i.e., the file being patched isn't changed), so the purpose of this is to extract information from ui.menu. You can use the anonymous function construct.

UI_get_coordinates()=(patch_output:a) patch

Look through the current file for the coordinates of an object (specified by four integers separated by spaces) and/or a bam file (specified by 'BAM [whatever]'). Return them in an array with keys bam, xloc, yloc, width, height. (Use in conjuction with UI_analyze_object).

UI_insert_into_object(object:s, object_type:s, object_name_field:s="name", insert:s, insert_data:s, path:s, location:s, locbase:s)=() patch

Insert the contents of the file 'insert' (optionally located at the location picked out by path/location/locbase in usual SFO fashion) at the end of the matched ui object in the current file. Alternately, insert the string 'insert_data' in this way.

UI_install_function(inline:b, lua_file:s, new_function:s, new_function_path:s, location:s, locbase:s, path:s, search_string:s)=() action

Add the contents of the file at 'new_function' (legacy synonym: new_function_path), optionally located at the location specified SFO-style by location/locbase/path (or inline if inline=1), to the end of the in-game lua file 'lua_file', creating it if necessary. If 'search_string' is set, only add the function if that string is not present in the lua already.

UI_remove_function(function:s)=() patch

Find the lua function 'function' in the current file. Remove it.

Note that the heuristic used to find the function is fairly crude: it assumes that the function finishes at the first 'end' that starts a new line. (This matches most, but not quite all, functions in ui.menu.)

UI_replace_function(inline:b, function:s, new_function:s, new_function_path:s, location:s, locbase:s, path:s)=() patch

Find the lua function 'function' in the current file. Replace it with the contents of the file at 'new_function' (legacy synonym: new_function_path), optionally located at the location specified SFO-style by location/locbase/path (or inline if inline=1.

Note that the heuristic used to find the function is fairly crude: it assumes that the function finishes at the first 'end' that starts a new line. (This matches most, but not quite all, functions in ui.menu.)

UI_replace_object(object:s, object_type:s, object_name_field:s="name", replace:s, path:s, location:s, locbase:s)=() patch

Replace the matched ui object in the current file with the contents of the file 'replace' (optionally located at the location picked out by path/location/locbase in usual SFO fashion).

UI_return_object(object:s, object_type:s, object_name_field:s="name", patch:f)=(object_data:s) patch

Apply the patch function 'patch' to the matched ui object in the current file, and then return that object, as the value of a string variable.

## Internal functions

These should not be called from outside the library itself.

find_parenthesis_range_localcopy(left:s="{", right:s="}", index:s=0)=(start:s, end:s) patch

UI_patch_object_master(silent:i, object:s, object_type:s, object_name_field:s="name", patch:s, type:s, insert_data:s)=(object_data:s, patch_output:a) patch