pygame_gui.core.interfaces package

Submodules

pygame_gui.core.interfaces.container_interface module

class pygame_gui.core.interfaces.container_interface.IContainerLikeInterface

Bases: object

A meta class that defines the interface for containers used by elements.

This interface lets us treat classes like UIWindows and UIPanels like containers for elements even though they actually pass this functionality off to the proper UIContainer class.

get_container() → pygame_gui.core.interfaces.container_interface.IUIContainerInterface

Gets an actual container from this container-like UI element.

hide()

Hides the container, which means the container will not get drawn and will not process events. Should also hide all the children elements. If the container was hidden before - ignore.

show()

Shows the container, which means the container will get drawn and will process events. Should also show all the children elements. If the container was visible before - ignore.

class pygame_gui.core.interfaces.container_interface.IUIContainerInterface

Bases: object

Interface for the actual container class. Not to be confused with the IContainerLikeInterface which is an interface for all the things we can treat like containers when creating elements.

add_element(element: pygame_gui.core.interfaces.element_interface.IUIElementInterface)

Add a UIElement to the container. The UI's relative_rect parameter will be relative to this container.

Parameters:element -- A UIElement to add to this container.
change_layer(new_layer: int)

Change the layer of this container. Layers are used by the GUI to control the order in which things are drawn and which things should currently be interactive (so you can't interact with things behind other things).

This particular method is most often used to shift the visible contents of a window in front of any others when it is moved to the front of the window stack.

Parameters:new_layer -- The layer to move our container to.
check_hover(time_delta: float, hovered_higher_element: bool) → bool

A method that helps us to determine which, if any, UI Element is currently being hovered by the mouse.

Parameters:
  • time_delta -- A float, the time in seconds between the last call to this function and now (roughly).
  • hovered_higher_element -- A boolean, representing whether we have already hovered a 'higher' element.
Returns:

A boolean that is true if we have hovered a UI element, either just now or before this method.

clear()

Removes and kills all the UI elements inside this container.

get_image_clipping_rect() → Optional[pygame.Rect]

Obtain the current image clipping rect.

Returns:The current clipping rect. May be None.
get_rect() → pygame.Rect

Access to the container's rect

Returns:a pygame rectangle
get_size() → Tuple[int, int]

Get the container's pixel size.

Returns:the pixel size as tuple [x, y]
get_thickness() → int

Get the container's layer thickness.

Returns:the thickness as an integer.
get_top_layer() → int

Assuming we have correctly calculated the 'thickness' of this container, this method will return the 'highest' layer in the LayeredDirty UI Group.

Returns:An integer representing the current highest layer being used by this container.
kill()

Overrides the standard kill method of UI Elements (and pygame sprites beyond that) to also call the kill method on all contained UI Elements.

recalculate_container_layer_thickness()

This function will iterate through the elements in our container and determine the maximum 'height' that they reach in the 'layer stack'. We then use that to determine the overall 'thickness' of this container. The thickness value is used to determine where to place overlapping windows in the layers

remove_element(element: pygame_gui.core.interfaces.element_interface.IUIElementInterface)

Remove a UIElement from this container.

Parameters:element -- A UIElement to remove from this container.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Set the dimension of this container and update the positions of elements within it accordingly.

Parameters:dimensions -- the new dimensions.
set_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Set the absolute position of this container - it is usually less chaotic to deal with setting relative positions.

Parameters:position -- the new absolute position to set.
set_relative_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Set the position of this container, relative to the container it is within.

Parameters:position -- the new relative position to set.
update_containing_rect_position()

This function is called when we move the container to update all the contained UI Elements to move as well.

pygame_gui.core.interfaces.manager_interface module

class pygame_gui.core.interfaces.manager_interface.IUIManagerInterface

Bases: object

A meta class that defines the interface that a UI Manager uses.

Interfaces like this help us evade cyclical import problems by allowing us to define the actual manager class later on and have it make use of the classes that use the interface.

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.

Parameters:
  • 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.
calculate_scaled_mouse_position(position: Tuple[int, int]) → Tuple[int, int]

Scaling an input mouse position by a scale factor.

clear_and_reset()

Clear the whole UI.

create_tool_tip(text: str, position: Tuple[int, int], hover_distance: Tuple[int, int]) → pygame_gui.core.interfaces.tool_tip_interface.IUITooltipInterface

Creates a tool tip ands returns it.

Parameters:
  • text -- The tool tips text, can utilise the HTML subset used in all UITextBoxes.
  • position -- The screen position to create the tool tip for.
  • hover_distance -- The distance we should hover away from our target position.
Returns:

A tool tip placed somewhere on the screen.

draw_ui(window_surface: pygame.Surface)

Draws the UI.

Parameters:window_surface -- The screen or window surface on which we are going to draw all of our UI Elements.
get_double_click_time() → float

Returns time between clicks that counts as a double click.

Returns:A float, time measured in seconds.
get_focus_set() → Set[pygame_gui.core.interfaces.element_interface.IUIElementInterface]

Gets the focused set.

Returns:The set of elements that currently have interactive focus.
get_locale() → str

Get the locale language code being used in the UIManager

Returns:A two letter ISO 639-1 code for the current locale.
get_mouse_position() → Tuple[int, int]

Get the position of the mouse in the UI.

get_root_container() → pygame_gui.core.interfaces.container_interface.IUIContainerInterface

Returns the 'root' container. The one all UI elements are placed in by default if they are not placed anywhere else, fills the whole OS/pygame window.

Returns:A container.
get_shadow(size: Tuple[int, int], shadow_width: int = 2, shape: str = 'rectangle', corner_radius: int = 2) → pygame.Surface

Returns a 'shadow' surface scaled to the requested size.

Parameters:
  • size -- The size of the object we are shadowing + it's shadow.
  • shadow_width -- The width of the shadowed edge.
  • shape -- The shape of the requested shadow.
  • corner_radius -- The radius of the shadow corners if this is a rectangular shadow.
Returns:

A shadow as a pygame Surface.

get_sprite_group() → pygame.sprite.LayeredDirty

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

Returns:The UI's sprite group.
get_theme() → pygame_gui.core.interfaces.appearance_theme_interface.IUIAppearanceThemeInterface

Gets the theme so the data in it can be accessed.

Returns:The theme data used by this UIManager
get_universal_empty_surface() → pygame.Surface

Sometimes we want to hide sprites or just have sprites with no visual component, when we do we can just use this empty surface to save having lots of empty surfaces all over memory.

Returns:An empty, and therefore invisible pygame.surface.Surface
get_window_stack() → pygame_gui.core.interfaces.window_stack_interface.IUIWindowStackInterface

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.

Returns:The stack of windows.
preload_fonts(font_list: List[Dict[str, Union[str, int, float]]])

Pre-loads a list of fonts.

Parameters:font_list -- A list of font descriptions in dictionary format as described above.
print_layer_debug()

Print some formatted information on the current state of the UI Layers.

Handy for debugging layer problems.

print_unused_fonts()

Prints a list of fonts that have been loaded but are not being used.

process_events(event: pygame.event.Event)

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

Parameters:event -- pygame.event.Event - the event to process.
set_active_cursor(cursor: Tuple[Tuple[int, int], Tuple[int, int], Tuple[int, ...], Tuple[int, ...]])

This is for users of the library to set the currently active cursor, it will be currently only be overriden by the resizing cursors.

The expected input is in the same format as the standard pygame cursor module, except without expanding the initial Tuple. So, to call this function with the default pygame arrow cursor you would do:

manager.set_active_cursor(pygame.cursors.arrow)
set_focus_set(focus: Union[pygame_gui.core.interfaces.element_interface.IUIElementInterface, Set[pygame_gui.core.interfaces.element_interface.IUIElementInterface]])

Set a set of element as the focused set.

Parameters:focus -- The set of element to focus on.
set_locale(locale: str)

Set a locale language code to use in the UIManager

Parameters:locale -- A two letter ISO 639-1 code for a supported language.

TODO: Make this raise an exception for an unsupported language?

set_text_input_hovered(hovering_text_input: bool)

Set to true when hovering an area text can be input into.

Currently switches the cursor to the I-Beam cursor.

Parameters:hovering_text_input -- set to True to toggle the I-Beam cursor
set_visual_debug_mode(is_active: bool)

Loops through all our UIElements to turn visual debug mode on or off. Also calls print_layer_debug()

Parameters:is_active -- True to activate visual debug and False to turn it off.
set_window_resolution(window_resolution: Tuple[int, int])

Sets the window resolution.

Parameters:window_resolution -- the resolution to set.
update(time_delta: float)

Update the UIManager.

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

pygame_gui.core.interfaces.window_interface module

class pygame_gui.core.interfaces.window_interface.IWindowInterface

Bases: object

A meta class that defines the interface that the window stack uses to interface with the UIWindow class.

Interfaces like this help us evade cyclical import problems by allowing us to define the actual window class later on and have it make use of the window stack.

can_hover() → bool

Called to test if this window can be hovered.

change_layer(layer: int)

Change the drawing layer of this window.

Parameters:layer -- the new layer to move to.
check_clicked_inside_or_blocking(event: pygame.event.Event) → bool

A quick event check outside of the normal event processing so that this window is brought to the front of the window stack if we click on any of the elements contained within it.

Parameters:event -- The event to check.
Returns:returns True if the event represents a click inside this window or the window is blocking.
check_hover(time_delta: float, hovered_higher_element: bool) → bool

For the window the only hovering we care about is the edges if this is a resizable window.

Parameters:
  • time_delta -- time passed in seconds between one call to this method and the next.
  • hovered_higher_element -- Have we already hovered an element/window above this one.
get_hovering_edge_id() → str

Gets the ID of the combination of edges we are hovering for use by the cursor system.

Returns:a string containing the edge combination ID (e.g. xy,yx,xl,xr,yt,yb)
get_top_layer() → int

Returns the 'highest' layer used by this window so that we can correctly place other windows on top of it.

Returns:The top layer for this window as a number (greater numbers are higher layers).
kill()

Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this window, and remove if from the window stack.

on_moved_to_front()

Called when a window is moved to the front of the stack.

process_event(event: pygame.event.Event) → bool

Handles resizing & closing windows. Gives UI Windows access to pygame events. Derived windows should super() call this class if they implement their own process_event method.

Parameters:event -- The event to process.
Return bool:Return True if this element should consume this event and not pass it to the rest of the UI.
rebuild()

Rebuilds the window when the theme has changed.

rebuild_from_changed_theme_data()

Called by the UIManager to check the theming data and rebuild whatever needs rebuilding for this element when the theme data has changed.

set_blocking(state: bool)

Sets whether this window being open should block clicks to the rest of the UI or not. Defaults to False.

Parameters:state -- True if this window should block mouse clicks.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Set the size of this window and then re-sizes and shifts the contents of the windows container to fit the new size.

Parameters:dimensions -- The new dimensions to set.
set_display_title(new_title: str)

Set the title of the window.

Parameters:new_title -- The title to set.
set_minimum_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

If this window is resizable, then the dimensions we set here will be the minimum that users can change the window to. They are also used as the minimum size when 'set_dimensions' is called.

Parameters:dimensions -- The new minimum dimension for the window.
set_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the absolute screen rect position of an element.

Parameters:position -- The new position to set.
set_relative_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the relative rect position of an element.

Parameters:position -- The new position to set.
should_use_window_edge_resize_cursor() → bool

Returns true if this window is in a state where we should display one of the resizing cursors

Returns:True if a resizing cursor is needed.
update(time_delta: float)

A method called every update cycle of our application. Designed to be overridden by derived classes but also has a little functionality to make sure the window's layer 'thickness' is accurate and to handle window resizing.

Parameters:time_delta -- time passed in seconds between one call to this method and the next.

Module contents

class pygame_gui.core.interfaces.IColourGradientInterface

Bases: object

A meta class that defines the interface that a colour gradient uses.

Interfaces like this help us evade cyclical import problems by allowing us to define the actual manager class later on and have it make use of the classes that use the interface.

apply_gradient_to_surface(input_surface: pygame.Surface, rect: Optional[pygame.Rect] = None)

Applies this gradient to a specified input surface using blending multiplication. As a result this method works best when the input surface is a mostly white, stencil shape type surface.

Parameters:
  • input_surface --
  • rect -- The rectangle on the surface to apply the gradient to. If None, applies to the whole surface.
class pygame_gui.core.interfaces.IUIFontDictionaryInterface

Bases: object

A meta class that defines the interface that a font dictionary uses.

Interfaces like this help us evade cyclical import problems by allowing us to define the actual manager class later on and have it make use of the classes that use the interface.

add_font_path(font_name: str, font_path: str, bold_path: str = None, italic_path: str = None, bold_italic_path: str = None)

Adds paths to different font files for a font name.

Parameters:
  • font_name -- The name to assign to these font files.
  • font_path -- The path to the font's file with no particular style.
  • bold_path -- The path to the font's file with a bold style.
  • italic_path -- The path to the font's file with an italic style.
  • bold_italic_path -- The path to the font's file with a bold and an italic style.
check_font_preloaded(font_id: str) → bool

Check if a font is already preloaded or not.

Parameters:font_id -- The ID of the font to check for
Returns:True or False.
convert_html_to_point_size(html_size: float) → int

Takes in a HTML style font size and converts it into a point font size.

Parameters:html_size -- Size in HTML style.
Return int:A 'point' font size we can use with pygame.freetype.font
create_font_id(font_size: int, font_name: str, bold: bool, italic: bool) → str

Create an id for a particularly styled and sized font from those characteristics.

Parameters:
  • font_size -- The size of the font.
  • font_name -- The name of the font.
  • bold -- Whether the font is bold styled or not.
  • italic -- Whether the font is italic styled or not.
Return str:

The finished font id.

ensure_debug_font_loaded()

Ensure the font we use for debugging purposes is loaded. Generally called after we start a debugging mode.

find_font(font_size: int, font_name: str, bold: bool = False, italic: bool = False) → _freetype.Font

Find a loaded font from the font dictionary. Will load a font if it does not already exist and we have paths to the needed files, however it will issue a warning after doing so because dynamic file loading is normally a bad idea as you will get frame rate hitches while the running program waits for the font to load.

Instead it's best to preload all your needed files at another time in your program when you have more control over the user experience.

Parameters:
  • font_size -- The size of the font to find.
  • font_name -- The name of the font to find.
  • bold -- Whether the font is bold or not.
  • italic -- Whether the font is italic or not.
Return pygame.freetype.Font:
 

Returns either the font we asked for, or the default font.

get_default_font() → _freetype.Font

Grab the default font.

Returns:The default font.
preload_font(font_size: int, font_name: str, bold: bool = False, italic: bool = False, force_immediate_load: bool = False)

Lets us load a font at a particular size and style before we use it. While you can get away with relying on dynamic font loading during development, it is better to eventually pre-load all your font data at a controlled time, which is where this method comes in.

Parameters:
  • font_size -- The size of the font to load.
  • font_name -- The name of the font to load.
  • bold -- Whether the font is bold styled or not.
  • italic -- Whether the font is italic styled or not.
  • force_immediate_load -- bypasses any asynchronous threaded loading setup to immediately load the font on the main thread.
print_unused_loaded_fonts()

Can be called to check if the UI is loading any fonts that we haven't used by the point this function is called. If a font is truly unused then we can remove it from our loading and potentially speed up the overall loading of the program.

This is not a foolproof check because this function could easily be called before we have explored all the code paths in a project that may use fonts.

set_locale(new_locale: str)

This may change the default font.

Parameters:new_locale -- The new locale to set, a two letter country code ISO 639-1
class pygame_gui.core.interfaces.IUIAppearanceThemeInterface

Bases: object

A meta class that defines the interface that a UI Appearance Theme uses.

Interfaces like this help us evade cyclical import problems by allowing us to define the actual manager class later on and have it make use of the classes that use the interface.

build_all_combined_ids(element_ids: Union[None, List[str]], class_ids: Union[None, List[Optional[str]]], object_ids: Union[None, List[Optional[str]]]) → List[str]

Construct a list of combined element ids from the element's various accumulated ids.

Parameters:
  • element_ids -- All the ids of elements this element is contained within.
  • class_ids -- All the ids of 'classes' that this element is contained within.
  • object_ids -- All the ids of objects this element is contained within.
Returns:

A list of IDs that reference this element in order of decreasing specificity.

check_need_to_reload() → bool

Check if we need to reload our theme file because it's been modified. If so, trigger a reload and return True so that the UIManager can trigger elements to rebuild from the theme data.

Return bool:True if we need to reload elements because the theme data has changed.
get_colour(colour_id: str, combined_element_ids: List[str] = None) → pygame.Color

Uses data about a UI element and a specific ID to find a colour from our theme.

Parameters:
  • combined_element_ids -- A list of IDs representing an element's location in a hierarchy of elements.
  • colour_id -- The id for the specific colour we are looking for.
Return pygame.Color:
 

A pygame colour.

get_colour_or_gradient(colour_id: str, combined_ids: List[str] = None) → Union[pygame.Color, pygame_gui.core.interfaces.colour_gradient_interface.IColourGradientInterface]

Uses data about a UI element and a specific ID to find a colour, or a gradient, from our theme. Use this function if the UIElement can handle either type.

Parameters:
  • combined_ids -- A list of IDs representing an element's location in a hierarchy of elements.
  • colour_id -- The id for the specific colour we are looking for.
Return pygame.Color or ColourGradient:
 

A colour or a gradient object.

get_font(combined_element_ids: List[str]) → _freetype.Font

Uses some data about a UIElement to get a font object.

Parameters:combined_element_ids -- A list of IDs representing an element's location in a interleaved hierarchy of elements.
Return pygame.freetype.Font:
 A pygame font object.
get_font_dictionary() → pygame_gui.core.interfaces.font_dictionary_interface.IUIFontDictionaryInterface

Lets us grab the font dictionary, which is created by the theme object, so we can access it directly.

Return UIFontDictionary:
 The font dictionary.
get_font_info(combined_element_ids: List[str]) → Dict[str, Any]

Uses some data about a UIElement to get font data as dictionary

Parameters:combined_element_ids -- A list of IDs representing an element's location in a interleaved hierarchy of elements.
Return dictionary:
 Data about the font requested
get_image(image_id: str, combined_element_ids: List[str]) → pygame.Surface

Will raise an exception if no image with the ids specified is found. UI elements that have an optional image display will need to handle the exception.

Parameters:
  • combined_element_ids -- A list of IDs representing an element's location in a hierarchy of elements.
  • image_id -- The id identifying the particular image spot in the UI we are looking for an image to add to.
Returns:

A pygame.surface.Surface

get_misc_data(misc_data_id: str, combined_element_ids: List[str]) → Union[str, Dict[KT, VT]]

Uses data about a UI element and a specific ID to try and find a piece of miscellaneous theming data. Raises an exception if it can't find the data requested, UI elements requesting optional data will need to handle this exception.

Parameters:
  • combined_element_ids -- A list of IDs representing an element's location in a interleaved hierarchy of elements.
  • misc_data_id -- The id for the specific piece of miscellaneous data we are looking for.
Return Any:

Returns a string or a Dict

load_theme(file_path: Union[str, os.PathLike, _io.StringIO])

Loads a theme file, and currently, all associated data like fonts and images required by the theme.

Parameters:file_path -- The path to the theme we want to load.
reload_theming()

We need to load our theme file to see if anything expensive has changed, if so trigger it to reload/rebuild.

update_caching(time_delta: float)

Updates the various surface caches.

class pygame_gui.core.interfaces.IUIElementInterface

Bases: object

Interface for the ui element class. This is so we can refer to ui elements in other classes before the UIElement has itself been defined.

can_hover() → bool

A stub method to override. Called to test if this method can be hovered.

change_layer(new_layer: int)

Changes the layer this element is on.

Parameters:new_layer -- The layer to change this element to.
check_hover(time_delta: float, hovered_higher_element: bool) → bool

A method that helps us to determine which, if any, UI Element is currently being hovered by the mouse.

Parameters:
  • time_delta -- A float, the time in seconds between the last call to this function and now (roughly).
  • hovered_higher_element -- A boolean, representing whether we have already hovered a 'higher' element.
Return bool:

A boolean that is true if we have hovered a UI element, either just now or before this method.

disable()

Disables elements so they are no longer interactive.

Elements should handle their own enabling and disabling.

enable()

Enables elements so they are interactive again.

Elements should handle their own enabling and disabling.

focus()

A stub to override. Called when we focus this UI element.

get_abs_rect() → pygame.Rect

The absolute positioning rect.

Returns:A pygame rect.
get_anchor_targets() → list

Get any anchor targets this element has so we can update them when their targets change :return: the list of anchor targets.

get_element_ids() → List[str]

A list of all the element IDs in this element's theming/event hierarchy.

Returns:a list of strings, one ofr each element in the hierarchy.
get_focus_set() → Set[Any]

Return the set of elements to focus when we focus this element.

get_image_clipping_rect() → Optional[pygame.Rect]

Obtain the current image clipping rect.

Returns:The current clipping rect. May be None.
get_relative_rect() → pygame.Rect

The relative positioning rect.

Returns:A pygame rect.
get_starting_height() → int

Get the starting layer height of this element. (i.e. the layer we start placing it on above it's container, it may use more layers above this layer)

Returns:an integer representing the starting layer height.
get_top_layer() → int

Assuming we have correctly calculated the 'thickness' of it, this method will return the top of this element.

Return int:An integer representing the current highest layer being used by this element.
hide()

Hides the widget, which means the widget will not get drawn and will not process events. Clear hovered state.

hover_point(hover_x: float, hover_y: float) → bool

Test if a given point counts as 'hovering' this UI element. Normally that is a straightforward matter of seeing if a point is inside the rectangle. Occasionally it will also check if we are in a wider zone around a UI element once it is already active, this makes it easier to move scroll bars and the like.

Parameters:
  • hover_x -- The x (horizontal) position of the point.
  • hover_y -- The y (vertical) position of the point.
Returns:

Returns True if we are hovering this element.

join_focus_sets(element)

Join this element's focus set with another's.

Parameters:element -- The other element whose focus set we are joining with.
kill()

Overriding regular sprite kill() method to remove the element from it's container.

on_fresh_drawable_shape_ready()

Called when our drawable shape has finished rebuilding the active surface. This is needed because sometimes we defer rebuilding until a more advantageous (read quieter) moment.

on_hovered()

A stub to override. Called when this UI element first enters the 'hovered' state.

on_locale_changed()

Called for each element when the locale is changed on their UIManager

on_unhovered()

A stub to override. Called when this UI element leaves the 'hovered' state.

process_event(event: pygame.event.Event) → bool

A stub to override. Gives UI Elements access to pygame events.

Parameters:event -- The event to process.
Returns:Should return True if this element makes use of this event.
rebuild()

Takes care of rebuilding this element. Most derived elements are going to override this, and hopefully call the super() class method.

rebuild_from_changed_theme_data()

A stub to override. Used to test if the theming data for this element has changed and rebuild the element if so.

remove_element_from_focus_set(element)

remove an element from this sets focus group.

Parameters:element -- The element to remove.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the dimensions of an element.

NOTE: Using this on elements inside containers with non-default anchoring arrangements may make a mess of them.

Parameters:dimensions -- The new dimensions to set.
set_focus_set(focus_set: Set[Any])

Set the focus set to a specific set of elements.

Parameters:focus_set -- The focus set to set.
set_image(new_image: Optional[pygame.Surface])

Deprecated for most elements - to avoid confusion with setting the image for the UIImage element.

Generally the average user shouldn't be directly setting what this was setting.

Parameters:new_image -- The new image to set.
set_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the absolute screen rect position of an element.

Parameters:position -- The new position to set.
set_relative_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the relative rect position of an element.

Parameters:position -- The new position to set.
set_visual_debug_mode(activate_mode: bool)

Enables a debug mode for the element which displays layer information on top of it in a tiny font.

Parameters:activate_mode -- True or False to enable or disable the mode.
show()

Shows the widget, which means the widget will get drawn and will process events.

unfocus()

A stub to override. Called when we stop focusing this UI element.

update(time_delta: float)

Updates this element's drawable shape, if it has one.

Parameters:time_delta -- The time passed between frames, measured in seconds.
update_containing_rect_position()

Updates the position of this element based on the position of it's container. Usually called when the container has moved.

while_hovering(time_delta: float, mouse_pos: pygame.math.Vector2)

A stub method to override. Called when this UI element is currently hovered.

Parameters:
  • time_delta -- A float, the time in seconds between the last call to this function and now (roughly).
  • mouse_pos -- The current position of the mouse as 2D Vector.
class pygame_gui.core.interfaces.IUIContainerInterface

Bases: object

Interface for the actual container class. Not to be confused with the IContainerLikeInterface which is an interface for all the things we can treat like containers when creating elements.

add_element(element: pygame_gui.core.interfaces.element_interface.IUIElementInterface)

Add a UIElement to the container. The UI's relative_rect parameter will be relative to this container.

Parameters:element -- A UIElement to add to this container.
change_layer(new_layer: int)

Change the layer of this container. Layers are used by the GUI to control the order in which things are drawn and which things should currently be interactive (so you can't interact with things behind other things).

This particular method is most often used to shift the visible contents of a window in front of any others when it is moved to the front of the window stack.

Parameters:new_layer -- The layer to move our container to.
check_hover(time_delta: float, hovered_higher_element: bool) → bool

A method that helps us to determine which, if any, UI Element is currently being hovered by the mouse.

Parameters:
  • time_delta -- A float, the time in seconds between the last call to this function and now (roughly).
  • hovered_higher_element -- A boolean, representing whether we have already hovered a 'higher' element.
Returns:

A boolean that is true if we have hovered a UI element, either just now or before this method.

clear()

Removes and kills all the UI elements inside this container.

get_image_clipping_rect() → Optional[pygame.Rect]

Obtain the current image clipping rect.

Returns:The current clipping rect. May be None.
get_rect() → pygame.Rect

Access to the container's rect

Returns:a pygame rectangle
get_size() → Tuple[int, int]

Get the container's pixel size.

Returns:the pixel size as tuple [x, y]
get_thickness() → int

Get the container's layer thickness.

Returns:the thickness as an integer.
get_top_layer() → int

Assuming we have correctly calculated the 'thickness' of this container, this method will return the 'highest' layer in the LayeredDirty UI Group.

Returns:An integer representing the current highest layer being used by this container.
kill()

Overrides the standard kill method of UI Elements (and pygame sprites beyond that) to also call the kill method on all contained UI Elements.

recalculate_container_layer_thickness()

This function will iterate through the elements in our container and determine the maximum 'height' that they reach in the 'layer stack'. We then use that to determine the overall 'thickness' of this container. The thickness value is used to determine where to place overlapping windows in the layers

remove_element(element: pygame_gui.core.interfaces.element_interface.IUIElementInterface)

Remove a UIElement from this container.

Parameters:element -- A UIElement to remove from this container.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Set the dimension of this container and update the positions of elements within it accordingly.

Parameters:dimensions -- the new dimensions.
set_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Set the absolute position of this container - it is usually less chaotic to deal with setting relative positions.

Parameters:position -- the new absolute position to set.
set_relative_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Set the position of this container, relative to the container it is within.

Parameters:position -- the new relative position to set.
update_containing_rect_position()

This function is called when we move the container to update all the contained UI Elements to move as well.

class pygame_gui.core.interfaces.IContainerLikeInterface

Bases: object

A meta class that defines the interface for containers used by elements.

This interface lets us treat classes like UIWindows and UIPanels like containers for elements even though they actually pass this functionality off to the proper UIContainer class.

get_container() → pygame_gui.core.interfaces.container_interface.IUIContainerInterface

Gets an actual container from this container-like UI element.

hide()

Hides the container, which means the container will not get drawn and will not process events. Should also hide all the children elements. If the container was hidden before - ignore.

show()

Shows the container, which means the container will get drawn and will process events. Should also show all the children elements. If the container was visible before - ignore.

class pygame_gui.core.interfaces.IWindowInterface

Bases: object

A meta class that defines the interface that the window stack uses to interface with the UIWindow class.

Interfaces like this help us evade cyclical import problems by allowing us to define the actual window class later on and have it make use of the window stack.

can_hover() → bool

Called to test if this window can be hovered.

change_layer(layer: int)

Change the drawing layer of this window.

Parameters:layer -- the new layer to move to.
check_clicked_inside_or_blocking(event: pygame.event.Event) → bool

A quick event check outside of the normal event processing so that this window is brought to the front of the window stack if we click on any of the elements contained within it.

Parameters:event -- The event to check.
Returns:returns True if the event represents a click inside this window or the window is blocking.
check_hover(time_delta: float, hovered_higher_element: bool) → bool

For the window the only hovering we care about is the edges if this is a resizable window.

Parameters:
  • time_delta -- time passed in seconds between one call to this method and the next.
  • hovered_higher_element -- Have we already hovered an element/window above this one.
get_hovering_edge_id() → str

Gets the ID of the combination of edges we are hovering for use by the cursor system.

Returns:a string containing the edge combination ID (e.g. xy,yx,xl,xr,yt,yb)
get_top_layer() → int

Returns the 'highest' layer used by this window so that we can correctly place other windows on top of it.

Returns:The top layer for this window as a number (greater numbers are higher layers).
kill()

Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this window, and remove if from the window stack.

on_moved_to_front()

Called when a window is moved to the front of the stack.

process_event(event: pygame.event.Event) → bool

Handles resizing & closing windows. Gives UI Windows access to pygame events. Derived windows should super() call this class if they implement their own process_event method.

Parameters:event -- The event to process.
Return bool:Return True if this element should consume this event and not pass it to the rest of the UI.
rebuild()

Rebuilds the window when the theme has changed.

rebuild_from_changed_theme_data()

Called by the UIManager to check the theming data and rebuild whatever needs rebuilding for this element when the theme data has changed.

set_blocking(state: bool)

Sets whether this window being open should block clicks to the rest of the UI or not. Defaults to False.

Parameters:state -- True if this window should block mouse clicks.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Set the size of this window and then re-sizes and shifts the contents of the windows container to fit the new size.

Parameters:dimensions -- The new dimensions to set.
set_display_title(new_title: str)

Set the title of the window.

Parameters:new_title -- The title to set.
set_minimum_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

If this window is resizable, then the dimensions we set here will be the minimum that users can change the window to. They are also used as the minimum size when 'set_dimensions' is called.

Parameters:dimensions -- The new minimum dimension for the window.
set_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the absolute screen rect position of an element.

Parameters:position -- The new position to set.
set_relative_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the relative rect position of an element.

Parameters:position -- The new position to set.
should_use_window_edge_resize_cursor() → bool

Returns true if this window is in a state where we should display one of the resizing cursors

Returns:True if a resizing cursor is needed.
update(time_delta: float)

A method called every update cycle of our application. Designed to be overridden by derived classes but also has a little functionality to make sure the window's layer 'thickness' is accurate and to handle window resizing.

Parameters:time_delta -- time passed in seconds between one call to this method and the next.
class pygame_gui.core.interfaces.IUIWindowStackInterface

Bases: object

A class for managing a stack of GUI windows so that only one is 'in front' at a time and the rest are sorted based on the last time they were interacted with/created.

add_new_window(window: pygame_gui.core.interfaces.window_interface.IWindowInterface)

Adds a window to the top of the stack.

Parameters:window -- The window to add.
clear()

Empties the whole stack removing and killing all windows.

get_stack() → List[pygame_gui.core.interfaces.window_interface.IWindowInterface]

Return the internal window stack directly.

Returns:a list of Windows
is_window_at_top(window: pygame_gui.core.interfaces.window_interface.IWindowInterface) → bool

Checks if a window is at the top of the window stack or not.

Parameters:window -- The window to check.
Returns:returns True if this window is at the top of the stack.
move_window_to_front(window_to_front: pygame_gui.core.interfaces.window_interface.IWindowInterface)

Moves the passed in window to the top of the window stack and resorts the other windows to deal with the change.

Parameters:window_to_front -- the window to move to the front.
remove_window(window_to_remove: pygame_gui.core.interfaces.window_interface.IWindowInterface)

Removes a window from the stack and resorts the remaining windows to adjust for it's absence.

Parameters:window_to_remove -- the window to remove.
class pygame_gui.core.interfaces.IUITooltipInterface

Bases: object

A meta class that defines the interface that a UI Tool tip uses.

Interfaces like this help us evade cyclical import problems by allowing us to define the actual manager class later on and have it make use of the classes that use the interface.

find_valid_position(position: pygame.math.Vector2) → bool

Finds a valid position for the tool tip inside the root container of the UI.

The algorithm starts from the position of the target we are providing a tool tip for then it tries to fit the rectangle for the tool tip onto the screen by moving it above, below, to the left and to the right, until we find a position that fits the whole tooltip rectangle on the screen at once.

If we fail to manage this then the method will return False. Otherwise it returns True and set the position of the tool tip to our valid position.

Parameters:position -- A 2D vector representing the position of the target this tool tip is for.
Returns:returns True if we find a valid (visible) position and False if we do not.
kill()

Overrides the UIElement's default kill method to also kill the text block element that helps make up the complete tool tip.

rebuild()

Rebuild anything that might need rebuilding.

rebuild_from_changed_theme_data()

Called by the UIManager to check the theming data and rebuild whatever needs rebuilding for this element when the theme data has changed.

set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Directly sets the dimensions of this tool tip. This will overwrite the normal theming.

Parameters:dimensions -- The new dimensions to set
set_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Sets the absolute screen position of this tool tip, updating it's subordinate text box at the same time.

Parameters:position -- The absolute screen position to set.
set_relative_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Sets the relative screen position of this tool tip, updating it's subordinate text box at the same time.

Parameters:position -- The relative screen position to set.
class pygame_gui.core.interfaces.IUIManagerInterface

Bases: object

A meta class that defines the interface that a UI Manager uses.

Interfaces like this help us evade cyclical import problems by allowing us to define the actual manager class later on and have it make use of the classes that use the interface.

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.

Parameters:
  • 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.
calculate_scaled_mouse_position(position: Tuple[int, int]) → Tuple[int, int]

Scaling an input mouse position by a scale factor.

clear_and_reset()

Clear the whole UI.

create_tool_tip(text: str, position: Tuple[int, int], hover_distance: Tuple[int, int]) → pygame_gui.core.interfaces.tool_tip_interface.IUITooltipInterface

Creates a tool tip ands returns it.

Parameters:
  • text -- The tool tips text, can utilise the HTML subset used in all UITextBoxes.
  • position -- The screen position to create the tool tip for.
  • hover_distance -- The distance we should hover away from our target position.
Returns:

A tool tip placed somewhere on the screen.

draw_ui(window_surface: pygame.Surface)

Draws the UI.

Parameters:window_surface -- The screen or window surface on which we are going to draw all of our UI Elements.
get_double_click_time() → float

Returns time between clicks that counts as a double click.

Returns:A float, time measured in seconds.
get_focus_set() → Set[pygame_gui.core.interfaces.element_interface.IUIElementInterface]

Gets the focused set.

Returns:The set of elements that currently have interactive focus.
get_locale() → str

Get the locale language code being used in the UIManager

Returns:A two letter ISO 639-1 code for the current locale.
get_mouse_position() → Tuple[int, int]

Get the position of the mouse in the UI.

get_root_container() → pygame_gui.core.interfaces.container_interface.IUIContainerInterface

Returns the 'root' container. The one all UI elements are placed in by default if they are not placed anywhere else, fills the whole OS/pygame window.

Returns:A container.
get_shadow(size: Tuple[int, int], shadow_width: int = 2, shape: str = 'rectangle', corner_radius: int = 2) → pygame.Surface

Returns a 'shadow' surface scaled to the requested size.

Parameters:
  • size -- The size of the object we are shadowing + it's shadow.
  • shadow_width -- The width of the shadowed edge.
  • shape -- The shape of the requested shadow.
  • corner_radius -- The radius of the shadow corners if this is a rectangular shadow.
Returns:

A shadow as a pygame Surface.

get_sprite_group() → pygame.sprite.LayeredDirty

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

Returns:The UI's sprite group.
get_theme() → pygame_gui.core.interfaces.appearance_theme_interface.IUIAppearanceThemeInterface

Gets the theme so the data in it can be accessed.

Returns:The theme data used by this UIManager
get_universal_empty_surface() → pygame.Surface

Sometimes we want to hide sprites or just have sprites with no visual component, when we do we can just use this empty surface to save having lots of empty surfaces all over memory.

Returns:An empty, and therefore invisible pygame.surface.Surface
get_window_stack() → pygame_gui.core.interfaces.window_stack_interface.IUIWindowStackInterface

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.

Returns:The stack of windows.
preload_fonts(font_list: List[Dict[str, Union[str, int, float]]])

Pre-loads a list of fonts.

Parameters:font_list -- A list of font descriptions in dictionary format as described above.
print_layer_debug()

Print some formatted information on the current state of the UI Layers.

Handy for debugging layer problems.

print_unused_fonts()

Prints a list of fonts that have been loaded but are not being used.

process_events(event: pygame.event.Event)

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

Parameters:event -- pygame.event.Event - the event to process.
set_active_cursor(cursor: Tuple[Tuple[int, int], Tuple[int, int], Tuple[int, ...], Tuple[int, ...]])

This is for users of the library to set the currently active cursor, it will be currently only be overriden by the resizing cursors.

The expected input is in the same format as the standard pygame cursor module, except without expanding the initial Tuple. So, to call this function with the default pygame arrow cursor you would do:

manager.set_active_cursor(pygame.cursors.arrow)
set_focus_set(focus: Union[pygame_gui.core.interfaces.element_interface.IUIElementInterface, Set[pygame_gui.core.interfaces.element_interface.IUIElementInterface]])

Set a set of element as the focused set.

Parameters:focus -- The set of element to focus on.
set_locale(locale: str)

Set a locale language code to use in the UIManager

Parameters:locale -- A two letter ISO 639-1 code for a supported language.

TODO: Make this raise an exception for an unsupported language?

set_text_input_hovered(hovering_text_input: bool)

Set to true when hovering an area text can be input into.

Currently switches the cursor to the I-Beam cursor.

Parameters:hovering_text_input -- set to True to toggle the I-Beam cursor
set_visual_debug_mode(is_active: bool)

Loops through all our UIElements to turn visual debug mode on or off. Also calls print_layer_debug()

Parameters:is_active -- True to activate visual debug and False to turn it off.
set_window_resolution(window_resolution: Tuple[int, int])

Sets the window resolution.

Parameters:window_resolution -- the resolution to set.
update(time_delta: float)

Update the UIManager.

Parameters:time_delta -- The time passed since the last call to update, in seconds.
class pygame_gui.core.interfaces.IUITextOwnerInterface

Bases: object

A common interface for UIElements that own some text, to help make it easier to run text effects across multiple UIElements.

clear_all_active_effects(sub_chunk: Optional[TextLineChunkFTFont] = None)

Clears any active effects and redraws the text. A full reset, usually called before firing off a new effect if one is already in progress.

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
clear_text_surface(sub_chunk: Optional[TextLineChunkFTFont] = None)

Clear the text surface

Parameters:sub_chunk -- An optional chunk so we only clear the surface for this chunk.
get_object_id() → str

The UI object ID of this text owner for use in effect events.

Returns:the ID string
get_text_letter_count(sub_chunk: Optional[TextLineChunkFTFont] = None) → int

The amount of letters in the text

Parameters:sub_chunk -- An optional chunk to restrict the count to only this chunk.
Returns:number of letters as an int
set_active_effect(effect_type: Optional[pygame_gui._constants.UITextEffectType], params: Optional[Dict[str, Any]] = None, effect_tag: Optional[str] = None)

Set an animation effect to run on the text box. The effect will start running immediately after this call.

These effects are currently supported:

  • TEXT_EFFECT_TYPING_APPEAR - Will look as if the text is being typed in.
  • TEXT_EFFECT_FADE_IN - The text will fade in from the background colour.
  • TEXT_EFFECT_FADE_OUT - The text will fade out to the background colour.
Parameters:
  • effect_tag -- if not None, only apply the effect to chunks with this tag.
  • params -- Any parameters for the effect you are setting, if none are set defaults will be used.
  • effect_type -- The type of the effect to set. If set to None instead it will cancel any active effect.
set_text_alpha(alpha: int, sub_chunk: Optional[TextLineChunkFTFont] = None)

Set the global alpha value for the text

Parameters:
  • alpha -- the alpha to set.
  • sub_chunk -- An optional chunk so we only set the alpha for this chunk.
set_text_offset_pos(offset: Tuple[int, int], sub_chunk: Optional[TextLineChunkFTFont] = None)

Move the text around by this offset.

Parameters:
  • offset -- the offset to set
  • sub_chunk -- An optional chunk so we only set the offset for this chunk.
Returns:

set_text_rotation(rotation: int, sub_chunk: Optional[TextLineChunkFTFont] = None)

rotate the text by this int in degrees

Parameters:
  • rotation -- the rotation to set
  • sub_chunk -- An optional chunk so we only set the rotation for this chunk.
Returns:

set_text_scale(scale: float, sub_chunk: Optional[TextLineChunkFTFont] = None)

Scale the text by this float

Parameters:
  • scale -- the scale to set
  • sub_chunk -- An optional chunk so we only set the rotation for this chunk.
Returns:

stop_finished_effect(sub_chunk: Optional[TextLineChunkFTFont] = None)

Stops a finished effect. Will leave effected text in the state it was in when effect ended. Used when an effect reaches a natural end where we might want to keep it in the end of effect state (e.g. a fade out)

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
update_text_effect(time_delta: float)

Update any active text effect on the text owner

Parameters:time_delta -- the time delta in seconds
update_text_end_position(end_pos: int, sub_chunk: Optional[TextLineChunkFTFont] = None)

The position in the text to render up to.

Parameters:
  • end_pos -- The current end position as an int
  • sub_chunk -- An optional chunk to restrict the end_position to only this chunk.