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:

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 contribute 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 button banner

Adds a clickable button using only an Image.

Example:

menu = pygame_menu.Menu(...)

image = pygame_menu.BaseImage(
    image_path=pygame_menu.baseimage.IMAGE_EXAMPLE_PYGAME_MENU
).scale(0.25, 0.25)
menu.add.banner(image, pygame_menu.events.EXIT)

WidgetManager.banner(image, action=None, *args, **kwargs)

Adds a clickeable image to the Menu with same behaviour as a Button.

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

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:

image (BaseImage) – Image of the clickeable 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:

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 (apply) 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 contribute 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 changing the selector
onreturn (Optional[Callable]) – Callback executed when pressing return (apply)
onselect (Optional[Callable[[bool, Widget, Menu], Any]]) – Callback executed when selecting the widget
selector_id (str) – ID of the selector
style (str) – 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:

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}', wordwrap=False, **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 contribute 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
leading (int) - Font leading for wordwrap. If None retrieves from widget font
margin (tuple, list) – Widget (left, bottom) margin in px
max_nlines (int) - Number of maximum lines for wordwrap. If None the number is dynamically computed. If exceded, label.get_overflow_lines() will return the lines not displayed
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
wordwrap (bool) – Wraps label if newline is found on widget. If False the manager splits the string and creates a list of widgets, else, the widget itself splits and updates the height
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:

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 contribute 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 (bool) - Enable key repeat. True by default
repeat_keys_initial_ms (int, float) - Time in milliseconds before keys are repeated when held in milliseconds. 400 by default
repeat_keys_interval_ms (int, float) - Interval between key press repetition when held in milliseconds. 50 by default
repeat_mouse_interval_ms (int, float) - Interval between mouse events when held in milliseconds. 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 (str) – 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 (str) – 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 (apply) 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:

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 contribute 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 (apply) 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 contribute 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 (apply) 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[str, 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:

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:

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 contribute 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 contribute 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:

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, wordwrap=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 contribute 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
leading (int) - Font leading for wordwrap. If None retrieves from widget font
margin (tuple, list) – Widget (left, bottom) margin in px
max_nlines (int) - Number of maximum lines for wordwrap. If None the number is dynamically computed. If exceded, label.get_overflow_lines() will return the lines not displayed
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
wordwrap (bool) – Wraps label if newline is found on widget. If False the manager splits the string and creates a list of widgets, else, the widget itself splits and updates the height
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 menu link

Menu links are widgets that opens a new Menu within the parent Menu without using a button. Links can be opened using the open method.

Example:

menu = pygame_menu.Menu(...)
menu1 = pygame_menu.Menu(...)
menu2 = pygame_menu.Menu(...)
menu3 = pygame_menu.Menu(...)

def open_link(*args) -> None:
    link: 'pygame_menu.widgets.MenuLink' = args[-1]
    link.open()

# Create the links
link1 = menu.add.menu_link(menu1)
link2 = menu.add.menu_link(menu2)
link3 = menu.add.menu_link(menu3)

# Add a selection object, which opens the links
sel = menu.add.selector('Change menu ', [
    ('Menu 1', link1),
    ('Menu 2', link2),
    ('Menu 3', link3)
], onreturn=open_link)

WidgetManager.menu_link(menu, link_id='')

Adds a link to another Menu. The behaviour is similar to a button, but this widget is invisible, and cannot be selectable.

Added menus can be opened using the .open() method. Opened menus change the state of the parent Menu (the current pointer).

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:

menu (Menu) – Menu to be added as a link (the new submenu)
link_id (str) – ID of the menu link

Returns:

Menu link widget

Return type:

pygame_menu.widgets.MenuLink

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:

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 contribute 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:

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 (apply) 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 contribute 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 (bool) - Enable key repeat. True by default
repeat_keys_initial_ms (int) - Time in milliseconds before keys are repeated when held in milliseconds. 400 by default
repeat_keys_interval_ms (int) - Interval between key press repetition when held in milliseconds. 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 changing the value of the range slider
onreturn (Optional[Callable]) – Callback executed when pressing return (apply) 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:

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 contribute 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:

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

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 contribute 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:

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 (apply) 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 contribute 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 (bool) - Enable key repeat. True by default
repeat_keys_initial_ms (int, float) - Time in milliseconds before keys are repeated when held in milliseconds. 400 by default
repeat_keys_interval_ms (int, float) - Interval between key press repetition when held in milliseconds. 50 by default
repeat_mouse_interval_ms (int, float) - Interval between mouse events when held in milliseconds. 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 (apply) 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:

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', 'Encendido'), 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 contribute 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 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 fill

A vertical fill adds a vertical margin to fill the menu height. It depends on other vertical fillers in the same column, i.e., if three vertical fillers are in the same column, them will take a third of the available vertical space.

Example:

menu = pygame_menu.Menu(...)

menu.add.vertical_fill()
menu.add.button('Button 1')
menu.add.vertical_fill()
menu.add.button('Button 2')
menu.add.vertical_fill()

WidgetManager.vertical_fill(min_height=0, vfill_id='')

Adds a vertical fill to the Menu. This widget fills all vertical space if available, else, it uses the min height.

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:

min_height (Union[int, float]) – Minimum height in px
vfill_id (str) – ID of the vertical fill

Returns:

Widget object

Return type:

pygame_menu.widgets.VFill

Add a vertical spacer

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

Example:

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 a url link

Adds a clickable url link.

Example:

menu = pygame_menu.Menu(...)

menu.add.url('https://github.com/ppizarror/pygame-menu')
menu.add.url('https://github.com/ppizarror/pygame-menu', 'The best menu ever')
menu.add.url('https://pygame-menu.readthedocs.io/en/master/', 'pygame-menu documentation')

WidgetManager.url(href, title='', **kwargs)

Adds a Button url to the Menu. Clicking the widget will open the link. If title is defined, the link will not be written. For example: href='google.com', title='' will write the link, but href='google.com', title='Google' will write ‘Google’ and opens ‘google.com’ if clicked.

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. By default, is HAND
float (bool) - If True the widget don’t contribute 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. If not defined, uses theme.widget_url_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
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. True 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:

href (str) – Link to open
title (str) – Alternative title of the link
kwargs – Optional keyword arguments

Returns:

Widget object, or List of widgets if the text overflows

Return type:

pygame_menu.widgets.Button

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:

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 contribute 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