CursesMenu — Standard menu class

class cursesmenu.CursesMenu(title=None, subtitle=None, show_exit_option=True)

A class that displays a menu and allows the user to select an option

  • cls.currently_active_menu (CursesMenu) – Class variable that holds the currently active menu or None if no menu is currently active (E.G. when switching between menus)
  • title (str) – The title of the menu
  • subtitle (str) – The subtitle of the menu
  • show_exit_option (bool) – Whether this menu should show an exit item by default. Can be overridden when the menu is started
  • items (list[MenuItem]) – The list of MenuItems that the menu will display
  • parent (CursesMenu) – The parent of this menu
  • previous_active_menu (CursesMenu) – the previously active menu to be restored into the class’s currently active menu
  • current_option (int) – The currently highlighted menu option
  • current_item (MenuItem) – The item corresponding to the menu option that is currently highlighted
  • selected_option (int) – The option that the user has most recently selected
  • selected_item (MenuItem) – The item in items that the user most recently selected
  • returned_value – The value returned by the most recently selected item
  • screen – the curses window associated with this menu
  • normal – the normal text color pair for this menu
  • highlight – the highlight color pair associated with this window

Start the menu in a new thread and allow the user to interact with it. The thread is a daemon, so join() should be called if there’s a possibility that the main thread will exit before the menu is done

Parameters:show_exit_option (bool) – Whether the exit item should be shown, defaults to the value set in the constructor

Should be called at some point after start() to block until the menu exits. :param Number timeout: How long to wait before timing out


Calls start and then immediately joins.

Parameters:show_exit_option (bool) – Whether the exit item should be shown, defaults to the value set in the constructor

Item Management


Add an item to the end of the menu before the exit item

Parameters:item (MenuItem) – The item to be added

Add the exit item if necessary. Used to make sure there aren’t multiple exit items

Returns:True if item needed to be added, False otherwise
Return type:bool

Remove the exit item if necessary. Used to make sure we only remove the exit item, not something else

Returns:True if item needed to be removed, False otherwise
Return type:bool

User interaction


Can be overridden to change the input method. Called in process_user_input()

Returns:the ordinal value of a single character
Return type:int

Gets the next single character and decides what to do with it


Redraws the menu and refreshes the screen. Should be called whenever something changes that needs to be redrawn.


Go to the option entered by the user as a number

Parameters:option (int) – the option to go to

Go up one, wrap to end if necessary


Go down one, wrap to beginning if necessary


Select the current item and run it


Signal the menu to exit, then block until it’s done cleaning up

State management

Returns:True if the thread is still alive, False otherwise

Block until the menu is started

Parameters:timeout – How long to wait before timing out
Returns:False if timeout is given and operation times out, True otherwise. None before Python 2.7

Temporarily pause the menu until resume is called


Sets the currently active menu to this one and resumes it

Returns:True if the menu is started and hasn’t been paused