Listbox UI element

from ui import Listbox
...
lbc = [
["Option1", "option_1"],
["option_2"], # will be used as both name and value
]
choice = Listbox(lbc, i, o, name="My listbox of my app").activate()
if choice: # user didn't cancel and selected something
    # do things

Listbox will return the selected option’s value (element[1]), or name (element[0]) if no value was passed. Otherwise, if the user exited Listbox by pressing LEFT, returns None.

class ui.Listbox(*args, **kwargs)

Bases: ui.base_list_ui.BaseListUIElement

Implements a listbox to choose one thing from many.

Attributes:

• contents: list of listbox entries

  Listbox entry is a list, where:

  • entry[0] (entry’s label) is usually a string which will be displayed in the UI, such as “Option 1”. If entry_height > 1, can be a list of strings, each of those strings will be shown on a separate display row.
  • entry[1] (entry’s value) is the value to be returned when entry is selected. If it’s not supplied, entry’s label is returned instead.

  You can also pass Entry objects as entries - text will be used as label and name will be used as name.

  If you want to set contents after the initalisation, please, use set_contents() method.

• pointer: currently selected entry’s number in self.contents.

• in_foreground : a flag which indicates if listbox is currently displayed. If it’s not set, inhibits any of listboxes actions which can interfere with other UI element being displayed.

__init__(*args, **kwargs)

Initialises the Listbox object.

Args:

• contents: listbox contents
• i, o: input&output device objects

Kwargs:

• name: listbox name which can be used internally and for debugging.
• selected: value (that is, entry[1]) of the element to be selected. If no element with this value is found, this is ignored.
• entry_height: number of display rows one listbox entry occupies.
• append_exit: appends an “Exit” entry to listbox.

activate()

A method which is called when the UI element needs to start operating. Is blocking, sets up input&output devices, refreshes the UI element, then calls the idle_loop method while the UI element is active. self.in_foreground is True, while callbacks are executed from the input device thread.

deactivate()

Deactivates the UI element, exiting it.

set_contents(contents)

Sets the UI element contents and triggers pointer recalculation in the view.