pygame_gui.core.interfaces package

Submodules

pygame_gui.core.interfaces.container_interface module

class pygame_gui.core.interfaces.container_interface.IContainerLikeInterface

Bases: object

A metaclass 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.

are_contents_hovered() → bool

Are any of the elements in the container hovered? Used for handling mousewheel events.

Returns:: True if one of the elements is hovered, False otherwise.

abstract get_container() → IUIContainerInterface: Gets an actual container from this container-like UI element.

abstract 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.

abstract 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: IUIElementInterface

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.

abstract add_element(element: 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.

calc_add_element_changes_thickness(element: IUIElementInterface)

This function checks if a single added element will increase the containers thickness and if so updates containers recursively.

Parameters:: element -- the element to check.

abstract 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.

abstract 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.

abstract clear(): Removes and kills all the UI elements inside this container.

abstract get_image_clipping_rect() → Rect | None

Obtain the current image clipping rect.

Returns:: The current clipping rect. It may be None.

abstract get_rect() → Rect

Access to the container's rect

Returns:: a pygame rectangle

abstract get_size() → Tuple[int, int]

Get the container's pixel size.

Returns:: the pixel size as tuple [x, y]

abstract get_thickness() → int

Get the container's layer thickness.

Returns:: the thickness as an integer.

abstract 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.

abstract 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.

on_contained_elements_changed(target: IUIElementInterface) → None

Update the contents of this container that one of their layout anchors may have moved, or been resized.

Parameters:: target -- the UI element that has been benn moved or resized.

abstract 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

abstract remove_element(element: IUIElementInterface)

Remove a UIElement from this container.

Parameters:: element -- A UIElement to remove from this container.

abstract set_dimensions(dimensions: Vector2 | Tuple[float, float], clamp_to_container: bool = False)

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

Parameters:

clamp_to_container --
dimensions -- the new dimensions.

abstract set_position(position: Vector2 | 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.

abstract set_relative_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- the new relative position to set.

abstract 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 metaclass 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.

abstract add_font_paths(font_name: str, regular_path: str, bold_path: str | None = None, italic_path: str | None = None, bold_italic_path: str | None = 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.

abstract calculate_scaled_mouse_position(position: Tuple[int, int]) → Tuple[int, int]: Scaling an input mouse position by a scale factor.

abstract clear_and_reset(): Clear the whole UI.

abstract create_tool_tip(text: str, position: Tuple[int, int], hover_distance: Tuple[int, int], parent_element: IUIElementInterface, object_id: ObjectID, *, wrap_width: int | None = None, text_kwargs: Dict[str, str] | None = None) → 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.
parent_element -- The UIElement that spawned this tool tip.
object_id -- the object_id of the tooltip.
wrap_width -- an optional width for the tool tip, will overwrite any value from the theme file.
text_kwargs -- a dictionary of variable arguments to pass to the translated string useful when you have multiple translations that need variables inserted in the middle.

Returns:

A tool tip placed somewhere on the screen.

abstract draw_ui(window_surface: Surface)

Draws the UI.

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

abstract get_double_click_time() → float

Returns time between clicks that counts as a double click.

Returns:: A float, time measured in seconds.

abstract get_focus_set() → Set[IUIElementInterface]

Gets the focused set.

Returns:: The set of elements that currently have interactive focus. If None, nothing is currently focused.

abstract get_hovering_any_element() → bool

True if any UI element (other than the root container) is hovered by the mouse.

Combined with 'get_focus_set()' and the return value from process_events(), it should make it easier to switch input events between the UI and other parts of an application.

abstract 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.

abstract get_mouse_position() → Tuple[int, int]: Get the position of the mouse in the UI.

abstract get_root_container() → 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.

abstract get_shadow(size: Tuple[int, int], shadow_width: int = 2, shape: str = 'rectangle', corner_radius: List[int] | None = None) → 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.

abstract get_sprite_group() → LayeredGUIGroup

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.

abstract get_theme() → IUIAppearanceThemeInterface

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

Returns:: The theme data used by this UIManager

abstract get_universal_empty_surface() → 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

abstract get_window_stack() → 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.

abstract preload_fonts(font_list: List[Dict[str, str | int | float]])

Pre-loads a list of fonts.

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

abstract print_layer_debug()

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

Handy for debugging layer problems.

abstract print_unused_fonts(): Prints a list of fonts that have been loaded but are not being used.

abstract process_events(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.

abstract 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 overridden 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)

abstract set_focus_set(focus: IUIElementInterface | Set[IUIElementInterface] | None)

Set a set of element as the focused set.

Parameters:: focus -- The set of element to focus on.

abstract 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?

abstract set_text_hovered(hovering_text_input: bool)

Set to true when hovering an area containing selectable text.

Currently, switches the cursor to the I-Beam cursor.

Parameters:: hovering_text_input -- set to True to toggle the I-Beam cursor

abstract 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.

abstract set_window_resolution(window_resolution: Tuple[int, int])

Sets the window resolution.

Parameters:: window_resolution -- the resolution to set.

abstract 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 metaclass 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.

abstract property always_on_top: bool: Whether the window is always above normal windows or not. :return:

abstract can_hover() → bool: Called to test if this window can be hovered.

abstract change_layer(layer: int)

Change the drawing layer of this window.

Parameters:: layer -- the new layer to move to.

abstract check_clicked_inside_or_blocking(event: Event) → bool

A quick event check outside 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.

abstract 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?

abstract 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_layer_thickness() → int: The layer 'thickness' of this window/ :return: an integer

abstract 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).

abstract 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.

abstract property layer: int: The layer of this window (read-only)

abstract on_moved_to_front(): Called when a window is moved to the front of the stack.

abstract process_event(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.

abstract rebuild(): Rebuilds the window when the theme has changed.

abstract 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.

abstract 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.

abstract set_dimensions(dimensions: Vector2 | 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.

abstract set_display_title(new_title: str)

Set the title of the window.

Parameters:: new_title -- The title to set.

abstract set_minimum_dimensions(dimensions: Vector2 | 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.

abstract set_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- The new position to set.

abstract set_relative_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- The new position to set.

abstract 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.

abstract 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.

abstract apply_gradient_to_surface(input_surface: Surface, rect: Rect | None = 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.IContainerLikeInterface

Bases: object

A metaclass 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.

are_contents_hovered() → bool

Are any of the elements in the container hovered? Used for handling mousewheel events.

Returns:: True if one of the elements is hovered, False otherwise.

abstract get_container() → IUIContainerInterface: Gets an actual container from this container-like UI element.

abstract 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.

abstract 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.IGUIFontInterface

Bases: object

A font interface, so we can easily switch between pygame.freetype.Font and pygame.Font.

get_direction() → int

Returns:

abstract get_metrics(text: str)

Parameters:: text --
Returns:

abstract get_padding_height()

Returns:

abstract get_point_size()

abstract get_rect(text: str) → Rect: Not sure if we want this. :return:

abstract render_premul(text: str, text_color: Color) → Surface: Draws text to a surface ready for pre-multiplied alpha-blending

render_premul_to(text: str, text_colour: Color, surf_size: Tuple[int, int], surf_position: Tuple[int, int])

Parameters:

text --
text_colour --
surf_size --
surf_position --

Returns:

size(text: str) → Tuple[int, int]

Return the pixel size of a given text string in this font

Parameters:: text -- the text to check.
Returns:: the width & height in pixels.

abstract property underline: bool

Returns:

abstract property underline_adjustment: float

Returns:

class pygame_gui.core.interfaces.IGUISpriteInterface

Bases: object

A sprite Interface class specifically designed for the GUI. Very similar to pygame's DirtySprite but without the Dirty flag.

abstract add(*groups)

add the sprite to groups

Parameters:: groups -- sprite groups to add this sprite to.

Any number of Group instances can be passed as arguments. The Sprite will be added to the Groups it is not already a member of.

abstract add_internal(group)

For adding this sprite to a group internally.

Parameters:: group -- The group we are adding to.

abstract alive()

does the sprite belong to any groups

Sprite.alive(): return bool

Returns True when the Sprite belongs to one or more Groups.

abstract property blendmode

Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Overwrites dynamic property from sprite class for speed.

abstract groups()

list of Groups that contain this Sprite

Sprite.groups(): return group_list

Returns a list of all the Groups that contain this Sprite.

abstract property image

Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Overwrites dynamic property from sprite class for speed.

abstract kill()

remove the Sprite from all Groups

Sprite.kill(): return None

The Sprite is removed from all the Groups that contain it. This won't change anything about the state of the Sprite. It is possible to continue to use the Sprite after this method has been called, including adding it to Groups.

abstract property layer

Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Overwrites dynamic property from sprite class for speed.

abstract property rect

Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Overwrites dynamic property from sprite class for speed.

abstract remove(*groups)

remove the sprite from groups

Parameters:: groups -- sprite groups to remove this sprite from.

Any number of Group instances can be passed as arguments. The Sprite will be removed from the Groups it is currently a member of.

abstract remove_internal(group)

For removing this sprite from a group internally.

Parameters:: group -- The group we are removing from.

abstract update(time_delta: float)

A stub to override.

Parameters:: time_delta -- the time passed in seconds between calls to this function.

abstract property visible: You can make this sprite disappear without removing it from the group assign 0 for invisible and 1 for visible

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.

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

Parameters:

element_base_ids -- when an element is also another element (e.g. a file dialog is also a window)
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.

abstract 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.

abstract get_colour(colour_id: str, combined_element_ids: List[str] | None = None) → 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.

abstract get_colour_or_gradient(colour_id: str, combined_ids: List[str] | None = None) → Color | 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.

abstract get_font(combined_element_ids: List[str]) → IGUIFontInterface

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 IGUIFontInterface:: An interface to a pygame font object wrapper.

abstract get_font_dictionary() → 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.

abstract 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

abstract get_image(image_id: str, combined_element_ids: List[str]) → 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

abstract get_misc_data(misc_data_id: str, combined_element_ids: List[str]) → str | Dict

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

abstract load_theme(file_path: str | PathLike | StringIO | PackageResource | dict)

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

Parameters:: file_path -- The location of the theme, or the theme data we want to load.

abstract reload_theming(): We need to load our theme file to see if anything expensive has changed, if so trigger it to reload/rebuild.

abstract update_caching(time_delta: float): Updates the various surface caches.

abstract update_single_element_theming(element_name: str, new_theming_data: str): Update theming data, via string - for a single element. :param element_name: :param new_theming_data: :return:

abstract update_theming(new_theming_data: str, rebuild_all: bool = True)

Update theming data, via string - for the whole UI.

Parameters:

new_theming_data --
rebuild_all --

Returns:

class pygame_gui.core.interfaces.IUIContainerInterface

Bases: IUIElementInterface

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.

abstract add_element(element: 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.

calc_add_element_changes_thickness(element: IUIElementInterface)

This function checks if a single added element will increase the containers thickness and if so updates containers recursively.

Parameters:: element -- the element to check.

abstract 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.

abstract 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.

abstract clear(): Removes and kills all the UI elements inside this container.

abstract get_image_clipping_rect() → Rect | None

Obtain the current image clipping rect.

Returns:: The current clipping rect. It may be None.

abstract get_rect() → Rect

Access to the container's rect

Returns:: a pygame rectangle

abstract get_size() → Tuple[int, int]

Get the container's pixel size.

Returns:: the pixel size as tuple [x, y]

abstract get_thickness() → int

Get the container's layer thickness.

Returns:: the thickness as an integer.

abstract 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.

abstract 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.

on_contained_elements_changed(target: IUIElementInterface) → None

Update the contents of this container that one of their layout anchors may have moved, or been resized.

Parameters:: target -- the UI element that has been benn moved or resized.

abstract 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

abstract remove_element(element: IUIElementInterface)

Remove a UIElement from this container.

Parameters:: element -- A UIElement to remove from this container.

abstract set_dimensions(dimensions: Vector2 | Tuple[float, float], clamp_to_container: bool = False)

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

Parameters:

clamp_to_container --
dimensions -- the new dimensions.

abstract set_position(position: Vector2 | 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.

abstract set_relative_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- the new relative position to set.

abstract 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.IUIElementInterface

Bases: IGUISpriteInterface

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.

abstract can_hover() → bool: A stub method to override. Called to test if this method can be hovered.

abstract change_layer(new_layer: int)

Changes the layer this element is on.

Parameters:: new_layer -- The layer to change this element to.

abstract 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.

abstract disable()

Disables elements so they are no longer interactive.

Elements should handle their own enabling and disabling.

abstract enable()

Enables elements so they are interactive again.

Elements should handle their own enabling and disabling.

abstract focus(): A stub to override. Called when we focus this UI element.

abstract get_abs_rect() → Rect

The absolute positioning rect.

Returns:: A pygame rect.

abstract 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.

abstract get_anchors() → Dict[str, str | IUIElementInterface]

A dictionary containing all the anchors defining what the relative rect is relative to

Returns:: A dictionary containing all the anchors defining what the relative rect is relative to

abstract get_class_ids() → List[str]

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

Returns:: a list of strings, one for each element in the hierarchy.

abstract get_element_base_ids() → List[str]

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

Returns:: a list of strings, one for each element in the hierarchy.

abstract 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 for each element in the hierarchy.

abstract get_focus_set() → Set[Any]: Return the set of elements to focus when we focus this element.

abstract get_image_clipping_rect() → Rect | None

Obtain the current image clipping rect.

Returns:: The current clipping rect. Maybe None.

abstract get_object_ids() → List[str]

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

Returns:: a list of strings, one for each element in the hierarchy.

abstract get_relative_rect() → Rect

The relative positioning rect.

Returns:: A pygame rect.

abstract 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.

abstract 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.

abstract hide(): Hides the widget, which means the widget will not get drawn and will not process events. Clear hovered state.

abstract 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.

abstract property hovered: bool

Are we hovering over this element with the mouse pointer or other input highlighting method.

Returns:: True if hovered.

abstract join_focus_sets(element)

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

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

abstract kill(): Overriding regular sprite kill() method to remove the element from its container.

abstract 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.

abstract on_hovered(): A stub to override. Called when this UI element first enters the 'hovered' state.

abstract on_locale_changed(): Called for each element when the locale is changed on their UIManager

abstract on_unhovered(): A stub to override. Called when this UI element leaves the 'hovered' state.

abstract process_event(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.

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

abstract 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.

abstract remove_element_from_focus_set(element)

remove an element from this sets focus group.

Parameters:: element -- The element to remove.

abstract set_anchors(anchors: Dict[str, str | IUIElementInterface] | None) → None

Wraps the setting of the anchors with some validation

Parameters:: anchors -- A dictionary of anchors defining what the relative rect is relative to
Returns:: None

abstract set_dimensions(dimensions: Vector2 | Tuple[float, float], clamp_to_container: bool = False)

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.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

abstract 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.

abstract set_image(new_image: Surface | None)

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.

abstract set_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- The new position to set.

abstract set_relative_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- The new position to set.

abstract 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.

abstract show(): Shows the widget, which means the widget will get drawn and will process events.

abstract unfocus(): A stub to override. Called when we stop focusing this UI element.

abstract 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.

abstract update_containing_rect_position(): Updates the position of this element based on the position of its container. Usually called when the container has moved.

abstract while_hovering(time_delta: float, mouse_pos: 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.IUIFontDictionaryInterface

Bases: object

A metaclass 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.

abstract add_font_path(font_name: str, font_path: str, bold_path: str | None = None, italic_path: str | None = None, bold_italic_path: str | None = 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.

abstract 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.

abstract convert_html_to_point_size(html_size: float) → int

Takes in an 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.

abstract create_font_id(font_size: int, font_name: str, bold: bool, italic: bool, antialiased: bool = True) → 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.
antialiased -- Whether the font is antialiased or not.

Return str:

The finished font id.

abstract ensure_debug_font_loaded(): Ensure the font we use for debugging purposes is loaded. Generally called after we start a debugging mode.

abstract find_font(font_size: int, font_name: str, bold: bool = False, italic: bool = False, antialiased: bool = True, script: str = 'Latn', direction: int = 0) → IGUIFontInterface

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.
antialiased -- Whether the font is antialiased or not.
script -- The ISO 15924 script code used for text shaping as a string.
direction -- the direction of text e.g. left to right or right to left. An integer.

Return IGUIFontInterface:

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

abstract get_default_font() → IGUIFontInterface

Grab the default font.

Returns:: The default font.

abstract preload_font(font_size: int, font_name: str, bold: bool = False, italic: bool = False, force_immediate_load: bool = False, antialiased: bool = True, script: str = 'Latn', direction: int = 0)

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 preload 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.
antialiased -- Whether the font is antialiased or not.
script -- The ISO 15924 script code used for text shaping as a string.
direction -- the direction of text e.g. left to right or right to left. An integer.

abstract 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.IUIManagerInterface

Bases: object

A metaclass 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.

abstract add_font_paths(font_name: str, regular_path: str, bold_path: str | None = None, italic_path: str | None = None, bold_italic_path: str | None = 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.

abstract calculate_scaled_mouse_position(position: Tuple[int, int]) → Tuple[int, int]: Scaling an input mouse position by a scale factor.

abstract clear_and_reset(): Clear the whole UI.

abstract create_tool_tip(text: str, position: Tuple[int, int], hover_distance: Tuple[int, int], parent_element: IUIElementInterface, object_id: ObjectID, *, wrap_width: int | None = None, text_kwargs: Dict[str, str] | None = None) → 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.
parent_element -- The UIElement that spawned this tool tip.
object_id -- the object_id of the tooltip.
wrap_width -- an optional width for the tool tip, will overwrite any value from the theme file.
text_kwargs -- a dictionary of variable arguments to pass to the translated string useful when you have multiple translations that need variables inserted in the middle.

Returns:

A tool tip placed somewhere on the screen.

abstract draw_ui(window_surface: Surface)

Draws the UI.

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

abstract get_double_click_time() → float

Returns time between clicks that counts as a double click.

Returns:: A float, time measured in seconds.

abstract get_focus_set() → Set[IUIElementInterface]

Gets the focused set.

Returns:: The set of elements that currently have interactive focus. If None, nothing is currently focused.

abstract get_hovering_any_element() → bool

True if any UI element (other than the root container) is hovered by the mouse.

Combined with 'get_focus_set()' and the return value from process_events(), it should make it easier to switch input events between the UI and other parts of an application.

abstract 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.

abstract get_mouse_position() → Tuple[int, int]: Get the position of the mouse in the UI.

abstract get_root_container() → 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.

abstract get_shadow(size: Tuple[int, int], shadow_width: int = 2, shape: str = 'rectangle', corner_radius: List[int] | None = None) → 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.

abstract get_sprite_group() → LayeredGUIGroup

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.

abstract get_theme() → IUIAppearanceThemeInterface

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

Returns:: The theme data used by this UIManager

abstract get_universal_empty_surface() → 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

abstract get_window_stack() → 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.

abstract preload_fonts(font_list: List[Dict[str, str | int | float]])

Pre-loads a list of fonts.

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

abstract print_layer_debug()

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

Handy for debugging layer problems.

abstract print_unused_fonts(): Prints a list of fonts that have been loaded but are not being used.

abstract process_events(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.

abstract 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 overridden 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)

abstract set_focus_set(focus: IUIElementInterface | Set[IUIElementInterface] | None)

Set a set of element as the focused set.

Parameters:: focus -- The set of element to focus on.

abstract 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?

abstract set_text_hovered(hovering_text_input: bool)

Set to true when hovering an area containing selectable text.

Currently, switches the cursor to the I-Beam cursor.

Parameters:: hovering_text_input -- set to True to toggle the I-Beam cursor

abstract 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.

abstract set_window_resolution(window_resolution: Tuple[int, int])

Sets the window resolution.

Parameters:: window_resolution -- the resolution to set.

abstract 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.

abstract clear_all_active_effects(sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = 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.

abstract clear_text_surface(sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = None)

Clear the text surface

Parameters:: sub_chunk -- An optional chunk so we only clear the surface for this chunk.

abstract get_object_id() → str

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

Returns:: the ID string

abstract get_text_letter_count(sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = 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

abstract set_active_effect(effect_type: UITextEffectType | None, params: Dict[str, Any] | None = None, effect_tag: str | None = 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.

abstract set_text_alpha(alpha: int, sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = 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.

abstract set_text_offset_pos(offset: Tuple[int, int], sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = 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:

abstract set_text_rotation(rotation: int, sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = 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:

abstract set_text_scale(scale: float, sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = 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:

abstract stop_finished_effect(sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = 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.

abstract update_text_effect(time_delta: float)

Update any active text effect on the text owner

Parameters:: time_delta -- the time delta in seconds

abstract update_text_end_position(end_pos: int, sub_chunk: pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont | None = 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.

class pygame_gui.core.interfaces.IUITooltipInterface

Bases: object

A metaclass 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.

abstract find_valid_position(position: Vector2 | Tuple[float, float]) → 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.

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

abstract rebuild(): Rebuild anything that might need rebuilding.

abstract 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.

abstract set_dimensions(dimensions: Vector2 | Tuple[float, float])

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

Parameters:: dimensions -- The new dimensions to set

abstract set_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- The absolute screen position to set.

abstract set_relative_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- The relative screen position to set.

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.

abstract add_new_window(window: IWindowInterface)

Adds a window to the top of the stack.

Parameters:: window -- The window to add.

abstract clear(): Empties the whole stack removing and killing all windows.

abstract get_full_stack() → List[IWindowInterface]

Returns the full stack of normal and always on top windows.

Returns:: a list of Windows

abstract is_window_at_top(window: 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.

is_window_at_top_of_top(window: IWindowInterface) → bool

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

Parameters:: window -- The window to check.
Returns:: returns True if this window is at the top of the stack.

abstract move_window_to_front(window_to_front: 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.

abstract remove_window(window_to_remove: 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.IWindowInterface

Bases: object

A metaclass 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.

abstract property always_on_top: bool: Whether the window is always above normal windows or not. :return:

abstract can_hover() → bool: Called to test if this window can be hovered.

abstract change_layer(layer: int)

Change the drawing layer of this window.

Parameters:: layer -- the new layer to move to.

abstract check_clicked_inside_or_blocking(event: Event) → bool

A quick event check outside 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.

abstract 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?

abstract 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_layer_thickness() → int: The layer 'thickness' of this window/ :return: an integer

abstract 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).

abstract 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.

abstract property layer: int: The layer of this window (read-only)

abstract on_moved_to_front(): Called when a window is moved to the front of the stack.

abstract process_event(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.

abstract rebuild(): Rebuilds the window when the theme has changed.

abstract 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.

abstract 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.

abstract set_dimensions(dimensions: Vector2 | 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.

abstract set_display_title(new_title: str)

Set the title of the window.

Parameters:: new_title -- The title to set.

abstract set_minimum_dimensions(dimensions: Vector2 | 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.

abstract set_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- The new position to set.

abstract set_relative_position(position: Vector2 | Tuple[float, float])

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

Parameters:: position -- The new position to set.

abstract 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.

abstract 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.