GUI

class arcade.gui.UIMessageBox(*, width: float, height: float, message_text: str, title: str | None = None, 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.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, button_factory: type = <class 'arcade.gui.widgets.buttons.UIFlatButton'>, **kwargs)[source]

Bases: UIBoxLayout

Places buttons in a row.

Parameters:
  • vertical – Whether the button row is vertical or not.

  • align – Where to align the button row.

  • size_hint – Tuple of floats (0.0 - 1.0) of how much space of the parent should be requested.

  • size_hint_min – Min width and height in pixel.

  • size_hint_max – Max width and height in pixel.

  • space_between – The space between the children.

  • callback – The callback function which will receive the text of the clicked button.

  • button_factory – The factory to create the buttons. Default is py:class:UIFlatButton.

  • **kwargs – Passed to UIBoxLayout

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

Add a button to the row.

Parameters:
  • label – The text of the button.

  • style – The style of the button.

  • multiline – Whether the button is multiline or not.

  • **kwargs – Passed to the button factory.

on_action(event: UIOnActionEvent)[source]

Called when button was pressed, override this method to handle button presses.

class arcade.gui.UIDraggableMixin(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, children: Iterable[UIWidget] = (), size_hint: Tuple[float | None, float | None] | None = None, size_hint_min: Tuple[float | None, float | None] | None = None, size_hint_max: Tuple[float | None, float | None] | None = 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 behavior which position themselves, like UIAnchorWidget

Warning

This mixin in its current form is not recommended for production use. It is a quick way to get a draggable window like widget. It does not respect the layout system and can break other widgets which rely on the layout system.

Further the dragging is not smooth, as it uses a very simple approach.

Will be fixed in future versions, but might break existing code within a minor update.

do_layout()[source]
on_event(event) bool | None[source]

Handle dragging of the widget.

class arcade.gui.UIMouseFilterMixin(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, children: Iterable[UIWidget] = (), size_hint: Tuple[float | None, float | None] | None = None, size_hint_min: Tuple[float | None, float | None] | None = None, size_hint_max: Tuple[float | None, float | None] | None = 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]

Catch all mouse events, that are inside this widget.

class arcade.gui.UIWindowLikeMixin(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, children: Iterable[UIWidget] = (), size_hint: Tuple[float | None, float | None] | None = None, size_hint_min: Tuple[float | None, float | None] | None = None, size_hint_max: Tuple[float | None, float | None] | None = 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:

Internal abstraction for widget rendering.

Holds a arcade.gl.Framebuffer and provides helper methods and properties for drawing to it.

Parameters:
  • size – The size of the surface in window coordinates

  • position – The position of the surface in window

  • pixel_ratio – The pixel scale of the window

activate() Generator[Self, None, None][source]

Context manager for rendering safely to this Surface.

It does the following:

  1. Apply this surface’s viewport, projection, and blend settings

  2. Allow any rendering to take place

  3. Restore the old OpenGL context settings

Use it in with blocks like other managers:

with surface.activate():
    # draw stuff here
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

clear(color: tuple[int, int, int, int] = (0, 0, 0, 0))[source]

Clear the surface

draw(area: Rect | 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 (l, b, w, h)

draw_sprite(x: float, y: float, width: float, height: float, sprite: Sprite)[source]

Draw a sprite to the surface

Parameters:
  • x – The x coordinate of the sprite.

  • y – The y coordinate of the sprite.

  • width – The width of the sprite.

  • height – The height of the sprite.

  • sprite – The sprite to draw.

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

Draw a texture to the surface.

Parameters:
  • x – The x coordinate of the texture.

  • y – The y coordinate of the texture.

  • width – The width of the texture.

  • height – The height of the texture.

  • tex – The texture to draw, also supports NinePatchTexture.

  • angle – The angle of the texture.

  • alpha – The alpha value of the texture.

property height: int

Height of the surface

limit(rect: Rect | None = None)[source]

Reduces the draw area to the given rect, or resets it to the full surface.

property pixel_ratio: float

The pixel ratio of the surface

property position: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3

Get or set the surface position

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

property size

Size of the surface in window coordinates

property size_scaled

The physical size of the buffer

to_image() Image[source]

Convert the surface to an PIL image

property width: int

Width of the surface

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

window – The window to bind the UIManager to, if None the current window is used.

OVERLAY_LAYER = 10
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

adjust_mouse_coordinates(x: float, y: float) tuple[float, float][source]

This method is used, to translate mouse coordinates to coordinates respecting the viewport and projection of cameras.

It uses the internal camera’s map_coordinate methods, and should work with all transformations possible with the basic orthographic camera.

clear()[source]

Remove all widgets from UIManager

debug()[source]

Walks through all widgets of a UIManager and prints out layout information.

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: UIEvent)[source]

Dispatch a UI event to all widgets in the UIManager, by triggering py:meth:on_event().

Parameters:

event – The event to dispatch.

draw() None[source]

Will draw all widgets to the window.

UIManager caches all rendered widgets into a framebuffer (something like a window sized image) and only updates the framebuffer if a widget requests rendering via trigger_render().

To ensure that the children are positioned properly, a layout process is executed before rendering, changes might also trigger a re-rendering of all widgets.

Layouting is a two-step process: 1. Prepare layout, which prepares children and updates own values 2. Do layout, which actually sets the position and size of the children

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

execute_layout()[source]

Execute layout process for all widgets.

This is automatically called during UIManager.draw().

get_widgets_at(pos: tuple[float | int, float | int] | ~pyglet.math.Vec2, cls: 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]

Forwards an event to all widgets in the UIManager.

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

Converts key press event to UI event and dispatches it.

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

Converts key release event to UI event and dispatches it.

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

Converts mouse drag event to UI event and dispatches it.

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

Converts mouse motion event to UI event and dispatches it.

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

Converts mouse press event to UI event and dispatches it.

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

Converts mouse release event to UI event and dispatches it.

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

Converts mouse scroll event to UI event and dispatches it.

on_resize(width, height)[source]

Resize the UIManager and all of its surfaces.

on_text(text)[source]

Converts text event to UI event and dispatches it.

on_text_motion(motion)[source]

Converts text motion event to UI event and dispatches it.

on_text_motion_select(motion)[source]

Converts text motion select event to UI event and dispatches it.

on_update(time_delta)[source]

Dispatches an update event to all widgets in the UIManager.

property rect: Rect

The rect of the UIManager, which is the window size.

remove(child: UIWidget)[source]

Removes the given widget from UIManager.

Parameters:

child – widget to remove

trigger_render()[source]

Request rendering of all widgets before next draw

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

class arcade.gui.NinePatchTexture(left: int, right: int, bottom: int, top: int, texture: Texture, *, atlas: DefaultTextureAtlas | 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

property bottom: int

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

property ctx: ArcadeContext

The OpenGL context.

draw_rect(*, rect: Rect, pixelated: bool = True, blend: bool = True, **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:
  • rect – Rectangle to draw the 9-patch texture in

  • pixelated – Whether to draw with nearest neighbor interpolation

property height: int

The height of the texture in pixels.

property left: int

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

property program: Program

Get or set the shader program.

Returns the default shader if no other shader is assigned.

property right: int

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

property size: tuple[int, int]

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

property texture: Texture

Get or set the texture.

property top: int

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

property width: int

The width of the texture in pixels.

class arcade.gui.UIView[source]

Bases: View

This view provides basic GUI setup.

This is a convenience class, which adds the UIManager to the view under self.ui. The UIManager is enabled when the view is shown and disabled when the view is hidden.

This class provides two draw callbacks: on_draw_before_ui and on_draw_after_ui. Use these to draw custom elements before or after the UI elements are drawn.

The screen is cleared before on_draw_before_ui is called with the background color of the window.

If you override on_show_view or on_show_view, don’t forget to call super().on_show_view() or super().on_hide_view().

add_widget(widget: W) W[source]

Add a widget to the UIManager of this view.

on_draw()[source]

To subclass UIView and add custom drawing, override on_draw_before_ui and on_draw_after_ui.

on_draw_after_ui()[source]

Use this method to draw custom elements after the UI elements are drawn.

on_draw_before_ui()[source]

Use this method to draw custom elements before the UI elements are drawn.

on_hide_view()[source]

If subclassing UIView, don’t forget to call super().on_hide_view().

on_show_view()[source]

If subclassing UIView, don’t forget to call super().on_show_view().