Gizmos Widget Reference

Gizmos are custom dialog windows built in XML that Lua scripts can create. They provide interactive UIs for scripts — editing forms, data-bound views, multi-step workflows — anything beyond a simple alert() or query table.

You define the layout in XML, load it with gizmos.load(), then show it. The script handles events from the dialog’s widgets and can read or update their values at any time.

A complete example

This script creates a dialog with a text field and a button. When the user clicks the button, it reads the text field and shows a greeting.

–[[
@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()

Creating and showing a gizmo

The basic sequence is:

1. Build an XML string describing the layout.
2. Call gizmos.load(xml) to parse and create the widgets.
3. Register any event handlers.
4. Call gizmos.show() or gizmos.show_modal().

show() opens a non-modal dialog — the user can still interact with the main window. show_modal() blocks interaction with the main window until the dialog is closed.

The gizmos table

All gizmo functions live in the global gizmos table.

gizmos.call() is the low-level way to interact with widgets. You pass the widget’s id, the method name, and any arguments. For example, gizmos.call("name_input", "text") reads the value, and gizmos.call("name_input", "text", "Alice") sets it.

gizmos.on_closing() lets you intercept the user pressing the close button. Return true to allow the close, or false to prevent it (useful for confirming unsaved changes).

Widget proxy shorthand

The Widget() function provides a convenient shorthand that avoids repeated calls to gizmos.call(). It returns a proxy object for the widget with the given id:

local w = Widget("my_field")

– Get a value (calls gizmos.call("my_field", "text"))
local value = w.text

– Set a value (calls gizmos.call("my_field", "text", "hello"))
w.text = "hello"

– Register an event handler
w.on_action = function()
    – handle click
end

This is the recommended way to interact with widgets.

Event handling

There are two styles for handling events:

Convention-based

Define a global function named {id}_{event_type}. The gizmo framework finds it automatically:

function ok_btn_action()
    gizmos.close()
end

function search_field_change()
    – respond to text changes
end

Explicit registration

Use gizmos.on() or the Widget proxy:

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

– or equivalently:
Widget("ok_btn").on_action = function()
    gizmos.close()
end

Event types

Common attributes

These attributes are available on all widgets:

Common methods

These methods are available on all widgets via gizmos.call() or the Widget proxy:

Dialog and frame attributes

The ‘<dialog>‘ element

The root element for gizmos embedded in Pedigree Forge scripts:

The ‘<gizmos>‘ wrapper

An alternative root element that supports additional modes:

Available themes: light, dark, light_alt, dark_alt, high_contrast, fluent, sepia, parchment, forest, midnight, ocean, lavender, slate, autumn.

Layout widgets

‘<vbox>‘ — Vertical box

Arranges children in a vertical stack.

‘<hbox>‘ — Horizontal box

Arranges children in a horizontal row.

‘<grid>‘ — Grid layout

Arranges children in a grid. Children fill cells left-to-right, top-to-bottom.

‘<panel>‘ — Panel container

A general-purpose container. Also used as tab pages inside <tabs> (see below).

‘<spacer>‘ — Flexible space

Pushes siblings apart by consuming available space. Takes no attributes beyond the common ones.

‘<strut>‘ — Fixed-size spacer

Inserts a fixed gap.

‘<field_sep>‘ — Field separator

A horizontal rule, optionally with a title.

‘<zbox>‘ — Stacked layout

Stacks all children on top of each other. Only one child is visible at a time — useful for wizard-style step-by-step interfaces.

‘<collapsible_panel>‘ — Expandable section

A section with a clickable header that expands or collapses its content.

‘<split_pane>‘ — Resizable split

Splits its area into two resizable panels.

‘<tabs>‘ — Tab container

Contains <panel> children, each shown as a tab page. The name attribute on each <panel> becomes the tab label.

<tabs id="my_tabs">
  <panel name="General">
    <!– general content –>
  </panel>
  <panel name="Advanced">
    <!– advanced content –>
  </panel>
</tabs>

Input widgets

‘<button>‘ — Push button

‘<label>‘ — Text label

‘<check>‘ — Checkbox

‘<radio>‘ — Radio button

Radio buttons with the same group value are mutually exclusive.

‘<text_field>‘ — Single-line text input

‘<text_area>‘ — Multi-line text input

‘<choice>‘ — Dropdown list

A non-editable dropdown. Items are defined in XML as children:

<choice id="colour">
  <item label="Red" />
  <item label="Green" />
  <item label="Blue" />
</choice>

‘<combo>‘ — Editable dropdown

Like <choice>, but the user can also type a custom value.

Children: <item label="…"> elements.

‘<list>‘ — List box

Children: <item label="…" value="…"> elements.

‘<table>‘ — Data table

Columns are defined as children:

<table id="results" width="400" height="200">
  <column text="Name" width="200" />
  <column text="Born" width="100" right_align="true" />
</table>

‘<spinner>‘ — Integer spinner

‘<numeric_spinner>‘ — Floating-point spinner

‘<slider>‘ — Slider

‘<range_slider>‘ — Range slider

A slider with two thumbs for selecting a range.

‘<toggle_switch>‘ — Toggle switch

‘<search_box>‘ — Search input

A text field with a search icon and clear button.

‘<password_field>‘ — Password input

Text is masked. Otherwise behaves like <text_field>.

‘<tri_check>‘ — Three-state checkbox

Cycles through three states: unchecked (false), checked (true), and indeterminate (nil).

‘<segmented_control>‘ — Segmented button bar

A row of mutually exclusive buttons. Items defined as children:

<segmented_control id="view_mode">
  <item label="List" />
  <item label="Grid" />
  <item label="Detail" />
</segmented_control>

‘<link>‘ — Clickable link

‘<progress>‘ — Progress bar

Display widgets

‘<text_block>‘ — Wrapped text block

Displays read-only text that wraps within a given width.

‘<image>‘ — Image display

‘<icon_button>‘ — Icon button

A button that displays an icon rather than text.

‘<badge>‘ — Badge indicator

A small indicator, typically overlaid on another widget.

Data widgets

‘<tree>‘ — Tree view

A hierarchical tree. Items are added from Lua code rather than XML.

Tip — Use nil or 0 as parent_data to add root-level items.

‘<editable_table>‘ — Editable table

Like <table>, but cells can be edited directly.

Columns are defined as children: <column text="…" width="…">.

‘<property_grid>‘ — Property grid

A two-column grid of named properties, grouped by category. Properties are added from Lua code.

Data-bound widgets

These widgets connect directly to the genealogy database. They automatically load data when shown and save changes back when edited.

‘<bound_text_field>‘

An editable text field bound to a database field.

When the path’s data type is a date, place, age, trade, or similar structured type, the field automatically includes a helper button with an entry assistant. See the entry assistants table below for details.

Supports the same methods as <text_field>.

‘<bound_label>‘

A read-only label bound to a database field.

Supports the same methods as <label>.

Query-bound widgets

These widgets are populated by a query language query string.

‘<bound_table>‘

A read-only table populated from a query.

‘<bound_edit_table>‘

An editable table populated from a query. Edits are written back to the database. Date, place, and age columns automatically receive helper buttons with entry assistants.

‘<bound_detail_grid>‘

A detail view populated from a query, displaying results as a property-style grid rather than a table. Date, place, and age properties automatically receive helper buttons with entry assistants.

Completers and validators

Bound text fields automatically receive a completer and validator based on the type of data they are bound to:

You can override these defaults using the completer and validator attributes. Available values: place, names, trades, date, none.

Setting completer="none" or validator="none" disables the auto-assigned behaviour.

Entry assistants

Some field types also receive a helper button that opens an entry assistant dialog. Press F2 or click the button to open it.

Entry assistants appear automatically on <bound_text_field>, <bound_edit_table>, and <bound_detail_grid> widgets when their data type matches the table above.