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)[source]

Bases: ui.base_list_ui.BaseListUIElement

Implements a listbox to choose one thing from many.


  • 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)[source]

Initialises the Listbox object.


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


  • 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.

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.


Deactivates the UI element, exiting it.


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