pygame_gui.elements package

Submodules

pygame_gui.elements.ui_2d_slider module

Bases: UIElement

A 2d slider is intended to help users adjust values within a range, for example a volume control.

Parameters:

relative_rect -- A rectangle describing the position and dimensions of the element.
start_value_x -- The x value to start the slider at.
value_range_x -- The full range of x values.
start_value_y -- The y value to start the slider at.
value_range_y -- The full range of y values.
invert_y -- Should the y increase from bottom to top instead of the other way round?
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element "belongs to" in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

disable(): Disable the slider. It should not be interactive and will use the disabled theme colours.

enable(): Enable the slider. It should become interactive and will use the normal theme colours.

get_current_value() → Tuple[float, int]

Gets the current value the slider is set to.

Returns:: The current value recorded by the slider.

hide(): In addition to the base UIElement.hide() - hide the sliding button and hide the button_container which will propagate and hide the left and right buttons.

kill(): Overrides the normal sprite kill() method to also kill the button elements that help make up the slider.

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

rebuild_from_changed_theme_data() → None

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

Returns:: None

set_current_value(value_x: float | int, value_y: float | int, warn: bool = True) → None

Sets the value of the slider, which will move the position of the slider to match. Will issue a warning if the value set is not in the value range.

Parameters:

value_x -- The x value to set.
value_y -- The y value to set.
warn -- set to false in order to suppress the default warning, instead the value will be clamped.

Param:

invert_y: Should the y value be inverted? If not passed then will use self.invert_value for this info.

Returns:

None

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

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this slider, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this slider, updating all subordinate button elements at the same time.

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

show(): In addition to the base UIElement.show() - show the sliding button and show the button_container which will propagate and show the left and right buttons.

update(time_delta: float)

Takes care of actually moving the slider based on interactions reported by the buttons or based on movement of the mouse if we are gripping the slider itself.

Parameters:: time_delta -- the time in seconds between calls to update.

pygame_gui.elements.ui_auto_resizing_container module

class pygame_gui.elements.ui_auto_resizing_container.UIAutoResizingContainer(relative_rect: Rect | FRect | Tuple[float, float, float, float], min_edges_rect: Rect | None = None, max_edges_rect: Rect | None = None, resize_left: bool = True, resize_right: bool = True, resize_top: bool = True, resize_bottom: bool = True, manager: IUIManagerInterface | None = None, *, starting_height: int = 1, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1)

Bases: UIContainer

A container like UI element that updates its size as elements within it change size, or new elements are added

Parameters:

relative_rect -- The starting size and relative position of the container.
min_edges_rect -- The Rect which defines the maximum values for the left and top, and the minimum values for the right and bottom edges of the container. Defaults to the None (current rect)
max_edges_rect -- The Rect which defines the minimum values for the left and top, and the maximum values for the right and bottom edges of the container. Defaults to the None (unbounded)
resize_left -- Should the left side be resized?
resize_right -- Should the right side be resized?
resize_top -- Should the top side be resized?
resize_bottom -- Should the bottom side be resized?
manager -- The UI manager for this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
starting_height -- The starting layer height of this container above its container. Defaults to 1.
container -- The container this container is within. Defaults to None (which is the root container for the UI)
parent_element -- A parent element for this container. Defaults to None, or the container if you've set that.
object_id -- An object ID for this element.
anchors -- Layout anchors in a dictionary.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

add_element(element: IUIElementInterface) → None

Add a UIElement to the container. The UIElement's relative_rect parameter will be relative to this container. Overridden to also update dimensions.

Parameters:: element -- A UIElement to add to this container.
Returns:: None

on_contained_elements_changed(target: UIElement) → None

Update the positioning of the contained elements of this container. To be called when one of the contained elements may have moved, been resized or changed its anchors.

Parameters:: target -- the UI element that has been benn moved resized or changed its anchors.
Returns:: None

recalculate_abs_edges_rect() → None

Used to recalculate the absolute rects from the min and max edges rect which control the minimum and maximum sizes of the container. Usually called when the container of this container has moved, or the minimum or maximum rects have changed.

Returns:: None

remove_element(element: IUIElementInterface) → None

Remove a UIElement from this container.

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

update(time_delta: float) → None

Updates the container's size based upon the elements inside.

Call this function if you have added or removed an element from this container and want to update the size in the same frame, otherwise it will update in the next frame.

Parameters:: time_delta -- The time passed between frames, measured in seconds.
Returns:: None

update_containing_rect_position() → None

Overridden to also recalculate the absolute rects which control the minimum and maximum sizes of the container

Returns:: None

update_max_edges_rect(new_rect: Rect) → None

Updates the container's minimum values for the left and top, and the maximum value for the right and bottom edges based upon the edges of the new rect.

Call the update function if you want to update the elements contained in the same frame, otherwise the elements contained within will update in the next frame.

Parameters:: new_rect -- Rect to update the max_edges_rect with
Returns:: None

update_min_edges_rect(new_rect: Rect) → None

Updates the container's maximum values for the left and top, and the minimum value for the right and bottom edges based upon the edges of the new rect.

Call the update function if you want to update the elements contained in the same frame, otherwise the elements contained within will update in the next frame.

Parameters:: new_rect -- Rect to update the min_edges_rect with
Returns:: None

pygame_gui.elements.ui_button module

class pygame_gui.elements.ui_button.UIButton(relative_rect: Rect | FRect | Tuple[float, float, float, float] | Vector2 | Tuple[float, float], text: str, manager: IUIManagerInterface | None = None, container: IContainerLikeInterface | None = None, tool_tip_text: str | None = None, starting_height: int = 1, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, allow_double_clicks: bool = False, generate_click_events_from: Iterable[int] = frozenset({1}), visible: int = 1, *, command: Callable | Dict[int, Callable] | None = None, tool_tip_object_id: ObjectID | None = None, text_kwargs: Dict[str, str] | None = None, tool_tip_text_kwargs: Dict[str, str] | None = None, max_dynamic_width: int | None = None)

Bases: UIElement

A push button, a lot of the appearance of the button, including images to be displayed, is set up via the theme file. This button is designed to be pressed, do something, and then reset - rather than to be toggled on or off.

The button element is reused throughout the UI as part of other elements as it happens to be a very flexible interactive element.

Parameters:

relative_rect -- Normally a rectangle describing the position (relative to its container) and dimensions. Also accepts a position Coordinate where the dimensions will be dynamic depending on the text contents. Dynamic dimensions can be requested by setting the required dimension to -1.
text -- Text for the button.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
tool_tip_text -- Optional tool tip text, can be formatted with HTML. If supplied will appear on hover.
starting_height -- The height in layers above its container that this element will be placed.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
allow_double_clicks -- Enables double-clicking on buttons which will generate a unique event.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
command -- Functions to be called when an event is triggered by this element.
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.

bind(event: int, function: Callable | None = None)

Bind a function to an element event.

Parameters:

event -- The event to bind.
function -- The function to bind. None to unbind.

can_hover() → bool

Tests whether we can trigger the hover state for this button, other states take priority over it.

Returns:: True if we are able to hover this button.

check_pressed() → bool

A direct way to check if this button has been pressed in the last update cycle.

Returns:: True if the button has been pressed.

disable(): Disables the button so that it is no longer interactive.

enable(): Re-enables the button, so we can once again interact with it.

hide(): In addition to the base UIElement.hide() - Change the hovered state to a normal state.

hover_point(hover_x: int, hover_y: int) → bool

Tests if a position should be considered 'hovering' the button. Normally this just means our mouse pointer is inside the buttons rectangle, however if we are holding onto the button for a purpose(e.g. dragging a window around by its menu bar) the hover radius can be made to grow, so we don't keep losing touch with whatever we are moving.

Parameters:

hover_x -- horizontal pixel coordinate to test.
hover_y -- vertical pixel coordinate to test

Returns:

Returns True if we are hovering.

in_hold_range(position: Vector2 | Tuple[int, int] | Tuple[float, float]) → bool

Imagines a potentially larger rectangle around our button in which range we still grip hold of our button when moving the mouse. Makes it easier to use scrollbars.

Parameters:: position -- The position we are testing.
Return bool:: Returns True if our position is inside the hold range.

kill(): Overrides the standard sprite kill method to also kill any tooltips belonging to this button.

on_hovered(): Called when we enter the hover state, it sets the colours and image of the button to the appropriate values and redraws it.

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

on_self_event(event: int, data: Dict[str, Any] | None = None)

Called when an event is triggered by this element. Handles these events either by posting the event back to the event queue, or by running a function supplied by the user.

Parameters:

event -- The event triggered.
data -- event data

on_unhovered(): Called when we leave the hover state. Resets the colours and images to normal and kills any tooltip that was created while we were hovering the button.

process_event(event: Event) → bool

Handles various interactions with the button.

Parameters:: event -- The event to process.
Returns:: Return True if we want to consume this event, so it is not passed on to the rest of the UI.

rebuild(): A complete rebuild of the drawable shape used by this button.

rebuild_from_changed_theme_data(): Checks if any theming parameters have changed, and if so triggers a full rebuild of the button's drawable shape

select(): Called when we select focus this element. Changes the colours and image to the appropriate ones for the new state then redraws the button.

set_hold_range(xy_range: Tuple[int, int])

Set x and y values, in pixels, around our button to use as the hold range for time when we want to drag a button about but don't want it to slip out of our grasp too easily.

Imagine it as a large rectangle around our button, larger in all directions by whatever values we specify here.

Parameters:: xy_range -- The x and y values used to create our larger 'holding' rectangle.

set_text(text: str, *, text_kwargs: Dict[str, str] | None = None)

Sets the text on the button. The button will rebuild.

Parameters:

text -- The new text to set.
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.

unselect(): Called when we are no longer select focusing this element. Restores the colours and image to the default state then redraws the button.

update(time_delta: float)

Sets the pressed state for an update cycle if we've pressed this button recently.

Parameters:: time_delta -- the time in seconds between one call to update and the next.

pygame_gui.elements.ui_drop_down_menu module

class pygame_gui.elements.ui_drop_down_menu.UIClosedDropDownState(drop_down_menu_ui: UIDropDownMenu, selected_option: Tuple[str, str], base_position_rect: Rect | None, open_button_width: int, expand_direction: str | None, manager: IUIManagerInterface, container: IContainerLikeInterface, object_ids: List[str | None] | None, element_ids: List[str] | None, visible: int = 1, expand_on_option_click=True)

Bases: object

The closed state of the drop-down just displays the currently chosen option and a button that will switch the menu to the expanded state.

Parameters:

drop_down_menu_ui -- The UIDropDownElement this state belongs to.
selected_option -- The currently selected option.
base_position_rect -- Position and dimensions rectangle.
open_button_width -- Width of open button.
expand_direction -- Direction of expansion, 'up' or 'down'.
manager -- The UI Manager for the whole UI.
container -- The container the element is within.
object_ids -- The object IDs for the drop-down UI element.
element_ids -- The element IDs for the drop-down UI element.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

disable(): Disables the closed state so that it is no longer interactive.

enable(): Re-enables the closed state, so we can once again interact with it.

finish(): Called when we leave the closed state. Kills the open button and the selected option button.

hide(): Hide selected_option_button and open_button.

process_event(event: Event) → bool

Processes events for the closed state of the drop-down.

Parameters:: event -- The event to process.
Returns:: Return True if we want to consume this event, so it is not passed on to the rest of the UI.

rebuild(): Rebuild the closed state from theming parameters and dimensions.

show(): Show selected_option_button and open_button.

start(should_rebuild: bool = True): Called each time we enter the closed state. It creates the necessary elements, the selected option and the open button.

update_dimensions()

Update the dimensions of all the button elements in the closed drop-down state.

Used when the dimensions of the drop-down have been altered.

update_position()

Update the position of all the button elements in the closed drop-down state.

Used when the position of the drop-down has been altered directly, rather than when it has been moved as a consequence of its container being moved.

class pygame_gui.elements.ui_drop_down_menu.UIDropDownMenu(options_list: List[str] | List[Tuple[str, str]], starting_option: str | Tuple[str, str], relative_rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, expansion_height_limit: int | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1, *, expand_on_option_click: bool = True)

Bases: UIContainer

A drop-down menu lets us choose one text option from a list. That list of options can be expanded and hidden at the press of a button. While the element is called a drop-down, it can also be made to 'climb up' by changing the 'expand_direction' styling option to 'up' in the theme file.

The drop-down is implemented through two states, one representing the 'closed' menu state and one for when it has been 'expanded'.

Parameters:

options_list -- The list of options to choose from. They must be strings.
starting_option -- The starting option, selected when the menu is first created.
relative_rect -- The size and position of the element when not expanded.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
expansion_height_limit -- Limit on the height that this will expand to, defaults to the container bounds.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
expand_on_option_click -- If this is set to False the drop-down will only expand when the open/close button is pressed and not when the selected option is pressed.

add_options(new_options: List[str] | List[Tuple[str, str]]) → None

Add new options to the drop-down. Will close the drop-down if it is currently open.

In many cases it may be easier just to recreate the drop-down with whatever the new options list is.

Parameters:: new_options -- The list of new options to add.

disable(): Disables the button so that it is no longer interactive.

enable(): Re-enables the button so, we can once again interact with it.

hide(): In addition to the base UIElement.hide() - if the current state is 'expanded' call its hide() method, which begins a transition of the UIDropDownMenu to the 'closed' state, and call the hide() method of the 'closed' state which hides all it's children widgets.

kill(): Overrides the standard sprite kill to also properly kill/finish the current state of the drop-down. Depending on whether it is expanded or closed the drop-down menu will have different elements to clean up.

on_fresh_drawable_shape_ready(): Called by an element's drawable shape when it has a new image surface ready for use, normally after a rebuilding/redrawing of some kind.

process_event(event: Event) → bool

Handles various interactions with the drop-down menu by passing them along to the active state.

Parameters:: event -- The event to process.
Returns:: Return True if we want to consume this event, so it is not passed on to the rest of the UI.

rebuild(): A complete rebuild of the drawable parts of this element.

rebuild_from_changed_theme_data(): Triggers the element to rebuild if any of its theming data has changed, which involves a lot of checking and validating its theming data.

remove_options(options_to_remove: List[str] | List[Tuple[str, str]]) → None

Will remove all instances of the options provided.

Parameters:: options_to_remove -- The list of new options to remove.

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

Sets the dimensions of this drop down, updating all subordinate button elements at the same time.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this drop down, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this drop down, updating all subordinate button elements at the same time.

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

show(): In addition to the base UIElement.show() - call show() on the closed state - showing its buttons.

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

update(time_delta: float)

The update here deals with transitioning between the two states of the drop-down menu and then passes the rest of the work onto whichever state is active.

Parameters:: time_delta -- The time in second between calls to update.

class pygame_gui.elements.ui_drop_down_menu.UIExpandedDropDownState(drop_down_menu_ui: UIDropDownMenu, options_list: List[Tuple[str, str]], selected_option: Tuple[str, str], base_position_rect: Rect | None, close_button_width: int, expand_direction: str | None, manager: IUIManagerInterface, container: IContainerLikeInterface, object_ids: List[str | None] | None, element_ids: List[str] | None, expand_on_option_click)

Bases: object

The expanded state of the drop-down displays the currently chosen option, all the available options and a button to close the menu and return to the closed state.

Picking an option will also close the menu.

Parameters:

drop_down_menu_ui -- The UIDropDownElement this state belongs to.
options_list -- The list of options in this drop down.
selected_option -- The currently selected option.
base_position_rect -- Position and dimensions rectangle.
close_button_width -- Width of close button.
expand_direction -- Direction of expansion, 'up' or 'down'.
manager -- The UI Manager for the whole UI.
container -- The container the element is within.
object_ids -- The object IDs for the drop-down UI element.
element_ids -- The element IDs for the drop-down UI element.

finish(): cleans everything up upon exiting the expanded menu state.

hide(): Transition from expanded state to closed state.

process_event(event: Event) → bool

Processes events for the closed state of the drop-down.

Parameters:: event -- The event to process.
Returns:: Return True if we want to consume this event, so it is not passed on to the rest of the UI.

rebuild(): Rebuild the state from theming parameters and dimensions.

start(should_rebuild: bool = True): Called each time we enter the expanded state. It creates the necessary elements, the selected option, all the other available options and the close button.

update_dimensions()

Update the dimensions of all the button elements in the closed drop-down state.

Used when the dimensions of the drop-down have been altered.

update_position()

Update the position of all the button elements in the open drop-down state.

Used when the position of the drop-down has been altered directly, rather than when it has been moved as a consequence of its container being moved.

pygame_gui.elements.ui_horizontal_scroll_bar module

Bases: UIElement

A horizontal scroll bar allows users to position a smaller visible area within a horizontally larger area.

Parameters:

relative_rect -- The size and position of the scroll bar.
visible_percentage -- The horizontal percentage of the larger area that is visible, between 0.0 and 1.0.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

check_has_moved_recently() → bool

Returns True if the scroll bar was moved in the last call to the update function.

Returns:: True if we've recently moved the scroll bar, False otherwise.

disable(): Disables the scroll bar, so it is no longer interactive.

enable(): Enables the scroll bar, so it is interactive once again.

hide(): In addition to the base UIElement.hide() - hide the self.button_container which will propagate and hide all the buttons.

kill()

Overrides the kill() method of the UI element class to kill all the buttons in the scroll bar and clear any of the parts of the scroll bar that are currently recorded as the 'last focused horizontal scroll bar element' on the ui manager.

NOTE: the 'last focused' state on the UI manager is used so that the mouse wheel will move whichever scrollbar we last fiddled with even if we've been doing other stuff. This seems to be consistent with the most common mousewheel/scrollbar interactions used elsewhere.

process_event(event: Event) → bool

Checks an event from pygame's event queue to see if the scroll bar needs to react to it. In this case it is just mousewheel events, mainly because the buttons that make up the scroll bar will handle the required mouse click events.

Parameters:: event -- The event to process.
Returns:: Returns True if we've done something with the input event.

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.

redraw_scrollbar(): Redraws the 'scrollbar' portion of the whole UI element. Called when we change the visible percentage.

reset_scroll_position(): Reset the current scroll position back to the top.

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

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this scroll bar, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this scroll bar, updating all subordinate button elements at the same time.

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

set_scroll_from_start_percentage(new_start_percentage: float)

Set the scroll bar's scrolling position from a percentage between 0.0 and 1.0.

Parameters:: new_start_percentage -- the percentage to set.

set_visible_percentage(percentage: float)

Sets the percentage of the total 'scrollable area' that is currently visible. This will affect the size of the scrollbar and should be called if the horizontal size of the 'scrollable area' or the horizontal size of the visible area change.

Parameters:: percentage -- A float between 0.0 and 1.0 representing the percentage that is visible.

show(): In addition to the base UIElement.show() - show the self.button_container which will propagate and show all the buttons.

property start_percentage: turning start_percentage into a property, so we can round it to mitigate floating point errors

update(time_delta: float)

Called once per update loop of our UI manager. Deals largely with moving the scroll bar and updating the resulting 'start_percentage' variable that is then used by other 'scrollable' UI elements to control the point they start drawing.

Reacts to presses of the up and down arrow buttons, movement of the mouse wheel and dragging of the scroll bar itself.

Parameters:: time_delta -- A float, roughly representing the time in seconds between calls to this method.

pygame_gui.elements.ui_horizontal_slider module

Bases: UIElement

A horizontal slider is intended to help users adjust values within a range, for example a volume control.

Parameters:

relative_rect -- A rectangle describing the position and dimensions of the element.
start_value -- The value to start the slider at.
value_range -- The full range of values.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
click_increment -- the amount to increment by when clicking one of the arrow buttons.

disable(): Disable the slider. It should not be interactive and will use the disabled theme colours.

enable(): Enable the slider. It should become interactive and will use the normal theme colours.

get_current_value() → float | int

Gets the current value the slider is set to.

Returns:: The current value recorded by the slider.

hide(): In addition to the base UIElement.hide() - hide the sliding button and hide the button_container which will propagate and hide the left and right buttons.

kill(): Overrides the normal sprite kill() method to also kill the button elements that help make up the slider.

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.

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_current_value(value: float | int, warn: bool = True)

Sets the value of the slider, which will move the position of the slider to match. Will issue a warning if the value set is not in the value range.

Parameters:

value -- The value to set.
warn -- set to 'False' to suppress the default warning, instead the value will be clamped.

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

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this slider, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this slider, updating all subordinate button elements at the same time.

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

show(): In addition to the base UIElement.show() - show the sliding button and show the button_container which will propagate and show the left and right buttons.

update(time_delta: float)

Takes care of actually moving the slider based on interactions reported by the buttons or based on movement of the mouse if we are gripping the slider itself.

Parameters:: time_delta -- the time in seconds between calls to update.

pygame_gui.elements.ui_image module

class pygame_gui.elements.ui_image.UIImage(relative_rect: Rect | FRect | Tuple[float, float, float, float], image_surface: Surface, manager: IUIManagerInterface | None = None, image_is_alpha_premultiplied: bool = False, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1, *, starting_height: int = 1)

Bases: UIElement

Displays a pygame surface as a UI element, intended for an image, but it can serve other purposes.

Parameters:

relative_rect -- The rectangle that contains, positions and scales the image relative to its container.
image_surface -- A pygame surface to display.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

rebuild_from_changed_theme_data(): A stub to override when we want to rebuild from theme data.

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

Set the dimensions of this image, scaling the image surface to match.

Parameters:

dimensions -- The new dimensions of the image.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

set_image(new_image: Surface | None, image_is_alpha_premultiplied: bool = False) → None

Allows users to change the image displayed on a UIImage element during run time, without recreating the element.

GUI images are converted to the correct format for the GUI if the supplied image is not the dimensions of the UIImage element it will be scaled to fit. In this situation, an original size image is retained as well in case of future resizing events.

Parameters:

new_image -- the new image surface to use in the UIImage element.
image_is_alpha_premultiplied -- set to True if the image is already in alpha multiplied colour format.

pygame_gui.elements.ui_label module

Bases: UIElement, IUITextOwnerInterface

A label lets us display a single line of text with a single font style. It's a quick to rebuild and simple alternative to the text box element.

Parameters:

relative_rect -- Normally a rectangle describing the position (relative to its container) and dimensions. Also accepts a position Coordinate where the dimensions will be dynamic depending on the text contents. Dynamic dimensions can be requested by setting the required dimension to -1.
text -- The text to display in the label.
manager -- The UIManager that manages this label. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
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.

clear_all_active_effects(sub_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.

clear_text_surface(sub_chunk: TextLineChunkFTFont | None = None)

Clear the text surface

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

disable(): Disables the label so that its text changes to the disabled colour.

enable(): Re-enables the label so that its text changes to the normal colour

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

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

rebuild(): Re-render the text to the label's underlying sprite image. This allows us to change what the displayed text is or remake it with different theming (if the theming has changed).

rebuild_from_changed_theme_data(): Checks if any theming parameters have changed, and if so triggers a full rebuild of the element.

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.

set_text(text: str, *, text_kwargs: Dict[str, str] | None = None)

Changes the string displayed by the label element. Labels do not support HTML styling.

Parameters:

text -- the text to set the label to.
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.

set_text_alpha(alpha: int, sub_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.

set_text_offset_pos(offset: Tuple[int, int], sub_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:

set_text_rotation(rotation: int, sub_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:

set_text_scale(scale: int, sub_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:

stop_finished_effect(sub_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.

update(time_delta: float)

Called once every update loop of the UI Manager.

Parameters:: time_delta -- The time in seconds between calls to update. Useful for timing things.

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

pygame_gui.elements.ui_panel module

Bases: UIElement, IContainerLikeInterface

A rectangular panel that holds a UI container and is designed to overlap other elements. It acts a little like a window that is not shuffled about in a stack - instead remaining at the same layer distance from the container it was initially placed in.

It's primary purpose is for things like involved HUDs in games that want to always sit on top of UI elements that may be present 'inside' the game world (e.g. player health bars). By creating a UI Panel at a height above the highest layer used by the game world's UI elements we can ensure that all elements added to the panel are always above the fray.

Parameters:

relative_rect -- The positioning and sizing rectangle for the panel. See the layout guide for details.
starting_height -- How many layers above its container to place this panel on.
manager -- The GUI manager that handles drawing and updating the UI and interactions between elements. If not provided or set to None, it will try to use the first UIManager that was created by your application.
margins -- Controls the distance between the edge of the panel and where it's container should begin.
container -- The container this panel is inside - distinct from this panel's own container.
parent_element -- A hierarchical 'parent' used for signifying belonging and used in theming and events.
object_id -- An identifier that can be used to help distinguish this particular panel from others.
anchors -- Used to layout elements and dictate what the relative_rect is relative to. Defaults to the top left.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

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.

disable(): Disables all elements in the panel, so they are no longer interactive.

enable(): Enables all elements in the panel, so they are interactive again.

get_container() → IUIContainerInterface

Returns the container that should contain all the UI elements in this panel.

Return UIContainer:: The panel's container.

hide(): In addition to the base UIElement.hide() - call hide() of owned container - panel_container.

kill(): Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this panel.

process_event(event: Event) → bool

Can be overridden, also handle resizing windows. Gives UI Windows access to pygame events. Currently just blocks mouse click down events from passing through the panel.

Parameters:: event -- The event to process.
Returns:: Should return True if this element consumes this event.

rebuild(): A complete rebuild of the drawable shape used by this button.

rebuild_from_changed_theme_data(): Checks if any theming parameters have changed, and if so triggers a full rebuild of the button's drawable shape.

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

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

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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.

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.

show(): In addition to the base UIElement.show() - call show() of owned container - panel_container.

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 panel'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.

pygame_gui.elements.ui_progress_bar module

Bases: UIStatusBar

A UI that will display a progress bar from 0 to 100%

Parameters:

relative_rect -- The rectangle that defines the size and position of the progress bar.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

status_text(): Subclass and override this method to change what text is displayed, or to suppress the text.

pygame_gui.elements.ui_screen_space_health_bar module

Bases: UIStatusBar

A UI that will display health capacity and current health for a sprite in 'screen space'. That means it won't move with the camera. This is a good choice for a user/player sprite.

Parameters:

relative_rect -- The rectangle that defines the size and position of the health bar.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
sprite_to_monitor -- The sprite we are displaying the health of.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

status_text(): Subclass and override this method to change what text is displayed, or to suppress the text.

pygame_gui.elements.ui_scrolling_container module

class pygame_gui.elements.ui_scrolling_container.UIScrollingContainer(relative_rect: Rect, manager: IUIManagerInterface | None = None, *, starting_height: int = 1, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, element_id: List[str] | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1, should_grow_automatically: bool = True, allow_scroll_x: bool = True, allow_scroll_y: bool = True)

Bases: UIElement, IContainerLikeInterface

A container like UI element that lets users scroll around a larger container of content with scroll bars.

Parameters:

relative_rect -- The size and relative position of the container. This will also be the starting size of the scrolling area.
manager -- The UI manager for this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
starting_height -- The starting layer height of this container above its container. Defaults to 1.
container -- The container this container is within. Defaults to None (which is the root container for the UI)
parent_element -- A parent element for this container. Defaults to None, or the container if you've set that.
object_id -- An object ID for this element.
anchors -- Layout anchors in a dictionary.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
allow_scroll_x -- Whether a scrollbar should be added to scroll horizontally (when needed). Defaults to True.
allow_scroll_y -- Whether a scrollbar should be added to scroll vertically (when needed). Defaults to True.

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.

disable(): Disables all elements in the container, so they are no longer interactive.

enable(): Enables all elements in the container, so they are interactive again.

get_container() → IUIContainerInterface

Gets the scrollable container area (the one that moves around with the scrollbars) from this container-like UI element.

Returns:: the scrolling container.

hide(): In addition to the base UIElement.hide() - call hide() of owned container - _root_container. All other sub-elements (view_container, scrollbars) are children of _root_container, so it's visibility will propagate to them - there is no need to call their hide() methods separately.

kill(): Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this panel.

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.

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.

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.

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

Set the size of the scrollable area container. It starts the same size as the view container, but often you want to expand it, or why have a scrollable container?

Parameters:: dimensions -- The new dimensions.

show(): In addition to the base UIElement.show() - call show() of owned container - _root_container. All other sub-elements (view_container, scrollbars) are children of _root_container, so it's visibility will propagate to them - there is no need to call their show() methods separately.

update(time_delta: float)

Updates the scrolling container's position based upon the scroll bars and updates the scrollbar's visible percentage as well if that has changed.

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

pygame_gui.elements.ui_selection_list module

Bases: UIElement

A rectangular element that holds any number of selectable text items displayed as a list.

Parameters:

relative_rect -- The positioning and sizing rectangle for the panel. See the layout guide for details.
item_list -- A list of items as strings (item name only), or tuples of two strings (name, theme_object_id).
default_selection -- Default item(s) that should be selected: a string or a (str, str) tuple for single-selection lists or a list of strings or list of (str, str) tuples for multi-selection lists.
manager -- The GUI manager that handles drawing and updating the UI and interactions between elements. If not provided or set to None, it will try to use the first UIManager that was created by your application.
allow_multi_select -- True if we are allowed to pick multiple things from the selection list.
allow_double_clicks -- True if we can double-click on items in the selection list.
container -- The container this element is inside (by default the root container) distinct from this panel's container.
starting_height -- The starting height up from its container where this list is placed into a layer.
parent_element -- A hierarchical 'parent' used for signifying belonging and used in theming and events.
object_id -- An identifier that can be used to help distinguish this particular element from others with the same hierarchy.
anchors -- Used to layout elements and dictate what the relative_rect is relative to. Defaults to the top left.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

add_items(new_items: List[str] | List[Tuple[str, str]]) → None

Add any number of new items to the selection list. Uses the same format as when the list is first created.

Parameters:: new_items -- the list of new items to add

disable(): Disables all elements in the selection list, so they are no longer interactive.

enable(): Enables all elements in the selection list, so they are interactive again.

get_multi_selection(include_object_id: bool = False) → List[str] | List[Tuple[str, str]]

Get all the selected items in our selection list. Only works if this is a multi-selection list.

Parameters:: include_object_id -- if True adds the object id of this list item to the returned list of Tuples. If False we just get a list of the visible text strings only.
Returns:: A list of the selected items in our selection list. May be empty if nothing selected.

get_single_selection(include_object_id: bool = False) → Tuple[str, str] | str | None

Get the selected item in a list, if any. Only works if this is a single-selection list.

Parameters:: include_object_id -- if True adds the object id of this list item to the returned list of Tuples. If False we just get a list of the visible text strings only.
Returns:: A single item name as a string or None.

get_single_selection_start_percentage(): The percentage through the height of the list where the top of the first selected option is.

hide(): In addition to the base UIElement.hide() - call hide() of owned container - list_and_scroll_bar_container. All other sub-elements (item_list_container, scrollbar) are children of list_and_scroll_bar_container, so it's visibility will propagate to them - there is no need to call their hide() methods separately.

kill(): Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this panel.

process_event(event: Event) → bool

Can be overridden, also handle resizing windows. Gives UI Windows access to pygame events. Currently just blocks mouse click down events from passing through the panel.

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

rebuild(): A complete rebuild of the drawable shape used by this element.

rebuild_from_changed_theme_data(): Checks if any theming parameters have changed, and if so triggers a full rebuild of the button's drawable shape

remove_items(items_to_remove: List[str] | List[Tuple[str, str]]) → None

Will remove all instances of the items provided. The full tuple is required for items with a display name and an object ID.

Parameters:: items_to_remove -- The list of new options to remove.

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

Set the size of this panel and then resizes and shifts the contents of the panel container to fit the new size.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- clamp these dimensions to the size of the element's container.

set_item_list(new_item_list: List[str] | List[Tuple[str, str]])

Set a new string list (or tuple of strings & ids list) as the item list for this selection list. This will change what is displayed in the list.

Tuples should be arranged like so:

(list_text, object_ID)

list_text: displayed in the UI

object_ID: used for theming and events

Parameters:: new_item_list -- The new list to switch to. Can be a list of strings or tuples.

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

Sets the absolute screen position of this slider, updating all subordinate button elements at the same time.

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

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.

show(): In addition to the base UIElement.show() - call show() of owned container - list_and_scroll_bar_container. All other sub-elements (item_list_container, scrollbar) are children of list_and_scroll_bar_container, so it's visibility will propagate to them - there is no need to call their show() methods separately.

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 panel'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.

pygame_gui.elements.ui_status_bar module

Bases: UIElement

Displays a status/progress bar.

This is a flexible class that can be used to display status for a sprite (health/mana/fatigue, etc.), or to provide a status bar on the screen not attached to any particular object. You can use multiple status bars for a sprite to show different status items if desired.

You can use the percent_full attribute to manually set the status, or you can provide a pointer to a method that will provide the percentage information.

This is a kitchen sink class with several ways to use it; you may want to look at the subclasses built on top of it that are designed to be simpler to use, such as UIProgressBar, UIWorldSpaceHealthBar, and UIScreenSpaceHealthBar.

Parameters:

relative_rect -- The rectangle that defines the size of the health bar.
sprite -- Optional sprite to monitor for status info, and for drawing the bar with the sprite.
follow_sprite -- If there's a sprite, this indicates whether the bar should be drawn at the sprite's location.
percent_method -- Optional method signature to call to get the percent complete. (To provide a method signature, simply reference the method without parenthesis, such as self.health_percent.)
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

property percent_full: Use this property to directly change the status bar.

rebuild(): Rebuild the status bar entirely because the theming data 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.

redraw(): Redraw the status bar when something, other than it's position has changed.

status_text(): To display text in the bar, subclass UIStatusBar and override this method.

update(time_delta: float)

Updates the status bar sprite's image and rectangle with the latest status and position data from the sprite we are monitoring

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

pygame_gui.elements.ui_text_box module

class pygame_gui.elements.ui_text_box.UITextBox(html_text: str, relative_rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, wrap_to_height: bool = False, starting_height: int = 1, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1, *, pre_parsing_enabled: bool = True, text_kwargs: Dict[str, str] | None = None, allow_split_dashes: bool = True, plain_text_display_only: bool = False, should_html_unescape_input_text: bool = False, placeholder_text: str | None = None)

Bases: UIElement, IUITextOwnerInterface

A Text Box element lets us display word-wrapped, formatted text. If the text to display is longer than the height of the box given then the element will automatically create a vertical scroll bar so that all the text can be seen.

Formatting the text is done via a subset of HTML tags. Currently supported tags are:

or - to encase bold styled text.
, or <var></var> - to encase italic styled text.
- to encase underlined text.
<a href='id'></a> - to encase 'link' text that can be clicked on to generate events with the
id given in href.
<body bgcolor='#FFFFFF'></body> - to change the background colour of encased text.
or - to start a new line.
- To set the font, colour and size of
encased text.
<hr> a horizontal rule.
<effect id='custom_id'></effect> - to encase text to that will have an effect applied. The custom id
supplied is used when setting an effect on this text box.
<shadow size=1 offset=1,1 color=#808080></shadow> - puts a shadow behind the text encased. Can also be used to
make a glow effect.
<img src="data/images/test_images/london.jpg" float=right> Inserts an image into the text with options on how to
float the text around the image. Float options are left, right or none.

More may be added in the future if needed or frequently requested.

NOTE: if dimensions of the initial containing rect are set to -1 the text box will match the final dimension to whatever the text rendering produces. This lets us make dynamically sized text boxes depending on their contents.

Parameters:

html_text -- The HTML formatted text to display in this text box.
relative_rect -- The 'visible area' rectangle, positioned relative to its container.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
wrap_to_height -- False by default, if set to True the box will increase in height to match the text within.
starting_height -- Sets the height, above its container, to start placing the text box at.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
pre_parsing_enabled -- When enabled will replace all newline characters with html tags.
text_kwargs -- A dictionary of variable arguments to pass to the translated text useful when you have multiple translations that need variables inserted in the middle.
allow_split_dashes -- Sets whether long words that don't fit on a single line will be split with a dash or just split without a dash (more compact).
plain_text_display_only -- No markup based styling & formatting will be done on the input text.
should_html_unescape_input_text -- When enabled turns plain text encoded html back into html for this text box. e.g. < will become '<'
placeholder_text -- If the text line is empty, and not focused, this placeholder text will be shown instead.

append_html_text(new_html_str: str)

Adds a string, that is parsed for any HTML tags that pygame_gui supports, onto the bottom of the text box's current contents.

This is useful for making things like logs.

Parameters:: new_html_str -- The, potentially HTML tag, containing string of text to append.

clear_all_active_effects(sub_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.

clear_text_surface(sub_chunk: TextLineChunkFTFont | None = None)

Clear the text surface

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

disable(): Disable the text box. Basically just disables the scroll bar if one exists.

enable(): Enable the text box. Re-enables the scroll bar if one exists.

focus(): Called when we 'select focus' on this element.

full_redraw()

Trigger a full redraw of the entire text box. Useful if we have messed with the text chunks in a more fundamental fashion and need to reposition them (say, if some of them have gotten wider after being made bold).

NOTE: This doesn't reparse the text of our box. If you need to do that, just create a new text box.

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

hide(): In addition to the base UIElement.hide() - call hide() of scroll_bar if it exists.

kill(): Overrides the standard sprite kill method to also kill any scroll bars belonging to this text box.

on_fresh_drawable_shape_ready(): Called by an element's drawable shape when it has a new image surface ready for use, normally after a rebuilding/redrawing of some kind.

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

parse_html_into_style_data(): Parses HTML styled string text into a format more useful for styling rendered text.

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.

rebuild(): Rebuild whatever needs building.

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.

redraw_from_chunks()

Redraws from slightly earlier in the process than 'redraw_from_text_block'. Useful if we have redrawn individual chunks already (say, to change their style slightly after being hovered) and now want to update the text block with those changes without doing a full redraw.

This won't work very well if redrawing a chunk changed its dimensions.

redraw_from_text_block(): Redraws the final parts of the text box element that don't include redrawing the actual text. Useful if we've just moved the position of the text (say, with a scroll bar) without actually changing the text itself.

property select_range

The selected range for this text. A tuple containing the start and end indexes of the current selection.

Made into a property to keep it synchronised with the underlying drawable shape's representation.

set_active_effect(effect_type: UITextEffectType | None = 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.

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

Method to directly set the dimensions of a text box.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

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

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

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

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

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

set_text_alpha(alpha: int, sub_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.

set_text_offset_pos(offset: Tuple[int, int], sub_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:

set_text_rotation(rotation: int, sub_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:

set_text_scale(scale: float, sub_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:

show(): In addition to the base UIElement.show() - call show() of scroll_bar if it exists.

stop_finished_effect(sub_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.

unfocus(): Called when this element is no longer the current focus.

update(time_delta: float)

Called once every update loop of the UI Manager. Used to react to scroll bar movement (if there is one), update the text effect (if there is one) and check if we are hovering over any text links (if there are any).

Parameters:: time_delta -- The time in seconds between calls to update. Useful for timing things.

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

pygame_gui.elements.ui_text_entry_box module

Bases: UITextBox

Inherits from UITextBox but allows you to enter text with the keyboard, much like UITextEntryLine.

Parameters:

relative_rect -- The 'visible area' rectangle, positioned relative to its container.
initial_text -- The text that starts in the text box.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

Param:

placeholder_text: If the text line is empty, and not focused, this placeholder text will be shown instead.

focus(): Called when we 'select focus' on this element. In this case it sets up the keyboard to repeat held key presses, useful for natural feeling keyboard input.

get_text() → str

Gets the text in the entry box element.

Returns:: A string.

process_event(event: Event) → bool

Allows the text entry box to react to input events, which is its primary function. The entry element reacts to various types of mouse clicks (double click selecting words, drag select), keyboard combos (CTRL+C, CTRL+V, CTRL+X, CTRL+A), individual editing keys (Backspace, Delete, Left & Right arrows) and other keys for inputting letters, symbols and numbers.

Parameters:: event -- The current event to consider reacting to.
Returns:: Returns True if we've done something with the input event.

redraw_from_text_block(): Redraws the final parts of the text box element that don't include redrawing the actual text. Useful if we've just moved the position of the text (say, with a scroll bar) without actually changing the text itself.

unfocus(): Called when this element is no longer the current focus.

update(time_delta: float)

Called every update loop of our UI Manager. Largely handles text drag selection and making sure our edit cursor blinks on and off.

Parameters:: time_delta -- The time in seconds between this update method call and the previous one.

pygame_gui.elements.ui_text_entry_line module

Bases: UIElement

A GUI element for text entry from a keyboard, on a single line. The element supports the standard copy and paste keyboard shortcuts CTRL+V, CTRL+C & CTRL+X as well as CTRL+A.

There are methods that allow the entry element to restrict the characters that can be input into the text box

The height of the text entry line element will be determined by the font used rather than the standard method for UIElements of just using the height of the input rectangle.

Parameters:

relative_rect -- A rectangle describing the position and width of the text entry element.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

Param:

initial_text: A string that will start in this box. This text will remain when box is focused for editing.

Param:

placeholder_text: If the text line is empty, and not focused, this placeholder text will be shown instead.

disable(): Disables the element so that it is no longer interactive.

enable(): Re-enables the element, so we can once again interact with it.

focus(): Called when we 'select focus' on this element. In this case it sets up the keyboard to repeat held key presses, useful for natural feeling keyboard input.

get_text() → str

Gets the text in the entry line element.

Returns:: A string.

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

process_event(event: Event) → bool

Allows the text entry box to react to input events, which is its primary function. The entry element reacts to various types of mouse clicks (double click selecting words, drag select), keyboard combos (CTRL+C, CTRL+V, CTRL+X, CTRL+A), individual editing keys (Backspace, Delete, Left & Right arrows) and other keys for inputting letters, symbols and numbers.

Parameters:: event -- The current event to consider reacting to.
Returns:: Returns True if we've done something with the input event.

rebuild(): Rebuild whatever needs building.

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.

redraw(): Redraws the entire text entry element onto the underlying sprite image. Usually called when the displayed text has been edited or changed in some fashion.

property select_range

The selected range for this text. A tuple containing the start and end indexes of the current selection.

Made into a property to keep it synchronised with the underlying drawable shape's representation.

set_allowed_characters(allowed_characters: str | List[str])

Sets a whitelist of characters that will be the only ones allowed in our text entry element. We can either set the list directly, or request one of the already existing lists by a string identifier. The currently supported lists for allowed characters are:

'numbers'
'letters'
'alpha_numeric'

Parameters:: allowed_characters -- The characters to allow, either in a list form or one of the supported string ids.

set_forbidden_characters(forbidden_characters: str | List[str])

Sets a blacklist of characters that will be banned from our text entry element. We can either set the list directly, or request one of the already existing lists by a string identifier. The currently supported lists for forbidden characters are:

'numbers'
'forbidden_file_path'

Parameters:: forbidden_characters -- The characters to forbid, either in a list form or one of the supported string ids.

set_text(text: str)

Allows the text displayed in the text entry element to be set via code. Useful for setting an initial or existing value that can be edited.

The string to set must be valid for the text entry element for this to work.

Parameters:: text -- The text string to set.

set_text_hidden(is_hidden=True)

Passing in True will hide text typed into the text line, replacing it with ● characters and also disallow copying the text into the clipboard. It is designed for basic 'password box' usage.

Parameters:: is_hidden -- Can be set to True or False. Defaults to True because if you are calling this you likely want a password box with no fuss. Set it back to False if you want to un-hide the text (e.g. for one of those 'Show my password' buttons).

set_text_length_limit(limit: int)

Allows a character limit to be set on the text entry element. By default, there is no limit on the number of characters that can be entered.

Parameters:: limit -- The character limit as an integer.

unfocus(): Called when this element is no longer the current focus.

update(time_delta: float)

Called every update loop of our UI Manager. Largely handles text drag selection and making sure our edit cursor blinks on and off.

Parameters:: time_delta -- The time in seconds between this update method call and the previous one.

validate_text_string(text_to_validate: str) → bool

Checks a string of text to see if any of its characters don't meet the requirements of the allowed and forbidden character sets.

Parameters:: text_to_validate -- The text string to check.

pygame_gui.elements.ui_tool_tip module

Bases: UIElement, IUITooltipInterface

A tool tip is a floating block of text that gives additional information after a user hovers over an interactive part of a GUI for a short time. In Pygame GUI the tooltip's text is style-able with HTML.

At the moment the tooltips are only available as an option on UIButton elements.

Tooltips also don't allow a container as they are designed to overlap normal UI boundaries and be contained only within the 'root' window/container, which is synonymous with the pygame display surface.

Parameters:

html_text -- Text styled with HTML, to be displayed on the tooltip.
hover_distance -- Distance in pixels between the tooltip and the thing being hovered.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
text_kwargs -- a dictionary of variable arguments to pass to the translated text useful when you have multiple translations that need variables inserted in the middle.

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.

hide(): This is a base method hide() of a UIElement, but since it's not intended to be used on a UIToolTip - display a warning.

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: Vector2 | Tuple[float, float], clamp_to_container: bool = False)

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

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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.

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.

show(): This is a base method show() of a UIElement, but since it's not intended to be used on a UIToolTip - display a warning.

pygame_gui.elements.ui_vertical_scroll_bar module

Bases: UIElement

A vertical scroll bar allows users to position a smaller visible area within a vertically larger area.

Parameters:

relative_rect -- The size and position of the scroll bar.
visible_percentage -- The vertical percentage of the larger area that is visible, between 0.0 and 1.0.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

check_has_moved_recently() → bool

Returns True if the scroll bar was moved in the last call to the update function.

Returns:: True if we've recently moved the scroll bar, False otherwise.

disable(): Disables the scroll bar so it is no longer interactive.

enable(): Enables the scroll bar so it is interactive once again.

hide(): In addition to the base UIElement.hide() - hide the self.button_container which will propagate and hide all the buttons.

kill()

Overrides the kill() method of the UI element class to kill all the buttons in the scroll bar and clear any of the parts of the scroll bar that are currently recorded as the 'last focused vertical scroll bar element' on the ui manager.

NOTE: the 'last focused' state on the UI manager is used so that the mouse wheel will move whichever scrollbar we last fiddled with even if we've been doing other stuff. This seems to be consistent with the most common mousewheel/scrollbar interactions used elsewhere.

process_event(event: Event) → bool

Checks an event from pygame's event queue to see if the scroll bar needs to react to it. In this case it is just mousewheel events, mainly because the buttons that make up the scroll bar will handle the required mouse click events.

Parameters:: event -- The event to process.
Returns:: Returns True if we've done something with the input event.

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.

redraw_scrollbar(): Redraws the 'scrollbar' portion of the whole UI element. Called when we change the visible percentage.

reset_scroll_position(): Reset the current scroll position back to the top.

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

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this scroll bar, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this scroll bar, updating all subordinate button elements at the same time.

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

set_scroll_from_start_percentage(new_start_percentage: float)

Set the scroll bar's scrolling position from a percentage between 0.0 and 1.0.

Parameters:: new_start_percentage -- the percentage to set.

set_visible_percentage(percentage: float)

Sets the percentage of the total 'scrollable area' that is currently visible. This will affect the size of the scrollbar and should be called if the vertical size of the 'scrollable area' or the vertical size of the visible area change.

Parameters:: percentage -- A float between 0.0 and 1.0 representing the percentage that is visible.

show(): In addition to the base UIElement.show() - show the self.button_container which will propagate and show all the buttons.

property start_percentage: turning start_percentage into a property, so we can round it to mitigate floating point errors

update(time_delta: float)

Called once per update loop of our UI manager. Deals largely with moving the scroll bar and updating the resulting 'start_percentage' variable that is then used by other 'scrollable' UI elements to control the point they start drawing.

Reacts to presses of the up and down arrow buttons, movement of the mouse wheel and dragging of the scroll bar itself.

Parameters:: time_delta -- A float, roughly representing the time in seconds between calls to this method.

pygame_gui.elements.ui_window module

class pygame_gui.elements.ui_window.UIWindow(rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, window_display_title: str = '', element_id: List[str] | str | None = None, object_id: ObjectID | str | None = None, resizable: bool = False, visible: int = 1, draggable: bool = True, *, ignore_shadow_for_initial_size_and_pos: bool = True, always_on_top: bool = False)

Bases: UIElement, IContainerLikeInterface, IWindowInterface

A base class for window GUI elements, any windows should inherit from this class.

Parameters:

rect -- A rectangle, representing size and position of the window (including title bar, shadow and borders).
manager -- The UIManager that manages this UIWindow. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_display_title -- A string that will appear in the windows title bar if it has one.
element_id -- An element ID for this window, if one is not supplied it defaults to 'window'.
object_id -- An optional object ID for this window, useful for distinguishing different windows.
resizable -- Whether this window is resizable or not, defaults to False.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
draggable -- Whether this window is draggable or not, defaults to True.

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

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.

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

change_layer(new_layer: int)

Move this window, and it's contents, to a new layer in the UI.

Parameters:: new_layer -- The layer to move to.

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.

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?

disable(): Disables the window and it's contents so it is no longer interactive.

enable(): Enables the window and it's contents so it is interactive again.

get_container() → IUIContainerInterface

Returns the container that should contain all the UI elements in this window.

Return UIContainer:: The window's container.

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

get_relative_mouse_pos()

Returns the current mouse position relative to the inside of this window.

If the cursor is outside the window contents area it returns None

Returns:: tuple of relative mouse co-ords or None

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

hide(): In addition to the base UIElement.hide() - hide the _window_root_container which will propagate and hide all the children.

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_close_window_button_pressed(): Override this method to call 'hide()' instead if you want to hide a window when the close button is pressed.

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

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.

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: Vector2 | Tuple[float, float], clamp_to_container: bool = False)

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

set_display_title(new_title: str)

Set the title of the window.

Parameters:: new_title -- The title to set.

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.

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.

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.

show(): In addition to the base UIElement.show() - show the _window_root_container which will propagate and show all the children.

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.

pygame_gui.elements.ui_world_space_health_bar module

Bases: UIStatusBar

A UI that will display a sprite's 'health_capacity' and their 'current_health' in 'world space' above the sprite. This means that the health bar will move with the camera and the sprite itself.

A sprite passed to this class must have the attributes 'health_capacity' and 'current_health'.

Parameters:

relative_rect -- The rectangle that defines the size of the health bar.
sprite_to_monitor -- The sprite we are displaying the health of.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

class ExampleHealthSprite(*groups)

Bases: Sprite

An example sprite with health instance attributes.

Parameters:: groups -- Sprite groups to put the sprite in.

Module contents

Bases: UIElement

A 2d slider is intended to help users adjust values within a range, for example a volume control.

Parameters:

relative_rect -- A rectangle describing the position and dimensions of the element.
start_value_x -- The x value to start the slider at.
value_range_x -- The full range of x values.
start_value_y -- The y value to start the slider at.
value_range_y -- The full range of y values.
invert_y -- Should the y increase from bottom to top instead of the other way round?
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element "belongs to" in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

disable(): Disable the slider. It should not be interactive and will use the disabled theme colours.

enable(): Enable the slider. It should become interactive and will use the normal theme colours.

get_current_value() → Tuple[float, int]

Gets the current value the slider is set to.

Returns:: The current value recorded by the slider.

hide(): In addition to the base UIElement.hide() - hide the sliding button and hide the button_container which will propagate and hide the left and right buttons.

kill(): Overrides the normal sprite kill() method to also kill the button elements that help make up the slider.

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

rebuild_from_changed_theme_data() → None

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

Returns:: None

set_current_value(value_x: float | int, value_y: float | int, warn: bool = True) → None

Sets the value of the slider, which will move the position of the slider to match. Will issue a warning if the value set is not in the value range.

Parameters:

value_x -- The x value to set.
value_y -- The y value to set.
warn -- set to false in order to suppress the default warning, instead the value will be clamped.

Param:

invert_y: Should the y value be inverted? If not passed then will use self.invert_value for this info.

Returns:

None

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

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this slider, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this slider, updating all subordinate button elements at the same time.

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

show(): In addition to the base UIElement.show() - show the sliding button and show the button_container which will propagate and show the left and right buttons.

update(time_delta: float)

Takes care of actually moving the slider based on interactions reported by the buttons or based on movement of the mouse if we are gripping the slider itself.

Parameters:: time_delta -- the time in seconds between calls to update.

class pygame_gui.elements.UIAutoResizingContainer(relative_rect: Rect | FRect | Tuple[float, float, float, float], min_edges_rect: Rect | None = None, max_edges_rect: Rect | None = None, resize_left: bool = True, resize_right: bool = True, resize_top: bool = True, resize_bottom: bool = True, manager: IUIManagerInterface | None = None, *, starting_height: int = 1, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1)

Bases: UIContainer

A container like UI element that updates its size as elements within it change size, or new elements are added

Parameters:

relative_rect -- The starting size and relative position of the container.
min_edges_rect -- The Rect which defines the maximum values for the left and top, and the minimum values for the right and bottom edges of the container. Defaults to the None (current rect)
max_edges_rect -- The Rect which defines the minimum values for the left and top, and the maximum values for the right and bottom edges of the container. Defaults to the None (unbounded)
resize_left -- Should the left side be resized?
resize_right -- Should the right side be resized?
resize_top -- Should the top side be resized?
resize_bottom -- Should the bottom side be resized?
manager -- The UI manager for this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
starting_height -- The starting layer height of this container above its container. Defaults to 1.
container -- The container this container is within. Defaults to None (which is the root container for the UI)
parent_element -- A parent element for this container. Defaults to None, or the container if you've set that.
object_id -- An object ID for this element.
anchors -- Layout anchors in a dictionary.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

add_element(element: IUIElementInterface) → None

Add a UIElement to the container. The UIElement's relative_rect parameter will be relative to this container. Overridden to also update dimensions.

Parameters:: element -- A UIElement to add to this container.
Returns:: None

on_contained_elements_changed(target: UIElement) → None

Update the positioning of the contained elements of this container. To be called when one of the contained elements may have moved, been resized or changed its anchors.

Parameters:: target -- the UI element that has been benn moved resized or changed its anchors.
Returns:: None

recalculate_abs_edges_rect() → None

Used to recalculate the absolute rects from the min and max edges rect which control the minimum and maximum sizes of the container. Usually called when the container of this container has moved, or the minimum or maximum rects have changed.

Returns:: None

remove_element(element: IUIElementInterface) → None

Remove a UIElement from this container.

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

update(time_delta: float) → None

Updates the container's size based upon the elements inside.

Call this function if you have added or removed an element from this container and want to update the size in the same frame, otherwise it will update in the next frame.

Parameters:: time_delta -- The time passed between frames, measured in seconds.
Returns:: None

update_containing_rect_position() → None

Overridden to also recalculate the absolute rects which control the minimum and maximum sizes of the container

Returns:: None

update_max_edges_rect(new_rect: Rect) → None

Updates the container's minimum values for the left and top, and the maximum value for the right and bottom edges based upon the edges of the new rect.

Call the update function if you want to update the elements contained in the same frame, otherwise the elements contained within will update in the next frame.

Parameters:: new_rect -- Rect to update the max_edges_rect with
Returns:: None

update_min_edges_rect(new_rect: Rect) → None

Updates the container's maximum values for the left and top, and the minimum value for the right and bottom edges based upon the edges of the new rect.

Call the update function if you want to update the elements contained in the same frame, otherwise the elements contained within will update in the next frame.

Parameters:: new_rect -- Rect to update the min_edges_rect with
Returns:: None

class pygame_gui.elements.UIButton(relative_rect: Rect | FRect | Tuple[float, float, float, float] | Vector2 | Tuple[float, float], text: str, manager: IUIManagerInterface | None = None, container: IContainerLikeInterface | None = None, tool_tip_text: str | None = None, starting_height: int = 1, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, allow_double_clicks: bool = False, generate_click_events_from: Iterable[int] = frozenset({1}), visible: int = 1, *, command: Callable | Dict[int, Callable] | None = None, tool_tip_object_id: ObjectID | None = None, text_kwargs: Dict[str, str] | None = None, tool_tip_text_kwargs: Dict[str, str] | None = None, max_dynamic_width: int | None = None)

Bases: UIElement

A push button, a lot of the appearance of the button, including images to be displayed, is set up via the theme file. This button is designed to be pressed, do something, and then reset - rather than to be toggled on or off.

The button element is reused throughout the UI as part of other elements as it happens to be a very flexible interactive element.

Parameters:

relative_rect -- Normally a rectangle describing the position (relative to its container) and dimensions. Also accepts a position Coordinate where the dimensions will be dynamic depending on the text contents. Dynamic dimensions can be requested by setting the required dimension to -1.
text -- Text for the button.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
tool_tip_text -- Optional tool tip text, can be formatted with HTML. If supplied will appear on hover.
starting_height -- The height in layers above its container that this element will be placed.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
allow_double_clicks -- Enables double-clicking on buttons which will generate a unique event.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
command -- Functions to be called when an event is triggered by this element.
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.

bind(event: int, function: Callable | None = None)

Bind a function to an element event.

Parameters:

event -- The event to bind.
function -- The function to bind. None to unbind.

can_hover() → bool

Tests whether we can trigger the hover state for this button, other states take priority over it.

Returns:: True if we are able to hover this button.

check_pressed() → bool

A direct way to check if this button has been pressed in the last update cycle.

Returns:: True if the button has been pressed.

disable(): Disables the button so that it is no longer interactive.

enable(): Re-enables the button, so we can once again interact with it.

hide(): In addition to the base UIElement.hide() - Change the hovered state to a normal state.

hover_point(hover_x: int, hover_y: int) → bool

Tests if a position should be considered 'hovering' the button. Normally this just means our mouse pointer is inside the buttons rectangle, however if we are holding onto the button for a purpose(e.g. dragging a window around by its menu bar) the hover radius can be made to grow, so we don't keep losing touch with whatever we are moving.

Parameters:

hover_x -- horizontal pixel coordinate to test.
hover_y -- vertical pixel coordinate to test

Returns:

Returns True if we are hovering.

in_hold_range(position: Vector2 | Tuple[int, int] | Tuple[float, float]) → bool

Imagines a potentially larger rectangle around our button in which range we still grip hold of our button when moving the mouse. Makes it easier to use scrollbars.

Parameters:: position -- The position we are testing.
Return bool:: Returns True if our position is inside the hold range.

kill(): Overrides the standard sprite kill method to also kill any tooltips belonging to this button.

on_hovered(): Called when we enter the hover state, it sets the colours and image of the button to the appropriate values and redraws it.

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

on_self_event(event: int, data: Dict[str, Any] | None = None)

Called when an event is triggered by this element. Handles these events either by posting the event back to the event queue, or by running a function supplied by the user.

Parameters:

event -- The event triggered.
data -- event data

on_unhovered(): Called when we leave the hover state. Resets the colours and images to normal and kills any tooltip that was created while we were hovering the button.

process_event(event: Event) → bool

Handles various interactions with the button.

Parameters:: event -- The event to process.
Returns:: Return True if we want to consume this event, so it is not passed on to the rest of the UI.

rebuild(): A complete rebuild of the drawable shape used by this button.

rebuild_from_changed_theme_data(): Checks if any theming parameters have changed, and if so triggers a full rebuild of the button's drawable shape

select(): Called when we select focus this element. Changes the colours and image to the appropriate ones for the new state then redraws the button.

set_hold_range(xy_range: Tuple[int, int])

Set x and y values, in pixels, around our button to use as the hold range for time when we want to drag a button about but don't want it to slip out of our grasp too easily.

Imagine it as a large rectangle around our button, larger in all directions by whatever values we specify here.

Parameters:: xy_range -- The x and y values used to create our larger 'holding' rectangle.

set_text(text: str, *, text_kwargs: Dict[str, str] | None = None)

Sets the text on the button. The button will rebuild.

Parameters:

text -- The new text to set.
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.

unselect(): Called when we are no longer select focusing this element. Restores the colours and image to the default state then redraws the button.

update(time_delta: float)

Sets the pressed state for an update cycle if we've pressed this button recently.

Parameters:: time_delta -- the time in seconds between one call to update and the next.

Bases: UIContainer

A drop-down menu lets us choose one text option from a list. That list of options can be expanded and hidden at the press of a button. While the element is called a drop-down, it can also be made to 'climb up' by changing the 'expand_direction' styling option to 'up' in the theme file.

The drop-down is implemented through two states, one representing the 'closed' menu state and one for when it has been 'expanded'.

Parameters:

options_list -- The list of options to choose from. They must be strings.
starting_option -- The starting option, selected when the menu is first created.
relative_rect -- The size and position of the element when not expanded.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
expansion_height_limit -- Limit on the height that this will expand to, defaults to the container bounds.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
expand_on_option_click -- If this is set to False the drop-down will only expand when the open/close button is pressed and not when the selected option is pressed.

add_options(new_options: List[str] | List[Tuple[str, str]]) → None

Add new options to the drop-down. Will close the drop-down if it is currently open.

In many cases it may be easier just to recreate the drop-down with whatever the new options list is.

Parameters:: new_options -- The list of new options to add.

disable(): Disables the button so that it is no longer interactive.

enable(): Re-enables the button so, we can once again interact with it.

hide(): In addition to the base UIElement.hide() - if the current state is 'expanded' call its hide() method, which begins a transition of the UIDropDownMenu to the 'closed' state, and call the hide() method of the 'closed' state which hides all it's children widgets.

kill(): Overrides the standard sprite kill to also properly kill/finish the current state of the drop-down. Depending on whether it is expanded or closed the drop-down menu will have different elements to clean up.

on_fresh_drawable_shape_ready(): Called by an element's drawable shape when it has a new image surface ready for use, normally after a rebuilding/redrawing of some kind.

process_event(event: Event) → bool

Handles various interactions with the drop-down menu by passing them along to the active state.

Parameters:: event -- The event to process.
Returns:: Return True if we want to consume this event, so it is not passed on to the rest of the UI.

rebuild(): A complete rebuild of the drawable parts of this element.

rebuild_from_changed_theme_data(): Triggers the element to rebuild if any of its theming data has changed, which involves a lot of checking and validating its theming data.

remove_options(options_to_remove: List[str] | List[Tuple[str, str]]) → None

Will remove all instances of the options provided.

Parameters:: options_to_remove -- The list of new options to remove.

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

Sets the dimensions of this drop down, updating all subordinate button elements at the same time.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this drop down, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this drop down, updating all subordinate button elements at the same time.

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

show(): In addition to the base UIElement.show() - call show() on the closed state - showing its buttons.

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

update(time_delta: float)

The update here deals with transitioning between the two states of the drop-down menu and then passes the rest of the work onto whichever state is active.

Parameters:: time_delta -- The time in second between calls to update.

Bases: UIElement

A horizontal scroll bar allows users to position a smaller visible area within a horizontally larger area.

Parameters:

relative_rect -- The size and position of the scroll bar.
visible_percentage -- The horizontal percentage of the larger area that is visible, between 0.0 and 1.0.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

check_has_moved_recently() → bool

Returns True if the scroll bar was moved in the last call to the update function.

Returns:: True if we've recently moved the scroll bar, False otherwise.

disable(): Disables the scroll bar, so it is no longer interactive.

enable(): Enables the scroll bar, so it is interactive once again.

hide(): In addition to the base UIElement.hide() - hide the self.button_container which will propagate and hide all the buttons.

kill()

Overrides the kill() method of the UI element class to kill all the buttons in the scroll bar and clear any of the parts of the scroll bar that are currently recorded as the 'last focused horizontal scroll bar element' on the ui manager.

NOTE: the 'last focused' state on the UI manager is used so that the mouse wheel will move whichever scrollbar we last fiddled with even if we've been doing other stuff. This seems to be consistent with the most common mousewheel/scrollbar interactions used elsewhere.

process_event(event: Event) → bool

Checks an event from pygame's event queue to see if the scroll bar needs to react to it. In this case it is just mousewheel events, mainly because the buttons that make up the scroll bar will handle the required mouse click events.

Parameters:: event -- The event to process.
Returns:: Returns True if we've done something with the input event.

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.

redraw_scrollbar(): Redraws the 'scrollbar' portion of the whole UI element. Called when we change the visible percentage.

reset_scroll_position(): Reset the current scroll position back to the top.

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

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this scroll bar, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this scroll bar, updating all subordinate button elements at the same time.

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

set_scroll_from_start_percentage(new_start_percentage: float)

Set the scroll bar's scrolling position from a percentage between 0.0 and 1.0.

Parameters:: new_start_percentage -- the percentage to set.

set_visible_percentage(percentage: float)

Sets the percentage of the total 'scrollable area' that is currently visible. This will affect the size of the scrollbar and should be called if the horizontal size of the 'scrollable area' or the horizontal size of the visible area change.

Parameters:: percentage -- A float between 0.0 and 1.0 representing the percentage that is visible.

show(): In addition to the base UIElement.show() - show the self.button_container which will propagate and show all the buttons.

property start_percentage: turning start_percentage into a property, so we can round it to mitigate floating point errors

update(time_delta: float)

Called once per update loop of our UI manager. Deals largely with moving the scroll bar and updating the resulting 'start_percentage' variable that is then used by other 'scrollable' UI elements to control the point they start drawing.

Reacts to presses of the up and down arrow buttons, movement of the mouse wheel and dragging of the scroll bar itself.

Parameters:: time_delta -- A float, roughly representing the time in seconds between calls to this method.

Bases: UIElement

A horizontal slider is intended to help users adjust values within a range, for example a volume control.

Parameters:

relative_rect -- A rectangle describing the position and dimensions of the element.
start_value -- The value to start the slider at.
value_range -- The full range of values.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
click_increment -- the amount to increment by when clicking one of the arrow buttons.

disable(): Disable the slider. It should not be interactive and will use the disabled theme colours.

enable(): Enable the slider. It should become interactive and will use the normal theme colours.

get_current_value() → float | int

Gets the current value the slider is set to.

Returns:: The current value recorded by the slider.

hide(): In addition to the base UIElement.hide() - hide the sliding button and hide the button_container which will propagate and hide the left and right buttons.

kill(): Overrides the normal sprite kill() method to also kill the button elements that help make up the slider.

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.

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_current_value(value: float | int, warn: bool = True)

Sets the value of the slider, which will move the position of the slider to match. Will issue a warning if the value set is not in the value range.

Parameters:

value -- The value to set.
warn -- set to 'False' to suppress the default warning, instead the value will be clamped.

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

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this slider, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this slider, updating all subordinate button elements at the same time.

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

show(): In addition to the base UIElement.show() - show the sliding button and show the button_container which will propagate and show the left and right buttons.

update(time_delta: float)

Takes care of actually moving the slider based on interactions reported by the buttons or based on movement of the mouse if we are gripping the slider itself.

Parameters:: time_delta -- the time in seconds between calls to update.

class pygame_gui.elements.UIImage(relative_rect: Rect | FRect | Tuple[float, float, float, float], image_surface: Surface, manager: IUIManagerInterface | None = None, image_is_alpha_premultiplied: bool = False, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1, *, starting_height: int = 1)

Bases: UIElement

Displays a pygame surface as a UI element, intended for an image, but it can serve other purposes.

Parameters:

relative_rect -- The rectangle that contains, positions and scales the image relative to its container.
image_surface -- A pygame surface to display.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

rebuild_from_changed_theme_data(): A stub to override when we want to rebuild from theme data.

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

Set the dimensions of this image, scaling the image surface to match.

Parameters:

dimensions -- The new dimensions of the image.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

set_image(new_image: Surface | None, image_is_alpha_premultiplied: bool = False) → None

Allows users to change the image displayed on a UIImage element during run time, without recreating the element.

GUI images are converted to the correct format for the GUI if the supplied image is not the dimensions of the UIImage element it will be scaled to fit. In this situation, an original size image is retained as well in case of future resizing events.

Parameters:

new_image -- the new image surface to use in the UIImage element.
image_is_alpha_premultiplied -- set to True if the image is already in alpha multiplied colour format.

Bases: UIElement, IUITextOwnerInterface

A label lets us display a single line of text with a single font style. It's a quick to rebuild and simple alternative to the text box element.

Parameters:

relative_rect -- Normally a rectangle describing the position (relative to its container) and dimensions. Also accepts a position Coordinate where the dimensions will be dynamic depending on the text contents. Dynamic dimensions can be requested by setting the required dimension to -1.
text -- The text to display in the label.
manager -- The UIManager that manages this label. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
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.

clear_all_active_effects(sub_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.

clear_text_surface(sub_chunk: TextLineChunkFTFont | None = None)

Clear the text surface

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

disable(): Disables the label so that its text changes to the disabled colour.

enable(): Re-enables the label so that its text changes to the normal colour

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

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

rebuild(): Re-render the text to the label's underlying sprite image. This allows us to change what the displayed text is or remake it with different theming (if the theming has changed).

rebuild_from_changed_theme_data(): Checks if any theming parameters have changed, and if so triggers a full rebuild of the element.

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.

set_text(text: str, *, text_kwargs: Dict[str, str] | None = None)

Changes the string displayed by the label element. Labels do not support HTML styling.

Parameters:

text -- the text to set the label to.
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.

set_text_alpha(alpha: int, sub_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.

set_text_offset_pos(offset: Tuple[int, int], sub_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:

set_text_rotation(rotation: int, sub_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:

set_text_scale(scale: int, sub_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:

stop_finished_effect(sub_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.

update(time_delta: float)

Called once every update loop of the UI Manager.

Parameters:: time_delta -- The time in seconds between calls to update. Useful for timing things.

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

Bases: UIElement, IContainerLikeInterface

A rectangular panel that holds a UI container and is designed to overlap other elements. It acts a little like a window that is not shuffled about in a stack - instead remaining at the same layer distance from the container it was initially placed in.

It's primary purpose is for things like involved HUDs in games that want to always sit on top of UI elements that may be present 'inside' the game world (e.g. player health bars). By creating a UI Panel at a height above the highest layer used by the game world's UI elements we can ensure that all elements added to the panel are always above the fray.

Parameters:

relative_rect -- The positioning and sizing rectangle for the panel. See the layout guide for details.
starting_height -- How many layers above its container to place this panel on.
manager -- The GUI manager that handles drawing and updating the UI and interactions between elements. If not provided or set to None, it will try to use the first UIManager that was created by your application.
margins -- Controls the distance between the edge of the panel and where it's container should begin.
container -- The container this panel is inside - distinct from this panel's own container.
parent_element -- A hierarchical 'parent' used for signifying belonging and used in theming and events.
object_id -- An identifier that can be used to help distinguish this particular panel from others.
anchors -- Used to layout elements and dictate what the relative_rect is relative to. Defaults to the top left.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

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.

disable(): Disables all elements in the panel, so they are no longer interactive.

enable(): Enables all elements in the panel, so they are interactive again.

get_container() → IUIContainerInterface

Returns the container that should contain all the UI elements in this panel.

Return UIContainer:: The panel's container.

hide(): In addition to the base UIElement.hide() - call hide() of owned container - panel_container.

kill(): Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this panel.

process_event(event: Event) → bool

Can be overridden, also handle resizing windows. Gives UI Windows access to pygame events. Currently just blocks mouse click down events from passing through the panel.

Parameters:: event -- The event to process.
Returns:: Should return True if this element consumes this event.

rebuild(): A complete rebuild of the drawable shape used by this button.

rebuild_from_changed_theme_data(): Checks if any theming parameters have changed, and if so triggers a full rebuild of the button's drawable shape.

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

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

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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.

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.

show(): In addition to the base UIElement.show() - call show() of owned container - panel_container.

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 panel'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.

Bases: UIStatusBar

A UI that will display a progress bar from 0 to 100%

Parameters:

relative_rect -- The rectangle that defines the size and position of the progress bar.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

status_text(): Subclass and override this method to change what text is displayed, or to suppress the text.

Bases: UIStatusBar

A UI that will display health capacity and current health for a sprite in 'screen space'. That means it won't move with the camera. This is a good choice for a user/player sprite.

Parameters:

relative_rect -- The rectangle that defines the size and position of the health bar.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
sprite_to_monitor -- The sprite we are displaying the health of.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

status_text(): Subclass and override this method to change what text is displayed, or to suppress the text.

class pygame_gui.elements.UIScrollingContainer(relative_rect: Rect, manager: IUIManagerInterface | None = None, *, starting_height: int = 1, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, element_id: List[str] | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1, should_grow_automatically: bool = True, allow_scroll_x: bool = True, allow_scroll_y: bool = True)

Bases: UIElement, IContainerLikeInterface

A container like UI element that lets users scroll around a larger container of content with scroll bars.

Parameters:

relative_rect -- The size and relative position of the container. This will also be the starting size of the scrolling area.
manager -- The UI manager for this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
starting_height -- The starting layer height of this container above its container. Defaults to 1.
container -- The container this container is within. Defaults to None (which is the root container for the UI)
parent_element -- A parent element for this container. Defaults to None, or the container if you've set that.
object_id -- An object ID for this element.
anchors -- Layout anchors in a dictionary.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
allow_scroll_x -- Whether a scrollbar should be added to scroll horizontally (when needed). Defaults to True.
allow_scroll_y -- Whether a scrollbar should be added to scroll vertically (when needed). Defaults to True.

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.

disable(): Disables all elements in the container, so they are no longer interactive.

enable(): Enables all elements in the container, so they are interactive again.

get_container() → IUIContainerInterface

Gets the scrollable container area (the one that moves around with the scrollbars) from this container-like UI element.

Returns:: the scrolling container.

hide(): In addition to the base UIElement.hide() - call hide() of owned container - _root_container. All other sub-elements (view_container, scrollbars) are children of _root_container, so it's visibility will propagate to them - there is no need to call their hide() methods separately.

kill(): Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this panel.

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.

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.

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.

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

Set the size of the scrollable area container. It starts the same size as the view container, but often you want to expand it, or why have a scrollable container?

Parameters:: dimensions -- The new dimensions.

show(): In addition to the base UIElement.show() - call show() of owned container - _root_container. All other sub-elements (view_container, scrollbars) are children of _root_container, so it's visibility will propagate to them - there is no need to call their show() methods separately.

update(time_delta: float)

Updates the scrolling container's position based upon the scroll bars and updates the scrollbar's visible percentage as well if that has changed.

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

Bases: UIElement

A rectangular element that holds any number of selectable text items displayed as a list.

Parameters:

relative_rect -- The positioning and sizing rectangle for the panel. See the layout guide for details.
item_list -- A list of items as strings (item name only), or tuples of two strings (name, theme_object_id).
default_selection -- Default item(s) that should be selected: a string or a (str, str) tuple for single-selection lists or a list of strings or list of (str, str) tuples for multi-selection lists.
manager -- The GUI manager that handles drawing and updating the UI and interactions between elements. If not provided or set to None, it will try to use the first UIManager that was created by your application.
allow_multi_select -- True if we are allowed to pick multiple things from the selection list.
allow_double_clicks -- True if we can double-click on items in the selection list.
container -- The container this element is inside (by default the root container) distinct from this panel's container.
starting_height -- The starting height up from its container where this list is placed into a layer.
parent_element -- A hierarchical 'parent' used for signifying belonging and used in theming and events.
object_id -- An identifier that can be used to help distinguish this particular element from others with the same hierarchy.
anchors -- Used to layout elements and dictate what the relative_rect is relative to. Defaults to the top left.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

add_items(new_items: List[str] | List[Tuple[str, str]]) → None

Add any number of new items to the selection list. Uses the same format as when the list is first created.

Parameters:: new_items -- the list of new items to add

disable(): Disables all elements in the selection list, so they are no longer interactive.

enable(): Enables all elements in the selection list, so they are interactive again.

get_multi_selection(include_object_id: bool = False) → List[str] | List[Tuple[str, str]]

Get all the selected items in our selection list. Only works if this is a multi-selection list.

Parameters:: include_object_id -- if True adds the object id of this list item to the returned list of Tuples. If False we just get a list of the visible text strings only.
Returns:: A list of the selected items in our selection list. May be empty if nothing selected.

get_single_selection(include_object_id: bool = False) → Tuple[str, str] | str | None

Get the selected item in a list, if any. Only works if this is a single-selection list.

Parameters:: include_object_id -- if True adds the object id of this list item to the returned list of Tuples. If False we just get a list of the visible text strings only.
Returns:: A single item name as a string or None.

get_single_selection_start_percentage(): The percentage through the height of the list where the top of the first selected option is.

hide(): In addition to the base UIElement.hide() - call hide() of owned container - list_and_scroll_bar_container. All other sub-elements (item_list_container, scrollbar) are children of list_and_scroll_bar_container, so it's visibility will propagate to them - there is no need to call their hide() methods separately.

kill(): Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this panel.

process_event(event: Event) → bool

Can be overridden, also handle resizing windows. Gives UI Windows access to pygame events. Currently just blocks mouse click down events from passing through the panel.

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

rebuild(): A complete rebuild of the drawable shape used by this element.

rebuild_from_changed_theme_data(): Checks if any theming parameters have changed, and if so triggers a full rebuild of the button's drawable shape

remove_items(items_to_remove: List[str] | List[Tuple[str, str]]) → None

Will remove all instances of the items provided. The full tuple is required for items with a display name and an object ID.

Parameters:: items_to_remove -- The list of new options to remove.

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

Set the size of this panel and then resizes and shifts the contents of the panel container to fit the new size.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- clamp these dimensions to the size of the element's container.

set_item_list(new_item_list: List[str] | List[Tuple[str, str]])

Set a new string list (or tuple of strings & ids list) as the item list for this selection list. This will change what is displayed in the list.

Tuples should be arranged like so:

(list_text, object_ID)

list_text: displayed in the UI

object_ID: used for theming and events

Parameters:: new_item_list -- The new list to switch to. Can be a list of strings or tuples.

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

Sets the absolute screen position of this slider, updating all subordinate button elements at the same time.

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

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.

show(): In addition to the base UIElement.show() - call show() of owned container - list_and_scroll_bar_container. All other sub-elements (item_list_container, scrollbar) are children of list_and_scroll_bar_container, so it's visibility will propagate to them - there is no need to call their show() methods separately.

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 panel'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.

Bases: UIElement

Displays a status/progress bar.

This is a flexible class that can be used to display status for a sprite (health/mana/fatigue, etc.), or to provide a status bar on the screen not attached to any particular object. You can use multiple status bars for a sprite to show different status items if desired.

You can use the percent_full attribute to manually set the status, or you can provide a pointer to a method that will provide the percentage information.

This is a kitchen sink class with several ways to use it; you may want to look at the subclasses built on top of it that are designed to be simpler to use, such as UIProgressBar, UIWorldSpaceHealthBar, and UIScreenSpaceHealthBar.

Parameters:

relative_rect -- The rectangle that defines the size of the health bar.
sprite -- Optional sprite to monitor for status info, and for drawing the bar with the sprite.
follow_sprite -- If there's a sprite, this indicates whether the bar should be drawn at the sprite's location.
percent_method -- Optional method signature to call to get the percent complete. (To provide a method signature, simply reference the method without parenthesis, such as self.health_percent.)
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

property percent_full: Use this property to directly change the status bar.

rebuild(): Rebuild the status bar entirely because the theming data 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.

redraw(): Redraw the status bar when something, other than it's position has changed.

status_text(): To display text in the bar, subclass UIStatusBar and override this method.

update(time_delta: float)

Updates the status bar sprite's image and rectangle with the latest status and position data from the sprite we are monitoring

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

Bases: UIElement

** EXPERIMENTAL ** A tab container. The displayed panel can be switched by clicking on the tab.

Parameters:

relative_rect -- Normally a rectangle describing the position (relative to its container) and dimensions. Also accepts a position Tuple, or Vector2 where the dimensions will be dynamic depending on the button's contents. Dynamic dimensions can be requested by setting the required dimension to -1.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
starting_height -- The height in layers above its container that this element will be placed.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

add_tab(title_text: str, title_object_id: str) → int

Create a new tab.

:return : the integer id of the newly created tab

disable(): Disables the window and it's contents so it is no longer interactive.

enable(): Enables the window and it's contents so it is interactive again.

hide(): In addition to the base UIElement.hide() - hide the _window_root_container which will propagate and hide all the children.

kill(): Overrides the basic kill() method of a pygame sprite so that we also kill all the UI elements in this panel.

process_event(event: Event)

Handles various interactions with the tab container.

Parameters:: event -- The event to process.
Returns:: Return True if we want to consume this event, so it is not passed on to the rest of the UI.

rebuild(count: int | None = None): Rebuilds the tab container.

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

Set the size of this tab container.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

show(): In addition to the base UIElement.show() - show the _window_root_container which will propagate and show all the children.

class pygame_gui.elements.UITextBox(html_text: str, relative_rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, wrap_to_height: bool = False, starting_height: int = 1, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1, *, pre_parsing_enabled: bool = True, text_kwargs: Dict[str, str] | None = None, allow_split_dashes: bool = True, plain_text_display_only: bool = False, should_html_unescape_input_text: bool = False, placeholder_text: str | None = None)

Bases: UIElement, IUITextOwnerInterface

A Text Box element lets us display word-wrapped, formatted text. If the text to display is longer than the height of the box given then the element will automatically create a vertical scroll bar so that all the text can be seen.

Formatting the text is done via a subset of HTML tags. Currently supported tags are:

or - to encase bold styled text.
, or <var></var> - to encase italic styled text.
- to encase underlined text.
<a href='id'></a> - to encase 'link' text that can be clicked on to generate events with the
id given in href.
<body bgcolor='#FFFFFF'></body> - to change the background colour of encased text.
or - to start a new line.
- To set the font, colour and size of
encased text.
<hr> a horizontal rule.
<effect id='custom_id'></effect> - to encase text to that will have an effect applied. The custom id
supplied is used when setting an effect on this text box.
<shadow size=1 offset=1,1 color=#808080></shadow> - puts a shadow behind the text encased. Can also be used to
make a glow effect.
<img src="data/images/test_images/london.jpg" float=right> Inserts an image into the text with options on how to
float the text around the image. Float options are left, right or none.

More may be added in the future if needed or frequently requested.

NOTE: if dimensions of the initial containing rect are set to -1 the text box will match the final dimension to whatever the text rendering produces. This lets us make dynamically sized text boxes depending on their contents.

Parameters:

html_text -- The HTML formatted text to display in this text box.
relative_rect -- The 'visible area' rectangle, positioned relative to its container.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
wrap_to_height -- False by default, if set to True the box will increase in height to match the text within.
starting_height -- Sets the height, above its container, to start placing the text box at.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
pre_parsing_enabled -- When enabled will replace all newline characters with html tags.
text_kwargs -- A dictionary of variable arguments to pass to the translated text useful when you have multiple translations that need variables inserted in the middle.
allow_split_dashes -- Sets whether long words that don't fit on a single line will be split with a dash or just split without a dash (more compact).
plain_text_display_only -- No markup based styling & formatting will be done on the input text.
should_html_unescape_input_text -- When enabled turns plain text encoded html back into html for this text box. e.g. < will become '<'
placeholder_text -- If the text line is empty, and not focused, this placeholder text will be shown instead.

append_html_text(new_html_str: str)

Adds a string, that is parsed for any HTML tags that pygame_gui supports, onto the bottom of the text box's current contents.

This is useful for making things like logs.

Parameters:: new_html_str -- The, potentially HTML tag, containing string of text to append.

clear_all_active_effects(sub_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.

clear_text_surface(sub_chunk: TextLineChunkFTFont | None = None)

Clear the text surface

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

disable(): Disable the text box. Basically just disables the scroll bar if one exists.

enable(): Enable the text box. Re-enables the scroll bar if one exists.

focus(): Called when we 'select focus' on this element.

full_redraw()

Trigger a full redraw of the entire text box. Useful if we have messed with the text chunks in a more fundamental fashion and need to reposition them (say, if some of them have gotten wider after being made bold).

NOTE: This doesn't reparse the text of our box. If you need to do that, just create a new text box.

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

hide(): In addition to the base UIElement.hide() - call hide() of scroll_bar if it exists.

kill(): Overrides the standard sprite kill method to also kill any scroll bars belonging to this text box.

on_fresh_drawable_shape_ready(): Called by an element's drawable shape when it has a new image surface ready for use, normally after a rebuilding/redrawing of some kind.

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

parse_html_into_style_data(): Parses HTML styled string text into a format more useful for styling rendered text.

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.

rebuild(): Rebuild whatever needs building.

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.

redraw_from_chunks()

Redraws from slightly earlier in the process than 'redraw_from_text_block'. Useful if we have redrawn individual chunks already (say, to change their style slightly after being hovered) and now want to update the text block with those changes without doing a full redraw.

This won't work very well if redrawing a chunk changed its dimensions.

redraw_from_text_block(): Redraws the final parts of the text box element that don't include redrawing the actual text. Useful if we've just moved the position of the text (say, with a scroll bar) without actually changing the text itself.

property select_range

The selected range for this text. A tuple containing the start and end indexes of the current selection.

Made into a property to keep it synchronised with the underlying drawable shape's representation.

set_active_effect(effect_type: UITextEffectType | None = 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.

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

Method to directly set the dimensions of a text box.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

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

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

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

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

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

set_text_alpha(alpha: int, sub_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.

set_text_offset_pos(offset: Tuple[int, int], sub_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:

set_text_rotation(rotation: int, sub_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:

set_text_scale(scale: float, sub_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:

show(): In addition to the base UIElement.show() - call show() of scroll_bar if it exists.

stop_finished_effect(sub_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.

unfocus(): Called when this element is no longer the current focus.

update(time_delta: float)

Called once every update loop of the UI Manager. Used to react to scroll bar movement (if there is one), update the text effect (if there is one) and check if we are hovering over any text links (if there are any).

Parameters:: time_delta -- The time in seconds between calls to update. Useful for timing things.

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

Bases: UITextBox

Inherits from UITextBox but allows you to enter text with the keyboard, much like UITextEntryLine.

Parameters:

relative_rect -- The 'visible area' rectangle, positioned relative to its container.
initial_text -- The text that starts in the text box.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

Param:

placeholder_text: If the text line is empty, and not focused, this placeholder text will be shown instead.

focus(): Called when we 'select focus' on this element. In this case it sets up the keyboard to repeat held key presses, useful for natural feeling keyboard input.

get_text() → str

Gets the text in the entry box element.

Returns:: A string.

process_event(event: Event) → bool

Allows the text entry box to react to input events, which is its primary function. The entry element reacts to various types of mouse clicks (double click selecting words, drag select), keyboard combos (CTRL+C, CTRL+V, CTRL+X, CTRL+A), individual editing keys (Backspace, Delete, Left & Right arrows) and other keys for inputting letters, symbols and numbers.

Parameters:: event -- The current event to consider reacting to.
Returns:: Returns True if we've done something with the input event.

redraw_from_text_block(): Redraws the final parts of the text box element that don't include redrawing the actual text. Useful if we've just moved the position of the text (say, with a scroll bar) without actually changing the text itself.

unfocus(): Called when this element is no longer the current focus.

update(time_delta: float)

Called every update loop of our UI Manager. Largely handles text drag selection and making sure our edit cursor blinks on and off.

Parameters:: time_delta -- The time in seconds between this update method call and the previous one.

Bases: UIElement

A GUI element for text entry from a keyboard, on a single line. The element supports the standard copy and paste keyboard shortcuts CTRL+V, CTRL+C & CTRL+X as well as CTRL+A.

There are methods that allow the entry element to restrict the characters that can be input into the text box

The height of the text entry line element will be determined by the font used rather than the standard method for UIElements of just using the height of the input rectangle.

Parameters:

relative_rect -- A rectangle describing the position and width of the text entry element.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

Param:

initial_text: A string that will start in this box. This text will remain when box is focused for editing.

Param:

placeholder_text: If the text line is empty, and not focused, this placeholder text will be shown instead.

disable(): Disables the element so that it is no longer interactive.

enable(): Re-enables the element, so we can once again interact with it.

focus(): Called when we 'select focus' on this element. In this case it sets up the keyboard to repeat held key presses, useful for natural feeling keyboard input.

get_text() → str

Gets the text in the entry line element.

Returns:: A string.

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

process_event(event: Event) → bool

Allows the text entry box to react to input events, which is its primary function. The entry element reacts to various types of mouse clicks (double click selecting words, drag select), keyboard combos (CTRL+C, CTRL+V, CTRL+X, CTRL+A), individual editing keys (Backspace, Delete, Left & Right arrows) and other keys for inputting letters, symbols and numbers.

Parameters:: event -- The current event to consider reacting to.
Returns:: Returns True if we've done something with the input event.

rebuild(): Rebuild whatever needs building.

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.

redraw(): Redraws the entire text entry element onto the underlying sprite image. Usually called when the displayed text has been edited or changed in some fashion.

property select_range

The selected range for this text. A tuple containing the start and end indexes of the current selection.

Made into a property to keep it synchronised with the underlying drawable shape's representation.

set_allowed_characters(allowed_characters: str | List[str])

Sets a whitelist of characters that will be the only ones allowed in our text entry element. We can either set the list directly, or request one of the already existing lists by a string identifier. The currently supported lists for allowed characters are:

'numbers'
'letters'
'alpha_numeric'

Parameters:: allowed_characters -- The characters to allow, either in a list form or one of the supported string ids.

set_forbidden_characters(forbidden_characters: str | List[str])

Sets a blacklist of characters that will be banned from our text entry element. We can either set the list directly, or request one of the already existing lists by a string identifier. The currently supported lists for forbidden characters are:

'numbers'
'forbidden_file_path'

Parameters:: forbidden_characters -- The characters to forbid, either in a list form or one of the supported string ids.

set_text(text: str)

Allows the text displayed in the text entry element to be set via code. Useful for setting an initial or existing value that can be edited.

The string to set must be valid for the text entry element for this to work.

Parameters:: text -- The text string to set.

set_text_hidden(is_hidden=True)

Passing in True will hide text typed into the text line, replacing it with ● characters and also disallow copying the text into the clipboard. It is designed for basic 'password box' usage.

Parameters:: is_hidden -- Can be set to True or False. Defaults to True because if you are calling this you likely want a password box with no fuss. Set it back to False if you want to un-hide the text (e.g. for one of those 'Show my password' buttons).

set_text_length_limit(limit: int)

Allows a character limit to be set on the text entry element. By default, there is no limit on the number of characters that can be entered.

Parameters:: limit -- The character limit as an integer.

unfocus(): Called when this element is no longer the current focus.

update(time_delta: float)

Called every update loop of our UI Manager. Largely handles text drag selection and making sure our edit cursor blinks on and off.

Parameters:: time_delta -- The time in seconds between this update method call and the previous one.

validate_text_string(text_to_validate: str) → bool

Checks a string of text to see if any of its characters don't meet the requirements of the allowed and forbidden character sets.

Parameters:: text_to_validate -- The text string to check.

Bases: UIElement, IUITooltipInterface

A tool tip is a floating block of text that gives additional information after a user hovers over an interactive part of a GUI for a short time. In Pygame GUI the tooltip's text is style-able with HTML.

At the moment the tooltips are only available as an option on UIButton elements.

Tooltips also don't allow a container as they are designed to overlap normal UI boundaries and be contained only within the 'root' window/container, which is synonymous with the pygame display surface.

Parameters:

html_text -- Text styled with HTML, to be displayed on the tooltip.
hover_distance -- Distance in pixels between the tooltip and the thing being hovered.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
text_kwargs -- a dictionary of variable arguments to pass to the translated text useful when you have multiple translations that need variables inserted in the middle.

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.

hide(): This is a base method hide() of a UIElement, but since it's not intended to be used on a UIToolTip - display a warning.

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: Vector2 | Tuple[float, float], clamp_to_container: bool = False)

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

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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.

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.

show(): This is a base method show() of a UIElement, but since it's not intended to be used on a UIToolTip - display a warning.

Bases: UIElement

A vertical scroll bar allows users to position a smaller visible area within a vertically larger area.

Parameters:

relative_rect -- The size and position of the scroll bar.
visible_percentage -- The vertical percentage of the larger area that is visible, between 0.0 and 1.0.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

check_has_moved_recently() → bool

Returns True if the scroll bar was moved in the last call to the update function.

Returns:: True if we've recently moved the scroll bar, False otherwise.

disable(): Disables the scroll bar so it is no longer interactive.

enable(): Enables the scroll bar so it is interactive once again.

hide(): In addition to the base UIElement.hide() - hide the self.button_container which will propagate and hide all the buttons.

kill()

Overrides the kill() method of the UI element class to kill all the buttons in the scroll bar and clear any of the parts of the scroll bar that are currently recorded as the 'last focused vertical scroll bar element' on the ui manager.

NOTE: the 'last focused' state on the UI manager is used so that the mouse wheel will move whichever scrollbar we last fiddled with even if we've been doing other stuff. This seems to be consistent with the most common mousewheel/scrollbar interactions used elsewhere.

process_event(event: Event) → bool

Checks an event from pygame's event queue to see if the scroll bar needs to react to it. In this case it is just mousewheel events, mainly because the buttons that make up the scroll bar will handle the required mouse click events.

Parameters:: event -- The event to process.
Returns:: Returns True if we've done something with the input event.

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.

redraw_scrollbar(): Redraws the 'scrollbar' portion of the whole UI element. Called when we change the visible percentage.

reset_scroll_position(): Reset the current scroll position back to the top.

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

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

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

Sets the absolute screen position of this scroll bar, updating all subordinate button elements at the same time.

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

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

Sets the relative screen position of this scroll bar, updating all subordinate button elements at the same time.

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

set_scroll_from_start_percentage(new_start_percentage: float)

Set the scroll bar's scrolling position from a percentage between 0.0 and 1.0.

Parameters:: new_start_percentage -- the percentage to set.

set_visible_percentage(percentage: float)

Sets the percentage of the total 'scrollable area' that is currently visible. This will affect the size of the scrollbar and should be called if the vertical size of the 'scrollable area' or the vertical size of the visible area change.

Parameters:: percentage -- A float between 0.0 and 1.0 representing the percentage that is visible.

show(): In addition to the base UIElement.show() - show the self.button_container which will propagate and show all the buttons.

property start_percentage: turning start_percentage into a property, so we can round it to mitigate floating point errors

update(time_delta: float)

Called once per update loop of our UI manager. Deals largely with moving the scroll bar and updating the resulting 'start_percentage' variable that is then used by other 'scrollable' UI elements to control the point they start drawing.

Reacts to presses of the up and down arrow buttons, movement of the mouse wheel and dragging of the scroll bar itself.

Parameters:: time_delta -- A float, roughly representing the time in seconds between calls to this method.

class pygame_gui.elements.UIWindow(rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, window_display_title: str = '', element_id: List[str] | str | None = None, object_id: ObjectID | str | None = None, resizable: bool = False, visible: int = 1, draggable: bool = True, *, ignore_shadow_for_initial_size_and_pos: bool = True, always_on_top: bool = False)

Bases: UIElement, IContainerLikeInterface, IWindowInterface

A base class for window GUI elements, any windows should inherit from this class.

Parameters:

rect -- A rectangle, representing size and position of the window (including title bar, shadow and borders).
manager -- The UIManager that manages this UIWindow. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_display_title -- A string that will appear in the windows title bar if it has one.
element_id -- An element ID for this window, if one is not supplied it defaults to 'window'.
object_id -- An optional object ID for this window, useful for distinguishing different windows.
resizable -- Whether this window is resizable or not, defaults to False.
visible -- Whether the element is visible by default. Warning - container visibility may override this.
draggable -- Whether this window is draggable or not, defaults to True.

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

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.

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

change_layer(new_layer: int)

Move this window, and it's contents, to a new layer in the UI.

Parameters:: new_layer -- The layer to move to.

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.

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?

disable(): Disables the window and it's contents so it is no longer interactive.

enable(): Enables the window and it's contents so it is interactive again.

get_container() → IUIContainerInterface

Returns the container that should contain all the UI elements in this window.

Return UIContainer:: The window's container.

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

get_relative_mouse_pos()

Returns the current mouse position relative to the inside of this window.

If the cursor is outside the window contents area it returns None

Returns:: tuple of relative mouse co-ords or None

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

hide(): In addition to the base UIElement.hide() - hide the _window_root_container which will propagate and hide all the children.

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_close_window_button_pressed(): Override this method to call 'hide()' instead if you want to hide a window when the close button is pressed.

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

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.

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: Vector2 | Tuple[float, float], clamp_to_container: bool = False)

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

set_display_title(new_title: str)

Set the title of the window.

Parameters:: new_title -- The title to set.

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.

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.

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.

show(): In addition to the base UIElement.show() - show the _window_root_container which will propagate and show all the children.

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.

Bases: UIStatusBar

A UI that will display a sprite's 'health_capacity' and their 'current_health' in 'world space' above the sprite. This means that the health bar will move with the camera and the sprite itself.

A sprite passed to this class must have the attributes 'health_capacity' and 'current_health'.

Parameters:

relative_rect -- The rectangle that defines the size of the health bar.
sprite_to_monitor -- The sprite we are displaying the health of.
manager -- The UIManager that manages this element. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- The container that this element is within. If not provided or set to None will be the root window's container.
parent_element -- The element this element 'belongs to' in the theming hierarchy.
object_id -- A custom defined ID for fine-tuning of theming.
anchors -- A dictionary describing what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

class ExampleHealthSprite(*groups)

Bases: Sprite

An example sprite with health instance attributes.

Parameters:: groups -- Sprite groups to put the sprite in.