Variables

All required GUI variables should be defined before the GUI is built. This is typically done in the __init__() method of the Application class (in app.py). The standard way to set and get variables is through the gui object’s setvar and getvar methods.

Variable groups

GUI variables are stored in a dict organized into named groups. For simple applications, a single group is often sufficient. For more complex applications it is useful to organize variables into multiple groups, especially when the same variable name is needed for different purposes.

For example, if you use the name x for the x-coordinate of two different map features, define separate groups:

app.gui.setvar("feature1", "x", 1.0)
app.gui.setvar("feature2", "x", 2.0)

Setting variables

Use setvar to store a value:

app.gui.setvar("mygroup", "varname", value)

Alternatively, access the underlying dict directly:

app.gui.variables["mygroup"]["varname"]["value"] = value

When a variable is updated inside a callback, the GUI automatically refreshes to display the new value.

Getting variables

Use getvar to retrieve a value:

value = app.gui.getvar("mygroup", "varname")

Or access the dict directly:

value = app.gui.variables["mygroup"]["varname"]["value"]

Variable types

The type of a variable is inferred automatically from the value passed to setvar. The type determines how the widget displays and validates input:

Python type	Widget behavior
`str`	Edit box shows text; no numeric validation
`int`	Edit box and spinbox enforce integer input and right-align numbers
`float`	Edit box and spinbox enforce float input and right-align numbers
`bool`	Used by checkboxes and dependencies

Linking variables to elements

In the YAML configuration, each interactive element is linked to a variable via the variable and variable_group keys:

- style: edit
  variable: grid_resolution
  variable_group: model
  method: update_grid

When the user edits the value, the new value is written to gui.variables["model"]["grid_resolution"]["value"] and the callback update_grid is called.

The variable_group defaults to the value set in the window section of the config file, so it only needs to be specified when it differs from the window default.

Dynamic labels and tooltips

Labels (text) and tooltips can be either static strings or dynamic — reading from a variable:

text:
  variable: status_message
  variable_group: mygroup

When the variable changes, the label updates automatically on the next GUI refresh.