Parameters

Adding scalar parameters

There are four types of scalar parameters in sympathy: booleans, integers, floats, and strings. Use the methods set_boolean, set_integer, set_float, and set_string to add each of these types to a parameter group. The following arguments are accepted:

name

First positional argument is the name of the parameter. This is used as a key to get the specific parameter from the parameter group.

value

Default value.

label

Shown next to the parameter editor to help the user identify the different parameters. Placing a colon at the end of the label is discouraged unless needed to visually distinguish the editor from the label.

description

Shown as a tooltip for each parameter and can contain a longer description for each parameters.

editor

Changes how the parameter can be edited in the configuration GUI. See Editors.

Adding lists

If you need a parameter which at any given time has only one value chosen from a list of available options, you should use one of the scalar parameter types with a combo editor. See All parameters example for an example of this. On the other hand, if you actually want a parameter where the user can select multiple options, a list parameter is what you need. The method set_list adds a list parameter. It has all the arguments of the corresponding methods for adding scalar parameters, but it also accepts a few extra arguments:

list or plist

Two synonyms for specifying all the available options in the list.

value

A list of selected indices.

value_names

A list of selected entries from list/plist.

If list (or plist) is specified and non-empty, but neither value nor value_names is specified, the first element of list will automatically be selected. To avoid this behavior and leave the selection empty you can specify value_names (or value) as an empty list.

Adding groups and pages

To group related parameters together, use the methods create_group and create_page. Creating a group and then adding parameters to that group results in a border around those parameters in the GUI. Each page in the parameters is shown as a tab in the configuration GUI. See All parameters example for examples of how to use groups and pages.

Editors

The available parameter editors are:

Editor name	Description	Usable with data types
lineedit_editor	A single line input.	strings, floats and integers
bounded_lineedit_editor	A single line input with upper and/or lower bounds for input.	floats and integers
spinbox_editor	A line with buttons for increasing and decreasing the value with a predefined step.	floats and integers
bounded_spinbox_editor	A spinbox with upper and/or lower bounds.	floats and integers
decimal_spinbox_editor	A spinbox where the number of decimals can be defined.	floats
decimal_bounded_spinbox_editor	A spinbox both bounded and decimal.	floats
textedit_editor	A text editor with support for multiple lines of text.	strings
code_editor	A text edit suitable for editing code. The extra argument language can be used to specify the language for syntax highlighting.	strings
filename_editor	A line edit and a button to browse for existing files. A filter can be set to limit the types of files shown.	strings
savename_editor	A line edit and a button for choosing a new or existing path. A filter can be set to limit the types of files shown.	strings
directory_editor	A line edit and a button to browse for directories.	strings
combo_editor	A combobox, that is, a drop down list with a single selection.	lists, strings
list_editor	A list with checkboxes for selection.	lists
multilist_editor	A list with checkboxes for selection. Multiple selection enabled.	lists
selectionlist_editor	Removed. Use list_editor or multilist_editor instead.	lists
checkbox editor	A box which can be checked and unchecked. The default for boolean parameters.	boolean

All editors can be found in sympathy.api.node.editors. To set the editor of a parameter to for example spinbox_editor, set the parameters editor argument to sympathy.api.node.editors.spinbox_editor(). Once again refer to All parameters example for many examples of choosing and configuring editors.