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

../_images/theme_default.png

pygame_menu.themes.THEME_BLUE

../_images/theme_blue.png

pygame_menu.themes.THEME_DARK

../_images/theme_dark.png

pygame_menu.themes.THEME_GREEN

../_images/theme_green.png

pygame_menu.themes.THEME_ORANGE

../_images/theme_orange.png

pygame_menu.themes.THEME_SOLARIZED

../_images/theme_solarized.png

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

../_images/font_8bit.png

pygame_menu.font.FONT_BEBAS

../_images/font_bebas.png

pygame_menu.font.FONT_COMIC_NEUE

../_images/font_comic_neue.png

pygame_menu.font.FONT_DIGITAL

../_images/font_digital.png

pygame_menu.font.FONT_FRANCHISE

../_images/font_franchise.png

pygame_menu.font.FONT_HELVETICA

../_images/font_helvetica.png

pygame_menu.font.FONT_MUNRO

../_images/font_munro.png

pygame_menu.font.FONT_NEVIS

../_images/font_nevis.png

pygame_menu.font.FONT_OPEN_SANS

../_images/font_open_sans.png

pygame_menu.font.FONT_OPEN_SANS_BOLD

../_images/font_open_sans_bold.png

pygame_menu.font.FONT_OPEN_SANS_ITALIC

../_images/font_open_sans_italic.png

pygame_menu.font.FONT_OPEN_SANS_LIGHT

../_images/font_open_sans_light.png

pygame_menu.font.FONT_PT_SERIF

../_images/font_pt_serif.png

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

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)[source]

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, pygame_menu.baseimage.BaseImage) – Menu background color

  • 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 changes 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 contributes 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_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 contributes 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 changes 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’s 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) – Widget selection effect object. This is visual-only, the selection properties does not affect widget height/width

  • widget_tab_size (int) – Widget tab size

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

copy()[source]

Creates a deep copy of the object.

Return type

Theme

Returns

Copied theme

set_background_color_opacity(opacity)[source]

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()[source]

Validate the values of the theme. If there’s a 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