Adding widgets

For adding new widgets to the Menu you can create new instances of the respective widget class. Or you can use the pygame_menu._widgetmanager.WidgetManager class stored in Menu.add property. These methods configure the widget and add to the Menu in a simple way.

Add a button

A button is a text that fire action when the user trigger it. An action is linked to a button by defining the action parameter with one of the three values:

  • a pygame_menu.menu.Menu, in this case, it will be displayed when the button is triggered.

  • a python callable object (a function, a method, a class, …) that will be called with the given arguments.

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

    Event

    Description

    pygame_menu.events.BACK

    Go back to previously opened menu

    pygame_menu.events.CLOSE

    Close the menu

    pygame_menu.events.EXIT

    Exit the program (not only the menu)

    pygame_menu.events.NONE

    Literally this event does nothing

    pygame_menu.events.RESET

    Go back to first opened menu

Example:

../_images/widget_button.png
menu = pygame_menu.Menu(...)
about_menu = pygame_menu.Menu(...)

def func(name):
    print('Hello world from', name)  # Name will be 'foo'

menu.add.button('Exec', func, 'foo',                   # Execute a function
                align=pygame_menu.locals.ALIGN_LEFT)
menu.add.button(about_menu.get_title(), about_menu,    # Open a sub-menu
                shadow=True, shadow_color=(0, 0, 100))
menu.add.button('Exit', pygame_menu.events.EXIT,       # Link to exit action
                align=pygame_menu.locals.ALIGN_RIGHT)
WidgetManager.button(title, action=None, *args, **kwargs)

Adds a button to the Menu.

The arguments and unknown keyword arguments are passed to the action, if it’s a callable object:

action(*args)

If accept_kwargs=True then the **kwargs are also unpacked on action call:

action(*args, **kwargs)

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • accept_kwargs (bool) – Button action accepts **kwargs if it’s a callable object (function-type), False by default

  • align (str) – Widget alignment

  • back_count (int) – Number of menus to go back if action is pygame_menu.events.BACK event, default is 1

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • button_id (str) – Widget ID

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • onselect (callable, None) – Callback executed when selecting the widget

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • tab_size (int) – Width of a tab character

  • underline_color (tuple, list, str, int, pygame.Color, None) – Color of the underline. If None use the same color of the text

  • underline_offset (int) – Vertical offset in px. 2 by default

  • underline_width (int) – Underline width in px. 2 by default

  • underline (bool) – Enables text underline, using a properly placed decoration. False by default

Note

All theme-related optional kwargs use the default Menu theme if not defined.

Note

Using action=None is the same as using action=pygame_menu.events.NONE.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (Any) – Title of the button

  • action (Union[Menu, MenuAction, Callable, int, None]) – Action of the button, can be a Menu, an event, or a function

  • args – Additional arguments used by a function

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.Button

Add a choices list (selector)

A selector gives the possibility choose a value in a predefined list. An item of a selector is a tuple: the first element is the text displayed, the others are the arguments passed to the callbacks onchange and onreturn.

Example:

../_images/widget_selector.png
menu = pygame_menu.Menu(...)

def change_background_color(selected_value, color, **kwargs):
    value_tuple, index = selected_value
    print('Change widget color to', value_tuple[0])  # selected_value ('Color', surface, color)
    if color == (-1, -1, -1):  # Generate a random color
        color = (randrange(0, 255), randrange(0, 255), randrange(0, 255))
    widget: 'pygame_menu.widgets.Selector' = kwargs.get('widget')
    widget.update_font({'selected_color': color})
    widget.get_selection_effect().color = color

items = [('Default', (255, 255, 255)),
         ('Black', (0, 0, 0)),
         ('Blue', (0, 0, 255)),
         ('Random', (-1, -1, -1))]
selector = menu.add.selector(
    title='Current color:\t',
    items=items,
    onreturn=change_background_color,  # User press "Return" button
    onchange=change_background_color  # User changes value with left/right keys
)
selector.add_self_to_kwargs()  # Callbacks will receive widget as parameter
selector2 = menu.add.selector(
    title='New color:',
    items=items,
    style=pygame_menu.widgets.SELECTOR_STYLE_FANCY
)
WidgetManager.selector(title, items, default=0, onchange=None, onreturn=None, onselect=None, selector_id='', style='classic', **kwargs)

Add a selector to the Menu: several items and two functions that are executed when changing the selector (left/right) and pressing return button on the selected item.

The items of the selector are like:

items = [('Item1', a, b, c...), ('Item2', d, e, f...)]

The callbacks receive the current selected item, its index in the list, the associated arguments, and all unknown keyword arguments, where selected_item=widget.get_value() and selected_index=widget.get_index():

onchange((selected_item, selected_index), a, b, c..., **kwargs)
onreturn((selected_item, selected_index), a, b, c..., **kwargs)

For example, if selected_index=0 then selected_item=('Item1', a, b, c...).

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • style_fancy_arrow_color (tuple, list, str, int, pygame.Color) – Arrow color of fancy style

  • style_fancy_arrow_margin (tuple, list) – Margin of arrows on x-axis and y-axis in px; format: (left, right, vertical)

  • style_fancy_bgcolor (tuple, list, str, int, pygame.Color) – Background color of fancy style

  • style_fancy_bordercolor (tuple, list, str, int, pygame.Color) – Border color of fancy style

  • style_fancy_borderwidth (int) – Border width of fancy style; 1 by default

  • style_fancy_box_inflate (tuple, list) – Box inflate of fancy style on x-axis and y-axis (x, y) in px

  • style_fancy_box_margin (tuple, list) – Box margin on x-axis and y-axis (x, y) in fancy style from title in px

  • tab_size (int) – Width of a tab character

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (Any) – Title of the selector

  • items (Union[List[Tuple[Any, …]], List[str]]) – Item list of the selector; format [('Item1', a, b, c...), ('Item2', d, e, f...)]

  • default (int) – Index of default item to display

  • onchange (Optional[Callable]) – Callback executed when when changing the selector

  • onreturn (Optional[Callable]) – Callback executed when pressing return button

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget

  • selector_id (str) – ID of the selector

  • style (Literal[‘classic’, ‘fancy’]) – Selector style (visual)

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.Selector

Add a clock

A clock is a simple label object which updates the title text with a generator that retrieves the clock/date string from time.strftime.

Example:

../_images/widget_clock.png
menu = pygame_menu.Menu(...)

clock = menu.add.clock(font_size=25, font_name=pygame_menu.font.FONT_DIGITAL)
WidgetManager.clock(clock_format='%Y/%m/%d %H:%M:%S', clock_id='', onselect=None, selectable=False, title_format='{0}', **kwargs)

Add a clock label to the Menu. This creates a Label with a text generator that request a string from time.strftime module using clock_format.

Commonly used format codes:
  • %Y – Year with century as a decimal number

  • %m – Month as a decimal number [01, 12]

  • %d – Day of the month as a decimal number [01, 31]

  • %H – Hour (24-hour clock) as a decimal number [00, 23]

  • %M – Minute as a decimal number [00, 59]

  • %S – Second as a decimal number [00, 61]

  • %z – Time zone offset from UTC

  • %a – Locale’s abbreviated weekday name

  • %A – Locale’s full weekday name

  • %b – Locale’s abbreviated month name

  • %B – Locale’s full month name

  • %c – Locale’s appropriate date and time representation

  • %I – Hour (12-hour clock) as a decimal number [01, 12]

  • %p – Locale’s equivalent of either AM or PM

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect. Applied only if selectable is True

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • tab_size (int) – Width of a tab character

  • underline_color (tuple, list, str, int, pygame.Color, None) – Color of the underline. If None use the same color of the text

  • underline_offset (int) – Vertical offset in px. 2 by default

  • underline_width (int) – Underline width in px. 2 by default

  • underline (bool) – Enables text underline, using a properly placed decoration. False by default

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Parameters
  • clock_format (str) – Format of clock used by time.strftime

  • clock_id (str) – ID of the clock

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget; only executed if selectable is True

  • selectable (bool) – Label accepts user selection; useful to move along the Menu using label selection

  • title_format (str) – Title format which accepts {0} as the string from time.strftime, for example, 'My Clock {0}' can be a title format

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.Label

Add a color entry

A color input is similar as a text input but with a limited choice of characters to enter a RGB value of HEX decimal one. There is also a area to show the current color. By default the RGB integers separator is a comma (,).

Example:

../_images/widget_colorinput.png
menu = pygame_menu.Menu(...)

def check_color(value):
    print('New color:', value)

menu.add.color_input('RGB color 1: ',
                     color_type=pygame_menu.widgets.COLORINPUT_TYPE_RGB,
                     default=(255, 0, 255), font_size=18)
menu.add.color_input('RGB color 2: ',
                     color_type=pygame_menu.widgets.COLORINPUT_TYPE_RGB,
                     input_separator='-', font_size=18)
menu.add.color_input('HEX color 3: ',
                     color_type=pygame_menu.widgets.COLORINPUT_TYPE_HEX,
                     default='#ffaa11', font_size=18)
WidgetManager.color_input(title, color_type, color_id='', default='', hex_format='none', input_separator=',', input_underline='_', onchange=None, onreturn=None, onselect=None, **kwargs)

Add a color widget with RGB or HEX format to the Menu. Includes a preview box that renders the given color.

The callbacks (if defined) receive the current value and all unknown keyword arguments, where current_color=widget.get_value():

onchange(current_color, **kwargs)
onreturn(current_color, **kwargs)

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • dynamic_width (bool) – If True the widget width changes if the pre-visualization color box is active or not

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • input_underline_vmargin (int) – Vertical margin of underline in px

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • maxwidth_dynamically_update (bool) - Dynamically update maxwidth depending on char size. True by default

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • previsualization_margin (int) – Pre-visualization left margin from text input in px. Default is 0

  • previsualization_width (int, float) – Pre-visualization width as a factor of the height. Default is 3

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • repeat_keys_initial_ms (int, float) - Time in ms before keys are repeated when held in ms. 400 by default

  • repeat_keys_interval_ms (int, float) - Interval between key press repetition when held in ms. 50 by default

  • repeat_mouse_interval_ms (int, float) - Interval between mouse events when held in ms. 400 by default

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • tab_size (int) – Width of a tab character

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (Union[str, Any]) – Title of the color input

  • color_type (Literal[‘rgb’, ‘hex’]) – Type of the color input

  • color_id (str) – ID of the color input

  • default (Union[str, Tuple[int, int, int]]) – Default value to display, if RGB type it must be a tuple (r, g, b), if HEX must be a string "#XXXXXX"

  • hex_format (Literal[‘lower’, ‘upper’, ‘none’]) – Hex format string mode

  • input_separator (str) – Divisor between RGB channels, not valid in HEX format

  • input_underline (str) – Underline character

  • onchange (Optional[Callable]) – Callback executed when changing the values of the color text

  • onreturn (Optional[Callable]) – Callback executed when pressing return on the color input

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.ColorInput

Add a drop selection

A drop selector gives the possibility choose a value in a predefined list. An item of a drop selector is a tuple: the first element is the text displayed, the others are the arguments passed to the callbacks onchange and onreturn.

Example:

../_images/widget_dropselect.png
menu = pygame_menu.Menu(...)

selector_epic = menu.add.dropselect(
    title='Is pygame-menu epic?',
    items=[('Yes', 0),
           ('Absolutely Yes', 1)],
    font_size=16,
    selection_option_font_size=20
)
selector_sum = menu.add.dropselect(
    title='What is the value of π?',
    items=[('3 (Engineer)', 0),
           ('3.1415926535897932384626433832795028841971693993751058209', 1),
           ('4', 2),
           ('I don\'t know what is π', 3)],
    font_size=16,
    selection_box_width=173,
    selection_option_padding=(0, 5),
    selection_option_font_size=20
)
selector_country = menu.add.dropselect(
    title='Pick a country',
    items=[('Argentina', 'ar'),
           ('Australia', 'au'),
           ('Bolivia', 'bo'),
           ('Chile', 'ch'),
           ('China', 'cn'),
           ('Finland', 'fi'),
           ('France', 'fr'),
           ('Germany', 'de'),
           ('Italy', 'it'),
           ('Japan', 'jp'),
           ('Mexico', 'mx'),
           ('Peru', 'pe'),
           ('United States', 'us')],
    font_size=20,
    default=3,
    open_middle=True,  # Opens in the middle of the menu
    selection_box_height=5,
    selection_box_width=212,
    selection_infinite=True,
    selection_option_font_size=20
)
WidgetManager.dropselect(title, items, default=None, dropselect_id='', onchange=None, onreturn=None, onselect=None, open_middle=False, placeholder='Select an option', placeholder_add_to_selection_box=True, **kwargs)

Add a dropselect to the Menu: Drop select is a selector within a Frame. This drops a vertical frame if requested.

Drop select can contain selectable items (options), but only one can be selected.

The items of the DropSelect are:

items = [('Item1', a, b, c...), ('Item2', d, e, f...)]

The callbacks receive the current selected item, its index in the list, the associated arguments, and all unknown keyword arguments, where selected_item=widget.get_value() and selected_index=widget.get_index():

onchange((selected_item, selected_index), a, b, c..., **kwargs)
onreturn((selected_item, selected_index), a, b, c..., **kwargs)

For example, if selected_index=0 then selected_item=('Item1', a, b, c...).

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • tab_size (int) – Width of a tab character

kwargs for modifying selection box/option style (Optional)
  • scrollbar_color (tuple, list, str, int, pygame.Color) – Scrollbar color

  • scrollbar_cursor (int, pygame.cursors.Cursor, None) – Cursor of the scrollbars if the mouse is placed over

  • scrollbar_shadow_color (tuple, list, str, int, pygame.Color) – Color of the shadow of each scrollbar

  • scrollbar_shadow_offset (int) – Offset of the scrollbar shadow in px

  • scrollbar_shadow_position (str) – Position of the scrollbar shadow. See pygame_menu.locals

  • scrollbar_shadow (bool) – Indicate if a shadow is drawn on each scrollbar

  • scrollbar_slider_color (tuple, list, str, int, pygame.Color) – Color of the sliders

  • scrollbar_slider_hover_color (tuple, list, str, int, pygame.Color) – Color of the slider if hovered or clicked

  • scrollbar_slider_pad (int, float) – Space between slider and scrollbars borders in px

  • scrollbar_thick (int) – Scrollbar thickness in px

  • scrollbars (str) – Scrollbar position. See pygame_menu.locals

  • selection_box_arrow_color (tuple, list, str, int, pygame.Color) – Selection box arrow color

  • selection_box_arrow_margin (tuple) – Selection box arrow margin (left, right, vertical) in px

  • selection_box_bgcolor (tuple, list, str, int, pygame.Color) – Selection box background color

  • selection_box_border_color (tuple, list, str, int, pygame.Color) – Selection box border color

  • selection_box_border_width (int) – Selection box border width

  • selection_box_height (int) – Number of the options which can be packed before showing scroll

  • selection_box_inflate (tuple) – Selection box inflate on x-axis and y-axis (x, y) in px

  • selection_box_margin (tuple, list) – Selection box on x-axis and y-axis (x, y) margin from title in px

  • selection_box_text_margin (int) – Left margin of the text inside the selection box in px

  • selection_box_width (int) – Selection box width in px. If 0 compute automatically to fit placeholder

  • selection_infinite (bool) – If True selection can rotate through bottom/top

  • selection_option_border_color (tuple, list, str, int, pygame.Color) – Option border color

  • selection_option_border_width (int) – Option border width

  • selection_option_font_color (tuple, list, str, int, pygame.Color) – Option font color

  • selection_option_font_size (int, None) – Option font size. If None use the 75% of the widget font size

  • selection_option_font (str, pathlib.Path, pygame.font.Font) – Option font. If None use the same font as the widget

  • selection_option_padding (int, float, tuple, list ) – Selection padding. See padding styling

  • selection_option_selected_bgcolor (tuple, list, str, int, pygame.Color) – Selected option background color

  • selection_option_selected_font_color (tuple, list, str, int, pygame.Color) – Selected option font color

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (Any) – Drop select title

  • items (Union[List[Tuple[Any, …]], List[str]]) – Item list of the drop select; format [('Item1', a, b, c...), ('Item2', d, e, f...)]

  • default (Optional[int]) – Index of default item to display. If None no item is selected

  • dropselect_id (str) – ID of the dropselect

  • onchange (Optional[Callable]) – Callback when changing the drop select item

  • onreturn (Optional[Callable]) – Callback when pressing return on the selected item

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Function when selecting the widget

  • open_middle (bool) – If True the selection box is opened in the middle of the menu

  • placeholder (str) – Text shown if no option is selected yet

  • placeholder_add_to_selection_box (bool) – If True adds the placeholder button to the selection box

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.DropSelect

Add a drop selection multiple

A multiple drop selector gives the possibility choose a value in a predefined list. An item of a drop selector is a tuple: the first element is the text displayed, the others are the arguments passed to the callbacks onchange and onreturn.

Example:

../_images/widget_dropselect_multiple.png
menu = pygame_menu.Menu(...)

selector = menu.add.dropselect_multiple(
    title='Pick 3 colors',
    items=[('Black', (0, 0, 0)),
           ('Blue', (0, 0, 255)),
           ('Cyan', (0, 255, 255)),
           ('Fuchsia', (255, 0, 255)),
           ('Green', (0, 255, 0)),
           ('Red', (255, 0, 0)),
           ('White', (255, 255, 255)),
           ('Yellow', (255, 255, 0))],
    font_size=23,
    max_selected=3,
    selection_option_font_size=23
)
WidgetManager.dropselect_multiple(title, items, default=None, dropselect_multiple_id='', max_selected=0, onchange=None, onreturn=None, onselect=None, open_middle=False, placeholder='Select an option', placeholder_add_to_selection_box=True, placeholder_selected='{0} selected', selection_placeholder_format='total', **kwargs)

Add a dropselect multiple to the Menu: Drop select multiple is a drop select which can select many options at the same time. This drops a vertical frame if requested.

The items of the DropSelectMultiple are:

items = [('Item1', a, b, c...), ('Item2', d, e, f...), ('Item3', g, h, i...)]

The callbacks receive the current selected items (tuple) and the indices (tuple), where selected_item=widget.get_value() and selected_index=widget.get_index():

onchange((selected_item, selected_index), **kwargs)
onreturn((selected_item, selected_index), **kwargs)

For example, if selected_index=[0, 2] then selected_item=[('Item1', a, b, c...), ('Item3', g, h, i...)].

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • tab_size (int) – Width of a tab character

kwargs for modifying selection box/option style (Optional)
  • scrollbar_color (tuple, list, str, int, pygame.Color) – Scrollbar color

  • scrollbar_cursor (int, pygame.cursors.Cursor, None) – Cursor of the scrollbars if the mouse is placed over

  • scrollbar_shadow_color (tuple, list, str, int, pygame.Color) – Color of the shadow of each scrollbar

  • scrollbar_shadow_offset (int) – Offset of the scrollbar shadow in px

  • scrollbar_shadow_position (str) – Position of the scrollbar shadow. See pygame_menu.locals

  • scrollbar_shadow (bool) – Indicate if a shadow is drawn on each scrollbar

  • scrollbar_slider_color (tuple, list, str, int, pygame.Color) – Color of the sliders

  • scrollbar_slider_hover_color (tuple, list, str, int, pygame.Color) – Color of the slider if hovered or clicked

  • scrollbar_slider_pad (int, float) – Space between slider and scrollbars borders in px

  • scrollbar_thick (int) – Scrollbar thickness in px

  • scrollbars (str) – Scrollbar position. See pygame_menu.locals

  • selection_box_arrow_color (tuple, list, str, int, pygame.Color) – Selection box arrow color

  • selection_box_arrow_margin (tuple) – Selection box arrow margin (left, right, vertical) in px

  • selection_box_bgcolor (tuple, list, str, int, pygame.Color) – Selection box background color

  • selection_box_border_color (tuple, list, str, int, pygame.Color) – Selection box border color

  • selection_box_border_width (int) – Selection box border width

  • selection_box_height (int) – Selection box height, counted as how many options are packed before showing scroll

  • selection_box_inflate (tuple) – Selection box inflate on x-axis and y-axis in px

  • selection_box_margin (tuple, list) – Selection box on x-axis and y-axis (x, y) margin from title in px

  • selection_box_text_margin (int) – Selection box text margin (left) in px

  • selection_box_width (int) – Selection box width in px. If 0 compute automatically to fit placeholder

  • selection_infinite (bool) – If True selection can rotate through bottom/top

  • selection_option_active_bgcolor (tuple, list, str, int, pygame.Color) – Active option(s) background color; active options is the currently active (by user)

  • selection_option_active_font_color (tuple, list, str, int, pygame.Color) – Active option(s) font color

  • selection_option_border_color (tuple, list, str, int, pygame.Color) – Option border color

  • selection_option_border_width (int) – Option border width

  • selection_option_font_color (tuple, list, str, int, pygame.Color) – Option font color

  • selection_option_font_size (int, None) – Option font size. If None use the 75% of the widget font size

  • selection_option_font (str, pathlib.Path, pygame.font.Font) – Option font. If None use the same font as the widget

  • selection_option_padding (int, float, tuple, list) – Selection padding. See padding styling

  • selection_option_selected_bgcolor (tuple, list, str, int, pygame.Color) – Selected option background color

  • selection_option_selected_box_border (int) – Box border width in px

  • selection_option_selected_box_color (tuple, list, str, int, pygame.Color) – Box color

  • selection_option_selected_box_height (int, float) – Height of the selection box relative to the options height

  • selection_option_selected_box_margin (tuple, list) – Option box margin (left, right, vertical) in px

  • selection_option_selected_box (bool) – Draws a box in the selected option(s)

  • selection_option_selected_font_color (tuple, list, str, int, pygame.Color) – Selected option font color

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (Any) – Drop select title

  • items (Union[List[Tuple[Any, …]], List[str]]) – Item list of the drop select; format [('Item1', a, b, c...), ('Item2', d, e, f...)]

  • default (Union[int, List[int], None]) – Index(es) of default item(s) to display. If None no item is selected

  • dropselect_multiple_id (str) – ID of the dropselect multiple

  • max_selected (int) – Max items to be selected. If 0 there’s no limit

  • onchange (Optional[Callable]) – Callback when changing the drop select item

  • onreturn (Optional[Callable]) – Callback when pressing return on the selected item

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Function when selecting the widget

  • open_middle (bool) – If True the selection box is opened in the middle of the menu

  • placeholder (str) – Text shown if no option is selected yet

  • placeholder_add_to_selection_box (bool) – If True adds the placeholder button to the selection box

  • placeholder_selected (str) – Text shown if option is selected. Accepts the number of selected options

  • selection_placeholder_format (Union[Literal[‘total’, ‘comma-list’, ‘hyphen-list’], Callable[[List[str]], str]]) – Format of the string replaced in placeholder_selected. Can be a predefined string type (“total”, “comma-list”, “hyphen-list”, or any other string which will join the list) or a function that receives the list of selected items and returns a string

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.DropSelectMultiple

Add a frame

Frame is a widget container, it can pack many widgets both horizontally or vertically. All widgets within a same Frame count as one widget position, so using Frames is useful when designing column/row layout. Frames can contain widgets or even more frames.

There is two types of frames, horizontal (h) and vertical (v) ones. These change the way the widgets are added to the frame (packed).

Example:

../_images/widget_frame.png
menu = pygame_menu.Menu(...)

frame = menu.add.frame_v(250, 150, background_color=(50, 50, 50), padding=0)
frame_title = menu.add.frame_h(250, 29, background_color=(180, 180, 180), padding=0)
frame_content = menu.add.frame_v(250, 120, padding=0)
frame.pack(frame_title)
frame.pack(frame_content)

frame_title.pack(menu.add.label('Settings', padding=0), margin=(2, 2))
frame_title.pack(
    menu.add.button('Close', pygame_menu.events.EXIT, padding=(0, 5),
                    background_color=(100, 100, 100)),
    align=pygame_menu.locals.ALIGN_RIGHT, margin=(2, 2))
frame_content.pack(
    menu.add.label('Pick a number', font_color=(150, 150, 150)),
    align=pygame_menu.locals.ALIGN_CENTER)
frame_numbers = menu.add.frame_h(250, 41, padding=0)
frame_content.pack(frame_numbers)
for i in range(9):
    frame_numbers.pack(
        menu.add.button(i, font_color=(5 * i, 11 * i, 13 * i),
                        padding=(0, 5), font_size=30),
        align=pygame_menu.locals.ALIGN_CENTER)
frame_content.pack(menu.add.vertical_margin(15))
frame_content.pack(
    menu.add.toggle_switch('Nice toggle', False, width=100,
                           font_color=(150, 150, 150), padding=0),
    align=pygame_menu.locals.ALIGN_CENTER)

Example:

../_images/widget_frame_title.png
menu = pygame_menu.Menu(...)

frame = menu.add.frame_v(400, 800, background_color=(50, 50, 50), padding=0,
                         max_width=300, max_height=100)
frame.set_title('My Frame App', title_font_color='white', padding_inner=(2, 5))

frame.pack(menu.add.dropselect(
    title='Is pygame-menu epic?',
    items=[('Yes', 0),
           ('Absolutely Yes', 1)],
    font_color='white',
    font_size=16,
    selection_option_font_size=20
))
for i in range(20):
    frame.pack(menu.add.button(i, font_color='white', button_id=f'b{i}'))
WidgetManager.frame_h(width, height, frame_id='', **kwargs)

Adds a horizontal frame to the Menu. Frame is a widget container that packs many widgets within. All contained widgets have a floating position, and use only 1 position in column/row layout.

frame.pack(W1, alignment=ALIGN_LEFT, vertical_position=POSITION_NORTH)
frame.pack(W2, alignment=ALIGN_LEFT, vertical_position=POSITION_CENTER)
frame.pack(W3, alignment=ALIGN_LEFT, vertical_position=POSITION_SOUTH)
...

----------------
|W1            |
|   W2     ... |
|      W3      |
----------------
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the frame if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • max_height (int) – Max height in px. If this value is lower than the frame height a scrollbar will appear on vertical axis. None by default (same height)

  • max_width (int) – Max width in px. If this value is lower than the frame width a scrollbar will appear on horizontal axis. None by default (same width)

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • scrollarea_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage,None) – Scroll area color. If None area is transparent

  • scrollbar_color (tuple, list, str, int, pygame.Color) – Scrollbar color

  • scrollbar_cursor (int, pygame.cursors.Cursor, None) – Cursor of the scrollbars if the mouse is placed over

  • scrollbar_shadow_color (tuple, list, str, int, pygame.Color) – Color of the shadow of each scrollbar

  • scrollbar_shadow_offset (int) – Offset of the scrollbar shadow in px

  • scrollbar_shadow_position (str) – Position of the scrollbar shadow. See pygame_menu.locals

  • scrollbar_shadow (bool) – Indicate if a shadow is drawn on each scrollbar

  • scrollbar_slider_color (tuple, list, str, int, pygame.Color) – Color of the sliders

  • scrollbar_slider_hover_color (tuple, list, str, int, pygame.Color) – Color of the slider if hovered or clicked

  • scrollbar_slider_pad (int, float) – Space between slider and scrollbars borders in px

  • scrollbar_thick (int) – Scrollbar thickness in px

  • scrollbars (str) – Scrollbar position. See pygame_menu.locals

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

Note

All theme-related optional kwargs use the default Menu theme if not defined.

Note

If horizontal frame contains a scrollarea (setting max_height or max_width less than size) padding will be set at zero.

Note

Packing applies a virtual translation to the widget, previous translation is not modified.

Note

Widget floating is also considered within frames. If a widget is floating, it does not add any size to the respective positioning.

Note

The Frame size created with this method does consider the padding. Thus, if Frame is created with width=100, height=200 and padding=25 the final internal size is width=50 and height=150.

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.Menu.get_current() object.

Parameters
  • width (Union[int, float]) – Frame width in px

  • height (Union[int, float]) – Frame height in px

  • frame_id (str) – ID of the horizontal frame

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.Frame

WidgetManager.frame_v(width, height, frame_id='', **kwargs)

Adds a vertical frame to the Menu. Frame is a widget container that packs many widgets within. All contained widgets have a floating position, and use only 1 position in column/row layout.

frame.pack(W1, alignment=ALIGN_LEFT)
frame.pack(W2, alignment=ALIGN_CENTER)
frame.pack(W3, alignment=ALIGN_RIGHT)
...

--------
|W1    |
|  W2  |
|    W3|
| ...  |
--------
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the frame if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • max_height (int) – Max height in px. If this value is lower than the frame height a scrollbar will appear on vertical axis. None by default (same height)

  • max_width (int) – Max width in px. If this value is lower than the frame width a scrollbar will appear on horizontal axis. None by default (same width)

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • scrollarea_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage,None) – Scroll area color. If None area is transparent

  • scrollbar_color (tuple, list, str, int, pygame.Color) – Scrollbar color

  • scrollbar_cursor (int, pygame.cursors.Cursor, None) – Cursor of the scrollbars if the mouse is placed over

  • scrollbar_shadow_color (tuple, list, str, int, pygame.Color) – Color of the shadow of each scrollbar

  • scrollbar_shadow_offset (int) – Offset of the scrollbar shadow in px

  • scrollbar_shadow_position (str) – Position of the scrollbar shadow. See pygame_menu.locals

  • scrollbar_shadow (bool) – Indicate if a shadow is drawn on each scrollbar

  • scrollbar_slider_color (tuple, list, str, int, pygame.Color) – Color of the sliders

  • scrollbar_slider_hover_color (tuple, list, str, int, pygame.Color) – Color of the slider if hovered or clicked

  • scrollbar_slider_pad (int, float) – Space between slider and scrollbars borders in px

  • scrollbar_thick (int) – Scrollbar thickness in px

  • scrollbars (str) – Scrollbar position. See pygame_menu.locals

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

Note

All theme-related optional kwargs use the default Menu theme if not defined.

Note

If vertical frame contains a scrollarea (setting max_height or max_width less than size) padding will be set at zero.

Note

Packing applies a virtual translation to the widget, previous translation is not modified.

Note

Widget floating is also considered within frames. If a widget is floating, it does not add any size to the respective positioning.

Note

The Frame size created with this method does consider the padding. Thus, if Frame is created with width=100, height=200 and padding=25 the final internal size is width=50 and height=150.

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.Menu.get_current() object.

Parameters
  • width (Union[int, float]) – Frame width in px

  • height (Union[int, float]) – Frame height in px

  • frame_id (str) – ID of the vertical frame

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.Frame

Add a generic widget

A user-created widget can also be added to the menu. The widget must be fully configured before the addition.

Example:

def check_color(value):
    print('New color:', value)

menu = pygame_menu.Menu(...)

widget_label = pygame_menu.widgets.Label(...)
widget_image = pygame_menu.widgets.Image(...)

# This applies menu default widget configuration
menu.add.generic_widget(widget_label, configure_defaults=True)

# Adds menu without default configuration
menu.add.generic_widget(widget_image)
WidgetManager.generic_widget(widget, configure_defaults=False)[source]

Add generic widget to the Menu.

Note

The widget should be fully configured by the user: font, padding, etc.

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.Menu.get_current() object.

Warning

Unintended behaviours may happen while using this method, use only with caution; specially while creating nested submenus with buttons.

Parameters
  • widget (Widget) – Widget to be added

  • configure_defaults (bool) – Apply defaults widget configuration (for example, theme)

Returns

The added widget object

Return type

pygame_menu.widgets.Widget

Add a label

A label is used to display a text. If the text is too large, it can be wrapped in order to fit the menu size.

Example:

../_images/widget_label.png
menu = pygame_menu.Menu(...)

HELP = 'Press ESC to enable/disable Menu ' \
       'Press ENTER to access a Sub-Menu or use an option ' \
       'Press UP/DOWN to move through Menu ' \
       'Press LEFT/RIGHT to move through Selectors.'
menu.add.label(HELP, max_char=-1, font_size=20)
WidgetManager.label(title, label_id='', max_char=0, onselect=None, selectable=False, **kwargs)

Add a simple text to the Menu.

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect. Applied only if selectable is True

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • tab_size (int) – Width of a tab character

  • underline_color (tuple, list, str, int, pygame.Color, None) – Color of the underline. If None use the same color of the text

  • underline_offset (int) – Vertical offset in px. 2 by default

  • underline_width (int) – Underline width in px. 2 by default

  • underline (bool) – Enables text underline, using a properly placed decoration. False by default

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Parameters
  • title (Any) – Text to be displayed

  • label_id (str) – ID of the label

  • max_char (int) – Split the title in several labels if the string length exceeds max_char; 0: don’t split, -1: split to Menu width

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget; only executed if selectable is True

  • selectable (bool) – Label accepts user selection; useful to move along the Menu using label selection

  • kwargs – Optional keyword arguments

Returns

Widget object, or List of widgets if the text overflows

Return type

pygame_menu.widgets.Label, typing.List [pygame_menu.widgets.Label]

Add a none widget

A none widget is used to fill column/row layout, store information or even add drawing callbacks for being executed on each menu draw.

menu = pygame_menu.Menu(...)

menu.add.none_widget()
WidgetManager.none_widget(widget_id='')

Add a none widget to the Menu.

Note

This widget is useful to fill column/rows layout without compromising any visuals. Also it can be used to store information or even to add a draw_callback function to it for being called on each Menu draw.

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.Menu.get_current() object.

Parameters

widget_id (str) – Widget ID

Returns

Widget object

Return type

pygame_menu.widgets.NoneWidget

Add a progress bar

A progress bar widget, which accepts a percentage from 0 to 100.

Example:

../_images/widget_progressbar.png
menu = pygame_menu.Menu(...)

progress1 = menu.add.progress_bar('My Progress', default=75.6)
progress2 = menu.add.progress_bar('Pygame-menu epicness?', default=99.9)
WidgetManager.progress_bar(title, default=0, onselect=None, progressbar_id='', progress_text_format=<function ProgressBarManager.<lambda>>, selectable=False, width=150, **kwargs)

Add a progress bar, which offers a bar that accepts a percentage from 0 to 100.

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • box_background_color (tuple, list, str, int, pygame.Color) – Background color of the box

  • box_border_color (tuple, list, str, int, pygame.Color) – Border color of the box

  • box_border_width (int) - Border width of the box in px

  • box_margin (tuple, list) - Box margin on x-axis and y-axis (x, y) respect to the title of the widget in px

  • box_progress_color (tuple, list, str, int, pygame.Color) – Box progress color

  • box_progress_padding (int, float, tuple, list) – Box progress padding

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • progress_text_align (str) - Align of the progress text, can be CENTER, LEFT or RIGHT. See pygame_menu.locals

  • progress_text_enabled (bool) - Enables the progress text over box

  • progress_text_font_color (tuple, list, str, int, pygame.Color) – Progress font color. If None uses the same as the widget font

  • progress_text_font_hfactor (int, float) - Height factor of the font height relative to the widget font height

  • progress_text_font (str, pathlib.Path, pygame.font.Font) – Progress font. If None uses the same as the widget font

  • progress_text_margin (tuple, list) - Margin of the progress box on x-axis and y-axis in px

  • progress_text_placeholder (str) - Placeholder of the progress text, which considers as format the output of progress_text_format. "{0} %" by default

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • tab_size (int) – Width of a tab character

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (Any) – Title of the progress bar

  • default (Union[int, float]) – Default value of the progressbar, from 0 to 100

  • onselect (Optional[Callable]) – Callback executed when selecting the widget

  • progressbar_id (str) – ID of the progress bar

  • progress_text_format (Callable[[Union[int, float]], str]) – Format function of the progress text, which considers as input the progress value (0-100)

  • selectable (bool) – Progress bar accepts user selection

  • width (int) – Progress bar width in px

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.ProgressBar

Add a range slider

A range slider offers 1 or 2 sliders for defining a unique value or a range of numeric ones; values can be continuous or discrete.

Example:

../_images/widget_rangeslider.png
menu = pygame_menu.Menu(...)

# Single value
menu.add.range_slider('Choose a number', 50, (0, 100), 1,
                      rangeslider_id='range_slider',
                      value_format=lambda x: str(int(x)))

# Range
menu.add.range_slider('Pick a range', (7, 10), (1, 10), 1)

# Discrete value
range_values_discrete = {0: 'A', 1: 'B', 2: 'C', 3: 'D', 4: 'E', 5: 'F'}
menu.add.range_slider('Pick a letter', 0, list(range_values_discrete.keys()),
                      slider_text_value_enabled=False,
                      value_format=lambda x: range_values_discrete[x])

# Numeric discrete range
menu.add.range_slider('Pick a discrete range', (2, 4), [0, 1, 2, 3, 4, 5], 1)
WidgetManager.range_slider(title, default, range_values, increment=None, onchange=None, onreturn=None, onselect=None, rangeslider_id='', value_format=<function RangeSliderManager.<lambda>>, width=150, **kwargs)

Add a range slider to the Menu: Offers 1 or 2 sliders for defining a unique value or a range of numeric ones.

If the state of the widget changes the onchange callback is called. The state can change by pressing LEFT/RIGHT, or by mouse/touch events.

onchange(range_value, **kwargs)

If pressing return key on the widget:

onreturn(range_value, **kwargs)

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • range_box_color_readonly (tuple, list, str, int, pygame.Color) - Color of the range box if widget in readonly state

  • range_box_color (tuple, list, str, int, pygame.Color) - Color of the range box between the sliders

  • range_box_enabled (bool) - Enables a range box between two sliders

  • range_box_height_factor (int, float) - Height of the range box (factor of the range title height)

  • range_box_single_slider (bool) - Enables range box if there’s only 1 slider instead of 2

  • range_line_color (tuple, list, str, int, pygame.Color) - Color of the range line

  • range_line_height (int) - Height of the range line in px

  • range_margin (tuple, list) - Range margin on x-axis and y-axis (x, y) from title in px

  • range_text_value_color (tuple, list, str, int, pygame.Color) - Color of the range values text

  • range_text_value_enabled (bool) - Enables the range values text

  • range_text_value_font_height (int, float) - Height factor of the range value font (factor of the range title height)

  • range_text_value_font (str, pathlib.Path, pygame.font.Font) - Font of the ranges value. If None the same font as the widget is used

  • range_text_value_margin_f (int, float) - Margin of the range text values (factor of the range title height)

  • range_text_value_position (str) - Position of the range text values, can be NORTH or SOUTH. See pygame_menu.locals

  • range_text_value_tick_color (tuple, list, str, int, pygame.Color) - Color of the range text value tick

  • range_text_value_tick_enabled (bool) - Range text value tick enabled

  • range_text_value_tick_hfactor (bool) Height factor of the range text value tick (factor of the range title height)

  • range_text_value_tick_number (int) - Number of range value text, the values are placed uniformly distributed

  • range_text_value_tick_thick (int) - Thickness of the range text value tick in px

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • repeat_keys_initial_ms (int) - Time in ms before keys are repeated when held in ms. 400 by default

  • repeat_keys_interval_ms (int) - Interval between key press repetition when held in ms. 50 by default

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • slider_color (tuple, list, str, int, pygame.Color) - Slider color

  • slider_height_factor (int, float) - Height of the slider (factor of the range title height)

  • slider_sel_highlight_color (tuple, list, str, int, pygame.Color) - Color of the selected slider highlight box effect

  • slider_sel_highlight_enabled (bool) - Selected slider is highlighted

  • slider_sel_highlight_thick (int) - Thickness of the selected slider highlight

  • slider_selected_color (tuple, list, str, int, pygame.Color) - Selected slider color

  • slider_text_value_bgcolor (tuple, list, str, int, pygame.Color) - Background color of the value text on each slider

  • slider_text_value_color (tuple, list, str, int, pygame.Color) - Color of value text on each slider

  • slider_text_value_enabled (bool) - Enables a value text on each slider

  • slider_text_value_font_height (int, float) - Height factor of the slider font (factor of the range title height)

  • slider_text_value_font (str, pathlib.Path, pygame.font.Font) - Font of the slider value. If None the same font as the widget is used

  • slider_text_value_margin_f (int, float) - Margin of the slider text values (factor of the range title height)

  • slider_text_value_padding (int, float, tuple, list) – Padding of the slider text values

  • slider_text_value_position (str) - Position of the slider text values, can be NORTH or SOUTH. See pygame_menu.locals

  • slider_text_value_triangle (bool) - Draws a triangle between slider text value and slider

  • slider_thickness (int) - Slider thickness in px

  • slider_vmargin (int, float) - Vertical margin of the slider (factor of the range title height)

  • tab_size (int) – Width of a tab character

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (str) – Title of the range slider

  • default (Union[int, float, Tuple[Union[int, float], Union[int, float]], List[Union[int, float]]]) – Default range value, can accept a number or a tuple/list of 2 elements (min, max). If a single number is provided the rangeslider only accepts 1 value, if 2 are provided, the range is enabled (2 values)

  • range_values (Union[Tuple[Union[int, float], Union[int, float]], List[Union[int, float]], Tuple[Union[int, float], …]]) – Tuple/list of 2 elements of min/max values of the range slider. Also range can accept a list of numbers, in which case the values of the range slider will be discrete. List must be sorted

  • increment (Union[int, float, None]) – Increment of the value if using left/right keys; used only if the range values are not discrete

  • onchange (Optional[Callable]) – Callback executed when when changing the value of the range slider

  • onreturn (Optional[Callable]) – Callback executed when pressing return on the range slider

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget

  • rangeslider_id (str) – ID of the range slider

  • value_format (Callable[[Union[int, float]], str]) – Function that format the value and returns a string that is used in the range and slider text

  • width (int) – Width of the range in px

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.RangeSlider

Add a surface

A surface widget only accepts an external surface which is drawn on the Menu. The widget size is the same as the surface, considering also the margin and the padding.

Example:

../_images/widget_surface.png
menu = pygame_menu.Menu(...)

new_surface = pygame.Surface((160, 160))
new_surface.fill((255, 192, 203))
inner_surface = pygame.Surface((80, 80))
inner_surface.fill((75, 0, 130))
new_surface.blit(inner_surface, (40, 40))
menu.add.surface(new_surface)
WidgetManager.surface(surface, surface_id='', onselect=None, selectable=False, **kwargs)

Add a surface widget to the Menu.

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect. Applied only if selectable is True

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Parameters
  • surface (Surface) – Pygame surface object

  • surface_id (str) – Surface ID

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget; only executed if selectable is True

  • selectable (bool) – Surface accepts user selection

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.SurfaceWidget

Add a table

A table is a frame which packs widgets in a structured way. Tables can contain a text, numbers, or even more widgets (Frames, Tables, Images, etc). All widgets are read-only, them do not accept any event, only scrollable frames work.

Example:

../_images/widget_table.png
menu = pygame_menu.Menu(...)

table = menu.add.table(table_id='my_table', font_size=20)
table.default_cell_padding = 5
table.default_row_background_color = 'white'
table.add_row(['First item', 'Second item', 'Third item'],
              cell_font=pygame_menu.font.FONT_OPEN_SANS_BOLD)
table.add_row(['A', 'B', 1])
table.add_row(['α', 'β', 'γ'], cell_align=pygame_menu.locals.ALIGN_CENTER)

The following example show an advanced example, featuring tables within a table, and a widget (Image):

../_images/widget_table_advanced.png
menu = pygame_menu.Menu(...)

table = menu.add.table(font_size=20)
table.default_cell_padding = 5
table.default_cell_align = pygame_menu.locals.ALIGN_CENTER
table.default_row_background_color = 'white'
table.add_row(['A', 'B', 'C'],
              cell_font=pygame_menu.font.FONT_OPEN_SANS_BOLD)

# Sub-table
table_2 = menu.add.table(font_size=20)
table_2.default_cell_padding = 20
table_2.add_row([1, 2])
table_2.add_row([3, 4])

# Sub image
image = menu.add.image(pygame_menu.baseimage.IMAGE_EXAMPLE_PYGAME_MENU)
image.scale(0.25, 0.25)

# Add the sub-table and the image
table.add_row([table_2, '', image],
              cell_vertical_position=pygame_menu.locals.POSITION_CENTER)
table.update_cell_style(1, 2, padding=0)  # Disable padding for cell column 1, row 2 (table_2)
table.update_cell_style(2, 2, border_position=pygame_menu.locals.POSITION_SOUTH)
table.update_cell_style(3, 2, border_position=(pygame_menu.locals.POSITION_SOUTH,
                                               pygame_menu.locals.POSITION_EAST))
WidgetManager.table(table_id='', **kwargs)

Adds a Table to the Menu. A table is a frame which can pack widgets in a structured way.

kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the frame if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • max_height (int) – Max height in px. If lower than the frame height a scrollbar will appear on vertical axis. None by default (same height)

  • max_width (int) – Max width in px. If lower than the frame width a scrollbar will appear on horizontal axis. None by default (same width)

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Parameters
  • table_id (str) – ID of the table

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.Table

Add a text entry

A text input permits to enter a string using a keyboard. Restriction on entered characters can be set using input_type, maxchar, maxwidth and valid_chars parameters.

Example:

../_images/widget_textinput.png
menu = pygame_menu.Menu(...)

def check_name(value):
    print('User name:', value)

menu.add.text_input('First name: ', default='John', onreturn=check_name)
menu.add.text_input('Last name: ', default='Doe', maxchar=10, input_underline='_')
menu.add.text_input('Password: ', input_type=pygame_menu.locals.INPUT_INT, password=True)
WidgetManager.text_input(title, default='', copy_paste_enable=True, cursor_selection_enable=True, cursor_size=None, input_type='input-text', input_underline='', input_underline_len=0, maxchar=0, maxwidth=0, onchange=None, onreturn=None, onselect=None, password=False, textinput_id='', valid_chars=None, **kwargs)

Add a text input to the Menu: free text area and two functions that execute when changing the text and pressing return button on the element.

The callbacks receive the current value and all unknown keyword arguments, where current_text=widget.get_value:

onchange(current_text, **kwargs)
onreturn(current_text, **kwargs)

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • history (int) - Maximum number of editions stored. If 0 the feature is disabled. 50 by default

  • input_underline_vmargin (int) – Vertical margin of underline in px

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • maxwidth_dynamically_update (bool) - Dynamically update maxwidth depending on char size. True by default

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • password_char (str) - Character used by password type. "*" by default

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • repeat_keys_initial_ms (int, float) - Time in ms before keys are repeated when held in ms. 400 by default

  • repeat_keys_interval_ms (int, float) - Interval between key press repetition when held in ms. 50 by default

  • repeat_mouse_interval_ms (int, float) - Interval between mouse events when held in ms. 400 by default

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • tab_size (int) – Width of a tab character

  • text_ellipsis (str) - Ellipsis text when overflow occurs (input length exceeds maxwidth). "..." by default

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (Any) – Title of the text input

  • default (Union[str, int, float]) – Default value to display

  • copy_paste_enable (bool) – Enable text copy, paste and cut

  • cursor_selection_enable (bool) – Enable text selection on input

  • cursor_size (Optional[Tuple[int, int]]) – Size of the cursor (width, height) in px. If None uses the default sizing

  • input_type (str) – Data type of the input. See pygame_menu.locals

  • input_underline (str) – Underline character

  • input_underline_len (int) – Total of characters to be drawn under the input. If 0 this number is computed automatically to fit the font

  • maxchar (int) – Maximum length of string, if 0 there’s no limit

  • maxwidth (int) – Maximum size of the text widget (in number of chars), if 0 there’s no limit

  • onchange (Optional[Callable]) – Callback executed when changing the text input

  • onreturn (Optional[Callable]) – Callback executed when pressing return on the text input

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget

  • password (bool) – Text input is a password

  • textinput_id (str) – ID of the text input

  • valid_chars (Optional[List[str]]) – List of authorized chars. None if all chars are valid

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.TextInput

Add a toggle switch

A fully customizable switch between two states (On, Off). If you need more options, take a look at the ToggleSwitch widget class.

Example:

../_images/widget_toggleswitch.png
menu = pygame_menu.Menu(...)

menu.add.toggle_switch('First Switch', False, toggleswitch_id='first_switch')
menu.add.toggle_switch('Other Switch', True, toggleswitch_id='second_switch',
                       state_text=('Apagado', 'Encencido'), state_text_font_size=18)
WidgetManager.toggle_switch(title, default=0, onchange=None, onselect=None, toggleswitch_id='', single_click=True, state_text=('Off', 'On'), state_values=(False, True), width=150, **kwargs)

Add a toggle switch to the Menu: It can switch between two states.

If user changes the status of the callback, onchange is fired:

onchange(current_state_value, **kwargs)

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color

  • font_color (tuple, list, str, int, pygame.Color) – Widget font color

  • font_name (str, pathlib.Path, pygame.font.Font) – Widget font path

  • font_shadow_color (tuple, list, str, int, pygame.Color) – Font shadow color

  • font_shadow_offset (int) – Font shadow offset in px

  • font_shadow_position (str) – Font shadow position, see locals for position

  • font_shadow (bool) – Font shadow is enabled or disabled

  • font_size (int) – Font size of the widget

  • infinite (bool) – The state can rotate. False by default

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the widget if readonly mode and is selected

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

  • single_click_dir (bool) - Direction of the change if only 1 click is pressed. True for left direction (default), False for right

  • slider_color (tuple, list, str, int, pygame.Color) – Color of the slider

  • slider_height_factor (int, float) - Height of the slider (factor of the switch height). 1 by default

  • slider_thickness (int) – Slider thickness in px. 20 px by default

  • slider_vmargin (int, float) - Vertical margin of the slider (factor of the switch height). 0 by default

  • state_color (tuple) – 2-item color tuple for each state

  • state_text_font (str, pathlib.Path, pygame.font.Font, None) - Font of the state text. If None uses the widget font. None by default

  • state_text_font_color (tuple) – 2-item color tuple for each font state text color

  • state_text_font_size (str, None) – Font size of the state text. If None uses the widget font size

  • state_text_position (tuple) - Position of the state text respect to the switch rect. (0.5, 0.5) by default

  • switch_border_color (tuple, list, str, int, pygame.Color) – Switch border color

  • switch_border_width (int) – Switch border width

  • switch_height (int, float) – Height factor respect to the title font size height

  • switch_margin (tuple, list) – Switch on x-axis and y-axis (x, y) margin respect to the title of the widget in px

  • tab_size (int) – Width of a tab character

Note

This method only handles two states. If you need more states (for example 3, or 4), prefer using pygame_menu.widgets.ToggleSwitch and add it as a generic widget.

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Warning

Be careful with kwargs collision. Consider that all optional documented kwargs keys are removed from the object.

Parameters
  • title (Any) – Title of the toggle switch

  • default (Union[int, bool]) – Default state index of the switch; it can be 0 (False) or 1 (True)

  • onchange (Optional[Callable]) – Callback executed when when changing the state of the toggle switch

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget

  • toggleswitch_id (str) – Widget ID

  • single_click (bool) – Changes the state of the switch with 1 click instead of finding the closest position

  • state_text (Tuple[str, …]) – Text of each state

  • state_values (Tuple[Any, …]) – Value of each state of the switch

  • width (int) – Width of the switch box in px

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.ToggleSwitch

Add a vertical spacer

A vertical spacer can be added between two widgets to have a better visual rendering of the menu.

Example:

../_images/widget_vmargin.png
menu = pygame_menu.Menu(...)

menu.add.label('Text #1')
menu.add.vertical_margin(100)
menu.add.label('Text #2')
WidgetManager.vertical_margin(margin, margin_id='')

Adds a vertical margin to 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.Menu.get_current() object.

Parameters
  • margin (Union[int, float]) – Vertical margin in px

  • margin_id (str) – ID of the vertical margin

Returns

Widget object

Return type

pygame_menu.widgets.VMargin

Add an image

An image can be displayed on a menu. The scale parameter represent the scaling ratio of the image width and height. When scale_smooth=True, the rendering is better but it requires more CPU resources.

Example:

../_images/widget_image.png
menu = pygame_menu.Menu(...)

image_path = pygame_menu.baseimage.IMAGE_EXAMPLE_PYGAME_MENU
menu.add.image(image_path, angle=10, scale=(0.15, 0.15))
menu.add.image(image_path, angle=-10, scale=(0.15, 0.15))
WidgetManager.image(image_path, angle=0, image_id='', onselect=None, scale=(1, 1), scale_smooth=True, selectable=False, **kwargs)

Add a simple image to the Menu.

If onselect is defined, the callback is executed as follows, where selected is a boolean representing the selected status:

onselect(selected, widget, menu)
kwargs (Optional)
  • align (str) – Widget alignment

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Color of the background. None for no-color

  • background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px

  • border_color (tuple, list, str, int, pygame.Color) – Widget border color. None for no-color

  • border_inflate (tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in px

  • border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • border_width (int) – Border width in px. If 0 disables the border

  • cursor (int, pygame.cursors.Cursor, None) – Cursor of the widget if the mouse is placed over

  • float (bool) - If True the widget don’t contributes width/height to the Menu widget positioning computation, and don’t add one unit to the rows

  • float_origin_position (bool) - If True the widget position is set to the top-left position of the Menu if the widget is floating

  • margin (tuple, list) – Widget (left, bottom) margin in px

  • padding (int, float, tuple, list) – Widget padding according to CSS rules. General shape: (top, right, bottom, left)

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget; only affects the font color

  • selection_effect (pygame_menu.widgets.core.Selection) – Widget selection effect. Applied only if selectable is True

  • shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget shadow

  • shadow_radius (int) - Border radius of the shadow

  • shadow_type (str) - Shadow type, it can be 'rectangular' or 'ellipse'

  • shadow_width (int) - Width of the shadow. If 0 the shadow is disabled

Note

All theme-related optional kwargs use the default Menu theme if not defined.

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.Menu.get_current() object.

Parameters
  • image_path (Union[str, Path, BaseImage, BytesIO]) – Path of the image (file) or a BaseImage object. If BaseImage object is provided the angle and scale are ignored

  • angle (Union[int, float]) – Angle of the image in degrees (clockwise)

  • image_id (str) – ID of the image

  • onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget; only executed if selectable is True

  • scale (Union[Tuple[Union[int, float], Union[int, float]], List[Union[int, float]]]) – Scale of the image on x-axis and y-axis (x, y)

  • scale_smooth (bool) – Scale is smoothed

  • selectable (bool) – Image accepts user selection

  • kwargs – Optional keyword arguments

Returns

Widget object

Return type

pygame_menu.widgets.Image