GUI Widgets#

class arcade.gui.UIImage(*, texture: Texture | NinePatchTexture, **kwargs)[source]#

Bases: UIWidget

UIWidget showing a texture.

do_render(surface: Surface)[source]#

texture: Texture | NinePatchTexture#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

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, **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.

do_render(surface: Surface)[source]#

on_change(event: UIOnChangeEvent)[source]#: To be implemented by the user, triggered when the cursor’s value is changed.

on_click(event: UIOnClickEvent)[source]#

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

norm_value#: Normalized value between 0.0 and 1.0

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

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 = 20, size_hint=None, size_hint_min=None, size_hint_max=None, style: Mapping[str, UISliderStyle] | None = None, **kwargs)[source]#

Bases: UIStyledWidget[UISliderStyle], UIBaseSlider

A simple slider.

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.

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

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.
style (Mapping[str, "UISlider.UIStyle"] | None) – Used to style the slider for different states.

UIStyle#: alias of UISliderStyle

get_current_state() → str[source]#: Returns the current state of the slider i.e disabled, press, hover or normal.

DEFAULT_STYLE = {'disabled': UISliderStyle(bg=Color(r=94, g=104, b=117, a=255), border=Color(r=77, g=81, b=87, a=255), border_width=1, filled_track=Color(r=50, g=50, b=50, a=255), unfilled_track=Color(r=116, g=125, b=123, a=255)), 'hover': UISliderStyle(bg=Color(r=96, g=103, b=112, a=255), border=Color(r=77, g=81, b=87, a=255), border_width=2, filled_track=Color(r=50, g=50, b=50, a=255), unfilled_track=Color(r=116, g=125, b=123, a=255)), 'normal': UISliderStyle(bg=Color(r=94, g=104, b=117, a=255), border=Color(r=77, g=81, b=87, a=255), border_width=1, filled_track=Color(r=50, g=50, b=50, a=255), unfilled_track=Color(r=116, g=125, b=123, a=255)), 'press': UISliderStyle(bg=Color(r=96, g=103, b=112, a=255), border=Color(r=77, g=81, b=87, a=255), border_width=3, filled_track=Color(r=50, g=50, b=50, a=255), unfilled_track=Color(r=116, g=125, b=123, a=255))}#

parent: UIManager | UIWidget | None#

class arcade.gui.UISliderStyle(bg: Tuple[int, int, int, int] = (94, 104, 117, 255), border: Tuple[int, int, int, int] = (77, 81, 87, 255), border_width: int = 1, filled_track: Tuple[int, int, int, int] = (50, 50, 50, 255), unfilled_track: Tuple[int, int, int, int] = (116, 125, 123, 255))[source]#

Bases: UIStyleBase

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

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

bg: Tuple[int, int, int, int] = (94, 104, 117, 255)#

border: Tuple[int, int, int, int] = (77, 81, 87, 255)#

border_width: int = 1#

filled_track: Tuple[int, int, int, int] = (50, 50, 50, 255)#

unfilled_track: Tuple[int, int, int, int] = (116, 125, 123, 255)#

class arcade.gui.UITextureSlider(track: Texture | NinePatchTexture, thumb: 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.

parent: UIManager | UIWidget | None#

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.

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.

do_layout()[source]#

default_anchor_x = 'center'#

default_anchor_y = 'center'#

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]#

do_layout()[source]#

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]#

class arcade.gui.UIGridLayout(*, x=0, y=0, 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, style=None, **kwargs)[source]#

Bases: UILayout

Place widgets in a grid layout. This is similar to tkinter’s grid layout geometry manager.

Defaults to size_hint = (0, 0).

Supports the options size_hint, size_hint_min, and size_hint_max.

Children are resized based on size_hint. Maximum and minimum size_hint``s only take effect if a ``size_hint is given. size_hint_min is automatically updated based on the minimal required space by children.

Parameters:

x – x coordinate of bottom left corner.
y – y coordinate of bottom left corner.
align_horizontal – Align children in orthogonal direction. Options include left, center, and right.
align_vertical – Align children in orthogonal direction. Options include top, center, and bottom.
children – Initial list 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, col_num: int = 0, row_num: int = 0, col_span: int = 1, row_span: int = 1, **kwargs) → W[source]#

Add a widget to the grid layout.

Parameters:

child – Specified child widget to add.
col_num – Column index in which the widget is to be added. The first column is numbered 0; which is the top left corner.
row_num – The row number in which the widget is to be added. The first row is numbered 0; which is the
col_span – Number of columns the widget will stretch for.
row_span – Number of rows the widget will stretch for.

do_layout()[source]#

prepare_layout()[source]#: Updates the size hints if required.

remove(child: UIWidget)[source]#

class arcade.gui.UIDropdown(*, x: float = 0, y: float = 0, width: float = 100, height: float = 20, default: str | None = None, options: List[str | None] | None = None, 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.
style – Used to style the dropdown.

do_layout()[source]#

on_change(event: UIOnChangeEvent)[source]#: To be implemented by the user, triggered when the current selected value is changed to a different option.

DIVIDER = None#

value#: Current selected option.

class arcade.gui.UIInputText(*, x: float = 0, y: float = 0, width: float = 100, height: float = 24, text: str = '', font_name=('Arial',), font_size: float = 12, text_color: Tuple[int, int, int] | Tuple[int, int, int, int] = (0, 0, 0, 255), multiline=False, caret_color: Tuple[int, int, int] | Tuple[int, int, int, int] = (0, 0, 0, 255), size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]#

Bases: UIWidget

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.

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.
style – Style has not been implemented for this widget, however it will be added in the near future.

do_render(surface: Surface)[source]#

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

on_update(dt)[source]#

LAYOUT_OFFSET = 1#

text#

class arcade.gui.UILabel(text: str = '', *, x: float = 0, y: float = 0, width: float | None = None, height: float | None = None, font_name=('Arial',), font_size: float = 12, text_color: Tuple[int, int, int] | Tuple[int, int, int, int] = (255, 255, 255, 255), bold=False, italic=False, align='left', multiline: bool = False, size_hint=None, size_hint_min=None, 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.

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. A UITextWidget with multiline of True is the same thing as a UITextArea.
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.
style – Not used. Labels will have no need for a style; they are too simple (just a text display).

do_render(surface: Surface)[source]#

fit_content()[source]#: Set the width and height of the label to contain the whole text.

text#

class arcade.gui.UITextArea(*, x: float = 0, y: float = 0, width: float = 400, height: float = 40, text: str = '', font_name=('Arial',), font_size: float = 12, 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, **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.
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.
style – Style has not been implemented for this widget, however it will be added in the near future.

do_render(surface: Surface)[source]#

fit_content()[source]#: Set the width and height of the text area to contain the whole text.

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

text#

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

place_text(anchor_x: str | None = None, align_x: float = 0, anchor_y: str | None = None, align_y: float = 0, **kwargs)[source]#: Place widget’s text within the widget using UIAnchorLayout parameters.

label#

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.

parent: UIManager | UIWidget | None#

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

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

class arcade.gui.Rect(x: float, y: float, width: float, height: float)[source]#

Bases: NamedTuple

Representing a rectangle for GUI module. Rect is idempotent.

Bottom left corner is used as fix point (x, y)

🧙 repr(self)#: Return a nicely formatted representation string

align_bottom(value: float) → Rect[source]#: Returns new Rect, which is aligned to the bottom

align_center(center_x: float | int, center_y: float | int) → Rect[source]#: Returns new Rect, which is aligned to the center x and y

align_center_x(value: float | int) → Rect[source]#: Returns new Rect, which is aligned to the center_x

align_center_y(value: float | int) → Rect[source]#: Returns new Rect, which is aligned to the center_y

align_left(value: float) → Rect[source]#: Returns new Rect, which is aligned to the left

align_right(value: float | int) → Rect[source]#: Returns new Rect, which is aligned to the right

align_top(value: float) → Rect[source]#: Returns new Rect, which is aligned to the top

collide_with_point(x: float | int, y: float | int) → bool[source]#

Return true if x and y are within this rect.

This check is inclusive. Values on the left, right, top, and bottom edges will be counted as inside the rect.

>>> bounds = Rect(0.0, 0.0, 5.0, 5.0)
>>> bounds.collide_with_point(0.0, 0.0)
True
>>> bounds.collide_with_point(5.0, 5.0)
True

Parameters:

x – The x value to check as inside the rect.
y – The y value to check as inside the rect.

max_size(width: float | int | None = None, height: float | int | None = None) → Rect[source]#: Limits the size to the given max values.

min_size(width: float | int | None = None, height: float | int | None = None) → Rect[source]#: Sets the size to at least the given min values.

move(dx: float | int = 0.0, dy: float | int = 0.0) → Rect[source]#: Returns new Rect which is moved by dx and dy

resize(width: float | None = None, height: float | None = None) → Rect[source]#

Return a rect with a new width or height but same lower left.

Fix x and y coordinate. :param width: A width for the new rectangle. :param height: A height for the new rectangle.

scale(scale: float, rounding: ~typing.Callable[[...], float] | None = <built-in function floor>) → Rect[source]#

Return a new rect scaled relative to the origin.

By default, the new rect’s values are rounded down to whole values. You can alter this by passing a different rounding behavior:

Pass None to skip rounding
Pass a function which takes a number and returns a float to choose rounding behavior.

Parameters:

scale – A scale factor.
rounding – None or a callable specifying how to round the scaled values.

union(rect: Rect) → Rect[source]#: Returns a new Rect that is the union of this rect and another. The union is the smallest rectangle that contains theses two rectangles.

bottom#: The bottom edge on the Y axis.

center#

center_x#

center_y#

height: float#: Alias for field number 3

left#: The left edge on the X axis.

position#: Bottom left coordinates

right#: The right edge on the X axis.

size#

Read-only pixel size of the rect.

Since these rects are immutable, use helper instance methods to get updated rects. For example, resize() may be what you’re looking for.

top#: The top edge on the Y axis.

width: float#: Alias for field number 2

x: float#: Alias for field number 0

y: float#: Alias for field number 1

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

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
color – fill color for the widget
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
style – not used

do_render(surface: Surface)[source]#

on_click(event: UIOnClickEvent)[source]#

on_update(dt)[source]#

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

Bases: UIWidget

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

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:param x: center x of widget
style – not used

on_click(event: UIOnClickEvent)[source]#

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

disabled#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

hovered#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

pressed#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

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

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 – A hint for UILayout, if this UIWidget would like to grow
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
style – not used

do_layout()[source]#

Triggered by the UIManager before rendering, UILayout s should place themselves and/or children. Do layout will be triggered on children afterward.

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 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=100, height=100, color=(0, 0, 0, 0), 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
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
style – not used

do_render(surface: Surface)[source]#

color#

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
style – not used

do_render(surface: Surface)[source]#

on_update(dt)[source]#

class arcade.gui.UIWidget(*, 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: 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
style – not used

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

Add a widget to this UIWidget 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

center_on_screen() → W[source]#: Places this widget in the center of the current window.

clear()[source]#

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”

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.

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

remove(child: UIWidget)[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.

resize(*, width=None, height=None)[source]#

scale(factor)[source]#: Scales the size of the widget (x,y,width, height) by factor. :param factor: scale factor

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.

with_background(*, color: None | Color = Ellipsis, texture: None | Texture | NinePatchTexture = Ellipsis) → UIWidget[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=(0, 0, 0)) → Self[source]#: Sets border properties :param width: border width :param color: border color :return: self

with_padding(*, top: int | None = None, right: int | None = None, bottom: int | None = None, left: int | None = None, all: int | None = None) → UIWidget[source]#: Changes the padding to the given values if set. Returns itself :return: self

bottom#

center#

center_x#

center_y#

children#

content_height#

content_rect#

content_size#

content_width#

height#

left#

padding#

position#: Returns bottom left coordinates

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

right#

size#

size_hint: Tuple[float, float] | None#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

size_hint_max: Tuple[float, float] | None#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

size_hint_min: Tuple[float, float] | None#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

top#

visible: bool#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

width#

x#

y#

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

do_render(surface: Surface)[source]#

on_change(event: UIOnChangeEvent)[source]#

on_click(event: UIOnClickEvent)[source]#

value: bool#

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

:param default: Default value which is returned, if no value set before
:param default_factory: A callable which returns the default value.
                        Will be called with the property and the instance

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, 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

class UIStyle(font_size: int = 12, font_name: str | Tuple[str, ...] = ('calibri', 'arial'), font_color: Tuple[int, int, int, int] = (255, 255, 255, 255), bg: Tuple[int, int, int, int] = (21, 19, 21, 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] = (21, 19, 21, 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, ...] = ('calibri', 'arial')#

font_size: int = 12#

do_render(surface: Surface)[source]#

get_current_state() → str[source]#: Returns the current state of the button i.e disabled, press, hover or normal.

DEFAULT_STYLE = {'disabled': UIFlatButton.UIStyle(font_size=12, font_name=('calibri', 'arial'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=128, g=128, b=128, a=255), border=None, border_width=2), 'hover': UIFlatButton.UIStyle(font_size=12, font_name=('calibri', 'arial'), font_color=Color(r=255, g=255, b=255, a=255), bg=(21, 19, 21, 255), border=(77, 81, 87, 255), border_width=2), 'normal': UIFlatButton.UIStyle(font_size=12, font_name=('calibri', 'arial'), font_color=Color(r=255, g=255, b=255, a=255), bg=(21, 19, 21, 255), border=None, border_width=0), 'press': UIFlatButton.UIStyle(font_size=12, font_name=('calibri', 'arial'), font_color=Color(r=0, g=0, b=0, a=255), bg=Color(r=255, g=255, b=255, a=255), border=Color(r=255, g=255, b=255, a=255), border_width=2)}#

parent: UIManager | UIWidget | None#

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

UIStyle#: alias of UITextureButtonStyle

do_render(surface: Surface)[source]#

get_current_state() → str[source]#: Returns the current state of the button i.e disabled, press, hover or normal.

DEFAULT_STYLE = {'disabled': UITextureButtonStyle(font_size=12, font_name=('calibri', 'arial'), font_color=Color(r=255, g=255, b=255, a=255), border_width=2), 'hover': UITextureButtonStyle(font_size=12, font_name=('calibri', 'arial'), font_color=Color(r=255, g=255, b=255, a=255), border_width=2), 'normal': UITextureButtonStyle(font_size=12, font_name=('calibri', 'arial'), font_color=Color(r=255, g=255, b=255, a=255), border_width=2), 'press': UITextureButtonStyle(font_size=12, font_name=('calibri', 'arial'), font_color=Color(r=0, g=0, b=0, a=255), border_width=2)}#

texture#: Returns the normal texture for the face of the button.

texture_hovered#: Returns the hover texture for the face of the button.

texture_pressed#: Returns the pressed texture for the face of the button.

class arcade.gui.UITextureButtonStyle(font_size: int = 12, font_name: str | Tuple[str, ...] = ('calibri', 'arial'), font_color: Tuple[int, int, int, int] = (255, 255, 255, 255), border_width: int = 2)[source]#

Bases: UIStyleBase

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

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

border_width: int = 2#

font_color: Tuple[int, int, int, int] = (255, 255, 255, 255)#

font_name: str | Tuple[str, ...] = ('calibri', 'arial')#

font_size: int = 12#