Popup windows

Guitares supports modal popup windows — secondary dialogs that collect data from the user before returning control to the main application.

A popup has the same YAML structure as the main window and can contain any standard element. Guitares automatically adds OK and Cancel buttons at the bottom.

Creating a popup config

A popup config file looks like any other Guitares config, but the window section uses okay_method to define a callback that runs when OK is clicked:

# popup_settings.yml
window:
  title: Edit Settings
  width: 300
  height: 120
  module: popup_callbacks
  variable_group: popup
  okay_method: on_okay

element:
- style: edit
  position: {x: 100, y: 70, width: 150, height: 24}
  variable: name
  text: Name
  method: edit_name

- style: spinbox
  position: {x: 100, y: 40, width: 150, height: 24}
  variable: value
  minimum: 0
  maximum: 1000
  suffix: " m"
  text: Value

Opening a popup from a callback

Call app.gui.popup() from any callback to open the dialog:

# main_callbacks.py
from app import app

def open_settings(*args):
    # Pack current values into a data dict
    data = {
        "name": app.gui.getvar("myapp", "name"),
        "value": app.gui.getvar("myapp", "value"),
    }

    okay, result = app.gui.popup("popup_settings.yml", "settings", data)

    if okay:
        app.gui.setvar("myapp", "name", result["name"])
        app.gui.setvar("myapp", "value", result["value"])

The popup() call blocks until the user clicks OK or Cancel.

• If OK is clicked, it returns (True, data) where data contains the updated values.

• If Cancel is clicked, it returns (False, data) with the original values unchanged.

The popup callback module

Callbacks inside the popup work the same way as in the main window. The okay_method is called when the user clicks OK — it can perform validation and return False to keep the popup open:

# popup_callbacks.py
from app import app

def edit_name(*args):
    pass  # variable is updated automatically

def on_okay(*args):
    name = app.gui.getvar("popup", "name")
    if not name:
        # Keep the popup open if the name is empty
        return False
    return True

Popup data flow

Data is passed into and out of a popup through the data dict argument. Guitares maps the dict keys to variable names in the popup’s variable_group:

1. Before the popup opens, values from data are written to popup variables.

2. The user edits values through the popup elements.

3. When OK is clicked, popup variable values are written back to data.

4. app.gui.popup() returns the updated data dict.

This means the keys of your data dict should match the variable names used in the popup’s YAML config.