pygame_gui Documentation

Pygame GUI is a module designed for creating graphical user interfaces for games written in Pygame (compatible with Pygame 2 and Python 3).

Key features include:

• Theme-able UI elements: Use JSON theme files to modify colors, fonts, and appearance without changing code.
• HTML-like text support: A subset of HTML is supported for word-wrapped text, allowing for bold styling and links within paragraphs.
• Standard Widgets: Includes buttons, text entry, scroll bars, and drop-down menus.
• Window Stack: Supports multiple moveable and correctly sorted windows.
• Localization: Built-in support for localizing the GUI into different languages.
• Performance: Uses premultiplied alpha blending for improved clarity with semi-transparent pixels and better performance.

The pygame_gui.windows package provides several pre-built window and dialog modules to simplify common UI tasks. Instead of building complex window structures from scratch, you can use these specialized submodules to handle user interactions like file selection, color picking, and message confirmation.

Available window submodules include:

• ui_colour_picker_dialog: A dialog for selecting colors.
• ui_confirmation_dialog: A dialog for asking the user to confirm an action (e.g., Yes/No).
• ui_console_window: A window for displaying console-like text output.
• ui_file_dialog: A dialog for selecting files or directories from the system.
• ui_message_window: A window for displaying informational messages to the user.

The pygame_gui.core package contains the fundamental building blocks of the library. It includes subpackages for handling drawable shapes, interfaces, and text, as well as various modules for managing the core lifecycle and appearance of UI elements.

Key functional areas include:

• Visuals & Appearance: Modules like ui_appearance_theme, ui_shadow, colour_gradient, and surface_cache manage how elements look and how resources are cached.
• Layout & Organization: ui_container and layered_gui_group provide mechanisms for grouping and nesting UI elements.
• Resource Management: resource_loaders and gui_font_pygame handle the loading of assets like fonts and images.
• Core Logic: ui_element defines the base behavior for UI components, while ui_window_stack manages windowing logic.

The misc block in a theme file allows you to control more advanced visual properties. For example, you can change the shape of an element and its border properties using keys like shape, shape_corner_radius, and border_width. Note that these values are often passed as strings in the JSON file.

{
    "button":
    {
        "colours": {
            "normal_border": "White",
            "normal_bg": "SlateGray",
            "normal_text": "White"
        },
        "misc": {
            "shape": "rounded_rectangle",
            "shape_corner_radius": "10",
            "border_width": "2"
        }
    }
}

When interacting with UI elements, pygame_gui produces pygame.Event objects. These events follow a consistent structure that allows you to identify which element triggered the action and which specific object was involved.

Every GUI event contains these core attributes:

• type: A unique identifier for the event (e.g., 'pygame_gui.UI_BUTTON_PRESSED').
• ui_element: The actual UI element instance that fired the event.
• ui_object_id: A unique string ID assigned to the UI element (e.g., 'hud_window.#sell_button').

Note that some specific event types may include additional data fields relevant to that specific interaction.

In addition to unique object_ids, pygame_gui now supports class_ids. When creating a UIElement, you can pass an ObjectID that contains both a unique object_id and a class_id.

Elements sharing the same class_id can be styled together in a theme file using a theming block, similar to how you would theme a single object ID. This allows for organized, group-based styling. You can also load multiple theme files into a single UIManager to organize your theme data.

Pygame GUI elements are positioned on the x (horizontal) and y (vertical) axes, starting from 0 at the top-left corner.

Elements use a relative_rect for positioning, which is always relative to their container. If no container is provided, elements are assigned the default 'root container' created by the UI Manager, which matches the window_resolution.

Dynamic Sizing: For certain elements like UIButton and UILabel, you can specify a dynamic width or height by setting the corresponding value in the relative_rect to -1. This allows the final size to be determined by the text content provided during creation.

# Example of a button with a fixed size
button_layout_rect = pygame.Rect(30, 20, 100, 20)

# Example of a button with dynamic width (set to -1)
dynamic_button_rect = pygame.Rect(30, 20, -1, 20)