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 alignment¶

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

The widget alignment (str) 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

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

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.center_content()

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, overflow=(True, True), rows=None, screen_dimension=None, theme=<pygame_menu.themes.Theme object>, touchscreen_enabled=False, touchscreen_motion_selection=False)[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
enabled (bool) – Menu is enabled by default or not. If False Menu cannot be drawn
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 (pygame_menu.events.MenuAction, callable, None) – Event or function applied when closing the Menu
overflow (tuple, list) – Enables overflow in x/y axes. If False then scrollbars will not work and the maximum width/height of the scroll area is the same as the menu container. Style: (overflow_x, overflow_y)
rows (int, None) – Number of rows of each column, None if there’s only 1 column
screen_dimension (tuple, list, None) – List/Tuple representing the dimensions the menu should reference for sizing/positioning, if None pygame is queried for the display mode
theme (pygame_menu.themes.Theme) – Menu theme object, if None use the default theme
touchscreen_enabled (bool) – Enable/disable touch action inside the Menu
touchscreen_motion_selection (bool) – Select widgets using touchscreen motion

center_content()[source]¶

Centers the content of the menu vertically.

Note

If the height of the widgets is greater than the height of the Menu, the drawing region will cover all menu inner surface.

Returns: None

clear(reset=True)[source]¶

Full reset and clears all widgets.

Parameters: reset (bool) – If True the menu full-resets
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_attribute(key, default=None)[source]¶

Get attribute value.

Parameters

key (str) – Key of the attribute
default (any) – Value if does not exists

Returns

Attribute data

Return type

any

get_clock()[source]¶

Returns the pygame menu timer.

Returns: Pygame clock object
Return type: py:class:pygame.time.Clock

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_height(inner=False, widget=False)[source]¶

Get menu height.

Parameters

inner (bool) – If True returns the available height (menu height minus scroll and menubar)
widget (bool) – If True returns the height of the drawn widgets

Returns

Height in px

Return type

int, float

get_id()[source]¶

Return the ID of the current/base Menu.

Returns: Menu ID
Return type: str

get_index()[source]¶

Get selected widget index 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_menubar_widget()[source]¶

Return menubar widget.

Warning

Use with caution.

Returns: MenuBar widget
Return type: pygame_menu.widgets.MenuBar

get_rect()[source]¶

Return the Menu rect.

Returns: Rect
Return type: pygame.Rect

get_scrollarea()[source]¶

Return menu scroll area.

Warning

Use with caution.

Returns: MenuBar widget
Return type: pygame_menu.scrollarea.ScrollArea

get_selected_widget()[source]¶

Return the selected widget on the Menu.

Returns: Widget object, None if no widget is selected
Return type: pygame_menu.widgets.core.widget.Widget, None

get_size()[source]¶

Return the Menu size (px) as a tuple of (width,height).

Returns: Menu size in px
Return type: tuple

get_theme()[source]¶

Returns the menu theme.

Warning

Use with caution.

Returns: Menu theme
Return type: pygame_menu.themes.Theme

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, None

get_widgets()[source]¶

Return widgets as a tuple.

Warning

Use with caution.

Returns: Widgets tuple
Return type: tuple

get_width(inner=False, widget=False)[source]¶

Get menu width.

Note

This is applied only to the base Menu (not the currently displayed, stored in _current pointer); for such behaviour apply to pygame_menu.Menu.get_current() object.

Parameters

inner (bool) – If True returns the available width (menu width minus scroll if visible)
widget (bool) – If True returns the total width used by the widgets

Returns

Width in px

Return type

int, float

get_window_size()[source]¶

Return the window size (px) as a tuple of (width,height).

Returns: Window size in px
Return type: tuple

has_attribute(key)[source]¶

Returns true if widget has the given attribute.

Parameters: key (str) – Key of the attribute
Returns: True if exists
Return type: bool

in_submenu(menu, recursive=False)[source]¶

Returns true if menu is a submenu of the Menu.

Parameters

menu (Menu) – Menu to check
recursive (bool) – Check recursively

Returns

True if menu is in submenus

Return type

bool

is_enabled()[source]¶

Return True if the menu is enabled.

Returns: Menu enabled status
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_attribute(key)[source]¶

Removes the given attribute from the menu. Throws IndexError if given key does not exist.

Parameters: key (str) – Key of the attribute
Returns: None

remove_widget(widget)[source]¶

Remove a widget from the Menu.

Parameters: widget (pygame_menu.widgets.core.widget.Widget) – Widget object
Returns: None

render()[source]¶

Force current Menu rendering. Useful to force widget update.

Note

This method should not be called if the Menu is being drawn as this method is called by pygame_menu.Menu.draw()

Warning

This method should not be used along pygame_menu.Menu.get_current(), for example, menu.get_current().render(...)

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

select_widget(widget)[source]¶

Select a widget from the Menu.

Parameters: widget (pygame_menu.widgets.core.widget.Widget) – Widget to be selected
Returns: None

set_attribute(key, value)[source]¶

Set menu attribute.

Parameters

key (str) – Key of the attribute
value (any) – Value of the attribute

Returns

None

set_onclose(onclose)[source]¶

Set onclose callback.

Parameters: onclose (pygame_menu.events.MenuAction, callable, None) – Onclose callback, it can be a function, an event or None
Returns: None

set_relative_position(position_x, position_y)[source]¶

Set the menu position relative to the window.

Note

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.

Note

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

Parameters

sound (pygame_menu.sound.Sound, None) – Sound object
recursive (bool) – Set the sound engine to all submenus

Returns

None

set_title(title, offset=None)[source]¶

Set the title of the Menu.

Note

This is applied only to the base Menu (not the currently displayed, stored in _current pointer); for such behaviour apply to pygame_menu.Menu.get_current() object.

Parameters

title (str, any) – New menu title
offset (None, tuple, list) – If None uses theme offset, else it defines the title offset in (x, y)

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