GUI#

class arcade.gui.UIDraggableMixin(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, children: Iterable[UIWidget] = (), size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]#

Bases: UILayout

UIDraggableMixin can be used to make any UIWidget draggable.

Example, create a draggable Frame, with a background, useful for window like constructs:

class DraggablePane(UITexturePane, UIDraggableMixin):
…

This does overwrite UILayout behaviour which position themselves, like UIAnchorWidget

do_layout()[source]#

on_event(event) → bool | None[source]#

class arcade.gui.UIMouseFilterMixin(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, children: Iterable[UIWidget] = (), size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]#

Bases: UIWidget

UIMouseFilterMixin can be used to catch all mouse events which occur inside this widget.

Useful for window like widgets, UIMouseEvents should not trigger effects which are under the widget.

on_event(event) → bool | None[source]#

class arcade.gui.UIWindowLikeMixin(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, children: Iterable[UIWidget] = (), size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]#

Bases: UIMouseFilterMixin, UIDraggableMixin, UIWidget

Makes a widget window like:

handles all mouse events that occur within the widgets boundaries
can be dragged

class arcade.gui.Surface(*, size: Tuple[int, int], position: Tuple[int, int] = (0, 0), pixel_ratio: float = 1.0)[source]#

Bases:

Holds a arcade.gl.Framebuffer and abstracts the drawing on it. Used internally for rendering widgets.

activate()[source]#: Save and restore projection and activate Surface buffer to draw on. Also resets the limit of the surface (viewport).

clear(color: Tuple[int, int, int, int] = (0, 0, 0, 0))[source]#: Clear the surface

draw(area: Tuple[float, float, float, float] | List[float] | None = None) → None[source]#

Draws the contents of the surface.

The surface will be rendered at the configured position and limited by the given area. The area can be out of bounds.

Parameters:: area – Limit the area in the surface we’re drawing (x, y, w, h)

draw_sprite(x, y, width, height, sprite)[source]#: Draw a sprite to the surface

draw_texture(x: float, y: float, width: float, height: float, tex: Texture | NinePatchTexture, angle: float = 0.0, alpha: int = 255)[source]#

limit(x, y, width, height)[source]#: Reduces the draw area to the given rect

resize(*, size: Tuple[int, int], pixel_ratio: float) → None[source]#

Resize the internal texture by re-allocating a new one

Parameters:

size – The new size in pixels (xy)
pixel_ratio – The pixel scale of the window

blend_func_render#: Blend mode for when we’re drawing the surface

blend_func_render_into#: Blend modes for when we’re drawing into the surface

height#

pixel_ratio#

position#: Get or set the surface position

size#: Size of the surface in window coordinates

size_scaled#: The physical size of the buffer

width#

class arcade.gui.UIButtonRow(*, vertical: bool = False, align: str = 'center', size_hint: ~typing.Any = (0, 0), size_hint_min: ~typing.Any | None = None, size_hint_max: ~typing.Any | None = None, space_between: int = 10, style: ~typing.Any | None = None, button_factory: type = <class 'arcade.gui.widgets.buttons.UIFlatButton'>)[source]#

Bases: UIBoxLayout

Places buttons in a row. :param vertical: Whether the button row is vertical or not. :param align: Where to align the button row. :param size_hint: Tuple of floats (0.0 - 1.0) of how much space of the parent should be requested. :param size_hint_min: Min width and height in pixel. :param size_hint_max: Max width and height in pixel. :param space_between: The space between the children. :param style: Not used. :param Tuple[str, …] button_labels: The labels for the buttons. :param callback: The callback function which will receive the text of the clicked button.

add_button(label: str, *, style=None, multiline=False)[source]#

on_action(event: UIOnActionEvent)[source]#

class arcade.gui.UIMessageBox(*, width: float, height: float, message_text: str, buttons=('Ok',))[source]#

Bases: UIMouseFilterMixin, UIAnchorLayout

A simple dialog box that pops up a message with buttons to close. Subclass this class or overwrite the ‘on_action’ event handler with

box = UIMessageBox(...)
@box.event("on_action")
def on_action(event: UIOnActionEvent):
    pass

Parameters:

width – Width of the message box
height – Height of the message box
message_text – Text to show as message to the user
buttons – List of strings, which are shown as buttons

on_action(event: UIOnActionEvent)[source]#: Called when button was pressed

class arcade.gui.UIManager(window: Window | None = None)[source]#

Bases: EventDispatcher

UIManager is the central component within Arcade’s GUI system. Handles window events, layout process and rendering.

To process window events, UIManager.enable() has to be called, which will inject event callbacks for all window events and redirects them through the widget tree.

If used within a view UIManager.enable() should be called from View.on_show_view() and UIManager.disable() should be called from View.on_hide_view()

Supports size_hint to grow/shrink direct children dependent on window size. Supports size_hint_min to ensure size of direct children (e.g. UIBoxLayout). Supports size_hint_max to ensure size of direct children (e.g. UIBoxLayout).

class MyView(arcade.View):
    def __init__():
        super().__init__()
        manager = UIManager()

        manager.add(Dummy())

    def on_show_view(self):
        # Set background color
        self.window.background_color = arcade.color.DARK_BLUE_GRAY

        # Enable UIManager when view is shown to catch window events
        self.ui.enable()

    def on_hide_view(self):
        # Disable UIManager when view gets inactive
        self.ui.disable()

    def on_draw():
        self.clear()

        ...

        manager.draw() # draws the UI on screen

add(widget: W, *, index=None, layer=0) → W[source]#

Add a widget to the UIManager. Added widgets will receive ui events and be rendered.

By default the latest added widget will receive ui events first and will be rendered on top of others.

The UIManager supports layered setups, widgets added to a higher layer are drawn above lower layers and receive events first. The layer 10 is reserved for overlaying components like dropdowns or tooltips.

Parameters:

widget – widget to add
index – position a widget is added, None has the highest priority
layer – layer which the widget should be added to, higher layer are above

Returns:

the widget

adjust_mouse_coordinates(x, y)[source]#

This method is used, to translate mouse coordinates to coordinates respecting the viewport and projection of cameras. The implementation should work in most common cases.

If you use scrolling in the arcade.Camera you have to reset scrolling or overwrite this method using the camera conversion:

ui_manager.adjust_mouse_coordinates = camera.mouse_coordinates_to_world

clear()[source]#: Remove all widgets from UIManager

debug()[source]#: Walks through all widgets of a UIManager and prints out the rect

disable() → None[source]#

Remove handler functions (on_…) from arcade.Window

If every arcade.View uses its own arcade.gui.UIManager, this method should be called in arcade.View.on_hide_view().

dispatch_ui_event(event)[source]#

draw() → None[source]#

enable() → None[source]#

Registers handler functions (on_…) to arcade.gui.UIElement

on_draw is not registered, to provide full control about draw order, so it has to be called by the devs themselves.

Within a view, this method should be called from arcade.View.on_show_view().

get_widgets_at(pos: ~typing.Tuple[float, float], cls: ~typing.Type[~arcade.gui.ui_manager.W] = <class 'arcade.gui.widgets.UIWidget'>, layer=0) → Iterable[W][source]#

Yields all widgets containing a position, returns first top laying widgets which is instance of cls.

Parameters:

pos – Pos within the widget bounds
cls – class which the widget should be an instance of
layer – layer to search, None will search through all layers

Returns:

iterator of widgets of given type at position

on_event(event) → bool | None[source]#

on_key_press(symbol: int, modifiers: int)[source]#

on_key_release(symbol: int, modifiers: int)[source]#

on_mouse_drag(x: float, y: float, dx: float, dy: float, buttons: int, modifiers: int)[source]#

on_mouse_motion(x: float, y: float, dx: float, dy: float)[source]#

on_mouse_press(x: float, y: float, button: int, modifiers: int)[source]#

on_mouse_release(x: float, y: float, button: int, modifiers: int)[source]#

on_mouse_scroll(x, y, scroll_x, scroll_y)[source]#

on_resize(width, height)[source]#

on_text(text)[source]#

on_text_motion(motion)[source]#

on_text_motion_select(motion)[source]#

on_update(time_delta)[source]#

remove(child: UIWidget)[source]#

Removes the given widget from UIManager.

Parameters:: child – widget to remove

trigger_render()[source]#: Request rendering of all widgets

walk_widgets(*, root: UIWidget | None = None, layer=0) → Iterable[UIWidget][source]#

walks through widget tree, in reverse draw order (most top drawn widget first)

Parameters:

root – root widget to start from, if None, the layer is used
layer – layer to search, None will search through all layers

OVERLAY_LAYER = 10#

camera#: Camera used when drawing the UI

rect#

class arcade.gui.NinePatchTexture(*, left: int, right: int, bottom: int, top: int, texture: Texture, atlas: TextureAtlas | None = None)[source]#

Bases:

Keeps borders & corners at constant widths while stretching the middle.

It can be used with new or existing UIWidget subclasses wherever an ordinary arcade.Texture is supported. This is useful for GUI elements which must grow or shrink while keeping their border decorations constant, such as dialog boxes or text boxes.

The diagram below explains the stretching behavior of this class:

Numbered regions with arrows (<--->) stretch along the direction(s) of any arrows present
Bars (|---|) mark the distances specified by the border parameters (left, etc)

Stretch Axes & Border Parameters#

    left                        right
    |------|                 |------|
                                       top
    +------+-----------------+------+  ---
    | (1)  | (2)             | (3)  |   |
    |      | <-------------> |      |   |
    +------+-----------------+------+  ---
    | (4)  | (5)    ^        | (6)  |
    |  ^   |        |        |   ^  |
    |  |   |        |        |   |  |
    |  |   | <------+------> |   |  |
    |  |   |        |        |   |  |
    |  |   |        |        |   |  |
    |  v   |        v        |   v  |
    +------+-----------------+------+  ---
    | (7)  | (8)             | (9)  |   |
    |      | <-------------> |      |   |
    +------+-----------------+------+  ---
                                      bottom

As the texture is stretched, the numbered slices of the texture behave as follows:

Areas (1), (3), (7) and (9) never stretch.
Area (5) stretches both horizontally and vertically.
Areas (2) and (8) only stretch horizontally.
Areas (4) and (6) only stretch vertically.

Parameters:

left – The width of the left border of the 9-patch (in pixels)
right – The width of the right border of the 9-patch (in pixels)
bottom – The height of the bottom border of the 9-patch (in pixels)
top – The height of the top border of the 9-patch (in pixels)
texture – The raw texture to use for the 9-patch
atlas – Specify an atlas other than arcade’s default texture atlas

draw_sized(*, position: Tuple[float, float] = (0.0, 0.0), size: Tuple[float, float], pixelated: bool = False, **kwargs)[source]#

Draw the 9-patch texture with a specific size.

Warning

This method assumes the passed dimensions are proper!

Unexpected behavior may occur if you specify a size smaller than the total size of the border areas.

Parameters:

position – Bottom left offset of the texture in pixels
size – Size of the 9-patch as width, height in pixels
pixelated – Whether to draw with nearest neighbor interpolation

bottom#: Get or set the bottom border of the 9-patch.

ctx#: The OpenGL context.

height#: The height of the texture in pixels.

left#: Get or set the left border of the 9-patch.

program#

Get or set the shader program.

Returns the default shader if no other shader is assigned.

right#: Get or set the right border of the 9-patch.

size#: The size of texture as a width, height tuple in pixels.

texture#: Get or set the texture.

top#: Get or set the top border of the 9-patch.

width#: The width of the texture in pixels.