ConfigBuilder
Makes it possible to construct a config menu in a fairly human readable manner.
Description
The ConfigBuilder is used to create mod configs. It is supposed to provide an intuitive and human readable api for doing so. To achieve this, it relies on method chaining so the code for setting up a config may look structurally similar to the resulting config file. The following general types of methods are provided:
- Scene tree navigation (enter ( ) and exit ( ))
- Node attachment and creation (e.g. add_node ( Control node, bool legible_unique_name = false ))
- Node configuration (e.g. size_expand_fill ( ) and with ( String property, value ))
- Node referencing (see ref ( String reference_name ))
A ConfigBuilder is obtained by creating a mod config using the ModConfigApi:
var mod_id: String = "CreepyCre.ExampleMod"
var config_title: String = "Example Mod Config"
var config_file: String = self.Global.Root + "config.json"
var builder = self.Global.API.ModConfigApi.create_config(mod_id, config_title, config_file)
Control nodes may then be created and appended to the config screen using their appropriate methods. The config can be built at the end using
build ( bool should_load = true, bool should_free = true ):
# multiline method chaining does not allow comments inbetween
var config = builder\
.label("Hello World!")\
.check_button("key1", true, "This is a check Button!")\
.build()
\ at the end of a line allows for method chaining across multiple lines. Config nodes such as the CheckButton created throughcheck_button ( String save_entry, bool default_value, String text = "" )
take a save_entry and default_value as parameters. The save_entry is the key the setting will be saved under in the config file.
For appending nodes as children of other nodes enter ( ) and exit ( ) allow hopping into and out of nodes:
builder\
.v_box_container().enter()\
.h_box_container().enter()\
.label("Hello World!")\
.exit()\
.exit()
Also mind the optional save_entry parameter available for container type node creation. Supplying save_entry will create sub categories for all contained config nodes. For example:
var config = builder\
.h_box_container("category").enter()\
.check_button("key1", true, "Hello")\
.check_box("key2", true, "World")\
.exit()\
.line_edit("key3", "This is the default text.")\
.build()
Will result in the following config:
Config values may then be accessed and modified through the ConfigAgent returned when building the config:
For styling the nodes there are some shorthand methods available like
size_flags_h ( int flags ) or rect_min_size ( Vector2 min_size ).
For accessing properties and methods that do not have shorthand equivalents use
with ( String property, value ) and call_on ( String method_name, args... ) which both perform actions on the last node created. with directly sets the given property to value while call_on forwards its parameters to Object#call:
# hidden spin box. idk why you'd want this, it's just an example
builder.spin_box("key", 70)\
.with("suffix","dpi")\
.call_on("hide")
For connecting node signals use connect_current and connect_to_prop. While connect_current forwards its parameters to connect, connect_to_prop actually forwards the signal to a utility methods that always updates the property property of target with the emitted value.
How would you handle connecting different config nodes signals together? To avoid having to keep references to nodes which would interrupt code flow use ref ( String reference_name ). It assigns the key reference_name to the last node so it may later be retrieved using get_ref ( String reference_name ) or be called on using
call_on_ref ( String reference_name, String method_name, args... ),
connect_ref ( String reference_name, String signal_name, Object target, String method_name, Array binds = [], int flags = 0 ) and
connect_ref_to_prop ( String reference_name, String signal_name, target, String property ). E.g.:
builder\
.label().ref("slider_label")\
.h_slider("key", 42).size_flags_h(Control.SIZE_EXPAND_FILL)\
.connect_to_prop("loaded", builder.get_ref("slider_label"), "text")\
.connect_to_prop("value_changed", builder.get_ref("slider_label"), "text")\
loaded and value_changed signals to make it display the current slider value.
Methods
Method Descriptions
ConfigBuilder enter ( ):
Enters the last Control appended so new nodes will be created as its children.
ConfigBuilder exit ( ):
Exits the node previously entered.
ConfigBuilder add_node ( Control node, bool legible_unique_name = false ):
Adds node as child of the node currently entered.
ConfigBuilder add_node_direct ( Control node, bool legible_unique_name = false ):
Directly adds node as child of the node currently entered bypassing the get_target() call.
ConfigBuilder with ( String property, value ):
Sets the property property to value on the most recent node.
ConfigBuilder size_flags_h ( int flags ):
Sets the property Control#size_flags_horizontal to flags on the most recent node.
ConfigBuilder size_flags_v ( int flags ):
Sets the property Control#size_flags_vertical to flags on the most recent node.
ConfigBuilder size_expand_fill ( ):
Shorthand for:
ConfigBuilder rect_min_size ( Vector2 min_size ):
Sets the property Control#rect_min_size to min_size on the most recent node.
ConfigBuilder rect_min_x ( float min_x ):
Shorthand for:
ConfigBuilder rect_min_y ( float min_y ):
Shorthand for:
ConfigBuilder rect_size ( Vector2 size ):
Sets the property Control#rect_size to size on the most recent node.
ConfigBuilder rect_x ( float x ):
Shorthand for:
ConfigBuilder rect_y ( float y ):
Shorthand for:
ConfigBuilder flatten ( bool value = true ):
Calls flatten(value) on the most recent node. Setting value to true will make the most recent node flatten its child config entries into its parent node.
Control get_current ( ):
Returns the most recent node.
ConfigBuilder ref ( String reference_name ):
Gives the most recent node the identifier reference_name so it can be retrieved later using get_ref ( String reference_name )
Control get_ref ( String reference_name ):
Returns the node with identifier reference_name.
ConfigBuilder call_on ( String method_name, args... ):
Calls method method_name with arguments args on the most recent node.
ConfigBuilder call_on_ref ( String reference_name, String method_name, args... ):
Calls method method_name with arguments args on node with identifier reference_name.
ConfigBuilder connect_current ( String signal_name, Object target, String method_name, Array binds = [], int flags = 0 ):
Calls Object#connect on the most recent node using identical paramters.
ConfigBuilder connect_ref ( String reference_name, String signal_name, Object target, String method_name, Array binds = [], int flags = 0 ):
Calls Object#connect on the node with identifier reference_name using identical paramters besides reference_name.
ConfigBuilder connect_to_prop ( String signal_name, target, String property ):
Connects the signal signal_name from the most recent node such that the emitted value is applied to property :parameter:property in :parameter:target.
ConfigBuilder connect_ref_to_prop ( String reference_name, String signal_name, target, String property ):
Connects the signal signal_name from the node with identifier reference_name such that the emitted value is applied to property :parameter:property in :parameter:target.
ConfigBuilder add_color_override ( String name, Color color ):
Forwards call to Control#add_color_override on the most recent node.
ConfigBuilder add_constant_override ( String name, int constant ):
Forwards call to Control#add_constant_override on the most recent node.
ConfigBuilder add_font_override ( String name, Font font ):
Forwards call to Control#add_font_override on the most recent node.
ConfigBuilder add_icon_override ( String name, Texture texture ):
Forwards call to Control#add_icon_override on the most recent node.
ConfigBuilder add_shader_override ( String name, Shader shader ):
Forwards call to Control#add_shader_override on the most recent node.
ConfigBuilder add_stylebox_override ( String name, StyleBox stylebox ):
Forwards call to Control#add_stylebox_override on the most recent node.
ConfigBuilder wrap ( String save_entry, Control root_node, target_node = null ):
Wraps a scene in a WrappedControlConfigNode where root_node is the scene root and target_node is where new child nodes will be appended by the ConfigBuilder. The wrapped scenes config nodes will be saved into the category save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder extend ( String save_entry, Control node ):
Appends node as a child of the currently entered node and gives it config node capabilities by settings its script to ContainerExtensionConfigNode.
:
Appends a CheckButton config node with config key save_entry, default value default_value and text text.
ConfigBuilder check_box ( String save_entry, bool default_value, String text = "" ):
Appends a CheckBox config node with config key save_entry, default value default_value and text text.
ConfigBuilder h_slider ( String save_entry, float default_value ):
Appends an HSlider config node with config key save_entry and default value default_value.
ConfigBuilder v_slider ( String save_entry, float default_value ):
Appends a VSlider config node with config key save_entry and default value default_value.
ConfigBuilder spin_box ( String save_entry, float default_value ):
Appends a SpinBox config node with config key save_entry and default value default_value.
ConfigBuilder color_picker ( String save_entry, Color default_value ):
Appends a ColorPicker config node with config key save_entry and default value default_value.
:
Appends a ColorPickerButton config node with config key save_entry and default value default_value.
:
Appends an OptionButton config node with config key save_entry, default value default_value and options options. The entries of options can either be Strings for a plain labelled option or dictionaries with possible entries "label", "icon" and "meta". Accessing the config value from the ConfigAgent will return the selected options meta if available or its label. The selected option can be changed through the ConfigAgent by setting it to either its index or its label:
agent.some_option_button = 2 # this works
agent.some_option_button = "label goes here" # this also works
ConfigBuilder line_edit ( String save_entry, String default_value, bool require_hit_enter = true ):
Appends a LineEdit config node with config key save_entry and default value default_value. require_hit_enter configures whether the Enter key must be hit to update the config value.
ConfigBuilder text_edit ( String save_entry, String default_value ):
Appends a TextEdit config node with config key save_entry and default value default_value.
ConfigBuilder shortcuts ( String save_entry, Dictionary definitions ):
Appends a Tree config node with config key save_entry that contains shortcuts defined via definitions. definitions has to be structured equivalent to actions in InputMapApi#define_actions, though any default shortcuts will be ignored here.
ConfigBuilder aspect_ratio_container ( String save_entry = "" ):
Appends an AspectRatioContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder center_container ( String save_entry = "" ):
Appends a CenterContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder h_box_container ( String save_entry = "" ):
Appends a HBoxContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder v_box_container ( String save_entry = "" ):
Appends a VBoxContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder grid_container ( String save_entry = "" ):
Appends a GridContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder h_split_container ( String save_entry = "" ):
Appends an HSplitContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder v_split_container ( String save_entry = "" ):
Appends a VSplitContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder margin_container ( String save_entry = "" ):
Appends a MarginContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder panel_container ( String save_entry = "" ):
Appends a PanelContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder scroll_container ( String save_entry = "" ):
Appends a ScrollContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder tab_container ( String save_entry = "" ):
Appends a TabContainer with config key save_entry. Setting save_entry to "" flattens the node.
ConfigBuilder color_rect ( Color color ):
Appends a ColorRect with color as its color.
ConfigBuilder h_separator ( ):
Appends an HSeparator.
ConfigBuilder v_separator ( ):
Appends a VSeparator.
ConfigBuilder label ( String text = "" ):
Appends a Label with text text.
ConfigBuilder nine_patch_rect ( ):
Appends a NinePatchRect.
ConfigBuilder panel ( ):
Appends a Panel.
ConfigBuilder reference_rect ( ):
Appends a ReferenceRect.
ConfigBuilder rich_text_label ( String bbcode_text = "" ):
Appends a bbcode enabled RichTextLabel with bbcode_text as its bbcode_text.
ConfigBuilder texture_rect ( Texture texture ):
Appends a TextureRect with texture texture.
ConfigAgent build ( bool should_load = true, bool should_free = true ):
Builds the config panel and returns the ConfigAgent. If should_load is set to true the config will be loaded upon building it. If should_free is set to true the ConfigBuilder will be freed after the config has been built.
ConfigAgent get_agent ( ):
Returns the ConfigAgent