GUI Widgets

arcade.gui.UIAnchorWidget

class arcade.gui.UIAnchorWidget(*, child: arcade.gui.widgets.UIWidget, anchor_x: str = 'center', align_x: float = 0, anchor_y: str = 'center', align_y: float = 0, size_hint=None, size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

Widget, which places itself relative to the parent.

Parameters
  • child – Child of this wrapper

  • anchor_x – Which anchor to use for x axis (left, center, right)

  • align_x – offset for x value (- = left, + = right)

  • anchor_y – Which anchor to use for y axis (top, center, bottom)

  • align_y – offset for y value (- = down, + = up)

  • 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

arcade.gui.UIBorder

class arcade.gui.UIBorder(child: arcade.gui.widgets.UIWidget, border_width=2, border_color=(0, 0, 0, 255), size_hint=None, size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

Wraps a Widget with a border of given color.

Parameters
  • child – Child of this wrapper

  • border_width – Width of the border

  • border_color – Color of the border

  • 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

arcade.gui.UIBoxLayout

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

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

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – y coordinate of bottom left

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

  • align – Align children in orthogonal direction (x: left, center, right / y: top, center, bottom)

  • children – Initial children, more can be added

  • size_hint – A hint for UILayout, if this UIWidget would like to grow

arcade.gui.UIDummy

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

Solid color widget, used for testing.

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – 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

arcade.gui.UIFlatButton

class arcade.gui.UIFlatButton(x: float = 0, y: float = 0, width: float = 100, height: float = 50, text='', size_hint=None, size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

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

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – y coordinate of bottom left

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

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

  • text (str) – text to add to the button.

  • style – Used to style the button

arcade.gui.UIInputText

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

An input field the user can type text into.

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – y coordinate of bottom left

  • width – width of widget

  • height – height of widget

  • text – Text to show

  • font_name – string or tuple of font names, to load

  • font_size – size of the text

  • text_color – color of the text

  • multiline – support for multiline

  • 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

arcade.gui.UIInteractiveWidget

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

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

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – 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

arcade.gui.UILabel

class arcade.gui.UILabel(x: float = 0, y: float = 0, width: Optional[float] = None, height: Optional[float] = None, text: str = '', font_name=('Arial',), font_size: float = 12, text_color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]] = (255, 255, 255, 255), bold=False, italic=False, stretch=False, anchor_x='left', anchor_y='bottom', align='left', dpi=None, multiline: bool = False, size_hint=None, size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

A simple text label. Also supports multiline text. In case you want to scroll text use a UITextArea By default a UILabel will fit its initial content, if the text changed use UILabel.fit_content() to adjust the size.

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – y coordinate of bottom left

  • width (float) – width of widget. Defaults to text width if not specified.

  • height (float) – height of widget. Defaults to text height if not specified.

  • text (str) – text of the label.

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

  • font_size (float) – size of font.

  • text_color (arcade.Color) – Color of font.

  • bold (bool) – Bold font style.

  • italic (bool) – Italic font style.

  • stretch (bool) – Stretch font style.

  • anchor_x (str) – Anchor point of the X coordinate: one of "left", "center" or "right".

  • anchor_y (str) – Anchor point of the Y coordinate: one of "bottom", "baseline", "center" or "top".

  • align (str) – Horizontal alignment of text on a line, only applies if a width is supplied. One of "left", "center" or "right".

  • dpi (float) – Resolution of the fonts in this layout. Defaults to 96.

  • multiline (bool) – if multiline is true, a n will start a new line. A UITextWidget with multiline of true is the same thing as UITextArea.

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

fit_content()[source]

Sets the width and height of this UIWidget to contain the whole text.

arcade.gui.UILayout

class arcade.gui.UILayout(x=0, y=0, width=100, height=100, children: Iterable[arcade.gui.widgets.UIWidget] = (), size_hint=None, size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

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

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – 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 afterwards.

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.

arcade.gui.UIPadding

class arcade.gui.UIPadding(child: arcade.gui.widgets.UIWidget, padding=(0, 0, 0, 0), bg_color=None, size_hint=(1, 1), size_hint_min=None, size_hint_max=None, **kwargs)[source]

Wraps a Widget and applies padding.

Parameters
  • child – Child of this wrapper

  • bg_color – background color

  • padding – Space between the outer border of this widget and the child

  • 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

arcade.gui.UISpace

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, style=None, **kwargs)[source]

Widget reserving space, can also have a background color.

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – 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

arcade.gui.UISpriteWidget

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

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

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – 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

arcade.gui.UITextArea

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: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]] = (255, 255, 255, 255), multiline: bool = True, scroll_speed: Optional[float] = None, size_hint=None, size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

A text area for scrollable text.

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – y coordinate of bottom left

  • width – width of widget

  • height – height of widget

  • text – Text to show

  • font_name – string or tuple of font names, to load

  • font_size – size of the text

  • text_color – color of the text

  • multiline – support for multiline

  • scroll_speed – speed of scrolling

  • 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

fit_content()[source]

Sets the width and height of this UIWidget to contain the whole text.

arcade.gui.UITextureButton

class arcade.gui.UITextureButton(x: float = 0, y: float = 0, width: Optional[float] = None, height: Optional[float] = None, texture: Optional[arcade.texture.Texture] = None, texture_hovered: Optional[arcade.texture.Texture] = None, texture_pressed: Optional[arcade.texture.Texture] = None, text: str = '', scale: Optional[float] = None, size_hint=None, size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

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

Parameters
  • x (float) – x coordinate of bottom left

  • y (float) – y coordinate of bottom left

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

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

  • texture (Texture) – texture to display for the widget.

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

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

  • text (str) – text to add to the button.

  • style – style information for the button.

  • scale (float) – 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

arcade.gui.UITexturePane

class arcade.gui.UITexturePane(child: arcade.gui.widgets.UIWidget, tex: arcade.texture.Texture, padding=(0, 0, 0, 0), size_hint=(1, 1), size_hint_min=None, size_hint_max=None, style=None, **kwargs)[source]

This wrapper draws a background before child widget is rendered

Parameters
  • child – Child of this wrapper

  • tex – Texture to use as background

  • padding – Space between the outer border of this widget and the child

  • 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

arcade.gui.UIWidget

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

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 (float) – x coordinate of bottom left

  • y (float) – 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: arcade.gui.widgets.UIWidget, *, index=None)[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
  • widget – widget to add

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

center_on_screen()[source]

Places this widget in the center of the current window.

dispatch_ui_event(event: arcade.gui.events.UIEvent)[source]

Dispatch a UIEvent using pyglet event dispatch mechanism

do_render(surface: arcade.gui.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.

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: arcade.gui.events.UIEvent) Optional[bool][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

scale(factor)[source]

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

trigger_full_render()[source]

In case a widget uses transperant 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_border(width=2, color=(0, 0, 0))[source]

Wraps this Widget with a border :param width: border width :param color: border color :return: Wrapping Border with self as child

with_space_around(top: float = 0, right: float = 0, bottom: float = 0, left: float = 0, bg_color: Optional[Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]]] = None)[source]

Wraps this Widget with a border :param top: Top Padding :param right: Right Padding :param bottom: Bottom Padding :param left: Left Padding :param bg_color: Background color :return: Wrapping Padding with self as child

arcade.gui.UIWidgetParent

class arcade.gui.UIWidgetParent[source]
trigger_render()[source]

Widget might request parent to rerender due to transparent part of the widget

arcade.gui.UIWrapper

class arcade.gui.UIWrapper(*, child: arcade.gui.widgets.UIWidget, padding=(0, 0, 0, 0), size_hint=None, size_hint_min=None, size_hint_max=None, style=None)[source]

Wraps a arcade.gui.UIWidget and reserves space around it, exactly one child supported.

Parameters
  • child – Single child of this wrapper

  • padding – space around (top, right, bottom, left)

  • 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