pygame_gui.elements package

Submodules

pygame_gui.elements.ui_button module

class pygame_gui.elements.ui_button.UIButton(relative_rect: pygame.Rect, text: str, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, tool_tip_text: Optional[str] = None, starting_height: int = 1, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, allow_double_clicks: bool = False, generate_click_events_from: Iterable[int] = frozenset({1}), visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement

A push button, a lot of the appearance of the button, including images to be displayed, is setup 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 -- A rectangle describing the position (relative to its container) and dimensions.
  • text -- Text for the button.
  • manager -- The UIManager that manages this element.
  • container -- The container that this element is within. If 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 it's 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.
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 it's 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 co-ordinate to test.
  • hover_y -- vertical pixel co-ordinate to test
Returns:

Returns True if we are hovering.

in_hold_range(position: Union[pygame.math.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_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: pygame.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)

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

Parameters:text -- The new text to set.
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.
while_hovering(time_delta: float, mouse_pos: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Called while we are in the hover state. It will create a tool tip if we've been in the hover state for a while, the text exists to create one and we haven't created one already.

Parameters:
  • time_delta -- Time in seconds between calls to update.
  • mouse_pos -- The current position of the mouse.

pygame_gui.elements.ui_drop_down_menu module

class pygame_gui.elements.ui_drop_down_menu.UIClosedDropDownState(drop_down_menu_ui: pygame_gui.elements.ui_drop_down_menu.UIDropDownMenu, selected_option: str, base_position_rect: Optional[pygame.Rect], open_button_width: int, expand_direction: Optional[str], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: pygame_gui.core.interfaces.container_interface.IContainerLikeInterface, object_ids: Optional[List[Optional[str]]], element_ids: Optional[List[str]], visible: int = 1)

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: pygame.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 it's container being moved.

class pygame_gui.elements.ui_drop_down_menu.UIDropDownMenu(options_list: List[str], starting_option: str, relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, expansion_height_limit: Optional[int] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_container.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 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.
  • 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.
add_options(new_options: List[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 it's 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.

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

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

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

Returns True if we are hovering this element.

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: pygame.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 it's theming data has changed, which involves a lot of checking and validating it's theming data.

remove_options(options_to_remove: List[str]) → None

Will remove all instances of the options provided.

Parameters:options_to_remove -- The list of new options to remove.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

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

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

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

Sets the relative screen position of this 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 it's 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: pygame_gui.elements.ui_drop_down_menu.UIDropDownMenu, options_list: List[str], selected_option: str, base_position_rect: Optional[pygame.Rect], close_button_width: int, expand_direction: Optional[str], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: pygame_gui.core.interfaces.container_interface.IContainerLikeInterface, object_ids: Optional[List[Optional[str]]], element_ids: Optional[List[str]])

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: pygame.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 it's container being moved.

pygame_gui.elements.ui_horizontal_slider module

class pygame_gui.elements.ui_horizontal_slider.UIHorizontalSlider(relative_rect: pygame.Rect, start_value: Union[float, int], value_range: Tuple[Union[float, int], Union[float, int]], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1, click_increment: Union[float, int] = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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() → Union[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: pygame.event.Event) → bool

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

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

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: Union[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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the dimensions of an element.

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

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

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

Sets the relative screen position of this 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: pygame.Rect, image_surface: pygame.Surface, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, image_is_alpha_premultiplied: bool = False, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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 it's container.
  • image_surface -- A pygame surface to display.
  • manager -- The UIManager that manages this element.
  • 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.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

Parameters:dimensions -- The new dimensions of the image.
set_image(new_image: Optional[pygame.Surface], 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 UIIamge element.
  • image_is_alpha_premultiplied -- set to True if the image is already in alpha multiplied colour format.

pygame_gui.elements.ui_label module

class pygame_gui.elements.ui_label.UILabel(relative_rect: pygame.Rect, text: str, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1, **text_kwargs)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.text_owner_interface.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 -- The rectangle that contains and positions the label relative to it's container.
  • text -- The text to display in the label.
  • manager -- The UIManager that manages this label.
  • 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.
clear_all_active_effects(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

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

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
clear_text_surface(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = 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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None) → int

The amount of letters in the text

Parameters:sub_chunk -- An optional chunk to restrict the count to only this chunk.
Returns:number of letters as an int
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: Optional[pygame_gui._constants.UITextEffectType], params: Optional[Dict[str, Any]] = None, effect_tag: Optional[str] = None)

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

These effects are currently supported:

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

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

Parameters:text -- the text to set the label to.
set_text_alpha(alpha: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

Set the global alpha value for the text

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

Move the text around by this offset.

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

set_text_rotation(rotation: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

rotate the text by this int in degrees

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

set_text_scale(scale: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

Scale the text by this float

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

stop_finished_effect(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

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

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
update(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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

The position in the text to render up to.

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

pygame_gui.elements.ui_panel module

class pygame_gui.elements.ui_panel.UIPanel(relative_rect: pygame.Rect, starting_layer_height: int, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, *, element_id: str = 'panel', margins: Dict[str, int] = None, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.container_interface.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_layer_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.
  • margins -- Controls the distance between the edge of the panel and where it's container should begin.
  • container -- The container this panel is inside of 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.
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() → pygame_gui.core.interfaces.container_interface.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: pygame.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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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.
set_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

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

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

Parameters:position -- The new position to set.
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

class pygame_gui.elements.ui_progress_bar.UIProgressBar(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.elements.ui_status_bar.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.
  • 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_screen_space_health_bar module

class pygame_gui.elements.ui_screen_space_health_bar.UIScreenSpaceHealthBar(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, sprite_to_monitor: Optional[pygame.sprite.Sprite] = None, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.elements.ui_status_bar.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.
  • 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_selection_list module

class pygame_gui.elements.ui_selection_list.UISelectionList(relative_rect: pygame.Rect, item_list: Union[List[str], List[Tuple[str, str]]], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, *, allow_multi_select: bool = False, allow_double_clicks: bool = True, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, starting_height: int = 1, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1, default_selection: Union[str, Tuple[str, str], List[str], List[Tuple[str, str]], None] = None)

Bases: pygame_gui.core.ui_element.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.
  • 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 of (by default the root container) distinct from this panel's container.
  • starting_height -- The starting height up from it's 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: Union[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() → List[str]

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

Returns:A list of the selected items in our selection list. May be empty if nothing selected.
get_single_selection() → Optional[str]

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

Returns:A single item name as a string or None.
hide()

In addition to the base UIElement.hide() - call hide() of owned container - list_and_scroll_bar_container. All other subelements (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: pygame.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: Union[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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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.
set_item_list(new_item_list: Union[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: Union[pygame.math.Vector2, Tuple[int, int], 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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

Parameters:position -- The new position to set.
show()

In addition to the base UIElement.show() - call show() of owned container - list_and_scroll_bar_container. All other subelements (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

class pygame_gui.elements.ui_status_bar.UIStatusBar(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, sprite: Optional[pygame.sprite.Sprite] = None, follow_sprite: bool = True, percent_method: Optional[Callable[[], float]] = None, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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.
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: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, wrap_to_height: bool = False, layer_starting_height: int = 1, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.text_owner_interface.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:

  • <b></b> or <strong></strong> - to encase bold styled text.
  • <i></i>, <em></em> or <var></var> - to encase italic styled text.
  • <u></u> - 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.
  • <br> - to start a new line.
  • <font face='verdana' color='#000000' size=3.5></font> - To set the font, colour and size of
    encased text.

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 it's container.
  • manager -- The UIManager that manages this element.
  • wrap_to_height -- False by default, if set to True the box will increase in height to match the text within.
  • layer_starting_height -- Sets the height, above it's container, to start placing the text box at.
  • 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.
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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

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

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
clear_text_surface(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = 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. Renables the scroll bar if one exists.

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 re-parse 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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None) → int

The amount of letters in the text

Parameters:sub_chunk -- An optional chunk to restrict the count to only this chunk.
Returns:number of letters as an int
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 pygame.freetype rendered text.

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

Deals with input events. In this case we just handle clicks on any links in the text.

Parameters:event -- A pygame event to check for a reaction to.
Returns:Returns True if we consumed 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 it's 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.

set_active_effect(effect_type: Optional[pygame_gui._constants.UITextEffectType] = None, params: Optional[Dict[str, Any]] = None, effect_tag: Optional[str] = None)

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

These effects are currently supported:

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

Method to directly set the dimensions of a text box.

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

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

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

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

Parameters:position -- The relative screen position to set.
set_text_alpha(alpha: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

Set the global alpha value for the text

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

Move the text around by this offset.

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

set_text_rotation(rotation: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

rotate the text by this int in degrees

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

set_text_scale(scale: float, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

Scale the text by this float

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

show()

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

stop_finished_effect(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

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

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
update(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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

The position in the text to render up to.

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

pygame_gui.elements.ui_text_entry_line module

class pygame_gui.elements.ui_text_entry_line.UITextEntryLine(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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()

Disables the button so that it is no longer interactive.

enable()

Re-enables the button 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: pygame.event.Event) → bool

Allows the text entry box to react to input events, which is it's 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.

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: Union[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: Union[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 is able to 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 it's 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

class pygame_gui.elements.ui_tool_tip.UITooltip(html_text: str, hover_distance: Tuple[int, int], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.tool_tip_interface.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.
  • 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.
find_valid_position(position: pygame.math.Vector2) → bool

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

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

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

Parameters:position -- A 2D vector representing the position of the target this tool tip is for.
Returns:returns True if we find a valid (visible) position and False if we do not.
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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

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

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

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

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

Parameters:position -- The relative screen position to set.
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

class pygame_gui.elements.ui_vertical_scroll_bar.UIVerticalScrollBar(relative_rect: pygame.Rect, visible_percentage: float, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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 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: pygame.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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the dimensions of an element.

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

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

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

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

Parameters:position -- The relative screen position 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.

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: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, window_display_title: str = '', element_id: Optional[str] = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, resizable: bool = False, visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.container_interface.IContainerLikeInterface, pygame_gui.core.interfaces.window_interface.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.
  • 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.
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: pygame.event.Event) → bool

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

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

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

Parameters:
  • time_delta -- time passed in seconds between one call to this method and the next.
  • hovered_higher_element -- Have we already hovered an element/window above this one.
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() → pygame_gui.core.interfaces.container_interface.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_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 the stack.

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

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

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

Rebuilds the window when the theme has changed.

rebuild_from_changed_theme_data()

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

set_blocking(state: bool)

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

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

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

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

Set the title of the window.

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

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

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

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

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

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

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

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

Returns:True if a resizing cursor is needed.
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

class pygame_gui.elements.ui_world_space_health_bar.UIWorldSpaceHealthBar(relative_rect: pygame.Rect, sprite_to_monitor: Union[pygame.sprite.Sprite, pygame_gui.elements.ui_world_space_health_bar.UIWorldSpaceHealthBar.ExampleHealthSprite], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.elements.ui_status_bar.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.
  • 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.
class ExampleHealthSprite(*groups)

Bases: pygame.sprite.Sprite

An example sprite with health instance attributes.

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

Module contents

class pygame_gui.elements.UIImage(relative_rect: pygame.Rect, image_surface: pygame.Surface, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, image_is_alpha_premultiplied: bool = False, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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 it's container.
  • image_surface -- A pygame surface to display.
  • manager -- The UIManager that manages this element.
  • 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.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

Parameters:dimensions -- The new dimensions of the image.
set_image(new_image: Optional[pygame.Surface], 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 UIIamge element.
  • image_is_alpha_premultiplied -- set to True if the image is already in alpha multiplied colour format.
class pygame_gui.elements.UIButton(relative_rect: pygame.Rect, text: str, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, tool_tip_text: Optional[str] = None, starting_height: int = 1, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, allow_double_clicks: bool = False, generate_click_events_from: Iterable[int] = frozenset({1}), visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement

A push button, a lot of the appearance of the button, including images to be displayed, is setup 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 -- A rectangle describing the position (relative to its container) and dimensions.
  • text -- Text for the button.
  • manager -- The UIManager that manages this element.
  • container -- The container that this element is within. If 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 it's 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.
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 it's 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 co-ordinate to test.
  • hover_y -- vertical pixel co-ordinate to test
Returns:

Returns True if we are hovering.

in_hold_range(position: Union[pygame.math.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_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: pygame.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)

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

Parameters:text -- The new text to set.
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.
while_hovering(time_delta: float, mouse_pos: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Called while we are in the hover state. It will create a tool tip if we've been in the hover state for a while, the text exists to create one and we haven't created one already.

Parameters:
  • time_delta -- Time in seconds between calls to update.
  • mouse_pos -- The current position of the mouse.
class pygame_gui.elements.UIHorizontalSlider(relative_rect: pygame.Rect, start_value: Union[float, int], value_range: Tuple[Union[float, int], Union[float, int]], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1, click_increment: Union[float, int] = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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() → Union[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: pygame.event.Event) → bool

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

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

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: Union[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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the dimensions of an element.

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

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

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

Sets the relative screen position of this 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.UIVerticalScrollBar(relative_rect: pygame.Rect, visible_percentage: float, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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 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: pygame.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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the dimensions of an element.

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

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

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

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

Parameters:position -- The relative screen position 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.

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.UIHorizontalScrollBar(relative_rect: pygame.Rect, visible_percentage: float, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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: pygame.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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the dimensions of an element.

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

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

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

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

Parameters:position -- The relative screen position 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.

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.UILabel(relative_rect: pygame.Rect, text: str, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1, **text_kwargs)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.text_owner_interface.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 -- The rectangle that contains and positions the label relative to it's container.
  • text -- The text to display in the label.
  • manager -- The UIManager that manages this label.
  • 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.
clear_all_active_effects(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

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

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
clear_text_surface(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = 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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None) → int

The amount of letters in the text

Parameters:sub_chunk -- An optional chunk to restrict the count to only this chunk.
Returns:number of letters as an int
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: Optional[pygame_gui._constants.UITextEffectType], params: Optional[Dict[str, Any]] = None, effect_tag: Optional[str] = None)

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

These effects are currently supported:

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

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

Parameters:text -- the text to set the label to.
set_text_alpha(alpha: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

Set the global alpha value for the text

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

Move the text around by this offset.

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

set_text_rotation(rotation: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

rotate the text by this int in degrees

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

set_text_scale(scale: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

Scale the text by this float

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

stop_finished_effect(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

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

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
update(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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

The position in the text to render up to.

Parameters:
  • end_pos -- The current end position as an int
  • sub_chunk -- An optional chunk to restrict the end_position to only this chunk.
class pygame_gui.elements.UIPanel(relative_rect: pygame.Rect, starting_layer_height: int, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, *, element_id: str = 'panel', margins: Dict[str, int] = None, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.container_interface.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_layer_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.
  • margins -- Controls the distance between the edge of the panel and where it's container should begin.
  • container -- The container this panel is inside of 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.
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() → pygame_gui.core.interfaces.container_interface.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: pygame.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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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.
set_position(position: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

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

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

Parameters:position -- The new position to set.
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.
class pygame_gui.elements.UIProgressBar(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.elements.ui_status_bar.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.
  • 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.UIScreenSpaceHealthBar(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, sprite_to_monitor: Optional[pygame.sprite.Sprite] = None, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.elements.ui_status_bar.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.
  • 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.UISelectionList(relative_rect: pygame.Rect, item_list: Union[List[str], List[Tuple[str, str]]], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, *, allow_multi_select: bool = False, allow_double_clicks: bool = True, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, starting_height: int = 1, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1, default_selection: Union[str, Tuple[str, str], List[str], List[Tuple[str, str]], None] = None)

Bases: pygame_gui.core.ui_element.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.
  • 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 of (by default the root container) distinct from this panel's container.
  • starting_height -- The starting height up from it's 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: Union[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() → List[str]

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

Returns:A list of the selected items in our selection list. May be empty if nothing selected.
get_single_selection() → Optional[str]

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

Returns:A single item name as a string or None.
hide()

In addition to the base UIElement.hide() - call hide() of owned container - list_and_scroll_bar_container. All other subelements (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: pygame.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: Union[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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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.
set_item_list(new_item_list: Union[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: Union[pygame.math.Vector2, Tuple[int, int], 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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

Parameters:position -- The new position to set.
show()

In addition to the base UIElement.show() - call show() of owned container - list_and_scroll_bar_container. All other subelements (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.
class pygame_gui.elements.UITextBox(html_text: str, relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, wrap_to_height: bool = False, layer_starting_height: int = 1, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.text_owner_interface.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:

  • <b></b> or <strong></strong> - to encase bold styled text.
  • <i></i>, <em></em> or <var></var> - to encase italic styled text.
  • <u></u> - 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.
  • <br> - to start a new line.
  • <font face='verdana' color='#000000' size=3.5></font> - To set the font, colour and size of
    encased text.

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 it's container.
  • manager -- The UIManager that manages this element.
  • wrap_to_height -- False by default, if set to True the box will increase in height to match the text within.
  • layer_starting_height -- Sets the height, above it's container, to start placing the text box at.
  • 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.
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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

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

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
clear_text_surface(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = 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. Renables the scroll bar if one exists.

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 re-parse 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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None) → int

The amount of letters in the text

Parameters:sub_chunk -- An optional chunk to restrict the count to only this chunk.
Returns:number of letters as an int
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 pygame.freetype rendered text.

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

Deals with input events. In this case we just handle clicks on any links in the text.

Parameters:event -- A pygame event to check for a reaction to.
Returns:Returns True if we consumed 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 it's 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.

set_active_effect(effect_type: Optional[pygame_gui._constants.UITextEffectType] = None, params: Optional[Dict[str, Any]] = None, effect_tag: Optional[str] = None)

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

These effects are currently supported:

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

Method to directly set the dimensions of a text box.

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

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

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

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

Parameters:position -- The relative screen position to set.
set_text_alpha(alpha: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

Set the global alpha value for the text

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

Move the text around by this offset.

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

set_text_rotation(rotation: int, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

rotate the text by this int in degrees

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

set_text_scale(scale: float, sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

Scale the text by this float

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

show()

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

stop_finished_effect(sub_chunk: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

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

Parameters:sub_chunk -- An optional chunk so we only clear the effect from this chunk.
update(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: Optional[pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont] = None)

The position in the text to render up to.

Parameters:
  • end_pos -- The current end position as an int
  • sub_chunk -- An optional chunk to restrict the end_position to only this chunk.
class pygame_gui.elements.UITooltip(html_text: str, hover_distance: Tuple[int, int], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.tool_tip_interface.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.
  • 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.
find_valid_position(position: pygame.math.Vector2) → bool

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

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

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

Parameters:position -- A 2D vector representing the position of the target this tool tip is for.
Returns:returns True if we find a valid (visible) position and False if we do not.
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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

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

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

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

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

Parameters:position -- The relative screen position to set.
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.

class pygame_gui.elements.UIDropDownMenu(options_list: List[str], starting_option: str, relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, expansion_height_limit: Optional[int] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_container.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 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.
  • 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.
add_options(new_options: List[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 it's 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.

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

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

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

Returns True if we are hovering this element.

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: pygame.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 it's theming data has changed, which involves a lot of checking and validating it's theming data.

remove_options(options_to_remove: List[str]) → None

Will remove all instances of the options provided.

Parameters:options_to_remove -- The list of new options to remove.
set_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

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

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

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

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

Sets the relative screen position of this 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 it's 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.UIStatusBar(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, sprite: Optional[pygame.sprite.Sprite] = None, follow_sprite: bool = True, percent_method: Optional[Callable[[], float]] = None, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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.
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.
class pygame_gui.elements.UIWorldSpaceHealthBar(relative_rect: pygame.Rect, sprite_to_monitor: Union[pygame.sprite.Sprite, pygame_gui.elements.ui_world_space_health_bar.UIWorldSpaceHealthBar.ExampleHealthSprite], manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.elements.ui_status_bar.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.
  • 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.
class ExampleHealthSprite(*groups)

Bases: pygame.sprite.Sprite

An example sprite with health instance attributes.

Parameters:groups -- Sprite groups to put the sprite in.
class pygame_gui.elements.UIProgressBar(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.elements.ui_status_bar.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.
  • 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.UITextEntryLine(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: pygame_gui.core.ui_element.UIElement = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Dict[str, str] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.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.
  • 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()

Disables the button so that it is no longer interactive.

enable()

Re-enables the button 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: pygame.event.Event) → bool

Allows the text entry box to react to input events, which is it's 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.

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: Union[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: Union[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 is able to 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 it's characters don't meet the requirements of the allowed and forbidden character sets.

Parameters:text_to_validate -- The text string to check.
class pygame_gui.elements.UIWindow(rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, window_display_title: str = '', element_id: Optional[str] = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, resizable: bool = False, visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.container_interface.IContainerLikeInterface, pygame_gui.core.interfaces.window_interface.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.
  • 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.
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: pygame.event.Event) → bool

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

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

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

Parameters:
  • time_delta -- time passed in seconds between one call to this method and the next.
  • hovered_higher_element -- Have we already hovered an element/window above this one.
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() → pygame_gui.core.interfaces.container_interface.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_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 the stack.

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

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

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

Rebuilds the window when the theme has changed.

rebuild_from_changed_theme_data()

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

set_blocking(state: bool)

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

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

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

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

Set the title of the window.

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

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

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

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

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

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

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

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

Returns:True if a resizing cursor is needed.
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.
class pygame_gui.elements.UIScrollingContainer(relative_rect: pygame.Rect, manager: pygame_gui.core.interfaces.manager_interface.IUIManagerInterface, *, starting_height: int = 1, container: Optional[pygame_gui.core.interfaces.container_interface.IContainerLikeInterface] = None, parent_element: Optional[pygame_gui.core.ui_element.UIElement] = None, object_id: Union[pygame_gui.core.ui_element.ObjectID, str, None] = None, anchors: Optional[Dict[str, str]] = None, visible: int = 1)

Bases: pygame_gui.core.ui_element.UIElement, pygame_gui.core.interfaces.container_interface.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.
  • starting_height -- The starting layer height of this container above it's 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.
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() → pygame_gui.core.interfaces.container_interface.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 subelements (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: Union[pygame.math.Vector2, Tuple[int, int], Tuple[float, float]])

Method to directly set the dimensions of an element.

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

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

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

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

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

Parameters:position -- The new position to set.
set_scrollable_area_dimensions(dimensions: Union[pygame.math.Vector2, Tuple[int, int], 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 subelements (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.