Creating menus

Ready to go deeper into menu usage?

Configuring the menu

The pygame_menu.Menu is the base class to draw the graphical items on the screen. It offers many parameters to let you adapt the behavior and the visual aspects of the menu.

The less trivial ones are explained here.

Widgets position

By default, the widgets are centered horizontally (widget_alignment=ALIGN_CENTER). All are included in a virtual rectangle positioned at 0 pixel below the title bar and 0 pixel from the left border (widget_offset=(0, 0)).

In the same way, an offset can be defined for the title using the parameter title_offset.

The horizontal alignment can be changed with one of the following values:

Alignment Description
pygame_menu.locals.ALIGN_LEFT Left alignment
pygame_menu.locals.ALIGN_CENTER Center alignment
pygame_menu.locals.ALIGN_RIGHT Right alignment

The content of the menu can be centered vertically after all widgets have been added by calling the method pygame_menu.Menu.center_content():

menu = pygame_menu.Menu(...)

menu.add_text_input(...)
menu.add_selector(...)
menu.add_button(...)
menu.add_button(...)

Note

If the menu size is insufficient to show all of the widgets, horizontal and/or vertical scrollbar(s) will appear automatically.

Column and row

By default, the widgets are arranged in one unique column. But using the columns and rows parameters, it is possible to arrange them in a grid.

The defined grid of columns x rows cells will be completed with the widgets (in order of definition) column by column starting at the top-left corner of the menu.

On-close callback

A callback can be defined using the onclose parameter, it will be called when the menu (end sub-menus) is closing. This parameter can take one of these two types of values:

  • a python callable object (a function, a method, a class, …) that will be called without any arguments.

  • a specific event of pygame_menu. The possible events are the following:

    Event Description
    pygame_menu.events.BACK Go back to the previously opened menu
    pygame_menu.events.DISABLE_CLOSE The menu can not be closed
    pygame_menu.events.EXIT Exit the program (not only the menu)
    pygame_menu.events.RESET Go back to the first opened menu

Display a menu

The First steps chapter shows the way to display the menu, this method lets pygame-menu managing the event loop by calling the pygame_menu.Menu.mainloop() :

def draw_background():
    ...

mymenu = Menu(...)

mymenu.mainloop(surface, bgfun=draw_background)

There is a second way that gives more flexibility to the application because the events loop remains managed outside of the menu. In this case the application is in charge to update and draw the menu when it is necessary.

def draw_background():
    ...

mymenu = Menu(...)

while True:

    draw_background()

    events = pygame.event.get()
    for event in events:
        if event.type == pygame.QUIT:
            exit()

    if mymenu.is_enabled():
        mymenu.update(events)
        mymenu.draw(surface)

    pygame.display.update()
class pygame_menu.Menu(height, width, title, center_content=True, column_force_fit_text=False, column_max_width=None, columns=1, enabled=True, joystick_enabled=True, menu_id='', menu_position=(50, 50), mouse_enabled=True, mouse_motion_selection=False, mouse_visible=True, onclose=None, rows=None, theme=<pygame_menu.themes.Theme object>, **kwargs)[source]

Menu object.

Parameters:
  • height (int, float) – Height of the Menu (px)
  • width (int, float) – Width of the Menu (px)
  • title (str) – Title of the Menu (main title)
  • center_content (bool) – Auto centers the menu on the vertical position after a widget is added/deleted
  • column_force_fit_text (bool) – Force text fitting of widgets if the width exceeds the column max width
  • column_max_width (tuple, None) – List/Tuple representing the max width of each column in px, None equals no limit
  • columns (int) – Number of columns, by default it’s 1
  • enabled (bool) – Menu is enabled by default or not
  • joystick_enabled (bool) – Enable/disable joystick on the Menu
  • menu_id (str) – ID of the Menu
  • menu_position (tuple, list) – Position in x,y axis (%). Default (50, 50), vertically and horizontally centered
  • mouse_enabled (bool) – Enable/disable mouse click inside the Menu
  • mouse_motion_selection (bool) – Select widgets using mouse motion
  • mouse_visible (bool) – Set mouse visible on Menu
  • onclose (callable, None) – Function applied when closing the Menu
  • rows (int, None) – Number of rows of each column, None if there’s only 1 column
  • theme (pygame_menu.themes.Theme) – Menu theme object, if None use the default theme
  • kwargs – Optional keyword parameters
center_content()[source]

Update draw_region_y based on the current widgets, centering the content of the window.

If the height of the widgets is greater than the height of the Menu, the drawing region will start at zero, using all the height for the scrollbar.

Returns:None
clear()[source]

Full reset Menu and clear all widgets.

Returns:None
disable()[source]

Disables the Menu (doesn’t check events and draw on the surface).

Returns:None
draw(surface, clear_surface=False)[source]

Draw the current Menu into the given surface.

Note

This method should not be used along pygame_menu.Menu.get_current()

Parameters:
  • surface (pygame.Surface) – Pygame surface to draw the Menu
  • clear_surface (bool) – Clear surface using theme default color
Returns:

None

enable()[source]

Enables Menu (can check events and draw).

Returns:None
full_reset()[source]

Reset the Menu back to the first opened Menu.

Returns:None
get_current()[source]

Get current active Menu. If the user has not opened any submenu the pointer object must be the same as the base. If not, this will return the opened menu pointer.

Returns:Menu object
Return type:pygame_menu.Menu
get_id()[source]

Returns the ID of the current/base Menu.

Returns:Menu ID
Return type:str
get_index()[source]

Get selected widget from the Menu.

Returns:Selected widget index
Return type:int
get_input_data(recursive=False)[source]

Return input data from a Menu. The results are given as a dict object. The keys are the ID of each element.

With recursive=True: it collect also data inside the all sub-menus.

Parameters:recursive (bool) – Look in Menu and sub-menus
Returns:Input dict e.g.: {‘id1’: value, ‘id2’: value, …}
Return type:dict
get_rect()[source]

Return Menu rect.

Returns:Rect
Return type:pygame.Rect
get_selected_widget()[source]

Return the selected widget on the Menu.

Returns:Widget object
Return type:pygame_menu.widgets.core.widget.Widget
get_title()[source]

Return the title of the Menu.

Returns:Menu title
Return type:str
get_widget(widget_id, recursive=False)[source]

Return a widget by a given ID from the Menu.

With recursive=True: it looks for a widget in the Menu and all sub-menus. Use current for getting from current and base Menu.

None is returned if no widget found.

Parameters:
  • widget_id (str) – Widget ID
  • recursive (bool) – Look in Menu and submenus
Returns:

Widget object

Return type:

pygame_menu.widgets.core.widget.Widget

is_enabled()[source]
Returns:True if the Menu is enabled
Return type:bool
mainloop(surface, bgfun=None, disable_loop=False, fps_limit=30)[source]

Main loop of Menu. In this function, the Menu handle exceptions and draw. The Menu pauses the application and checks pygame events itself. This method returns until the menu is updated (a widget status has changed).

The execution of the mainloop is at the current Menu level.

menu = pygame_menu.Menu(...)

menu.mainloop(surface)

Note

This method should not be used along pygame_menu.Menu.get_current()

Parameters:
  • surface (pygame.Surface) – Pygame surface to draw the Menu
  • bgfun (callable, None) – Background function called on each loop iteration before drawing the Menu
  • disable_loop (bool) – If true run this method for only 1 loop
  • fps_limit (int, float) – Limit frame per second of the loop, if 0 there’s no limit
Returns:

None

remove_widget(widget)[source]

Remove a widget from the Menu.

Parameters:widget (pygame_menu.widgets.core.widget.Widget) – Widget object
Returns:None
reset(total)[source]

Go back in Menu history a certain number of times from the current Menu. This method operates through the current menu pointer.

Note

This method should not be used along pygame_menu.Menu.get_current()

Parameters:total (int) – How many menus to go back
Returns:None
set_relative_position(position_x, position_y)[source]

Set the menu position relative to the window.

  • Menu left position (x) must be between 0 and 100, if 0 the margin is at the left of the window, if 100 the menu is at the right of the window.
  • Menu top position (y) must be between 0 and 100, if 0 the margin is at the top of the window, if 100 the margin is at the bottom of the window.
Parameters:
  • position_x (int, float) – Left position of the window
  • position_y (int, float) – Top position of the window
Returns:

None

set_sound(sound, recursive=False)[source]

Add a sound engine to the Menu. If recursive=True, the sound is applied to all submenus.

The sound is applied only to the base Menu (not the currently displayed, stored in _current pointer).

Parameters:
Returns:

None

toggle()[source]

Switch between enable and disable.

Returns:None
update(events)[source]

Update the status of the Menu using external events. The update event is applied only on the current Menu.

Note

This method should not be used along pygame_menu.Menu.get_current()

Parameters:events (list[pygame.event.Event]) – Pygame events as a list
Returns:True if mainloop must be stopped
Return type:bool