GUI Experimental Features

class arcade.gui.experimental.UIPasswordInput(*, x: float = 0, y: float = 0, width: float = 100, height: float = 23, 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, **kwargs)[source]

Bases: UIInputText

A password input field. The text is hidden with asterisks.

Hint: It is recommended to set a background color to prevent full render cycles when the caret blinks.

do_render(surface: Surface)[source]

Override to render the text as asterisks.

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

Remove new lines from the input, which are not allowed in passwords.

class arcade.gui.experimental.scroll_area.UIScrollBar(scroll_area: UIScrollArea, vertical: bool = True)[source]

Bases: UIWidget

Scroll bar for a UIScrollLayout.

Indicating the current view position of the scroll area.

Does not support mouse interaction yet.

do_render(surface: Surface)[source]

Render the scroll bar.

class arcade.gui.experimental.UIScrollArea(*, x: float = 0, y: float = 0, width: float = 300, height: float = 300, children: Iterable[UIWidget] = (), size_hint=None, size_hint_min=None, size_hint_max=None, canvas_size=(300, 300), overscroll_x=False, overscroll_y=False, **kwargs)[source]

Bases: UILayout

A widget that can scroll its children.

This widget is highly experimental and only provides a proof of concept.

Parameters:
  • x – x position of the widget

  • y – y position of the widget

  • width – width of the widget

  • height – height of the widget

  • children – children of the widget

  • size_hint – size hint of the widget

  • size_hint_min – minimum size hint of the widget

  • size_hint_max – maximum size hint of the widget

  • canvas_size – size of the canvas, which is scrollable

  • overscroll_x – allow over scrolling in x direction (scroll past the end)

  • overscroll_y – allow over scrolling in y direction (scroll past the end)

  • **kwargs – passed to UIWidget

add(child: UIWidget, **kwargs)[source]

Add a child to the widget.

do_layout()[source]

Layout the children of the widget.

do_render(surface: Surface)[source]

Renders the scolled surface into the given surface.

invert_scroll = False
on_event(event: UIEvent) bool | None[source]

Handle scrolling of the widget.

remove(child: UIWidget)[source]

Remove a child from the widget.

scroll_speed = 1.8
scroll_x

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

scroll_y

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.experimental.typed_text_input.UITypedTextInput(parsed_type: ~typing.Type[~arcade.gui.experimental.typed_text_input.T], *, to_str: ~typing.Callable[[~arcade.gui.experimental.typed_text_input.T], str] = <built-in function repr>, from_str: ~typing.Callable[[str], ~arcade.gui.experimental.typed_text_input.T] | None = None, emit_parse_exceptions: bool = True, 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), error_color: tuple[int, int, int] | tuple[int, int, int, int] = (255, 0, 0, 255), multiline=False, size_hint=None, size_hint_min=None, size_hint_max=None, **kwargs)[source]

Bases: UIInputText, Generic[T]

A text box which auto-converts to and from a type.

The simplest usage is passing a type() which supports repr() and allows a single str as an argument:

self.float_input = UITypedTextInput(float, text="0.0")

In the example above, setting self.float_input.text to "string" will:

  1. Set both the text and the caret to the error_color passed at creation

  2. Re-raise the ValueError from float("string")

To stop error propagation, pass You can customize your conversion to and from strings by overriding the following arguments with custom callable objects:

Argument

Default

to_str

repr()

from_str

the parsed_type

Important

This class is meant to handle simple types in simple dev and test tools.

As a general rule, if you need to highlight a specific syntax error, this class is not the right tool.

Parameters:
  • parsed_type – The type to require. This is not meant to be changed after creation.

  • from_str – A type or other callable() which converts a str to an instance of parsed_type. It may raise exceptions and perform cleaning of text.

  • to_str – A callable() which converts parsed_type instances to str.

  • x – an X position (see UIInputText).

  • y – an X position (see UIInputText).

  • width – an X axis width (see UIInputText).

  • height – a Y axis height (see UIInputText).

  • text – The initial text to display.

  • font_name – (see UIInputText).

  • text_color – The color to use for non-error text.

  • error_color – The color to use when to_str or from_str raised an exception.

  • multiline – See UIInputText.

  • size_hint – See UIInputText.

  • size_hint_min – See UIInputText.

  • size_hint_max – See UIInputText.

on_event(event: UIEvent) bool | None[source]
property parsed_type: Type[T]

Get the type this input field expects to parse.

Note

This is not meant to be changed after creation.

property text: str

Get/set the text of the widget.

In addition to basic behavior from UITextWidget, this also performs validation. To silence error propagation from validation, set emit_parse_exceptions to False.

property value: T

The current instance of parsed_type.

Setting this automatically updates the text of the widget.