experimental.settings_menu

Contains objects used for interactive settings menus

Menu interaction is done using a knob and a button (K2 and B2 by default): - rotate the knob to select the menu item - short-press to enter edit mode - rotate knob to select an option - short-press button to apply the new option - long-press button to change between the 2 menu levels (if possible)

For examples of how to create and use the SettingsMenu, please refer to - contrib/settings_menu_example.py

Additional, more complex, examples can be found in: - contrib/euclid.py - contrib/pams.py (this is a very complex example) - contrib/sequential_switch.py - tools/conf_edit.py

class experimental.settings_menu.ActionMenuItem(actions: list[object], callback=<function ActionMenuItem.<lambda>>, callback_arg: ~typing.Optional[object] = None, parent: ~typing.Optional[~experimental.settings_menu.MenuItem] = None, children: ~typing.Optional[list[experimental.settings_menu.MenuItem]] = None, title: ~typing.Optional[str] = None, prefix: ~typing.Optional[str] = None, graphics: ~typing.Optional[dict] = None, labels: ~typing.Optional[dict] = None, is_visible: bool = True)

A menu item that just invokes a callback function when selected.

This class is similar to the SettingMenuItem, but doesn’t wrap a ConfigPoint; it just has options and fires the callback when you choose one

Parameters

• actions – The list of choices the user can pick from. e.g. [“Cancel”, “Ok”]

• callback – The function to call when the user invokes the action. The selected item from choices is passed as the first parameter

• callback_arg – The second parameter passed to the callback

• parent – If the menu has multiple levels, what is this item’s parent control?

• children – If this menu has multiple levels, whar are this item’s child controls?

• title – The title to display at the top of the display when this control is active

• prefix – A prefix to display before the title when this control is active

• graphics – A dict of values mapped to FrameBuffer or bytearray objects, representing 12x12 MONO_HLSB graphics to display along with the keyed values

• labels – A dict of values mapped to strings, representing human-readible versions of the ConfigPoint options

• is_visible – Is this menu item visible by default?

add_child(item)

Add a new child item to this item

Parameters

item – The menu item to add as a new child

draw(oled=<europi_display.DummyDisplay object>)

Draw the current item to the display object

You MUST call the display’s .show() function after calling this in order to send the buffer to the display hardware

Parameters

oled – A Display instance (or compatible class) to render the item

short_press()

Toggle is_editable on a short press

class experimental.settings_menu.ChoiceMenuItem(parent: Optional[MenuItem] = None, children: Optional[list[experimental.settings_menu.MenuItem]] = None, title: Optional[str] = None, prefix: Optional[str] = None, graphics: Optional[dict] = None, labels: Optional[dict] = None, is_visible: bool = True)

A generic menu item for displaying a choice of options to the user

Parameters

• parent – If the menu has multiple levels, what is this item’s parent control?

• children – If this menu has multiple levels, whar are this item’s child controls?

• title – The title to display at the top of the display when this control is active

• prefix – A prefix to display before the title when this control is active

• graphics – A dict of values mapped to FrameBuffer or bytearray objects, representing 12x12 MONO_HLSB graphics to display along with the keyed values

• labels – A dict of values mapped to strings, representing human-readible versions of the ConfigPoint options

• is_visible – Is this menu item visible by default?

add_child(item)

Add a new child item to this item

Parameters

item – The menu item to add as a new child

draw(oled=<europi_display.DummyDisplay object>)

Draw the current item to the display object

You MUST call the display’s .show() function after calling this in order to send the buffer to the display hardware

Parameters

oled – A Display instance (or compatible class) to render the item

short_press()

Toggle is_editable on a short press

class experimental.settings_menu.MenuItem(children: Optional[list[object]] = None, parent: Optional[object] = None, is_visible: bool = True)

Generic class for anything we can display in the menu

Parameters

• parent – A MenuItem representing this item’s parent, if this item is the bottom-level of a multi-level menu

• children – A list of MenuItems representing this item’s children, if this is the top-level of a multi-level menu

• is_visible – Is this menu item visible by default?

add_child(item)

Add a new child item to this item

Parameters

item – The menu item to add as a new child

draw(oled=<europi_display.DummyDisplay object>)

Draw the item to the screen

You must call the screen’s .show() method after calling this

Parameters

oled – A Display-compatible object we draw to

short_press()

Handler for when the user short-presses the button

This does nothing by default, but can be overridden by child classes

class experimental.settings_menu.SettingMenuItem(config_point: ~typing.Optional[~configuration.ConfigPoint] = None, parent: ~typing.Optional[~experimental.settings_menu.MenuItem] = None, children: ~typing.Optional[list[experimental.settings_menu.MenuItem]] = None, title: ~typing.Optional[str] = None, prefix: ~typing.Optional[str] = None, graphics: ~typing.Optional[dict] = None, labels: ~typing.Optional[dict] = None, callback=<function SettingMenuItem.<lambda>>, callback_arg=None, float_resolution=2, value_map: ~typing.Optional[dict] = None, is_visible: bool = True, autoselect_knob: bool = False, autoselect_cv: bool = False)

A single menu item that presents a setting the user can manipulate

The menu item is a wrapper around a ConfigPoint, and uses that object’s values as the available selections.

If the item has a callback function defined, it will be invoked once during initialization

Parameters

• config_point – The configration option this menu item controls

• parent – If the menu has multiple levels, what is this item’s parent control?

• children – If this menu has multiple levels, whar are this item’s child controls?

• title – The title to display at the top of the display when this control is active

• prefix – A prefix to display before the title when this control is active

• graphics – A dict of values mapped to FrameBuffer or bytearray objects, representing 12x12 MONO_HLSB graphics to display along with the keyed values

• labels – A dict of values mapped to strings, representing human-readible versions of the ConfigPoint options

• callback – A function to invoke when this item’s value changes. Must accept (new_value, old_value, config_point, arg=None) as parameters

• callback_arg – An optional additional argument to pass to the callback function

• float_resolution – The resolution of floating-point config points (ignored if config_point is not a FloatConfigPoint)

• value_map – An optional dict to map the underlying simple ConfigPoint values to more complex objects e.g. map the string “CMaj” to a Quantizer object

• is_visible – Is this menu item visible by default?

• autoselect_knob – If True, this item gets “Knob” as an additional choice, allowing ad-hoc selection via the knob

• autoselect_cv – If True, this item gets “AIN” as an additional choice, allowing ad-hoc selection via the CV input

add_child(item)

Add a new child item to this item

Parameters

item – The menu item to add as a new child

autoselect(percent: float)

Called by the parent menu when the Knob/CV timer fires, automatically updating the value of this item

Parameters

percent – A value 0-1 indicating the level of the knob/cv source

choose(choice)

Set the raw value of this item’s ConfigPoint

Parameters

choice – The value to assign to the ConfigPoint.

Raises

ValueError – if the given choice is not valid for this setting

draw(oled=<europi_display.DummyDisplay object>)

Render this item to the screen

You must call the screen’s .show() method after calling this

Parameters

oled – The screen we’re drawing to

get_option_list()

Get the list of options the user can choose from

Returns

A list of choices

property mapped_value

Get the value of this item mapped by the value_map

If value_map was not set by the constructor, this property returns the same thing as .value

modify_choices(choices=None, new_default=None)

Regenerate this item’s available choices

This is needed if we externally modify e.g. the maximum/minimum values of the underlying config point as a result of one option needing to be within a range determined by another.

Parameters

• choices – The list of new options we want to allow the user to choose from, excluding any autoselections

• new_default – A value to assign to this setting if its existing value is out-of-range

reset_to_default()

Reset this item to its default value

short_press()

Handle a short button press

This enters edit mode, or applies the selection and exits edit mode

property value

Get the raw value of this item’s ConfigPoint

You should use .mapped_value if you have assigned a value_map to the constructor

property value_choice

The value the user has chosen from the menu

class experimental.settings_menu.SettingsMenu(menu_items: ~typing.Optional[list] = None, navigation_button: ~europi_hardware.Button = <europi_hardware.Button object>, navigation_knob: ~europi_hardware.Knob = <europi_hardware.Knob object>, short_press_cb=<function SettingsMenu.<lambda>>, long_press_cb=<function SettingsMenu.<lambda>>, autoselect_knob: ~europi_hardware.Knob = <europi_hardware.Knob object>, autoselect_cv: ~europi_hardware.AnalogueInput = <europi_hardware.AnalogueInput object>)

A menu-based GUI for any EuroPi script.

This class is assumed to be the main interaction method for the program.

Long/short press callbacks are invoked inside the handler for the falling edge of the button. It is recommended to avoid any lengthy operations inside these callbacks, as they may prevent other interrupts from being handled properly.

Parameters

• menu_items – A list of MenuItem objects representing the top-level of the menu

• navigation_button – The button the user presses to interact with the menu

• navigation_knob – The knob the user turns to scroll through the menu. This may be an experimental.knobs.KnobBank with 3 menu levels called “main_menu”, “submenu” and “choice”, or a raw knob like europi.k2

• short_press_cb – An optional callback function to invoke when the user interacts with a short-press of the button

• long_press_cb – An optional callback function to invoke when the user interacts with a long-press of the button

• autoselect_knob – A knob that the user can turn to select items without needing to menu-dive

• autoselect_cv – An analogue input the user can use to select items with CV

do_autoselect(timer)

Callback function for the autoselection timer

Reads from ain and/or the autoselect knob and applies that choice to all subscribed menu items

Parameters

timer – The timer instance that fired this callback

draw(oled=<europi_display.DummyDisplay object>)

Draw the menu to the given display

You should call the display’s .fill(0) function before calling this in order to clear the screen. Otherwise the menu item will be drawn on top of whatever is on the screen right now. (In some cases this may be the desired result, but when in doubt, call oled.fill(0) first).

You MUST call the display’s .show() function after calling this in order to send the buffer to the display hardware

Parameters

oled – The display object to draw to

get_config_points()

Get the config points for the menu so we can load/save them as needed

property knob

Get the navigation knob that controls this menu

load_defaults(settings_file)

Load the initial settings from the file

Parameters

settings_file – The path to a JSON file where the user’s settings are saved

long_press()

Handle a long button press

This changes between the two menu levels (if possible)

on_button_press()

Handler for the rising edge of the button signal

on_button_release()

Handler for the falling edge of the button signal

register_autoselect_cv(menu_item: SettingMenuItem)

Connects a menu item to this menu’s CV input

Parameters

menu_item – The item that wants to subscribe to the CV input

register_autoselect_knob(menu_item: SettingMenuItem)

Connects a menu item to this menu’s knob input

Parameters

menu_item – The item that wants to subscribe to the knob input

save(settings_file)

Save the current settings to the specified file

Parameters

settings_file – The path to the JSON file to generate

short_press()

Handle a short button press

This enters edit mode, or applies the selection and exits edit mode

property ui_dirty

Is the UI currently dirty and needs re-drawing?

This will be true if the user has pressed the button or rotated the knob sufficiently to change the active item

unregister_autoselect_cv(menu_item: SettingMenuItem)

Disconnects a menu item to this menu’s CV input

Parameters

menu_item – The item that wants to unsubscribe from the CV input

unregister_autoselect_knob(menu_item: SettingMenuItem)

Disconnects a menu item to this menu’s knob input

Parameters

menu_item – The item that wants to unsubscribe from the knob input

property visible_items

Get the set of visible menu items for the current state of the menu

Menu items can be shown/hidden by setting their is_visible property. Normally this should be done in a value-change callback of a menu item to show/hide dependent other items.