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:
an other
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.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)
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, whereselected
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 defaultalign
(str) – Widget alignmentback_count
(int) – Number of menus to go back if action ispygame_menu.events.BACK
event, default is1
background_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the borderbutton_id
(str) – Widget IDcursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetmargin
(tuple, list) – Widget (left, bottom) margin in pxonselect
(callable, None) – Callback executed when selecting the widgetpadding
(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 modereadonly_selected_color
(tuple, list, str, int,pygame.Color
) – Color of the widget if readonly mode and is selectedselection_color
(tuple, list, str, int,pygame.Color
) – Color of the selected widget; only affects the font colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effecttab_size
(int) – Width of a tab characterunderline_color
(tuple, list, str, int,pygame.Color
, None) – Color of the underline. IfNone
use the same color of the textunderline_offset
(int) – Vertical offset in px.2
by defaultunderline_width
(int) – Underline width in px.2
by defaultunderline
(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 usingaction=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 topygame_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
- Returns
Widget object
- Return type
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
)
Add a selector to the Menu: several items and two functions that are executed when changing the selector (left/right) and pressing return button on the selected item.
The items of the selector are like:
items = [('Item1', a, b, c...), ('Item2', d, e, f...)]
The callbacks receive the current selected item, its index in the list, the associated arguments, and all unknown keyword arguments, where
selected_item=widget.get_value()
andselected_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
thenselected_item=('Item1', a, b, c...)
.If
onselect
is defined, the callback is executed as follows, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 modereadonly_selected_color
(tuple, list, str, int,pygame.Color
) – Color of the widget if readonly mode and is selectedselection_color
(tuple, list, str, int,pygame.Color
) – Color of the selected widget; only affects the font colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effectstyle_fancy_arrow_color
(tuple, list, str, int,pygame.Color
) – Arrow color of fancy stylestyle_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 stylestyle_fancy_bordercolor
(tuple, list, str, int,pygame.Color
) – Border color of fancy stylestyle_fancy_borderwidth
(int) – Border width of fancy style;1
by defaultstyle_fancy_box_inflate
(tuple, list) – Box inflate of fancy style on x-axis and y-axis (x, y) in pxstyle_fancy_box_margin
(tuple, list) – Box margin on x-axis and y-axis (x, y) in fancy style from title in pxtab_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 topygame_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 selectoritems (
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 displayonchange (
Optional
[Callable
]) – Callback executed when when changing the selectoronreturn (
Optional
[Callable
]) – Callback executed when pressing return buttononselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Callback executed when selecting the widgetselector_id (
str
) – ID of the selectorstyle (
Literal
[‘classic’, ‘fancy’]) – Selector style (visual)kwargs – Optional keyword arguments
- Returns
Widget object
- Return type
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)
Add a clock label to the Menu. This creates a Label with a text generator that request a string from
time.strftime
module usingclock_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, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effect. Applied only ifselectable
isTrue
tab_size
(int) – Width of a tab characterunderline_color
(tuple, list, str, int,pygame.Color
, None) – Color of the underline. IfNone
use the same color of the textunderline_offset
(int) – Vertical offset in px.2
by defaultunderline_width
(int) – Underline width in px.2
by defaultunderline
(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 topygame_menu.menu.Menu.get_current()
object.- Parameters
clock_format (
str
) – Format of clock used bytime.strftime
clock_id (
str
) – ID of the clockonselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Callback executed when selecting the widget; only executed ifselectable
isTrue
selectable (
bool
) – Label accepts user selection; useful to move along the Menu using label selectiontitle_format (
str
) – Title format which accepts{0}
as the string fromtime.strftime
, for example,'My Clock {0}'
can be a title formatkwargs – Optional keyword arguments
- Returns
Widget object
- Return type
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)
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, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overdynamic_width
(bool) – IfTrue
the widget width changes if the pre-visualization color box is active or notfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetinput_underline_vmargin
(int) – Vertical margin of underline in pxmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 is0
previsualization_width
(int, float) – Pre-visualization width as a factor of the height. Default is3
readonly_color
(tuple, list, str, int,pygame.Color
) – Color of the widget if readonly modereadonly_selected_color
(tuple, list, str, int,pygame.Color
) – Color of the widget if readonly mode and is selectedselection_color
(tuple, list, str, int,pygame.Color
) – Color of the selected widget; only affects the font colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effecttab_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 topygame_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
color_type (
Literal
[‘rgb’, ‘hex’]) – Type of the color inputcolor_id (
str
) – ID of the color inputdefault (
Union
[str
,Tuple
[int
,int
,int
]]) – Default value to display, if RGB type it must be a tuple(r, g, b)
, if HEX must be a string"#XXXXXX"
hex_format (
Literal
[‘lower’, ‘upper’, ‘none’]) – Hex format string modeinput_separator (
str
) – Divisor between RGB channels, not valid in HEX formatinput_underline (
str
) – Underline characteronchange (
Optional
[Callable
]) – Callback executed when changing the values of the color textonreturn (
Optional
[Callable
]) – Callback executed when pressing return on the color text inputonselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Callback executed when selecting the widgetkwargs – Optional keyword arguments
- Returns
Widget object
- Return type
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
)
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()
andselected_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
thenselected_item=('Item1', a, b, c...)
.If
onselect
is defined, the callback is executed as follows, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 modereadonly_selected_color
(tuple, list, str, int,pygame.Color
) – Color of the widget if readonly mode and is selectedselection_color
(tuple, list, str, int,pygame.Color
) – Color of the selected widget; only affects the font colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effecttab_size
(int) – Width of a tab character
- kwargs for modifying selection box/option style (Optional)
scrollbar_color
(tuple, list, str, int,pygame.Color
) – Scrollbar colorscrollbar_cursor
(int,pygame.cursors.Cursor
, None) – Cursor of the scrollbars if the mouse is placed overscrollbar_shadow_color
(tuple, list, str, int,pygame.Color
) – Color of the shadow of each scrollbarscrollbar_shadow_offset
(int) – Offset of the scrollbar shadow in pxscrollbar_shadow_position
(str) – Position of the scrollbar shadow. Seepygame_menu.locals
scrollbar_shadow
(bool) – Indicate if a shadow is drawn on each scrollbarscrollbar_slider_color
(tuple, list, str, int,pygame.Color
) – Color of the slidersscrollbar_slider_hover_color
(tuple, list, str, int,pygame.Color
) – Color of the slider if hovered or clickedscrollbar_slider_pad
(int, float) – Space between slider and scrollbars borders in pxscrollbar_thick
(int) – Scrollbar thickness in pxscrollbars
(str) – Scrollbar position. Seepygame_menu.locals
selection_box_arrow_color
(tuple, list, str, int,pygame.Color
) – Selection box arrow colorselection_box_arrow_margin
(tuple) – Selection box arrow margin (left, right, vertical) in pxselection_box_bgcolor
(tuple, list, str, int,pygame.Color
) – Selection box background colorselection_box_border_color
(tuple, list, str, int,pygame.Color
) – Selection box border colorselection_box_border_width
(int) – Selection box border widthselection_box_height
(int) – Selection box height, counted as how many options are packed before showing scrollselection_box_inflate
(tuple) – Selection box inflate on x-axis and y-axis (x, y) in pxselection_box_margin
(tuple, list) – Selection box on x-axis and y-axis (x, y) margin from title in pxselection_box_text_margin
(int) – Selection box text margin (left) in pxselection_box_width
(int) – Selection box width in px. If0
compute automatically to fit placeholderselection_infinite
(bool) – IfTrue
selection can rotate through bottom/topselection_option_border_color
(tuple, list, str, int,pygame.Color
) – Option border colorselection_option_border_width
(int) – Option border widthselection_option_font_color
(tuple, list, str, int,pygame.Color
) – Option font colorselection_option_font_size
(int, None) – Option font size. IfNone
use the 75% of the widget font sizeselection_option_font
(str,pathlib.Path
,pygame.font.Font
) – Option font. IfNone
use the same font as the widgetselection_option_padding
(int, float, tuple, list ) – Selection padding. See padding stylingselection_option_selected_bgcolor
(tuple, list, str, int,pygame.Color
) – Selected option background colorselection_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 topygame_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 titleitems (
Union
[List
[Tuple
[Any
, …]],List
[str
]]) – Item list of the drop select; format[('Item1', a, b, c...), ('Item2', d, e, f...)]
default (
int
) – Index of default item to displaydropselect_id (
str
) – ID of the selectoronchange (
Optional
[Callable
]) – Callback when changing the drop select itemonreturn (
Optional
[Callable
]) – Callback when pressing return on the selected itemonselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Function when selecting the widgetopen_middle (
bool
) – IfTrue
the selection box is opened in the middle of the menuplaceholder (
str
) – Text shown if no option is selected yetplaceholder_add_to_selection_box (
bool
) – IfTrue
adds the placeholder button to the selection boxkwargs – Optional keyword arguments
- Returns
Widget object
- Return type
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:
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
)
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()
andselected_index=widget.get_index()
:onchange((selected_item, selected_index), **kwargs) onreturn((selected_item, selected_index), **kwargs)
For example, if
selected_index=[0, 2]
thenselected_item=[('Item1', a, b, c...), ('Item3', g, h, i...)]
.If
onselect
is defined, the callback is executed as follows, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 modereadonly_selected_color
(tuple, list, str, int,pygame.Color
) – Color of the widget if readonly mode and is selectedselection_color
(tuple, list, str, int,pygame.Color
) – Color of the selected widget; only affects the font colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effecttab_size
(int) – Width of a tab character
- kwargs for modifying selection box/option style (Optional)
scrollbar_color
(tuple, list, str, int,pygame.Color
) – Scrollbar colorscrollbar_cursor
(int,pygame.cursors.Cursor
, None) – Cursor of the scrollbars if the mouse is placed overscrollbar_shadow_color
(tuple, list, str, int,pygame.Color
) – Color of the shadow of each scrollbarscrollbar_shadow_offset
(int) – Offset of the scrollbar shadow in pxscrollbar_shadow_position
(str) – Position of the scrollbar shadow. Seepygame_menu.locals
scrollbar_shadow
(bool) – Indicate if a shadow is drawn on each scrollbarscrollbar_slider_color
(tuple, list, str, int,pygame.Color
) – Color of the slidersscrollbar_slider_hover_color
(tuple, list, str, int,pygame.Color
) – Color of the slider if hovered or clickedscrollbar_slider_pad
(int, float) – Space between slider and scrollbars borders in pxscrollbar_thick
(int) – Scrollbar thickness in pxscrollbars
(str) – Scrollbar position. Seepygame_menu.locals
selection_box_arrow_color
(tuple, list, str, int,pygame.Color
) – Selection box arrow colorselection_box_arrow_margin
(tuple) – Selection box arrow margin (left, right, vertical) in pxselection_box_bgcolor
(tuple, list, str, int,pygame.Color
) – Selection box background colorselection_box_border_color
(tuple, list, str, int,pygame.Color
) – Selection box border colorselection_box_border_width
(int) – Selection box border widthselection_box_height
(int) – Selection box height, counted as how many options are packed before showing scrollselection_box_inflate
(tuple) – Selection box inflate on x-axis and y-axis in pxselection_box_margin
(tuple, list) – Selection box on x-axis and y-axis (x, y) margin from title in pxselection_box_text_margin
(int) – Selection box text margin (left) in pxselection_box_width
(int) – Selection box width in px. If0
compute automatically to fit placeholderselection_infinite
(bool) – IfTrue
selection can rotate through bottom/topselection_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 colorselection_option_border_color
(tuple, list, str, int,pygame.Color
) – Option border colorselection_option_border_width
(int) – Option border widthselection_option_font_color
(tuple, list, str, int,pygame.Color
) – Option font colorselection_option_font_size
(int, None) – Option font size. IfNone
use the 75% of the widget font sizeselection_option_font
(str,pathlib.Path
,pygame.font.Font
) – Option font. IfNone
use the same font as the widgetselection_option_padding
(int, float, tuple, list) – Selection padding. See padding stylingselection_option_selected_bgcolor
(tuple, list, str, int,pygame.Color
) – Selected option background colorselection_option_selected_box_border
(int) – Box border width in pxselection_option_selected_box_color
(tuple, list, str, int,pygame.Color
) – Box colorselection_option_selected_box_height
(int, float) – Height of the selection box relative to the options heightselection_option_selected_box_margin
(tuple, list) – Option box margin (left, right, vertical) in pxselection_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 topygame_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 titleitems (
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. IfNone
no item is selecteddropselect_multiple_id (
str
) – ID of the selectormax_selected (
int
) – Max items to be selected. If0
there’s no limitonchange (
Optional
[Callable
]) – Callback when changing the drop select itemonreturn (
Optional
[Callable
]) – Callback when pressing return on the selected itemonselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Function when selecting the widgetopen_middle (
bool
) – IfTrue
the selection box is opened in the middle of the menuplaceholder (
str
) – Text shown if no option is selected yetplaceholder_add_to_selection_box (
bool
) – IfTrue
adds the placeholder button to the selection boxplaceholder_selected (
str
) – Text shown if option is selected. Accepts the number of selected optionskwargs – Optional keyword arguments
- Returns
Widget object
- Return type
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='b{}'.format(i)))
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 alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the frame if the mouse is placed overmargin
(tuple, list) – Widget (left, bottom) margin in pxmax_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)scrollarea_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
,None) – Scroll area color. IfNone
area is transparentscrollbar_color
(tuple, list, str, int,pygame.Color
) – Scrollbar colorscrollbar_cursor
(int,pygame.cursors.Cursor
, None) – Cursor of the scrollbars if the mouse is placed overscrollbar_shadow_color
(tuple, list, str, int,pygame.Color
) – Color of the shadow of each scrollbarscrollbar_shadow_offset
(int) – Offset of the scrollbar shadow in pxscrollbar_shadow_position
(str) – Position of the scrollbar shadow. Seepygame_menu.locals
scrollbar_shadow
(bool) – Indicate if a shadow is drawn on each scrollbarscrollbar_slider_color
(tuple, list, str, int,pygame.Color
) – Color of the slidersscrollbar_slider_hover_color
(tuple, list, str, int,pygame.Color
) – Color of the slider if hovered or clickedscrollbar_slider_pad
(int, float) – Space between slider and scrollbars borders in pxscrollbar_thick
(int) – Scrollbar thickness in pxscrollbars
(str) – Scrollbar position. Seepygame_menu.locals
tab_size
(int) – Width of a tab character
Note
All theme-related optional kwargs use the default Menu theme if not defined.
Note
If horizontal frame contains a scrollarea (setting
max_height
ormax_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
andpadding=25
the final internal size iswidth=50
andheight=150
.Note
This is applied only to the base Menu (not the currently displayed, stored in
_current
pointer); for such behaviour apply topygame_menu.menu.Menu.get_current()
object.
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 alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the frame if the mouse is placed overmargin
(tuple, list) – Widget (left, bottom) margin in pxmax_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)scrollarea_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
,None) – Scroll area color. IfNone
area is transparentscrollbar_color
(tuple, list, str, int,pygame.Color
) – Scrollbar colorscrollbar_cursor
(int,pygame.cursors.Cursor
, None) – Cursor of the scrollbars if the mouse is placed overscrollbar_shadow_color
(tuple, list, str, int,pygame.Color
) – Color of the shadow of each scrollbarscrollbar_shadow_offset
(int) – Offset of the scrollbar shadow in pxscrollbar_shadow_position
(str) – Position of the scrollbar shadow. Seepygame_menu.locals
scrollbar_shadow
(bool) – Indicate if a shadow is drawn on each scrollbarscrollbar_slider_color
(tuple, list, str, int,pygame.Color
) – Color of the slidersscrollbar_slider_hover_color
(tuple, list, str, int,pygame.Color
) – Color of the slider if hovered or clickedscrollbar_slider_pad
(int, float) – Space between slider and scrollbars borders in pxscrollbar_thick
(int) – Scrollbar thickness in pxscrollbars
(str) – Scrollbar position. Seepygame_menu.locals
tab_size
(int) – Width of a tab character
Note
All theme-related optional kwargs use the default Menu theme if not defined.
Note
If vertical frame contains a scrollarea (setting
max_height
ormax_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
andpadding=25
the final internal size iswidth=50
andheight=150
.Note
This is applied only to the base Menu (not the currently displayed, stored in
_current
pointer); for such behaviour apply topygame_menu.menu.Menu.get_current()
object.
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)
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 topygame_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.
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)
Add a simple text to the Menu.
If
onselect
is defined, the callback is executed as follows, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effect. Applied only ifselectable
isTrue
tab_size
(int) – Width of a tab characterunderline_color
(tuple, list, str, int,pygame.Color
, None) – Color of the underline. IfNone
use the same color of the textunderline_offset
(int) – Vertical offset in px.2
by defaultunderline_width
(int) – Underline width in px.2
by defaultunderline
(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 topygame_menu.menu.Menu.get_current()
object.- Parameters
title (
Any
) – Text to be displayedlabel_id (
str
) – ID of the labelmax_char (
int
) – Split the title in several labels if the string length exceedsmax_char
;0
: don’t split,-1
: split to Menu widthonselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Callback executed when selecting the widget; only executed ifselectable
isTrue
selectable (
bool
) – Label accepts user selection; useful to move along the Menu using label selectionkwargs – Optional keyword arguments
- Returns
Widget object, or List of widgets if the text overflows
- Return type
pygame_menu.widgets.Label
,typing.List
[pygame_menu.widgets.Label
]
Add a none widget¶
A none widget is used to fill column/row layout, store information or even add drawing callbacks for being executed on each menu draw.
menu = pygame_menu.Menu(...)
menu.add.none_widget()
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 topygame_menu.menu.Menu.get_current()
object.- Parameters
widget_id (
str
) – Widget ID- Returns
Widget object
- Return type
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)
Add a surface widget to the Menu.
If
onselect
is defined, the callback is executed as follows, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effect. Applied only ifselectable
isTrue
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 topygame_menu.menu.Menu.get_current()
object.- Parameters
- Returns
Widget object
- Return type
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))
Adds a Table to the Menu. A table is a frame which can pack widgets in a structured way.
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the frame if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetmargin
(tuple, list) – Widget (left, bottom) margin in pxmax_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)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 topygame_menu.menu.Menu.get_current()
object.- Parameters
table_id (
str
) – ID of the tablekwargs – Optional keyword arguments
- Returns
Widget object
- Return type
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)
Add a text input to the Menu: free text area and two functions that execute when changing the text and pressing return button on the element.
The callbacks receive the current value and all unknown keyword arguments, where
current_text=widget.get_value
:onchange(current_text, **kwargs) onreturn(current_text, **kwargs)
If
onselect
is defined, the callback is executed as follows, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetinput_underline_vmargin
(int) – Vertical margin of underline in pxmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 modereadonly_selected_color
(tuple, list, str, int,pygame.Color
) – Color of the widget if readonly mode and is selectedselection_color
(tuple, list, str, int,pygame.Color
) – Color of the selected widget; only affects the font colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effecttab_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 topygame_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 inputcopy_paste_enable (
bool
) – Enable text copy, paste and cutcursor_selection_enable (
bool
) – Enable text selection on inputcursor_size (
Optional
[Tuple
[int
,int
]]) – Size of the cursor (width, height) in px. IfNone
uses the default sizinginput_type (
str
) – Data type of the input. Seepygame_menu.locals
input_underline (
str
) – Underline characterinput_underline_len (
int
) – Total of characters to be drawn under the input. If0
this number is computed automatically to fit the fontmaxchar (
int
) – Maximum length of string, if 0 there’s no limitmaxwidth (
int
) – Maximum size of the text widget (in number of chars), if0
there’s no limitonchange (
Optional
[Callable
]) – Callback executed when changing the text inputonreturn (
Optional
[Callable
]) – Callback executed when pressing return on the text inputonselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Callback executed when selecting the widgetpassword (
bool
) – Text input is a passwordtextinput_id (
str
) – ID of the text inputvalid_chars (
Optional
[List
[str
]]) – List of authorized chars.None
if all chars are validkwargs – Optional keyword arguments
- Returns
Widget object
- Return type
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', 'Encencido'), state_text_font_size=18)
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, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overfont_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font colorfont_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetinfinite
(bool) – The state can rotate.False
by defaultmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 modereadonly_selected_color
(tuple, list, str, int,pygame.Color
) – Color of the widget if readonly mode and is selectedselection_color
(tuple, list, str, int,pygame.Color
) – Color of the selected widget; only affects the font colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effectslider_color
(tuple, list, str, int,pygame.Color
) – Color of the sliderslider_thickness
(int) – Slider thickness in px.20
px by defaultstate_color
(tuple) – 2-item color tuple for each statestate_text_font_color
(tuple) – 2-item color tuple for each font state text colorstate_text_font_size
(str, None) – Font size of the state text. IfNone
uses the widget font sizeswitch_border_color
(tuple, list, str, int,pygame.Color
) – Switch border colorswitch_border_width
(int) – Switch border widthswitch_height
(int, float) – Height factor respect to the title font size heightswitch_margin
(tuple, list) – Switch on x-axis and y-axis (x, y) margin respect to the title of the widget in pxtab_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 topygame_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 switchdefault (
Union
[int
,bool
]) – Default state index of the switch; it can be0 (False)
or1 (True)
onchange (
Optional
[Callable
]) – Callback executed when when changing the state of the toggle switchonselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Callback executed when selecting the widgettoggleswitch_id (
str
) – Widget IDstate_values (
Tuple
[Any
, …]) – Value of each state of the switchwidth (
int
) – Width of the switch box in px
- Returns
Widget object
- Return type
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')
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 topygame_menu.menu.Menu.get_current()
object.- Parameters
- Returns
Widget object
- Return type
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')
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, buthref='google.com', title='Google'
will write ‘Google’ and opens ‘google.com’ if clicked.If
onselect
is defined, the callback is executed as follows, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed over. By default isHAND
font_background_color
(tuple, list, str, int,pygame.Color
, None) – Widget font background colorfont_color
(tuple, list, str, int,pygame.Color
) – Widget font color. If not defined, usestheme.widget_url_color
font_name
(str,pathlib.Path
,pygame.font.Font
) – Widget font pathfont_shadow_color
(tuple, list, str, int,pygame.Color
) – Font shadow colorfont_shadow_offset
(int) – Font shadow offset in pxfont_shadow_position
(str) – Font shadow position, see locals for positionfont_shadow
(bool) – Font shadow is enabled or disabledfont_size
(int) – Font size of the widgetmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effecttab_size
(int) – Width of a tab characterunderline_color
(tuple, list, str, int,pygame.Color
, None) – Color of the underline. IfNone
use the same color of the textunderline_offset
(int) – Vertical offset in px.2
by defaultunderline_width
(int) – Underline width in px.2
by defaultunderline
(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 topygame_menu.menu.Menu.get_current()
object.- Parameters
- Returns
Widget object, or List of widgets if the text overflows
- Return type
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))
Add a simple image to the Menu.
If
onselect
is defined, the callback is executed as follows, whereselected
is a boolean representing the selected status:onselect(selected, widget, menu)
- kwargs (Optional)
align
(str) – Widget alignmentbackground_color
(tuple, list, str, int,pygame.Color
,pygame_menu.baseimage.BaseImage
) – Color of the background.None
for no-colorbackground_inflate
(tuple, list) – Inflate background on x-axis and y-axis (x, y) in pxborder_color
(tuple, list, str, int,pygame.Color
) – Widget border color.None
for no-colorborder_inflate
(tuple, list) – Widget border inflate on x-axis and y-axis (x, y) in pxborder_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. Seepygame_menu.locals
border_width
(int) – Border width in px. If0
disables the bordercursor
(int,pygame.cursors.Cursor
, None) – Cursor of the widget if the mouse is placed overmargin
(tuple, list) – Widget (left, bottom) margin in pxpadding
(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 colorselection_effect
(pygame_menu.widgets.core.Selection
) – Widget selection effect. Applied only ifselectable
isTrue
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 topygame_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 ignoredangle (
Union
[int
,float
]) – Angle of the image in degrees (clockwise)image_id (
str
) – ID of the labelonselect (
Optional
[Callable
[[bool
,Widget
,Menu
],Any
]]) – Callback executed when selecting the widget; only executed ifselectable
isTrue
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 smoothedselectable (
bool
) – Image accepts user selectionkwargs – Optional keyword arguments
- Returns
Widget object
- Return type