Creating themes

pygame-menu offers many parameters to control the visual aspect of the menu. For an easier usage, all of them are gathered in a specific object called a theme. It is used to customize the menu window itself and all its widgets.

menu = pygame_menu.Menu(
    height=300,
    theme=pygame_menu.themes.THEME_BLUE,
    title='Welcome',
    width=400
)

Note

The theme parameters can be overwritten locally when adding a widget to the menu. See the overwritable ones in the add… methods

Default themes

Several predefined themes are proposed by pygame-menu.

Theme name	Example
pygame_menu.themes.THEME_DEFAULT
pygame_menu.themes.THEME_BLUE
pygame_menu.themes.THEME_DARK
pygame_menu.themes.THEME_GREEN
pygame_menu.themes.THEME_ORANGE
pygame_menu.themes.THEME_SOLARIZED

Create a theme

If none of the proposed theme fit to the needs, the Theme give the opportunity to create custom themes.

mytheme = Theme(background_color=(0, 0, 0, 0), # transparent background
                title_background_color=(4, 47, 126),
                title_font_shadow=True,
                widget_padding=25,
                ...)

menu = Menu(..., theme=mytheme)

Of course it is also possible to start from a predefined theme by copying it first.

mytheme = pygame_menu.themes.THEME_ORANGE.copy()
mytheme.title_background_color=(0, 0, 0)

menu = Menu(..., theme=mytheme)

Alignment

The alignment (str) can take one of the three following values:

Alignment	Description
pygame_menu.locals.ALIGN_LEFT	Left alignment
pygame_menu.locals.ALIGN_CENTER	Center alignment
pygame_menu.locals.ALIGN_RIGHT	Right alignment

Background Color/Images

Theme background can be both a color or an image. All colors can be defined using a tuple or a list of 3 or 4 numbers between 0 and 255. The format of the numbers are:

color_opaque = (R, G, B)
color_transparent = (R, G, B, A)

A alpha channels goes from 0 to 255. 0 is transparent, 255 is opaque. For using images as a background color, class pygame_menu.baseimage.BaseImage must be used.

Images needs a Path (file location on disk), a drawing mode, and an optional offset.

myimage = pygame_menu.baseimage.BaseImage(
    image_path=pygame_menu.baseimage.IMAGE_EXAMPLE_GRAY_LINES,
    drawing_mode=pygame_menu.baseimage.IMAGE_MODE_REPEAT_XY,
    offset=(0,0)
)
mytheme.background_color = myimage

Image drawing modes	Description
pygame_menu.baseimage.IMAGE_MODE_CENTER	Centers the image in the surface
pygame_menu.baseimage.IMAGE_MODE_FILL	Fill the image on the surface
pygame_menu.baseimage.IMAGE_MODE_REPEAT_X	Repeat the image on x axis
pygame_menu.baseimage.IMAGE_MODE_REPEAT_XY	Repeat the image on x and y axis
pygame_menu.baseimage.IMAGE_MODE_REPEAT_Y	Repeat the image on y axis
pygame_menu.baseimage.IMAGE_MODE_SIMPLE	Write the image on top-left location

Currently, Theme class only supports images for background_color and widget_background_color. Also, only IMAGE_MODE_FILL drawing mode is valid for widget_background_color.

Fonts

This library also has some fonts to use (TTF format). To load a font, run this code:

import pygame_menu

font = pygame_menu.font.FONT_NAME
my_theme = Theme(widget_font=font, ...)

Available fonts	Preview
pygame_menu.font.FONT_8BIT
pygame_menu.font.FONT_BEBAS
pygame_menu.font.FONT_COMIC_NEUE
pygame_menu.font.FONT_DIGITAL
pygame_menu.font.FONT_FIRACODE
pygame_menu.font.FONT_FIRACODE_BOLD
pygame_menu.font.FONT_FIRACODE_BOLD_ITALIC
pygame_menu.font.FONT_FIRACODE_ITALIC
pygame_menu.font.FONT_FIRACODE
pygame_menu.font.FONT_FRANCHISE
pygame_menu.font.FONT_HELVETICA
pygame_menu.font.FONT_MUNRO
pygame_menu.font.FONT_NEVIS
pygame_menu.font.FONT_OPEN_SANS
pygame_menu.font.FONT_OPEN_SANS_BOLD
pygame_menu.font.FONT_OPEN_SANS_ITALIC
pygame_menu.font.FONT_OPEN_SANS_LIGHT
pygame_menu.font.FONT_PT_SERIF

System fonts can also be used. The available system fonts can be listed using the following command in a python shell:

import pygame
print(pygame.font.get_fonts())

Menubar style

The visual style of the menubar is managed using the theme parameter title_bar_style which can take the following values:

Menubar style	Example
pygame_menu.widgets.MENUBAR_STYLE_ADAPTIVE
pygame_menu.widgets.MENUBAR_STYLE_SIMPLE
pygame_menu.widgets.MENUBAR_STYLE_TITLE_ONLY
pygame_menu.widgets.MENUBAR_STYLE_TITLE_ONLY_DIAGONAL
pygame_menu.widgets.MENUBAR_STYLE_NONE
pygame_menu.widgets.MENUBAR_STYLE_UNDERLINE
pygame_menu.widgets.MENUBAR_STYLE_UNDERLINE_TITLE

Positioning

Several possible positions are accepted by some configurations:

Position	Description
pygame_menu.locals.POSITION_EAST	East position
pygame_menu.locals.POSITION_NORTH	North position
pygame_menu.locals.POSITION_NORTHEAST	North/East position
pygame_menu.locals.POSITION_NORTHWEST	North/West position
pygame_menu.locals.POSITION_SOUTH	South position
pygame_menu.locals.POSITION_SOUTHEAST	South/East position
pygame_menu.locals.POSITION_SOUTHWEST	South/West position
pygame_menu.locals.POSITION_WEST	West position

Special positions used by Menu pygame_menu._scrollarea.ScrollArea (all above are available):

Position	Description
pygame_menu.locals.SCROLLAREA_POSITION_BOTH_HORIZONTAL	Scroll on both X axis
pygame_menu.locals.SCROLLAREA_POSITION_BOTH_VERTICAL	Scroll on both Y axis
pygame_menu.locals.SCROLLAREA_POSITION_FULL	Scroll on both X and Y axis

Widget selection effect

A selection effect is a drawing class used to define the way to highlight the focused widget. An instance of the selection effect class is defined in the Theme.widget_selection_effect Theme property. See example on how to add a selection effect in Create a selection effect chapter.

The available selection effects are:

Class	Selection effect
pygame_menu.widgets.HighlightSelection	Rectangular highlight
pygame_menu.widgets.LeftArrowSelection	Left arrow on the widget
pygame_menu.widgets.NoneSelection	No selection
pygame_menu.widgets.RightArrowSelection	Right arrow on the widget
pygame_menu.widgets.SimpleSelection	Only font color is changed

The selection color is defined in Theme.widget_selection_color.

Theme API

class pygame_menu.themes.Theme(**kwargs)

Class defining the visual rendering of menus and widgets.

Note

All colors must be defined with a tuple of 3 or 4 numbers in the formats:

• (R, G, B)

• (R, G, B, A)

Red (R), Green (G), and Blue (B) must be numbers between 0 and 255. A means the alpha channel (opacity), if 0 the color is transparent, 100 means opaque.

Note

Themes only modify visual behaviour of the Menu. For other options like rows/columns, enabling or disabling overflow, position, or Menu width/height see Menu parameters.

Parameters:

• background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Menu background color

• border_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage, None) – Menu border color. If border is an image, it will be split in 9 tiles to use top, left, bottom, right, and the corners

• border_width (int) – Border width in px. Used only if border_color is not an image

• cursor_color (tuple, list, str, int, pygame.Color) – Cursor color (used in some text-gathering widgets like TextInput)

• cursor_selection_color (tuple, list, str, int, pygame.Color) – Color of the text selection if the cursor is enabled on certain widgets

• cursor_switch_ms (int, float) – Interval of cursor switch between off and on status

• focus_background_color (tuple, list, str, int, pygame.Color) – Color of the widget focus, this must be a tuple of 4 elements (R, G, B, A)

• fps (int, float) – Menu max fps (frames per second). If 0 there’s no limit

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

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

• scrollarea_outer_margin (tuple, list) – Outer ScrollArea margin in px; the tuple is added to computed ScrollArea width/height, it can add a margin to bottom/right scrolls after widgets. If value less than 1 use percentage of width/height. It cannot be a negative value

• scrollarea_position (str) – Position of ScrollArea scrollbars. See pygame_menu.locals

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

• scrollbar_cursor (int, pygame.cursors.Cursor, None) – Scrollbar cursor if mouse is placed over. If None the scrollbar don’t change the cursor

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

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

• scrollbar_shadow_offset (int) – Offset of the scrollbar shadow

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

• 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

• scrollbar_thick (int) – Scrollbar thickness in px

• selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget. It updates both selected font and widget_selection_effect color

• surface_clear_color (tuple, list, str, int, pygame.Color) – Surface clear color before applying background function

• title (bool) – Title is enabled/disabled. If disabled the object is hidden

• title_background_color (tuple, list, str, int, pygame.Color) – Title background color

• title_bar_modify_scrollarea (bool) – If True title bar modifies the scrollbars of the scrollarea depending on the style

• title_bar_style (int) – Style of the title, use pygame_menu.widgets.MenuBar widget styles

• title_close_button (bool) – Draw a back-box button on header to close the Menu. If user moves through nested submenus this buttons turns to a back-arrow

• title_close_button_background_color (tuple, list, str, int, pygame.Color) – Title back-box background color

• title_close_button_cursor (int, pygame.cursors.Cursor, None) – Cursor applied over title close button

• title_fixed (bool) – If True title is drawn over the scrollarea, forcing widget surface area to be drawn behind the title

• title_floating (bool) – If True title don’t contribute height to the Menu. Thus, scroll uses full menu width/height

• title_font (str, pygame.font.Font, pathlib.Path) – Title font

• title_font_antialias (bool) – Title font renders with antialiasing

• title_font_color (tuple, list, str, int, pygame.Color) – Title font color

• title_font_shadow (bool) – Enable title font shadow

• title_font_shadow_color (tuple, list, str, int, pygame.Color) – Title font shadow color

• title_font_shadow_offset (int) – Offset of title font shadow in px

• title_font_shadow_position (str) – Position of the title font shadow. See pygame_menu.locals

• title_font_size (int) – Font size of the title

• title_offset (tuple, list) – Offset (x-position, y-position) of title in px

• title_updates_pygame_display (bool) – If True the menu title updates See pygame.display.caption automatically on draw

• widget_alignment (str) –

  Widget default alignment. See pygame_menu.locals

• widget_alignment_ignore_scrollbar_thickness (bool) – Widget positioning ignores the scrollbar thickness. If True, the widgets only consider the menu size, ignoring the thickness of the visible scrollbars

• widget_background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage, None) – Background color of a widget, it can be a color, None (transparent), or a BaseImage object. Background fills the entire widget + the padding

• widget_background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px. By default, it uses the highlight margin. This parameter is visual only. For modifying widget size use padding instead

• widget_background_inflate_to_selection (bool) – If True widget will inflate to match selection effect margin and overrides widget_background_inflate

• widget_border_color (tuple, list, str, int, pygame.Color) – Widget border color

• widget_border_inflate (tuple, list) – Widget inflate size on x-axis and y-axis (x, y) in px. These values cannot be negative

• widget_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

• widget_border_width (int) – Widget border width in px. If 0 the border is disabled. Border width don’t contribute to the widget width/height, it’s visual-only

• widget_box_arrow_color (tuple, list, str, int, pygame.Color) – Widget box arrow color, used by some widgets such as DropSelect, Fancy Selector, etc.

• widget_box_arrow_margin (tuple) – Widget box arrow margin (left, right, vertical) in px, used by some widgets such as DropSelect, Fancy Selector, etc.

• widget_box_background_color (tuple, list, str, int, pygame.Color) – Widget box background color, used by some widgets such as DropSelect, Fancy Selector, etc.

• widget_box_border_color (tuple, list, str, int, pygame.Color) – Widget box border color, used by some widgets such as DropSelect, Fancy Selector, etc.

• widget_box_border_width (int) – Widget box border width in px, used by some widgets such as DropSelect, Fancy Selector, etc.

• widget_box_inflate (tuple, list) – Widget box inflate on x-axis and y-axis (x, y) in px, used by some widgets such as DropSelect, Fancy Selector, etc.

• widget_box_margin (tuple, list) – Box margin on x-axis and y-axis (x, y) in px

• widget_cursor (int, pygame.cursors.Cursor, None) – Widget cursor if mouse is placed over. If None the widget don’t change the cursor

• widget_font (str, pygame.font.Font, pathlib.Path) – Widget font path or name

• widget_font_antialias (bool) – Widget font renders with antialiasing

• widget_font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color. If None the value will be the same as background_color if it is a color object and if widget_font_background_color_from_menu is True and widget_background_color is None

• widget_font_background_color_from_menu (bool) – Use Menu background color as font background color. Disabled by default

• widget_font_color (tuple, list, str, int, pygame.Color) – Color of the font

• widget_font_shadow (bool) – Indicate if the widget font shadow is enabled

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

• widget_font_shadow_offset (int) – Offset of the widget font shadow in px

• widget_font_shadow_position (str) – Position of the widget font shadow. See pygame_menu.locals

• widget_font_size (int) – Font size

• widget_margin (tuple, list) – Horizontal and vertical margin of each element in Menu in px

• widget_padding (int, float, tuple, list) – Padding of the widget according to CSS rules. It can be a single digit, or a tuple of 2, 3, or 4 elements. Padding modifies widget width/height

• widget_offset (tuple, list) – x-axis and y-axis (x, y) offset of widgets within Menu in px respect to top-left corner. If value less than 1 use percentage of width/height. It cannot be a negative value

• widget_selection_effect (pygame_menu.widgets.core.Selection, None) – Widget selection effect object. This is visual-only, the selection properties does not affect widget height/width

• widget_shadow_aa (int) – Widget shadow antialiasing factor, default is x4

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

• widget_shadow_radius (int) – The border radius of the widget shadow

• widget_shadow_type (str) – The shadow type, it can be ‘rectangular’ or ‘ellipse’

• widget_shadow_width (int) – The width of the shadow in px

• widget_tab_size (int) – Widget tab size

• widget_url_color (tuple, list, str, int, pygame.Color) – Color of url text links

copy()

Creates a deep copy of the object.

Return type:

Theme

Returns:

Copied theme

set_background_color_opacity(opacity)

Modify the Menu background color with given opacity.

Parameters:

opacity (float) – Opacity value, from 0 (transparent) to 1 (opaque)

Return type:

Theme

Returns:

Self reference

validate()

Validate the values of the theme. If there’s an invalid parameter throws an AssertionError.

This function also converts all lists to tuples. This is done because lists are mutable.

Return type:

Theme

Returns:

Self reference