CursesMenu — Standard menu class

class cursesmenu.CursesMenu(title='', subtitle='', *, show_exit_item=True, zero_pad=False, _debug_screens=False)[source]

A menu created with the curses library.

Parameters
  • title (str) – The title of the menu

  • subtitle (str) – The menu subtitle

  • show_exit_item (bool) – Whether the exit item is shown

  • zero_pad (bool) – Zero pad the item indices to match the width of the biggest one

Variables
  • screen – The curses window associated with the menu. Created using curses.newpad when the menu is started

  • highlight – Index of the curses color pair used to represent the highlighted item

  • normal – Index of the curses color pair used to represent other text

  • items – The list of items for the menu

  • current_option – The index of the currently highlighted menu item

  • selected_option – The index of the last item the user selected, initially -1

  • should_exit – Flag to signal that the menu should exit on its next pass through its main loop

  • returned_value – The value returned by the last selected item

  • parent – The parent menu of this one, or None if this menu is the root menu

  • user_input_handlers – A dictionary mapping character values to functions that handle those characters

  • current_item – The MenuItem that’s currently highlighted

  • selected_item – The Menu item that’s currently selected

  • stdscr – The root curses window

  • menu_height – The total height of the menu including the exit item

  • last_item_index – The index of the max item in the menu, including the exit item

  • currently_active_menu – Class variable that holds the currently active menu or None if no menu is currently active (E.G. when switching between menus)

append_item(item)[source]

Append an item to the list of items.

Return type

None

Lifecycle

start()[source]

Start the menu’s thread and return without blocking.

The menu’s thread is a daemon, so if the calling script may exit before the user is finished interacting, use join() to block until the menu exits.

Return type

None

join(timeout=None)[source]

Block until the menu exits.

Parameters

timeout (Optional[int]) – time in seconds until the menu is forced to close

Return type

Any

Returns

The value returned from the last selected item

show()[source]

Start the menu and blocks until it finishes.

Return type

Any

Returns

The return value from the last selected item

is_running()[source]

Check if the menu has is running (has not been paused).

Return type

bool

Returns

True if the menu has not been paused false otherwise.

wait_for_start(timeout=None)[source]

Block until the menu starts.

Parameters

timeout (Optional[int]) – Timeout in seconds

Return type

bool

Returns

True unless the operation times out

pause()[source]

Pause this menu’s thread.

Return type

None

resume()[source]

Resume this menu’s thread.

Return type

None

is_alive()[source]

Check if the menu’s thread is running.

Return type

bool

Returns

True if the menu’s thread is alive, false if not.

exit(timeout=None)[source]

Signal the menu to exit and block until it does.

Parameters

timeout (Optional[int]) – timeout before the menu is forced to close

Return type

Any

Returns

the value of the last selected item

User interaction

draw()[source]

Draw the menu.

Adds border, title and subtitle, and items, then refreshes the screen.

Return type

None

draw_item(index, item, index_text=None)[source]

Draw an individual item.

Parameters
  • index (int) – The numerical index of the item in the list

  • item (Any) – The item to be drawn

  • index_text (Optional[str]) – Text to override the index portion of the item

Return type

None

refresh_screen()[source]

Refresh what’s onscreen to match the cursor’s position.

Return type

None

clear_screen()[source]

Clear the screen for this menu.

Return type

None

process_user_input()[source]

Get and then handle the user’s input.

Return type

int

Returns

The character the user input.

get_input()[source]

Get the user’s input.

Return type

int

Returns

The character input by the user.

Input handlers

select(_=0)[source]

Select the current item.

Called for the enter/return key.

Return type

None

go_to(user_input)[source]

Go to a given numbered item.

Called on numerical input. Currently implementation only works on single digits.

Return type

None

go_to_exit(_=0)[source]

Go to the exit item.

Called for Q.

Return type

None

go_down(_=0)[source]

Go down one item, wrap if necessary.

Called when the user presses the down arrow.

Return type

None

go_up(_=0)[source]

Go up one item, wrap if necessary.

Called when the user presses the up arrow.

Return type

None

Get selections

classmethod get_selection(selections, title='', subtitle='')[source]

Present the user with a menu built from a list of strings and get the index of their selection.

Parameters
  • selections (List[str]) – The list of string possibilities

  • title (str) – The title of the menu

  • subtitle (str) – The subtitle of the menu

Return type

int

Returns

The index in the list of strings that the user selected

classmethod make_selection_menu(selections, title='', subtitle='', *, show_exit_item=False)[source]

Create a menu from a list of strings.

The return value of the menu will be an index into the list of strings.

Parameters
  • selections (List[str]) – A list of strings to be selected from

  • title (str) – The title of the menu

  • subtitle (str) – The subtitle of the menu

  • show_exit_item (bool) – If the exit item should be shown. If it is and the user selects it, the return value will be None

Return type

CursesMenu

Returns

A CursesMenu with items for each selection