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 menusubtitle (
str
) – The menu subtitleshow_exit_item (
bool
) – Whether the exit item is shownzero_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)
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
- 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 listitem (
Any
) – The item to be drawnindex_text (
Optional
[str
]) – Text to override the index portion of the item
- Return type
None
- process_user_input()[source]
Get and then handle the user’s input.
- Return type
int
- Returns
The character the user input.
Input handlers
- 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_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 possibilitiestitle (
str
) – The title of the menusubtitle (
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 fromtitle (
str
) – The title of the menusubtitle (
str
) – The subtitle of the menushow_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
- Returns
A CursesMenu with items for each selection