pygame_gui package


pygame_gui.ui_manager module

class pygame_gui.ui_manager.UIManager(window_resolution: Tuple[int, int], theme_path: str = None)

Bases: object

The UI Manager class helps keep track of all the moving parts in the pygame_gui system.

Before doing anything else with pygame_gui create a UIManager and remember to update it every frame.

add_font_paths(font_name: str, regular_path: str, bold_path: str = None, italic_path: str = None, bold_italic_path: str = None)

Add file paths for custom fonts you want to use in the UI. For each font name you add you can specify font files for different styles. Fonts with designed styles tend to render a lot better than fonts that are forced to make use of pygame’s bold and italic styling effects, so if you plan to use bold and italic text at small sizes - find fonts with these styles available as separate files.

The font name you specify here can be used to choose the font in the blocks of HTML-subset formatted text, available in some of the UI elements like the UITextBox.

It is recommended that you also pre-load any fonts you use at an appropriate moment in your project rather than letting the library dynamically load them when they are required. That is because dynamic loading of large font files can cause UI elements with a lot of font usage to appear rather slowly as they are waiting for the fonts they need to load.

  • font_name – The name of the font that will be used to reference it elsewhere in the GUI.
  • regular_path – The path of the font file for this font with no styles applied.
  • bold_path – The path of the font file for this font with just bold style applied.
  • italic_path – The path of the font file for this font with just italic style applied.
  • bold_italic_path – The path of the font file for this font with bold & italic style applied.

Clear all existing windows, including the root window, which should get rid of all created UI elements. We then recreate the UIWindowStack and the root window.


Clears the last scrollbar that we used.

Parameters:vert_scrollbar – A scrollbar UIElement.
draw_ui(window_surface: pygame.Surface)

Draws all the UI elements on the screen. Generally you want this to be after the rest of your game sprites have been drawn.

If you want to do something particularly unusual with drawing you may have to write your own UI manager.

Parameters:window_surface – The screen or window surface on which we are going to draw all of our UI Elements.

Gets the last scrollbar that we used.

Returns:A UIElement.
get_shadow(size: Tuple[int, int], shadow_width: int = 2) → pygame.Surface

Returns a ‘shadow’ surface scaled to the requested size.

  • size – The size of the object we are shadowing + it’s shadow.
  • shadow_width – The width of the shadowed edge.

A shadow.

get_sprite_group() → pygame.sprite.LayeredUpdates

Gets the sprite group used by the entire UI to keep it in the correct order for drawing and processing input. :return : pygame.sprite.LayeredUpdates -

get_theme() → pygame_gui.core.ui_appearance_theme.UIAppearanceTheme

Gets the theme so the data in it can be accessed. :return: UIAppearanceTheme - the theme data used by this UIManager

get_window_stack() → pygame_gui.core.ui_window_stack.UIWindowStack

The UIWindowStack organises any windows in the UI Manager so that they are correctly sorted and move windows we interact with to the top of the stack. :return: UIWindowStack

preload_fonts(font_list: List[Dict[str, Union[str, int, float]]])

It’s a good idea to pre-load the exact fonts your program uses during the loading phase of your program. By default the pygame_gui library will still work, but will spit out reminder warnings when you haven’t done this. Loading fonts on the fly will slow down the apparent responsiveness when creating UI elements that use a lot of different fonts.

To pre-load custom fonts, or to use custom fonts at all (i.e. ones that aren’t the default ‘fira_code’ font) you must first add the paths to the files for those fonts, then load the specific fonts with a list of font descriptions in a dictionary form like so:

code:{‘name’: ‘fira_code’, ‘point_size’: 12, ‘style’: ‘bold_italic’}

You can specify size either in pygame.Font point sizes with ‘point_size’, or in HTML style sizes with ‘html_size’. Style options are:

  • ‘regular’
  • ‘italic’
  • ‘bold’
  • ‘bold_italic’

The name parameter here must match the one you used when you added the file paths.

Parameters:font_list – A list of font descriptions in dictionary format as described above.

Helps you identify which pre-loaded fonts you are actually still using in your project after you’ve fiddled around with the text a lot by printing out a list of fonts that have not been used yet at the time this function is called.

Of course if you don’t run the code path in which a particular font is used before calling this function then it won’t be of much use, so take it’s results under advisement rather than as gospel.

process_events(event: pygame.event.Event)

This is the top level method through which all input to UI elements is processed and reacted to.

One of the key things it controls is the currently ‘focused’ or ‘selected’ element of which there can be only one at a time.

Parameters:event – pygame.event.Event - the event to process.
select_focus_element(ui_element: pygame_gui.core.ui_element.UIElement)

Set an element as the focused element.

If the element is a scroll bar we also keep track of that.

Parameters:ui_element – The element to focus on.

Unselect and clear the currently focused element.

update(time_delta: float)

From here all our UI elements are updated and it manages which element is currently ‘hovered’; which means the mouse pointer is overlapping them.

Parameters:time_delta – The time passed since the last call to update, in seconds.

Module contents