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, likeUIAnchorWidget
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.
- 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.
- 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:
Apply this surface’s viewport, projection, and blend settings
Allow any rendering to take place
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
- 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 givenarea
. 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.
- limit(rect: Rect | None = None)[source]
Reduces the draw area to the given rect, or resets it to the full 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
- 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 fromView.on_show_view()
andUIManager.disable()
should be called fromView.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.
- disable() None [source]
Remove handler functions (on_…) from
arcade.Window
If every
arcade.View
uses its ownarcade.gui.UIManager
, this method should be called inarcade.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_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_text_motion_select(motion)[source]
Converts text motion select event to UI event and dispatches it.
- 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 ordinaryarcade.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 presentBars (
|---|
) mark the distances specified by the border parameters (left
, etc)
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 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
- 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
oron_show_view
, don’t forget to call super().on_show_view() or super().on_hide_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.