Dependencies:
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.
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.
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