Callbacks

A callback is a Python function that is called automatically when the user interacts with a GUI element (e.g. edits a value, clicks a button, selects a list item).

Defining callbacks

Callbacks are defined as plain functions in a Python callback module. The module is specified in the YAML config at the window or element level:

window:
  module: callbacks        # default callback module for all elements
  variable_group: myapp

element:
- style: edit
  variable: dx
  method: update_resolution   # calls callbacks.update_resolution

- style: pushbutton
  text: Run
  method: run_model
  module: run_callbacks       # override: calls run_callbacks.run_model

Callback signature

Every callback function receives two arguments:

def my_callback(value, widget):
    ...

value — the current value of the variable linked to the element that triggered the callback. For an edit box this is the entered number or string; for a listbox it is the selected item or index; for a checkbox it is True or False.
widget — the underlying PySide6 widget object. This is rarely needed but can be used for advanced widget manipulation.

Both arguments can be ignored using *args:

def my_callback(*args):
    ...

Reading and writing variables inside a callback

Inside a callback, use app.gui.getvar and app.gui.setvar to read and update variables. After the callback returns, Guitares automatically refreshes all GUI elements to reflect any variable changes:

from app import app

def update_resolution(*args):
    dx = app.gui.getvar("model", "dx")
    dy = app.gui.getvar("model", "dy")
    # ... do something with dx, dy ...
    app.gui.setvar("model", "cell_count", int(domain_area / (dx * dy)))

Callback modules

A callback module is a plain Python file. It is imported once when the GUI is built. The app object should be imported at the top of the module so that variables and GUI methods are accessible:

# callbacks.py
from app import app

def enter_name(value, widget):
    name = app.gui.getvar("hello", "name")
    app.gui.setvar("hello", "response", f"Hello, {name}!")

Dot-notation for class methods

If callbacks are methods on a class, use dot notation in the method field:

method: MyProcessor.process

Guitares will instantiate MyProcessor() and call process() on it.

Slider callbacks

The slider supports two callbacks:

YAML key	When called
`slide_method`	Called continuously while the user is dragging the slider
`method`	Called once when the user releases the slider

This is useful when the dragging callback should do a lightweight update (e.g. update a year label) while the release callback triggers a heavier operation (e.g. reload map data).