Adding widgets

Add a text

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

Example:

../_images/widget_label.png 
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 = pygame_menu.Menu(...)
menu.add_label(HELP, max_char=-1, font_size=20)
Menu.add_label(title, label_id='', max_char=0, selectable=False, **kwargs)[source]

Add a simple text to the Menu.

kwargs (Optional):
  • align Widget alignment (str)
  • background_color Color of the background (tuple, list, pygame_menu.baseimage.BaseImage)
  • background_inflate Inflate background color if enabled (bool)
  • font_color Widget font color (tuple, list)
  • font_name Widget font (str)
  • font_size Font size of the widget (int)
  • margin (x,y) margin (tuple, list)
  • shadow Shadow is enabled or disabled (bool)
  • shadow_color Text shadow color (tuple, list)
  • shadow_position Text shadow position, see locals for position (str)
  • shadow_offset Text shadow offset (int, float, None)
Parameters:
  • title (str) – Text to be displayed
  • label_id (str) – ID of the label
  • max_char (int) – Split the title in several labels if length exceeds. (0: don’t split, -1: split to menu width)
  • selectable (bool) – Label accepts user selection
  • kwargs (any) – Optional keywords arguments
Returns:

Widget object or List of widgets if the text overflows
Return type:

pygame_menu.widgets.Label, list[pygame_menu.widgets.Label]

Add an image

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

Example:

../_images/widget_image.png 
PATH = os.path.join(os.path.dirname(pygame_menu.__file__),
                    'resources', 'images', 'pygame_menu.png')

menu = pygame_menu.Menu(...)

menu.add_image(PATH, angle=10, scale=(0.15, 0.15))
menu.add_image(PATH, angle=-10, scale=(0.15, 0.15), scale_smooth=True)
Menu.add_image(image_path, angle=0, image_id='', scale=(1, 1), scale_smooth=False, selectable=False, **kwargs)[source]

Add a simple image to the Menu.

kwargs (Optional):
  • align Widget alignment (str)
  • background_color Color of the background (tuple, list, pygame_menu.baseimage.BaseImage)
  • background_inflate Inflate background color if enabled (bool)
  • margin (x,y) margin (tuple, list)
  • selection_color Widget selection color (tuple, list)
  • selection_effect Widget selection effect (pygame_menu.widgets.core.Selection)
Parameters:
  • image_path (str) – Path of the image of the widget
  • angle (int, float) – Angle of the image in degrees (clockwise)
  • image_id (str) – ID of the label
  • scale (tuple, list) – Scale of the image (x,y), float or int
  • scale_smooth (bool) – Scale is smoothed
  • selectable (bool) – Image accepts user selection
  • kwargs (any) – Optional keywords arguments
Returns:

Widget object
Return type:

pygame_menu.widgets.Image

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

../_images/widget_button.png 
def func(name):
    print("Hello world from", name)  # name will be 'foo'

menu = pygame_menu.Menu(...)

about_menu = pygame_menu.Menu(...)

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)
Menu.add_button(title, action, *args, **kwargs)[source]

Adds a button to the Menu.

The arguments and unknown keyword arguments are passed to the action:

action(*args, **kwargs)
kwargs (Optional):
  • align Widget alignment (str)
  • background_color Color of the background (tuple, list, pygame_menu.baseimage.BaseImage)
  • background_inflate Inflate background color if enabled (bool)
  • button_id Widget ID (str)
  • font_color Widget font color (tuple, list)
  • font_name Widget font (str)
  • font_size Font size of the widget (int)
  • margin (x,y) margin (tuple, list)
  • selection_color Widget selection color (tuple, list)
  • selection_effect Widget selection effect (pygame_menu.widgets.core.Selection)
  • shadow Shadow is enabled or disabled (bool)
  • shadow_color Text shadow color (tuple, list)
  • shadow_position Text shadow position, see locals for position (str)
  • shadow_offset Text shadow offset (int, float, None)
Parameters:
  • title (str) – Title of the button
  • action (pygame_menu.Menu, pygame_menu.events.MenuAction, callable) – Action of the button, can be a Menu, an event or a function
  • args (any) – Additional arguments used by a function
  • kwargs (any) – Additional keyword arguments
Returns:

Widget object
Return type:

pygame_menu.widgets.Button

Add a choices list

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

Example:

../_images/widget_selector.png 
def change_background_color(value, surface, color):
    name, index = value
    print("Change color to", name)
    if color == (-1, -1, -1):
        # Generate a random color
        color = (randrange(0, 255), randrange(0, 255), randrange(0, 255))
    surface.fill(color)

menu = pygame_menu.Menu(...)

menu.add_selector('Current color',
                  # list of (Text, parameters...)
                  [('Default', surface, (128, 0, 128)),
                   ('Black', surface, (0, 0, 0)),
                   ('Blue', surface, (0, 0, 255)),
                   ('Random', surface, (-1, -1, -1))],
                  onchange=change_background_color)
Menu.add_selector(title, items, default=0, onchange=None, onreturn=None, selector_id='', **kwargs)[source]

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

The values of the selector are like:

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

The callbacks receive the current text, its index in the list, the associated arguments and all unknown keyword arguments:

onchange((current_text, index), a, b, c..., **kwargs)
onreturn((current_text, index), a, b, c..., **kwargs)
kwargs (Optional):
  • align Widget alignment (str)
  • background_color Color of the background (tuple, list, pygame_menu.baseimage.BaseImage)
  • background_inflate Inflate background color if enabled (bool)
  • font_color Widget font color (tuple, list)
  • font_name Widget font (str)
  • font_size Font size of the widget (int)
  • margin (x,y) margin (tuple, list)
  • selection_color Widget selection color (tuple, list)
  • selection_effect Widget selection effect (pygame_menu.widgets.core.Selection)
  • shadow Shadow is enabled or disabled (bool)
  • shadow_color Text shadow color (tuple, list)
  • shadow_position Text shadow position, see locals for position (str)
  • shadow_offset Text shadow offset (int, float, None)
Parameters:
  • title (str) – Title of the selector
  • items (list) – Elements of the selector [(‘Item1’, var1..), (‘Item2’…)]
  • default (int) – Index of default value to display
  • onchange (callable, None) – Function when changing the selector
  • onreturn (callable, None) – Function when pressing return button
  • selector_id (str) – ID of the selector
  • kwargs (any) – Additional parameters
Returns:

Widget object
Return type:

pygame_menu.widgets.Selector

Add a text entry

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

Example:

../_images/widget_textinput.png 
def check_name(value):
    print('User name:', value)

menu = pygame_menu.Menu(...)

menu.add_text_input('First name: ', default='John', onreturn=check_name)
menu.add_text_input('Last name: ', default='Doe', maxchar=20)
menu.add_text_input('Password: ', input_type=pygame_menu.locals.INPUT_INT, password=True)
Menu.add_text_input(title, default='', copy_paste_enable=True, cursor_selection_enable=True, input_type='__pygame_menu_input_text__', input_underline='', maxchar=0, maxwidth=0, onchange=None, onreturn=None, password=False, tab_size=4, textinput_id='', valid_chars=None, **kwargs)[source]

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:

onchange(current_text, **kwargs)
onreturn(current_text, **kwargs)
kwargs (Optional):
  • align Widget alignment (str)
  • background_color Color of the background (tuple, list, pygame_menu.baseimage.BaseImage)
  • background_inflate Inflate background color if enabled (bool)
  • font_color Widget font color (tuple, list)
  • font_name Widget font (str)
  • font_size Font size of the widget (int)
  • margin (x,y) margin (tuple, list)
  • selection_color Widget selection color (tuple, list)
  • selection_effect Widget selection effect (pygame_menu.widgets.core.Selection)
  • shadow Shadow is enabled or disabled (bool)
  • shadow_color Text shadow color (tuple, list)
  • shadow_position Text shadow position, see locals for position (str)
  • shadow_offset Text shadow offset (int, float, None)
Parameters:
  • title (str) – Title of the text input
  • default (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
  • input_type (str) – Data type of the input
  • input_underline (str) – Underline character
  • maxchar (int) – Maximum length of string, if 0 there’s no limit
  • maxwidth (int) – Maximum size of the text widget, if 0 there’s no limit
  • onchange (callable, None) – Function when changing the selector
  • onreturn (callable, None) – Function when pressing return button
  • password (bool) – Text input is a password
  • tab_size (int) – Size of tab key
  • textinput_id (str) – ID of the text input
  • valid_chars (list) – List of authorized chars, None if all chars are valid
  • kwargs (any) – Additional keyword-parameters
Returns:

Widget object
Return type:

pygame_menu.widgets.TextInput

Add a color entry

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

Example:

../_images/widget_colorinput.png 
def check_color(value):
    print('New color:', value)

menu = pygame_menu.Menu(...)

menu.add_color_input('RGB color 1: ', color_type='rgb', default=(255, 0, 255), onreturn=check_color, font_size=18)
menu.add_color_input('RGB color 2: ', color_type='rgb', input_separator='-', font_size=18)
menu.add_color_input('HEX color 3: ', color_type='hex', default='#ffaa11', font_size=18)
Menu.add_color_input(title, color_type, color_id='', default='', input_separator=', ', input_underline='_', onchange=None, onreturn=None, previsualization_width=3, **kwargs)[source]

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

The callbacks receive the current value and all unknown keyword arguments:

onchange(current_color, **kwargs)
onreturn(current_color, **kwargs)
kwargs (Optional):
  • align Widget alignment (str)
  • background_color Color of the background (tuple, list, pygame_menu.baseimage.BaseImage)
  • background_inflate Inflate background color if enabled (bool)
  • font_color Widget font color (tuple, list)
  • font_name Widget font (str)
  • font_size Font size of the widget (int)
  • margin (x,y) margin (tuple, list)
  • selection_color Widget selection color (tuple, list)
  • selection_effect Widget selection effect (pygame_menu.widgets.core.Selection)
  • shadow Shadow is enabled or disabled (bool)
  • shadow_color Text shadow color (tuple, list)
  • shadow_position Text shadow position, see locals for position (str)
  • shadow_offset Text shadow offset (int, float, None)
Parameters:
  • title (str) – Title of the color input
  • color_type (str) – Type of the color input, can be “rgb” or “hex”
  • color_id (str) – ID of the color input
  • default (str, tuple) – Default value to display, if RGB must be a tuple (r,g,b), if HEX must be a string “#XXXXXX”
  • input_separator (str) – Divisor between RGB channels, not valid in HEX format
  • input_underline (str) – Underline character
  • onchange (callable, None) – Function when changing the selector
  • onreturn (callable, None) – Function when pressing return button
  • previsualization_width (int, float) – Previsualization width as a factor of the height
  • kwargs (any) – Additional keyword-parameters
Returns:

Widget object
Return type:

pygame_menu.widgets.ColorInput

Add a vertical spacer

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

Example:

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

menu.add_label('Text #1')
menu.add_vertical_margin(100)
menu.add_label('Text #2')
Menu.add_vertical_margin(margin)[source]

Adds a vertical margin to the current Menu.

Parameters:margin (int, float) – Margin in px
Returns:Widget object
Return type:pygame_menu.widgets.VMargin