Widgets and dialogues for YAML-based forms.

Most of the time you can use YamlFormWidget. If you want to show the widget as a model dialog, FormBuilderModalDialog makes this a little more convenient (it provides methods for adding a message for the dialog and for getting the results when the dialog is closed).

Example of form widget:

>>> widget = YamlFormWidget(yaml_file="example.yaml")
>>> widget.mainAction.connect(my_function)

my_function will get called with form data when user clicks the main button (main button has type “button” and default “main action”)

Example of modal dialog:

>>> results = FormBuilderModalDialog(form_name="example").get_results()

The results will be empty dictionary if the user hit “cancel”, otherwise it will contain all data from form (dict keys matching names of fields).

The logic which creates each form field based on the data from the YAML file is :py:method:`FormBuilderLayout.add_item()`. Look there if you want to know what’s supported in the YAML file, what exactly each field type does, or if you want to add a new type of supported form field.

class sleap.gui.dialogs.formbuilder.FieldComboWidget(result_as_idx: bool = False, add_blank_option: bool = False, *args, **kwargs)[source]

Custom ComboBox-style widget with method to easily add set of options.

  • result_as_idx – If True, then set/get for value will use idx of option rather than string.

  • add_blank_option – If True, then blank (“”) option will be added at beginning of list (which will return “” as val instead of idx if result_as_idx is True).

set_options(options_list: List[str], select_item: Optional[str] = None)[source]

Sets list of menu options.

  • options_list – List of items (strings) to show in menu.

  • select_item – Item to select initially.



class sleap.gui.dialogs.formbuilder.FormBuilderLayout(items_to_create: List[Dict[str, Any]], field_options_lists: Optional[Dict[str, List[str]]] = None, *args, **kwargs)[source]

Custom QFormLayout which populates itself from list of form fields.

  • items_to_create – list of form items, each item in list is a dictionary with information about item. see :py:build_form() for details about the keys/values. typically this list comes straight from a YAML file.

  • field_options_lists – allows you to set list of options to use for “list” fields (i.e., FieldComboWidget or TextOrListWidget widgets) when creating the form programmatically, instead of having options as “options” key of dictionary (which typically would be hard-coded in YAML).

build_form(items_to_create: List[Dict[str, Any]])[source]

Adds widgets to form layout for each item in items_to_create.



list of dictionaries with keys

  • name: used as key when we return form data as dict

  • label: string to show in form

  • type: supports double, int, bool, list, button, stack

  • default: default value for form field

  • [options]: comma separated list of options, used for list or stack field-types

  • for stack, array of dicts w/ form data for each stack page

A “stack” has a dropdown menu that determines which stack page to show.



find_field(field_name: str)[source]

Finds form fields by name.


field_name – Name of field to find.


List of field widgets, including any in active stacked widget.

get_form_data() → dict[source]

Gets all user-editable data from the widgets in the form layout.


value for each user-editable widget in layout

Return type

Dict with key

static get_widget_value(widget: PySide2.QtWidgets.QWidget) → Any[source]

Returns value of form field.

This determines the method appropriate for the type of widget.


widget – The widget for which to return value.


value (can be bool, numeric, string, or None)

setEnabled(self, arg__1: bool)[source]
set_field_enabled(field_name: str, is_enabled: bool)[source]

Sets whether the field is enabled/disabled.

set_field_options(field_name: str, options_list: List[str])[source]

Sets custom list of options for specified field.

set_form_data(data: Dict[str, Any])[source]

Set specified user-editable data.


data – dictionary of data, key should match field name

static set_widget_value(widget: PySide2.QtWidgets.QWidget, val)[source]

Set value for specific widget.

property stacked

List of all “stack” widgets in form.


Updates options list for every field with custom list.

class sleap.gui.dialogs.formbuilder.FormBuilderModalDialog(form_widget: Optional[sleap.gui.dialogs.formbuilder.YamlFormWidget] = None, form_name: Optional[str] = None, *args, **kwargs)[source]

Blocking modal dialog to use with YamlFormWidget widget.

You can either initialize with a YamlFormWidget widget, or provide the name of the YAML form (i.e., the string you’d pass to YamlFormWidget.from_name()).

add_message(message: str)[source]

Adds text message between form fields and buttons.

get_results() → Optional[Dict[str, Any]][source]

Shows dialog, blocks till submitted, returns dict of form data.

set_message(message: str)[source]

Adds/replaces text message between form fields and buttons.

class sleap.gui.dialogs.formbuilder.OptionalSpinWidget(type='int', none_string='none', none_label: Optional[str] = None, *args, **kwargs)[source]

Numeric (spin) widget with checkbox to disable.

  • type – can be “int” or “double”.

  • none_string – value to use when numeric entry is disabled; i.e., widget returns this as value if checkbox is set, and setting value to this will make the checkbox checked.

  • note_label – text to show next to checkbox; defaults to none_string (in title case).

class sleap.gui.dialogs.formbuilder.ResizingStackedWidget(*args, **kwargs)[source]

QStackedWidget that updates its sizeHint and minimumSizeHint as needed.


Qt method.


Qt method.

class sleap.gui.dialogs.formbuilder.StackBuilderWidget(stack_data, field_options_lists=None, *args, **kwargs)[source]

Widget that shows different subforms depending on menu selection.

  • stack_data – Dictionary for field from items_to_create. The “options” key will give the list of options to show in menu. Each of the “options” will also be the key of a dictionary within stack_data that has the same structure as the dictionary passed to FormBuilderLayout.build_form().

  • field_options_list – passed to stacked forms, see FormBuilderLayout for details.

find_field(*args, **kwargs)[source]

Returns result of find_field method on currently shown subform.


Returns value from currently shown subform.

setEnabled(self, arg__1: bool)[source]

Sets value of menu.

set_field_options(*args, **kwargs)[source]

Calls set_field_options for every subform.


Switch currently shown widget from stack.


Returns value of menu.

class sleap.gui.dialogs.formbuilder.StringListWidget(delim=' ', *args, **kwargs)[source]

Free-form text field which converts value to/from list.


delim – the list delimiter to use; note that list values won’t be trimmed, so “,” and “item a, item b” will result in [“item a”, ” item b”].

class sleap.gui.dialogs.formbuilder.TextOrListWidget(result_as_idx=False, add_blank_option=False, *args, **kwargs)[source]

Widget with free-form text field or drop-down menu.

The “text” or “list” mode can be set using setMode method.

This widget is useful when we want a drop-down menu but need to fall back to a text field when (e.g.) the current value isn’t in list.

  • result_as_idx – If True, then set/get for value will use idx of option rather than string.

  • add_blank_option – If True, then blank (“”) option will be added at beginning of list (which will return “” as val instead of idx if result_as_idx is True).

class sleap.gui.dialogs.formbuilder.YamlFormWidget(yaml_file: str, which_form: str = 'main', field_options_lists: Optional[Dict[str, list]] = None, *args, **kwargs)[source]

Widget which shows form created from a YAML file.

Typically you’ll want to save the YAML in sleap/config/ and use the from_name() method to make the form (e.g., if your form data is in sleap/config/foo.yaml, then you can create form like so:

>>> widget = YamlFormWidget.from_name("foo")
  • yaml_file – filename of YAML file to load.

  • which_form (optional) – key to form in YAML file, default is “main”. this allows a single YAML file to contain data for multiple forms.

property buttons

Returns a list of buttons in form (so we can connect to handlers).

property fields

widget} fields in form.


Return a dict of {name

classmethod from_name(form_name: str, *args, **kwargs)sleap.gui.dialogs.formbuilder.YamlFormWidget[source]

Instantiate class from the short name of form (e.g., “suggestions”).

Short name is converted to path to YAML file in sleap/config/, and then class is instantiated using this path.

  • form_name – Short name of form, corresponds to name of YAML file.

  • args – Positional args passed to class initializer.

  • kwargs – Named args passed to class initializer.


Instance of YamlFormWidget class.


Returns dict of form data.

set_field_options(field_name: str, options_list: List[str], **kwargs)[source]

Sets option list for specified field.


Set data for form from dict.


Emit mainAction signal with form data.