Script Gizmos

Gizmos are custom windows that Lua scripts can create using an XML layout. They come in two flavours:

• Dialog gizmos — popup windows launched from the Tools > Scripts menu of the running application. This is what the rest of this page describes, and is the usual case.
• App gizmos — full top-level application windows defined by a Lua script run from the command line. A script opens its own menus, tabs, status bar and data-bound widgets, and Pedigree Forge acts purely as the runtime. See Running scripts from the command line for the syntax, modes and a worked example.

Both flavours share the same widgets, event model, Widget() proxy and data-bound tags — the only differences are the top-level container (<dialog> vs <frame>) and how the script is launched. The rest of this page covers the dialog case, but applies directly to app gizmos too.

A quick example

This script creates a dialog with a text field and a button:

–[[
@tool
@name Greeting
]]

local xml = [[
<dialog title="Greeting" width="300" height="150">
  <vbox>
    <hbox collapse="yes">
      <label value="Name:" />
      <text_field id="name_input" expand="horizontal" />
    </hbox>
    <hbox collapse="yes">
      <spacer />
      <button id="greet_btn" label="Greet" />
    </hbox>
  </vbox>
</dialog>
]]

gizmos.load(xml)

function greet_btn_action()
    local name = Widget("name_input").text
    alert("Hello, " .. name .. "!")
    gizmos.close()
end

gizmos.show_modal()

How it works

1. Define the dialog layout in an XML string.
2. Call gizmos.load(xml) to create the dialog.
3. Define event handler functions named {widget_id}_{event_type} — for example, greet_btn_action handles clicks on the button with id="greet_btn".
4. Call gizmos.show() for a non-blocking dialog or gizmos.show_modal() to block until it closes.

Reading and writing widget values

Use the Widget() proxy to get and set values:

local name = Widget("name_input").text     – read
Widget("name_input").text = "new value"    – write
Widget("my_check").checked = true
Widget("my_choice").select = 2

Or use gizmos.call() for the same thing:

local name = gizmos.call("name_input", "text")
gizmos.call("name_input", "text", "new value")

Event handling

There are two event types: "action" (button clicks, Enter key, double-clicks) and "change" (value or selection changes).

You can handle them by convention:

function my_button_action()
    – runs when button with id="my_button" is clicked
end

function my_choice_change()
    – runs when the choice with id="my_choice" changes
end

Or register handlers explicitly:

gizmos.on("my_button", "action", function()
    gizmos.close()
end)

Data-bound widgets

Gizmos can include widgets that are bound directly to genealogy records. They load and save data automatically:

<bound_text_field path="person.surname" record="I1" />
<bound_label path="person.birth.date" />

The path attribute uses data expression syntax. Bound fields automatically get appropriate completers and validators (place fields suggest from the place database, date fields validate date formats, etc.).

When the path points to a date, place, age, or trade field, the text field automatically upgrades to include a helper button with an entry assistant dialog — no extra code needed. For example, <bound_text_field path="fact.date" /> shows a calendar icon that opens a date entry assistant.

Query-bound tables

Tables can be populated from a query:

<bound_table query="SELECT surname, given_names FROM persons" />
<bound_edit_table query="SELECT name, trade FROM persons" />

bound_edit_table creates an editable grid where changes are written back to the database.

Widget reference

For the complete catalogue of available widgets — layout containers, input controls, display widgets, and data widgets — see the Gizmos Widget Reference.