GUI Widgets

class arcade.gui.widgets.FocusMode(value)[source]

Bases: IntEnum

Defines the focus mode of a widget.

0: Not focusable 1: Focusable

We might support different focus modes in the future, but for now on/off is enough.

ALL = 2
NONE = 0
class arcade.gui.widgets.WeakRef[source]

Bases: Generic[P]

A weak reference to a UIWidget parent, which is used to prevent memory leaks.

get(instance: Any) → P | None[source]

Get value for owner instance

name: str

Attribute name of the property

obs: WeakKeyDictionary[Any, ReferenceType[P]]

Weak dictionary to hold the values

set(instance, value: P | None)[source]

Set value for owner instance

class arcade.gui.UIWidget(*, 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: EventDispatcher, ABC

The UIWidget class is the base class required for creating widgets.

We also have some default values and behaviors that you should be aware of:

  • A UIWidget is not a UILayout: it will not change the position or the size of its children. If you want control over positioning or sizing, use a UILayout.

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – width of widget

  • height – height of widget

  • size_hint – Tuple of floats (0.0-1.0), 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

add(child: W, **kwargs) → W[source]

Add a widget as a child.

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.

Parameters:

  • child – widget to add

  • index – position a widget is added, None has the highest priority

Returns:

given child

property bottom: float

Bottom coordinate of the widget

property center: Vec2

Returns center coordinates

center_on_screen() → W[source]

Places this widget in the center of the current window.

This is a convenience method for simple centering of widgets without using a layout.

In general, it is recommended to use layouts for more complex UIs.

property center_x: float

Center x coordinate

property center_y: float

Center y coordinate

property children: list[UIWidget]

Provides all child widgets.

clear()[source]

Removes all children

property content_height: float

Returns the height of the content area, which is the height of the widget minus padding and border.

property content_rect: Rect

Returns the content area as a rect. The content area is the area of the widget minus padding and border.

property content_size: tuple[float, float]

Returns the size of the content area, which is the size of the widget minus padding and border.

property content_width: float

Returns the width of the content area, which is the width of the widget minus padding and border.

dispatch_ui_event(event: UIEvent)[source]

Dispatch a UIEvent using pyglet event dispatch mechanism

do_render(surface: Surface)[source]

Render the widgets graphical representation, use UIWidget.prepare_render() to limit the drawing area to the widgets rect and draw relative to 0,0.

do_render_base(surface: Surface)[source]

Renders background, border and “padding

do_render_focus(surface: Surface)[source]

Render the widgets focus representation overlay`

focus_mode: FocusMode = 0
focused

An observable property which triggers observers when changed.

def log_change(instance, value):
    print("Something changed")

class MyObject:
    name = Property()

my_obj = MyObject()
bind(my_obj, "name", log_change)
unbind(my_obj, "name", log_change)

my_obj.name = "Hans"
# > Something changed

Properties provide a less verbose way to implement the observer pattern in comparison to using the property decorator.

Parameters:

  • default – Default value which is returned, if no value set before

  • default_factory – A callable which returns the default value. Will be called with the property and the instance

get_ui_manager() → UIManager | None[source]

The UIManager this widget is attached to. During creation, this will be None.

property height: float

Height of the widget.

property left: float

Left coordinate of the widget

move(dx=0, dy=0)[source]

Move the widget by dx and dy.

Parameters:

  • dx – x axis difference

  • dy – y axis difference

on_event(event: UIEvent) → bool | None[source]

Passes UIEvent s through the widget tree.

on_update(dt)[source]

Custom logic which will be triggered.

property padding

Returns padding as tuple (top, right, bottom, left)

parent: WeakRef[UIManager | UIWidget | None]

A weak reference to the parent UIManager or UIWidget, which does not prevent garbage collection of the parent.

property position: Vec2

Returns bottom left coordinates

prepare_render(surface)[source]

Helper for rendering, the drawing area will be adjusted to the own position and size. Draw calls have to be relative to 0,0. This will also prevent any overdraw outside of the widgets area

Parameters:

surface – Surface used for rendering

rect

An observable property which triggers observers when changed.

def log_change(instance, value):
    print("Something changed")

class MyObject:
    name = Property()

my_obj = MyObject()
bind(my_obj, "name", log_change)
unbind(my_obj, "name", log_change)

my_obj.name = "Hans"
# > Something changed

Properties provide a less verbose way to implement the observer pattern in comparison to using the property decorator.

Parameters:

  • default – Default value which is returned, if no value set before

  • default_factory – A callable which returns the default value. Will be called with the property and the instance

remove(child: UIWidget) → dict | None[source]

Removes a child from the UIManager which was directly added to it. This will not remove widgets which are added to a child of UIManager.

Returns:

kwargs which were used when child was added

resize(*, width=None, height=None, anchor: Vec2 = (0.5, 0.5))[source]

Resizes the widget.

Parameters:

  • width – new width

  • height – new height

  • anchor – anchor point for resizing, default is center

property right: float

Right coordinate of the widget

scale(factor: float | int, anchor: Vec2 = (0.5, 0.5))[source]

Scales the size of the widget (x,y,width, height) by factor.

Parameters:

  • factor – scale factor

  • anchor – anchor point

property size: Vec2

Size of the widget.

size_hint

An observable property which triggers observers when changed.

def log_change(instance, value):
    print("Something changed")

class MyObject:
    name = Property()

my_obj = MyObject()
bind(my_obj, "name", log_change)
unbind(my_obj, "name", log_change)

my_obj.name = "Hans"
# > Something changed

Properties provide a less verbose way to implement the observer pattern in comparison to using the property decorator.

Parameters:

  • default – Default value which is returned, if no value set before

  • default_factory – A callable which returns the default value. Will be called with the property and the instance

size_hint_max

An observable property which triggers observers when changed.

def log_change(instance, value):
    print("Something changed")

class MyObject:
    name = Property()

my_obj = MyObject()
bind(my_obj, "name", log_change)
unbind(my_obj, "name", log_change)

my_obj.name = "Hans"
# > Something changed

Properties provide a less verbose way to implement the observer pattern in comparison to using the property decorator.

Parameters:

  • default – Default value which is returned, if no value set before

  • default_factory – A callable which returns the default value. Will be called with the property and the instance

size_hint_min

An observable property which triggers observers when changed.

def log_change(instance, value):
    print("Something changed")

class MyObject:
    name = Property()

my_obj = MyObject()
bind(my_obj, "name", log_change)
unbind(my_obj, "name", log_change)

my_obj.name = "Hans"
# > Something changed

Properties provide a less verbose way to implement the observer pattern in comparison to using the property decorator.

Parameters:

  • default – Default value which is returned, if no value set before

  • default_factory – A callable which returns the default value. Will be called with the property and the instance

property top: float

Top coordinate of the widget

trigger_full_render() → None[source]

In case a widget uses transparent areas or was moved, it might be important to request a full rendering of parents

trigger_render()[source]

This will delay a render right before the next frame is rendered, so that UIWidget.do_render() is not called multiple times.

visible

If True, the widget is visible and will be rendered. If None, the widget should also be skipped by layouts.

property width: float

Width of the widget.

with_background(*, color: Color | ellipsis | None = Ellipsis, texture: Texture | NinePatchTexture | ellipsis | None = Ellipsis) → Self[source]

Set widgets background.

A color or texture can be used for background, if a texture is given, start and end point can be added to use the texture as ninepatch.

Parameters:

  • color – A color used as background

  • texture – A texture or ninepatch texture used as background

Returns:

self

with_border(*, width=2, color: Color | None = (128, 128, 128, 255)) → Self[source]

Sets border properties

Parameters:

  • width – border width

  • color – border color

Returns:

self

with_padding(*, top: int | None = None, right: int | None = None, bottom: int | None = None, left: int | None = None, all: int | None = None) → Self[source]

Changes the padding to the given values if set. Returns itself

Returns:

self

class arcade.gui.UIInteractiveWidget(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, size_hint=None, size_hint_min=None, size_hint_max=None, interaction_buttons=(1,), **kwargs)[source]

Bases: UIWidget

Base class for widgets which use mouse interaction (hover, pressed, clicked)

It provides properties for hovered, pressed and disabled states.

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – width of widget

  • height – height of widget

  • size_hint – Tuple of floats (0.0-1.0), 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

  • interaction_buttons – defines, which mouse buttons should trigger the interaction (default: left mouse button)

disabled

True if the widget is disabled

focus_mode: FocusMode = 2
hovered

True if the mouse is over the widget

on_click(event: UIOnClickEvent)[source]

Triggered when the widget is clicked.

on_event(event: UIEvent) → bool | None[source]

Handles mouse events and triggers on_click event if the widget is clicked.

This also sets the hovered and pressed state of the widget.

pressed

True if the widget is pressed

class arcade.gui.UIDummy(*, x=0, y=0, width=100, height=100, size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]

Bases: UIInteractiveWidget

Solid color widget used for testing & examples.

Starts with a random color. It should not be subclassed for real-world usage.

When clicked, it does the following:

  • Outputs its rect attribute to the console

  • Changes its color to a random fully opaque color

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – width of widget

  • height – height of widget

  • size_hint – Tuple of floats (0.0-1.0), 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

  • **kwargs – passed to UIWidget

on_click(event: UIOnClickEvent)[source]

Prints the rect and changes the color

on_update(dt)[source]

Update the border of the widget if hovered

class arcade.gui.UISpriteWidget(*, x=0, y=0, width=100, height=100, sprite: Sprite | None = None, size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]

Bases: UIWidget

Create a UI element with a sprite that controls what is displayed.

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – width of widget

  • height – height of widget

  • sprite – Sprite to embed in gui

  • size_hint – Tuple of floats (0.0-1.0), 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

do_render(surface: Surface)[source]

Render the sprite

on_update(dt)[source]

Pass update event to sprite

class arcade.gui.UILayout(*, 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

Base class for widgets, which position themselves or their children.

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – width of widget

  • height – height of widget

  • children – Child widgets of this group

  • size_hint – Tuple of floats (0.0-1.0), 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

do_layout()[source]
do_layout is triggered by the UIManager before rendering.

UILayout should position their children. Afterward, do_layout of child widgets will be triggered.

Use UIWidget.trigger_render() to trigger a rendering before the next frame, this will happen automatically if the position or size of this widget changed.

static min_size_of(child: UIWidget) → tuple[float, float][source]

Resolves the minimum size of a child. If it has a size_hint set for the axis, it will use size_hint_min if set, otherwise the actual size will be used.

prepare_layout()[source]

Triggered by the UIManager before layouting, UILayout s should prepare themselves based on children.

Prepare layout is triggered on children first.

class arcade.gui.UISpace(*, x=0, y=0, width=1, height=1, color=None, size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]

Bases: UIWidget

Widget reserving space, can also have a background color.

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – width of widget

  • height – height of widget

  • color – Color for widget area, if None, it will be transparent (this will set the background color)

  • size_hint – Tuple of floats (0.0-1.0), 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

  • **kwargs – passed to UIWidget

property color

Color of the widget, alias for background color

class arcade.gui.UITextureButtonStyle(font_size: int = 12, font_name: str | tuple[str, ...] = ('Kenney Future', 'arial', 'calibri'), font_color: tuple[int, int, int, int] = (255, 255, 255, 255))[source]

Bases: UIStyleBase

Used to style the texture button. Below is its use case.

button = UITextureButton(style={"normal": UITextureButton.UIStyle(...),})
font_color: tuple[int, int, int, int] = (255, 255, 255, 255)
font_name: str | tuple[str, ...] = ('Kenney Future', 'arial', 'calibri')
font_size: int = 12
class arcade.gui.UITextureButton(*, x: float = 0, y: float = 0, width: float | None = None, height: float | None = None, texture: None | Texture | NinePatchTexture = None, texture_hovered: None | Texture | NinePatchTexture = None, texture_pressed: None | Texture | NinePatchTexture = None, texture_disabled: None | Texture | NinePatchTexture = None, text: str = '', multiline: bool = False, scale: float | None = None, style: dict[str, UIStyleBase] | None = None, size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]

Bases: UIInteractiveWidget, UIStyledWidget[UITextureButtonStyle], UITextWidget

A button with an image for the face of the button.

There are four states of the UITextureButton i.e.normal, hovered, pressed and disabled.

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – width of widget. Defaults to texture width if not specified.

  • height – height of widget. Defaults to texture height if not specified.

  • texture – texture to display for the widget.

  • texture_hovered – different texture to display if mouse is hovering over button.

  • texture_pressed – different texture to display if mouse button is pressed while hovering over button.

  • text – text to add to the button.

  • multiline – allows to wrap text, if not enough width available

  • style – Used to style the button for different states.

  • scale – scale the button, based on the base texture size.

  • size_hint – Tuple of floats (0.0-1.0), 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

DEFAULT_STYLE = {'disabled': UITextureButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=189, g=195, b=199, a=255)), 'hover': UITextureButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255)), 'normal': UITextureButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255)), 'press': UITextureButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=44, g=62, b=80, a=255))}
UIStyle

alias of UITextureButtonStyle

do_render(surface: Surface)[source]

Render the widgets graphical representation.

get_current_state() → str[source]

Returns the current state of the button i.e.disabled, press, hover or normal.

property texture

Returns the normal texture for the face of the button.

property texture_hovered

Returns the hover texture for the face of the button.

property texture_pressed

Returns the pressed texture for the face of the button.

class arcade.gui.widgets.buttons.UIFlatButtonStyle(font_size: int = 12, font_name: str | tuple[str, ...] = ('Kenney Future', 'arial', 'calibri'), font_color: tuple[int, int, int, int] = (255, 255, 255, 255), bg: tuple[int, int, int, int] = (44, 62, 80, 255), border: tuple[int, int, int, int] | None = None, border_width: int = 0)[source]

Bases: UIStyleBase

Used to style the button. Below is its use case.

button = UIFlatButton(style={"normal": UIFlatButton.UIStyle(...),})
bg: tuple[int, int, int, int] = (44, 62, 80, 255)
border: tuple[int, int, int, int] | None = None
border_width: int = 0
font_color: tuple[int, int, int, int] = (255, 255, 255, 255)
font_name: str | tuple[str, ...] = ('Kenney Future', 'arial', 'calibri')
font_size: int = 12
class arcade.gui.UIFlatButton(*, x: float = 0, y: float = 0, width: float = 100, height: float = 50, text='', multiline=False, size_hint=None, size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

Bases: UIInteractiveWidget, UIStyledWidget[UIFlatButtonStyle], UITextWidget

A text button, with support for background color and a border.

There are four states of the UITextureButton i.e. normal, hovered, pressed and disabled.

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – width of widget. Defaults to texture width if not specified.

  • height – height of widget. Defaults to texture height if not specified.

  • text – text to add to the button.

  • multiline – allows to wrap text, if not enough width available

  • style – Used to style the button

DEFAULT_STYLE = {'disabled': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=189, g=195, b=199, a=255), bg=Color(r=127, g=140, b=141, a=255), border=None, border_width=0), 'hover': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=52, g=73, b=94, a=255), border=Color(r=149, g=165, b=166, a=255), border_width=0), 'normal': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=44, g=62, b=80, a=255), border=None, border_width=0), 'press': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=44, g=62, b=80, a=255), bg=Color(r=236, g=240, b=241, a=255), border=Color(r=149, g=165, b=166, a=255), border_width=0)}
STYLE_BLUE = {'disabled': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=127, g=140, b=141, a=255), border=None, border_width=0), 'hover': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=41, g=128, b=185, a=255), border=Color(r=189, g=195, b=199, a=255), border_width=2), 'normal': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=52, g=152, b=219, a=255), border=None, border_width=0), 'press': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=44, g=62, b=80, a=255), border=Color(r=189, g=195, b=199, a=255), border_width=2)}
STYLE_RED = {'disabled': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=127, g=140, b=141, a=255), border=None, border_width=0), 'hover': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=231, g=76, b=60, a=255), border=Color(r=189, g=195, b=199, a=255), border_width=2), 'normal': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=231, g=76, b=60, a=255), border=Color(r=192, g=57, b=43, a=255), border_width=0), 'press': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=192, g=57, b=43, a=255), border=Color(r=189, g=195, b=199, a=255), border_width=2)}
UIStyle

alias of UIFlatButtonStyle

do_render(surface: Surface)[source]

Render a flat button, graphical representation depends on the current state.

get_current_state() → str[source]

Returns the current state of the button i.e.disabled, press, hover or normal.

class arcade.gui.UIDropdown(*, x: float = 0, y: float = 0, width: float = 150, height: float = 30, default: str | None = None, options: list[str | None] | None = None, primary_style=None, dropdown_style=None, active_style=None, **kwargs)[source]

Bases: UILayout

A dropdown layout. When clicked displays a list of options provided.

Triggers an event when an option is clicked, the event can be read by

dropdown = Dropdown()

@dropdown.event()
def on_change(event: UIOnChangeEvent):
    print(event.old_value, event.new_value)
Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – Width of each of the option.

  • height – Height of each of the option.

  • default – The default value shown.

  • options – The options displayed when the layout is clicked.

  • primary_style – The style of the primary button.

  • dropdown_style – The style of the buttons in the dropdown.

  • active_style – The style of the dropdown button, which represents the active option.

DEFAULT_BUTTON_STYLE = {'disabled': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=189, g=195, b=199, a=255), bg=Color(r=127, g=140, b=141, a=255), border=None, border_width=0), 'hover': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=52, g=73, b=94, a=255), border=Color(r=149, g=165, b=166, a=255), border_width=0), 'normal': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=39, g=174, b=96, a=255), bg=Color(r=44, g=62, b=80, a=255), border=None, border_width=0), 'press': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=44, g=62, b=80, a=255), bg=Color(r=236, g=240, b=241, a=255), border=Color(r=149, g=165, b=166, a=255), border_width=0)}
DEFAULT_DROPDOWN_STYLE = {'disabled': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=189, g=195, b=199, a=255), bg=Color(r=127, g=140, b=141, a=255), border=None, border_width=0), 'hover': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=52, g=73, b=94, a=255), border=Color(r=149, g=165, b=166, a=255), border_width=0), 'normal': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=44, g=62, b=80, a=255), border=None, border_width=0), 'press': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=44, g=62, b=80, a=255), bg=Color(r=236, g=240, b=241, a=255), border=Color(r=149, g=165, b=166, a=255), border_width=0)}
DIVIDER = None
do_layout()[source]

Position the overlay, this is not a common thing to do in do_layout, but is required for the dropdown.

on_change(event: UIOnChangeEvent)[source]

To be implemented by the user, triggered when the current selected value is changed to a different option.

property value: str | None

Current selected option.

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

Bases: UILayout

Places children based on anchor values.

Defaults to size_hint = (1, 1).

Supports the options size_hint, size_hint_min, and size_hint_max. Children are allowed to overlap.

Child are resized based on size_hint. size_hint_min/max only take effect if a size_hint is set.

Allowed keyword options for add():

  • anchor_x: str = None

    Horizontal anchor position for the layout. The class constant default_anchor_x is used as default.

  • anchor_y: str = None

    Vertical anchor position for the layout. The class constant default_anchor_y is used as default.

  • align_x: float = 0

    Horizontal alignment for the layout.

  • align_y: float = 0

    Vertical alignement for the layout.

Parameters:

  • x – x coordinate of the bottom left corner.

  • y – y coordinate of the bottom left corner.

  • width – Width of the layout.

  • height – Height of the layout.

  • children – Initial list of children. More can be added later.

  • size_hint – Size hint for UILayout

  • size_hint_min – Minimum width and height in pixels.

  • size_hint_max – Maximum width and height in pixels.

  • **kwargs – Additional keyword arguments passed to UILayout.

add(child: W, *, anchor_x: str | None = None, align_x: float = 0, anchor_y: str | None = None, align_y: float = 0, **kwargs) → W[source]

Add a widget to the layout as a child. Added widgets will receive all user-interface events and be rendered.

By default, the latest added widget will receive events first and will be rendered on top of others. The widgets will be automatically placed within this widget.

Parameters:

  • child – Specified child widget to add.

  • anchor_x – Horizontal anchor. Valid options are left, right, and center.

  • align_x – Offset or padding for the horizontal anchor.

  • anchor_y – Vertical anchor. Valid options are top, center, and bottom.

  • align_y – Offset or padding for the vertical anchor.

Returns:

Given child that was just added to the layout.

default_anchor_x = 'center'
default_anchor_y = 'center'
do_layout()[source]

Executes the layout algorithm.

Children are placed based on their anchor values.

class arcade.gui.UIBoxLayout(*, x=0, y=0, width=1, height=1, vertical=True, align='center', children: Iterable[UIWidget] = (), size_hint=(0, 0), size_hint_max=None, space_between=0, style=None, **kwargs)[source]

Bases: UILayout

Place widgets next to each other. Depending on the vertical attribute, the widgets are placed top to bottom or left to right.

Hint

UIBoxLayout does not adjust its own size if children are added. This requires a UIManager or a UIAnchorLayout as a parent.

Or use arcade.gui.UIBoxLayout.fit_content() to resize the layout. The bottom-left corner is used as the default anchor point.

Supports the options: size_hint, size_hint_min, size_hint_max. size_hint_min is automatically updated based on the minimal required space by children.

If a child widget provides a size_hint for a dimension, the child will be resized within the given range of size_hint_min and size_hint_max (unrestricted if not given). If the parameter vertical is True, any available space (layout size - min_size of children) will be distributed to the child widgets based on their size_hint.

Parameters:

  • x – x coordinate of the bottom left corner.

  • y – y coordinate of the bottom left corner.

  • vertical – Layout children vertical (True) or horizontal (False).

  • align – Align children in orthogonal direction:: - x: left, center, and right - y: top, center, and bottom

  • children – Initial list of children. More can be added later.

  • size_hint – Size hint for the UILayout if the widget would like to grow. Defaults to 0, 0 -> minimal size to contain children.

  • size_hint_max – Maximum width and height in pixels.

  • space_between – Space in pixels between the children.

add(child: W, **kwargs) → W[source]

Add a widget to this layout

Parameters:

child – The widget to add to the layout.

do_layout()[source]

Executes the layout algorithm.

This method is called by the parent layout to place the children, after the rect was set.

The layout algorithm will place the children based on the size hints next to each other. Depending on the vertical attribute, the children are placed top to bottom or left to right.

fit_content()[source]

Resize the layout to fit the content. This will take the minimal required size into account.

prepare_layout()[source]

Updates the size hints if required.

remove(child: UIWidget)[source]

Remove a child from the layout.

class arcade.gui.UIGridLayout(*, x=0, y=0, width=1, height=1, align_horizontal='center', align_vertical='center', children: Iterable[UIWidget] = (), size_hint=(0, 0), size_hint_max=None, horizontal_spacing: int = 0, vertical_spacing: int = 0, column_count: int = 1, row_count: int = 1, **kwargs)[source]

Bases: UILayout

Arranges each child widget over one or more columns and rows.

The layout’s size_hint requests a target size as a tuple of (x, y) floats as ratios relative to the layout’s parent:

  • The default of (0, 0) requests the minimum possible space

  • (1.0, 1.0) requests the maximum possible space

  • (0.1, 0.1) requests 10% of the layout parent’s total size

Each child widget’s size_hint value will be used to:

  • control its size within the layout

  • automatically re-calculate the layout’s size_hint_min

The width of each column and height of each row will be calculated on update by reading the sizing data of each child widget. For each row/column, the corresponding values along its axis will be read from widgets along its axis:

  • the maximum size_hint_min of its widgets

  • the minimum size_hint_max of its widgets

If any widget lacks size hint data, its “actual” will be used instead. See do_layout() to learn more.

Note

Maximum and minimum size hints only take effect when a size_hint is set.

Parameters:

  • x – x coordinate of bottom left corner.

  • y – y coordinate of bottom left corner.

  • width – Width of the layout.

  • height – Height of the layout.

  • align_horizontal – Align children in along the X axis to the "left", "center", or "right".

  • align_vertical – Align children in along the Y axis to the "top", "center", or "bottom".

  • children – An initial iterable of children. More can be added later.

  • size_hint – A size hint for UILayout, if the UIWidget would like to grow.

  • size_hint_max – Maximum width and height in pixels.

  • horizontal_spacing – Space between columns.

  • vertical_spacing – Space between rows.

  • column_count – Number of columns in the grid. This can be changed later.

  • row_count – Number of rows in the grid. This can be changed later.

add(child: W, column: int = 0, row: int = 0, column_span: int = 1, row_span: int = 1, **kwargs) → W[source]

Add a widget to the grid layout.

Parameters:

  • child – Specified widget to add as a child of the layout.

  • column – Column index in which the widget is to be added. The first column at the left of the widget starts at 0.

  • row – The row number in which the widget is to be added. The first row at the top of the layout is numbered 0.

  • column_span – Number of columns the widget will stretch for.

  • row_span – Number of rows the widget will stretch for.

do_layout()[source]

Arrange children in the grid based on their size hints.

Algorithm

  1. Generate lists of child widgets for each row and column

  2. For each column, calculate the following values:

    • If a widget lacks size hints, substitute the “actual” width instead

    • The max() of all its child size_hint_min[0] values

    • The max() of all its child size_hint[0] values

  3. For each row, calculate the following values:

    • If a widget lacks size hints, substitute the “actual” height instead

    • The max() of all its child size_hint_min[1] values

    • The max() of all its child size_hint[1] values

  4. Use box layout algorithm to allocate on-screen space

  5. Re-size and place the widgets to match the calculated grid layout

prepare_layout()[source]

Updates the size hints if required.

remove(child: UIWidget)[source]

Remove a child from the layout.

class arcade.gui.UIBaseSlider(*, value: float = 0, min_value: float = 0, max_value: float = 100, x: float = 0, y: float = 0, width: float = 300, height: float = 20, size_hint=None, size_hint_min=None, size_hint_max=None, style: Mapping[str, UISliderStyle] | None = None, step: float | None = None, **kwargs)[source]

Bases: UIInteractiveWidget

Base class for sliders.

A slider contains of a horizontal track and a thumb. The thumb can be moved along the track to set the value of the slider.

Use the on_change event to get notified about value changes.

Subclasses should implement the _render_track and _render_thumb methods.

Parameters:

  • value – Current value of the curosr of the slider.

  • min_value – Minimum value of the slider.

  • max_value – Maximum value of the slider.

  • x – x coordinate of bottom left.

  • y – y coordinate of bottom left.

  • width – Width of the slider.

  • height – Height of the slider.

  • size_hint – Size hint of the slider.

  • size_hint_min – Minimum size hint of the slider.

  • size_hint_max – Maximum size hint of the slider.

  • style – Used to style the slider for different states.

  • step – Smallest change the slider value can move by.

  • **kwargs – Passed to UIInteractiveWidget.

do_render(surface: Surface)[source]

Render the slider, including track and thumb.

property norm_value

Normalized value between 0.0 and 1.0

on_change(event: UIOnChangeEvent)[source]

To be implemented by the user, triggered when the cursor’s value is changed.

Parameters:

event – Event containing the old and new value of the cursor.

on_click(event: UIOnClickEvent)[source]

Handle click events to set the value of the slider.

A new value is calculated based on the click position and the slider’s width and the on_change event is dispatched.

Parameters:

event – Click event.

on_event(event: UIEvent) → bool | None[source]
Parameters:

event – Event to handle.

Returns: True if event was handled, False otherwise.

value

An observable property which triggers observers when changed.

def log_change(instance, value):
    print("Something changed")

class MyObject:
    name = Property()

my_obj = MyObject()
bind(my_obj, "name", log_change)
unbind(my_obj, "name", log_change)

my_obj.name = "Hans"
# > Something changed

Properties provide a less verbose way to implement the observer pattern in comparison to using the property decorator.

Parameters:

  • default – Default value which is returned, if no value set before

  • default_factory – A callable which returns the default value. Will be called with the property and the instance

class arcade.gui.UISliderStyle(bg: tuple[int, int, int, int] = (189, 195, 199, 255), border: tuple[int, int, int, int] = (44, 62, 80, 255), border_width: int = 2, filled_track: tuple[int, int, int, int] = (44, 62, 80, 255), filled_step: tuple[int, int, int, int] | None = (52, 152, 219, 255), unfilled_track: tuple[int, int, int, int] = (189, 195, 199, 255), unfilled_step: tuple[int, int, int, int] | None = (52, 152, 219, 255))[source]

Bases: UIStyleBase

Used to style the slider for different states. Below is its use case.

button = UITextureButton(style={"normal": UITextureButton.UIStyle(...),})
Parameters:

  • bg – Background color.

  • border – Border color.

  • border_width – Width of the border.

  • filled_track – Color of the filled track.

  • filled_step – Color of the step in filled area.

  • unfilled_track – Color of the unfilled track.

  • unfilled_step – Color of the step in unfilled area.

bg: tuple[int, int, int, int] = (189, 195, 199, 255)
border: tuple[int, int, int, int] = (44, 62, 80, 255)
border_width: int = 2
filled_step: tuple[int, int, int, int] | None = (52, 152, 219, 255)
filled_track: tuple[int, int, int, int] = (44, 62, 80, 255)
unfilled_step: tuple[int, int, int, int] | None = (52, 152, 219, 255)
unfilled_track: tuple[int, int, int, int] = (189, 195, 199, 255)
class arcade.gui.UISlider(*, value: float = 0, min_value: float = 0, max_value: float = 100, x: float = 0, y: float = 0, width: float = 300, height: float = 25, size_hint=None, size_hint_min=None, size_hint_max=None, style: dict[str, UISliderStyle] | None = None, step: float | None = None, **kwargs)[source]

Bases: UIStyledWidget[UISliderStyle], UIBaseSlider

A simple slider.

A slider consists of a horizontal track and a thumb. The thumb can be moved along the track to set the value of the slider.

Use the on_change event to get notified about value changes.

There are four states of the UISlider i.e. normal, hovered, pressed and disabled.

Parameters:

  • value – Current value of the cursor of the slider.

  • min_value – Minimum value of the slider.

  • max_value – Maximum value of the slider.

  • x – x coordinate of bottom left.

  • y – y coordinate of bottom left.

  • width – Width of the slider.

  • height – Height of the slider.

  • style – Used to style the slider for different states.

  • step – Smallest change the slider value can move by.

DEFAULT_STYLE = {'disabled': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=44, g=62, b=80, a=255), border_width=1, filled_track=Color(r=127, g=140, b=141, a=255), filled_step=Color(r=52, g=152, b=219, a=255), unfilled_track=Color(r=189, g=195, b=199, a=255), unfilled_step=Color(r=52, g=152, b=219, a=255)), 'hover': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=52, g=152, b=219, a=255), border_width=2, filled_track=Color(r=52, g=152, b=219, a=255), filled_step=Color(r=44, g=62, b=80, a=255), unfilled_track=Color(r=189, g=195, b=199, a=255), unfilled_step=Color(r=52, g=152, b=219, a=255)), 'normal': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=44, g=62, b=80, a=255), border_width=2, filled_track=Color(r=44, g=62, b=80, a=255), filled_step=Color(r=52, g=152, b=219, a=255), unfilled_track=Color(r=189, g=195, b=199, a=255), unfilled_step=Color(r=52, g=152, b=219, a=255)), 'press': UISliderStyle(bg=Color(r=52, g=152, b=219, a=255), border=Color(r=52, g=73, b=94, a=255), border_width=3, filled_track=Color(r=52, g=152, b=219, a=255), filled_step=Color(r=44, g=62, b=80, a=255), unfilled_track=Color(r=189, g=195, b=199, a=255), unfilled_step=Color(r=52, g=152, b=219, a=255))}
NO_STEP_STYLE = {'disabled': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=44, g=62, b=80, a=255), border_width=1, filled_track=Color(r=127, g=140, b=141, a=255), filled_step=None, unfilled_track=Color(r=189, g=195, b=199, a=255), unfilled_step=None), 'hover': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=52, g=152, b=219, a=255), border_width=2, filled_track=Color(r=52, g=152, b=219, a=255), filled_step=None, unfilled_track=Color(r=189, g=195, b=199, a=255), unfilled_step=None), 'normal': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=44, g=62, b=80, a=255), border_width=2, filled_track=Color(r=44, g=62, b=80, a=255), filled_step=None, unfilled_track=Color(r=189, g=195, b=199, a=255), unfilled_step=None), 'press': UISliderStyle(bg=Color(r=52, g=152, b=219, a=255), border=Color(r=52, g=73, b=94, a=255), border_width=3, filled_track=Color(r=52, g=152, b=219, a=255), filled_step=None, unfilled_track=Color(r=189, g=195, b=199, a=255), unfilled_step=None)}

Removing the step colors from the style. So sliders with a step value do not show the steps visually.

UIStyle

alias of UISliderStyle

get_current_state() → str[source]

Get the current state of the slider.

Returns:

“”normal””, “”hover””, “”press”” or “”disabled””.

class arcade.gui.UITextureSlider(track_texture: Texture | NinePatchTexture, thumb_texture: Texture | NinePatchTexture, style=None, **kwargs)[source]

Bases: UISlider

A custom slider subclass which supports textures.

You can copy this as-is into your own project, or you can modify the class to have more features as needed.

Parameters:

  • track_texture – Texture for the track, should be a NinePatchTexture.

  • thumb_texture – Texture for the thumb.

  • style – Used to style the slider for different states.

  • **kwargs – Passed to UISlider.

class arcade.gui.UILabel(text: str = '', *, x: float = 0, y: float = 0, width: float | None = None, height: float | None = None, font_name=('calibri', 'arial'), font_size: float = 12, text_color: tuple[int, int, int] | tuple[int, int, int, int] = (255, 255, 255, 255), bold: str | bool = False, italic=False, align='left', multiline: bool = False, size_hint=(0, 0), size_hint_max=None, **kwargs)[source]

Bases: UIWidget

A simple text label. This widget is meant to display user instructions or information. This label supports multiline text.

If you want to make a scrollable viewing text box, use a UITextArea.

By default, a label will fit its initial content. If the text is changed use fit_content() to adjust the size.

If the text changes frequently, ensure to set a background color or texture, which will prevent a full rendering of the whole UI and only render the label itself.

Parameters:

  • text – Text displayed on the label.

  • x – x position (default anchor is bottom-left).

  • y – y position (default anchor is bottom-left).

  • width – Width of the label. Defaults to text width if not specified. See content_width().

  • height – Height of the label. Defaults to text height if not specified. See content_height().

  • font_name – A list of fonts to use. Arcade will start at the beginning of the tuple and keep trying to load fonts until success.

  • font_size – Font size of font.

  • text_color – Color of the text.

  • bold – If enabled, the label’s text will be in a bold style.

  • italic – If enabled, the label’s text will be in an italic style.

  • stretch – Stretch font style.

  • align – Horizontal alignment of text on a line. This only applies if a width is supplied. Valid options include "left", "center" or "right".

  • dpi – Resolution of the fonts in the layout. Defaults to 96.

  • multiline – If enabled, a \n will start a new line. Changing text or font will require a manual call of fit_content() to prevent text line wrap.

  • size_hint – A tuple of floats between 0 and 1 defining the amount of space of the parent should be requested. Default (0, 0) which fits the content.

  • size_hint_max – Maximum size hint width and height in pixel.

ADAPTIVE_MULTILINE_WIDTH = 999999
property bold: bool | str

Return if the label is in bold style. Use update_font() to change.

do_render(surface: Surface)[source]

Render the label via py:class:~arcade.Text.

fit_content()[source]

Manually set the width and height of the label to contain the whole text. Based on the size_hint_min.

If multiline is enabled, the width will be calculated based on longest line of the text. And size_hint_min will be updated.

property font_color: Color

Font color of the label. Use update_font() to change.

property font_name: str | tuple[str, ...]

Font name of the label. Use update_font() to change.

property font_size: float

Font size of the label. Use update_font() to change.

property italic: bool | str

Return if the label is in italic style. Use update_font() to change.

property multiline: bool

Return if the label is in multiline mode.

property text

Text of the label.

update_font(font_name: str | tuple[str, ...] | None = None, font_size: float | None = None, font_color: Color | None = None, bold: bool | str | None = None, italic: bool | None = None)[source]

Update font of the label.

Parameters:

  • font_name – A list of fonts to use. Arcade will start at the beginning of the tuple and keep trying to load fonts until success.

  • font_size – Font size of font.

  • font_color – Color of the text.

  • bold – May be any value in pyglet.text.Weight, True (converts to "bold"), or False (converts to "regular").

  • italic – If enabled, the label’s text will be in an italic

class arcade.gui.UITextWidget(*, text: str, multiline: bool = False, **kwargs)[source]

Bases: UIAnchorLayout

Adds the ability to add text to a widget. Use this to create subclass widgets, which have text.

The text can be placed within the widget using UIAnchorLayout parameters with place_text().

The widget holds reference to one primary UILabel, which is placed in the widget’s layout. This label can be accessed via ui_label.

To change font, font size, or text color, use py:meth:~arcade.gui.UILabel.update_font.

Parameters:

  • text – Text displayed on the label.

  • multiline – If enabled, a \n will start a new line.

  • **kwargs – passed to UIWidget.

property multiline

Get or set the multiline mode.

Newline characters ("\n") will only be honored when this is set to True. If you want a scrollable text widget, please use UITextArea instead.

place_text(anchor_x: str | None = None, align_x: float = 0, anchor_y: str | None = None, align_y: float = 0, **kwargs) → UILabel[source]

Place widget’s text within the widget using UIAnchorLayout parameters.

Parameters:

  • anchor_x – Horizontal anchor. Valid options are left, right, and center.

  • align_x – Offset or padding for the horizontal anchor.

  • anchor_y – Vertical anchor. Valid options are top, center, and bottom.

  • align_y – Offset or padding for the vertical anchor.

  • **kwargs – Additional keyword arguments passed to the layout function.

property text

Text of the widget. Modifying this repeatedly will cause significant lag; calculating glyph position is very expensive.

property ui_label: UILabel

Internal py:class:~arcade.gui.UILabel used for rendering the text.

class arcade.gui.widgets.text.UIInputTextStyle(bg: tuple[int, int, int, int] | None = None, border: tuple[int, int, int, int] | None = (255, 255, 255, 255), border_width: int = 2)[source]

Bases: UIStyleBase

Used to style the UITextWidget for different states. Below is its use case.

button = UIInputText(style={"normal": UIInputText.UIStyle(...),})
Parameters:

  • bg – Background color.

  • border – Border color.

  • border_width – Width of the border.

bg: tuple[int, int, int, int] | None = None
border: tuple[int, int, int, int] | None = (255, 255, 255, 255)
border_width: int = 2
class arcade.gui.UIInputText(*, x: float = 0, y: float = 0, width: float = 100, height: float = 25, text: str = '', font_name=('Arial',), font_size: float = 12, text_color: tuple[int, int, int] | tuple[int, int, int, int] = (255, 255, 255, 255), multiline=False, caret_color: tuple[int, int, int] | tuple[int, int, int, int] = (255, 255, 255, 255), border_color: Color | None = (255, 255, 255, 255), border_width: int = 2, size_hint=None, size_hint_min=None, size_hint_max=None, style: dict[str, UIInputTextStyle] | None = None, **kwargs)[source]

Bases: UIStyledWidget[UIInputTextStyle], UIInteractiveWidget

An input field the user can type text into.

This is useful in returning string input from the user. A caret is displayed, which the user can move around with a mouse or keyboard.

A mouse drag selects text, a mouse press moves the caret, and keys can move around the caret. Arcade confirms that the field is active before allowing users to type, so it is okay to have multiple of these.

By default, a border is drawn around the input field.

The widget emits a UIOnChangeEvent event when the text changes.

Parameters:

  • x – x position (default anchor is bottom-left).

  • y – y position (default anchor is bottom-left).

  • width – Width of the text field.

  • height – Height of the text field.

  • text – Initial text displayed. This can be modified later programmatically or by the user’s interaction with the caret.

  • font_name – A list of fonts to use. Arcade will start at the beginning of the tuple and keep trying to load fonts until success.

  • font_size – Font size of font.

  • text_color – Color of the text.

  • multiline – If enabled, a \n will start a new line. A UITextWidget multiline of True is the same thing as a UITextArea.

  • caret_color – An RGBA or RGB color for the caret with each channel between 0 and 255, inclusive.

  • size_hint – A tuple of floats between 0 and 1 defining the amount of space of the parent should be requested.

  • size_hint_min – Minimum size hint width and height in pixel.

  • size_hint_max – Maximum size hint width and height in pixel.

  • **kwargs – passed to UIWidget.

DEFAULT_STYLE = {'disabled': UIInputTextStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=255, g=255, b=255, a=255), border_width=2), 'hover': UIInputTextStyle(bg=None, border=Color(r=236, g=240, b=241, a=255), border_width=2), 'invalid': UIInputTextStyle(bg=Color(r=231, g=76, b=60, a=42), border=Color(r=231, g=76, b=60, a=255), border_width=2), 'normal': UIInputTextStyle(bg=None, border=Color(r=255, g=255, b=255, a=255), border_width=2), 'press': UIInputTextStyle(bg=None, border=Color(r=189, g=195, b=199, a=255), border_width=2)}
LAYOUT_OFFSET = 1
UIStyle

alias of UIInputTextStyle

activate()[source]

Programmatically activate the text input field.

property active: bool

Return if the text input field is active.

An active text input field will show a caret and accept text input.

deactivate()[source]

Programmatically deactivate the text input field.

do_render(surface: Surface)[source]

Render the text input field.

get_current_state() → str[source]

Get the current state of the slider.

Returns:

“”normal””, “”hover””, “”press”” or “”disabled””.

invalid

An observable property which triggers observers when changed.

def log_change(instance, value):
    print("Something changed")

class MyObject:
    name = Property()

my_obj = MyObject()
bind(my_obj, "name", log_change)
unbind(my_obj, "name", log_change)

my_obj.name = "Hans"
# > Something changed

Properties provide a less verbose way to implement the observer pattern in comparison to using the property decorator.

Parameters:

  • default – Default value which is returned, if no value set before

  • default_factory – A callable which returns the default value. Will be called with the property and the instance

on_change(event: UIOnChangeEvent)[source]

Event handler for text change.

on_click(event: UIOnClickEvent)[source]
on_event(event: UIEvent) → bool | None[source]

Handle events for the text input field.

Text input is only active when the user clicks on the input field.

on_update(dt)[source]

Update the caret blink state.

property text

Text of the input field.

class arcade.gui.UITextArea(*, x: float = 0, y: float = 0, width: float = 400, height: float = 40, text: str = '', font_name=('arial', 'calibri'), font_size: float = 12, bold=False, italic=False, text_color: tuple[int, int, int, int] = (255, 255, 255, 255), multiline: bool = True, scroll_speed: float | None = None, size_hint=None, size_hint_min=None, size_hint_max=None, document_mode: Literal['PLAIN', 'ATTRIBUTED', 'HTML'] = 'PLAIN', **kwargs)[source]

Bases: UIWidget

A text area that allows users to view large documents of text by scrolling the mouse.

Parameters:

  • x – x position (default anchor is bottom-left).

  • y – y position (default anchor is bottom-left).

  • width – Width of the text area.

  • height – Height of the text area.

  • text – Initial text displayed.

  • font_name – A list of fonts to use. Arcade will start at the beginning of the tuple and keep trying to load fonts until success.

  • font_size – Font size of font.

  • text_color – Color of the text.

  • bold – If enabled, the label’s text will be in a bold style.

  • italic – If enabled, the label’s text will be in an italic

  • multiline – If enabled, a \n will start a new line.

  • scroll_speed – Speed of mouse scrolling.

  • size_hint – A tuple of floats between 0 and 1 defining the amount of space of the parent should be requested.

  • size_hint_min – Minimum size hint width and height in pixel.

  • size_hint_max – Maximum size hint width and height in pixel.

  • document_mode – Mode of the document. Can be “PLAIN”, “ATTRIBUTED”, or “HTML”. PLAIN will decode the text as plain text, ATTRIBUTED and HTML will decode the text as pyglet documents here https://pyglet.readthedocs.io/en/latest/programming_guide/text.html

  • **kwargs – passed to UIWidget.

do_render(surface: Surface)[source]

Render the text area.

fit_content()[source]

Set the width and height of the text area to contain the whole text.

on_event(event: UIEvent) → bool | None[source]

Handle scrolling of the widget.

property text

Text of the text area.

class arcade.gui.UITextureToggle(*, x: float = 0, y: float = 0, width: float = 100, height: float = 50, on_texture: Texture | None = None, off_texture: Texture | None = None, value=False, size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]

Bases: UIInteractiveWidget

A toggle button switching between on (True) and off (False) state.

on_texture and off_texture are required. State dependent textures are generated by changing the brightness (hover, press) of the provided textures or converting them to grayscale (disabled).

Parameters:

  • x – x coordinate of bottom left

  • y – y coordinate of bottom left

  • width – Width of the button.

  • height – Height of the button.

  • on_texture – Texture to show when the button is on.

  • off_texture – Texture to show when the button is off.

  • value – Initial value of the button.

  • size_hint – Size hint for the layout.

  • size_hint_min – Minimum size hint for the layout.

  • size_hint_max – Maximum size hint for the layout.

do_render(surface: Surface)[source]

Render the button, using texture depending on the state.

on_change(event: UIOnChangeEvent)[source]

To be implemented by the user, triggered when the cursor’s value is changed.

Parameters:

event – Event containing the old and new value of the cursor.

on_click(event: UIOnClickEvent)[source]

Change the value of the button on click.

value

An observable property which triggers observers when changed.

def log_change(instance, value):
    print("Something changed")

class MyObject:
    name = Property()

my_obj = MyObject()
bind(my_obj, "name", log_change)
unbind(my_obj, "name", log_change)

my_obj.name = "Hans"
# > Something changed

Properties provide a less verbose way to implement the observer pattern in comparison to using the property decorator.

Parameters:

  • default – Default value which is returned, if no value set before

  • default_factory – A callable which returns the default value. Will be called with the property and the instance

class arcade.gui.UIImage(*, texture: Texture | NinePatchTexture, width: float | None = None, height: float | None = None, angle: int = 0, alpha: int = 255, **kwargs)[source]

Bases: UIWidget

UIWidget showing a texture.

If no size given, the texture size is used.

The UIImage supports rotation and alpha values, which only apply to the texture. Border, and background color are not affected by this. The size of the image is reduced when rotated to stay within bounce of the widget.

Parameters:

  • texture – Texture to show

  • width – width of widget

  • height – height of widget

  • angle – angle of the texture in degrees

  • alpha – alpha value of the texture, value between 0 and 255

  • **kwargs – passed to UIWidget

alpha

Alpha value of the texture, value between 0 and 255. 0 is fully transparent, 255 is fully visible.

angle

Angle of the texture in degrees. The image will be rotated around its center and fitted into the widget size.

do_render(surface: Surface)[source]

Render the stored texture in the size of the widget.

texture

Texture to show