sleap.gui.dialogs.formbuilder¶
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.
- Parameters
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.
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.
- Parameters
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
orTextOrListWidget
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.
- Parameters
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.
- Returns
None.
-
find_field
(field_name: str)[source]¶ Finds form fields by name.
- Parameters
field_name – Name of field to find.
- Returns
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.
- Returns
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.
- Parameters
widget – The widget for which to return value.
- Returns
value (can be bool, numeric, string, or None)
-
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.
- Parameters
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.
-
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 toYamlFormWidget.from_name()
).
-
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.
- Parameters
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.
-
class
sleap.gui.dialogs.formbuilder.
StackBuilderWidget
(stack_data, field_options_lists=None, *args, **kwargs)[source]¶ Widget that shows different subforms depending on menu selection.
- Parameters
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.
-
class
sleap.gui.dialogs.formbuilder.
StringListWidget
(delim=' ', *args, **kwargs)[source]¶ Free-form text field which converts value to/from list.
- Parameters
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.
- Parameters
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")
- Parameters
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.
Returns a list of buttons in form (so we can connect to handlers).
-
property
fields
¶ widget} fields in form.
- Type
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.
- Parameters
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.
- Returns
Instance of YamlFormWidget class.