arcade.gui package

This module provides UIElements which can be used to ease the interaction with the player.

Starting with arcade.gui.UIManager you can add new arcade.gui.UIElement which will be drawn on top of your other sprites.

The UI interactions are implemented using Pyglets pyglet.event.EventDispatcher. The arcade.gui.UIManager subscribes to all arcade.Window events and converts them into a arcade.gui.UIEvent object, which is passed to all added arcade.gui.UIElement.

Available arcade.gui.UIElement

Run examples with python -m arcade.gui.examples.<example name>

class arcade.gui.UIClickable(center_x=0, center_y=0, id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Bases: pyglet.event.EventDispatcher, arcade.gui.core.UIElement

Texture based UIElement supporting hover and press, this should fit every use case

CLICKED = 'UIClickable_CLICKED'
__init__(center_x=0, center_y=0, id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Create a clickable UI Element

Parameters
property focus_texture
property focused

True if mouse is clicked on this element, until click outside of this element

property hover_texture
property hovered

True if mouse is over this element, only one element at a time

property normal_texture
on_click()[source]
on_focus()[source]
on_hover()[source]
on_press()[source]
on_release()[source]
on_ui_event(event: arcade.gui.core.UIEvent)[source]
on_unfocus()[source]
on_unhover()[source]
property press_texture
property pressed

True if mouse is over this element and mouse button gets pressed, only one element at a time

render()[source]

Render and update textures, called on style change. Initially called while added to arcade.gui.UIManager

Has to be implemented by subclasses of arcade.gui.UIElement.

Recommendation: call arcade.gui.UIClickable.set_proper_texture() after setting up the textures if you don’t use property textures which handle this. Property textures: * self.normal_texture * self.hover_texture * self.press_texture * self.focus_texture

set_proper_texture()[source]

Set normal, mouse-over, or clicked texture.

class arcade.gui.UIElement(center_x=0, center_y=0, id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Bases: arcade.sprite.Sprite

Base class for all UI elements. Implements arcade.Sprite, requires a texture to be set in arcade.gui.UIElement.render()

arcade.gui.UIElement contains an id, which can be used to retrieve it from arcade.gui.UIManager

Holds a reference to a arcade.gui.UIStyle, resolving values depending on the UIElement().id, UIElement().style_classes, and element specific style attributes.

__init__(center_x=0, center_y=0, id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]
property id

You can set id on creation, but it can’t be modify later

on_focus()[source]

Callback if the element gets focused

on_hover()[source]

Callback if the element gets hovered

on_style_change(style_classes: Set[str])[source]

Callback which is used to trigger rerender. Normal subclasses don’t have to overwrite this method.

on_ui_event(event: arcade.gui.core.UIEvent)[source]

Callback for a arcade.gui.UIEvent, triggered through pyglet.EventDispatcher

Parameters

event (UIEvent) – Dispatched event

Returns

If True is returned the dispatch will stop

on_unfocus()[source]

Callback if the element gets unfocused aka is not focused any more

on_unhover()[source]

Callback if the element gets unhovered aka is not focused any more

render()[source]

Render and update textures, called on style change. Initially called while added to arcade.gui.UIManager

Has to be implemented by subclasses of arcade.gui.UIElement.

set_style_attrs(**kwargs)[source]

Sets a custom style attribute for this UIElement The value will be returned unparsed (like given) Setting an attribute to None will remove the overwrite, defaults will apply

Parameters

kwargs – key-value pairs

property style
Returns

Referenced arcade.gui.UIStyle

style_attr(key, default=None)[source]

Resolve a style attribute.

Parameters
  • key – Attribute key

  • default – default return if not found.

Returns

Attribute value or default value if attribute key was not found.

class arcade.gui.UIEvent(type: str, **kwargs)[source]

Bases: object

Represents an interaction with the gui.

__init__(type: str, **kwargs)[source]
Parameters
  • type – Type of the event, like arcade.gui.MOUSE_PRESS arcade.gui.KEY_PRESS

  • kwargs – Data of the event

get(key: str) → Any[source]

Retrieve value for given key

:param str key

exception arcade.gui.UIException[source]

Bases: Exception

Abstract Exception within the UI.

class arcade.gui.UIFlatButton(text: str, center_x: int = 0, center_y: int = 0, width: int = 0, height: int = 0, align='center', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Bases: arcade.gui.elements.flat_button.UIAbstractFlatButton

__init__(text: str, center_x: int = 0, center_y: int = 0, width: int = 0, height: int = 0, align='center', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]
Parameters
  • text – Text

  • center_x – center X of element

  • center_y – center y of element

  • width – width of element

  • height – height of element

  • align – align of text, requires set width

  • id – id of arcade.gui.UIElement

  • style – style of arcade.gui.UIElement

  • kwargs – catches unsupported named parameters

class arcade.gui.UIGhostFlatButton(text: str, center_x: int = 0, center_y: int = 0, width: int = 0, height: int = 0, align='center', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Bases: arcade.gui.elements.flat_button.UIAbstractFlatButton

__init__(text: str, center_x: int = 0, center_y: int = 0, width: int = 0, height: int = 0, align='center', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]
Parameters
  • text – Text

  • center_x – center X of element

  • center_y – center y of element

  • width – width of element

  • height – height of element

  • align – align of text, requires set width

  • id – id of arcade.gui.UIElement

  • style – style of arcade.gui.UIElement

  • kwargs – catches unsupported named parameters

class arcade.gui.UIImageButton(center_x, center_y, normal_texture: arcade.texture.Texture, hover_texture: arcade.texture.Texture, press_texture: arcade.texture.Texture, text='', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Bases: arcade.gui.elements.UIClickable

__init__(center_x, center_y, normal_texture: arcade.texture.Texture, hover_texture: arcade.texture.Texture, press_texture: arcade.texture.Texture, text='', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]
Parameters
  • center_x – center X of element

  • center_y – center y of element

  • normal_texture

  • hover_texture

  • press_texture

  • text

  • id – id of arcade.gui.UIElement

  • style – style of arcade.gui.UIElement

  • kwargs – catches unsupported named parameters

render()[source]
render_with_text(text: str)[source]
property text
class arcade.gui.UIInputBox(center_x, center_y, width: int, height=0, text='', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Bases: arcade.gui.elements.UIClickable

Provides an input field for the user. If it gets focus, user clicks on it, it will show a cursor and will react to keystrokes, changing the text and cursor position.

Style attributes: * font_name * font_size * font_color * font_color_hover * font_color_focus * border_width * border_color * border_color_hover * border_color_focus * bg_color * bg_color_hover * bg_color_focus * vmargin - Vertical margin around text * margin_left

ENTER = 'ENTER'
__init__(center_x, center_y, width: int, height=0, text='', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]
Parameters
  • center_x – center X of element

  • center_y – center y of element

  • width – width of element

  • height – height of element

  • text – text

  • id – id of arcade.gui.UIElement

  • style – style of arcade.gui.UIElement

  • kwargs – catches unsupported named parameters

property cursor_index

Current index of cursor

on_ui_event(event: arcade.gui.core.UIEvent)[source]
render()[source]
property text

Stored text

class arcade.gui.UILabel(text: str, center_x: int, center_y: int, width: int = 0, align='center', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Bases: arcade.gui.elements.UIClickable

arcade.gui.UIElement for showing text.

__init__(text: str, center_x: int, center_y: int, width: int = 0, align='center', id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]
Parameters
  • text – Text to show

  • center_x – center X of element

  • center_y – center y of element

  • width – width, 0 will use the width of the rendered text

  • align – position of the text, requires a fix width

  • id – id of arcade.gui.UIElement

  • style – style of arcade.gui.UIElement

  • kwargs – catches unsupported named parameters

render()[source]
property text

Text of the label

class arcade.gui.UIManager(window=None, **kwargs)[source]

Bases: pyglet.event.EventDispatcher

Central component of arcade.gui . Holds arcade.gui.UIElement and connects them with arcade.Window callbacks.

Basics:

__init__(window=None, **kwargs)[source]

Creates a new arcade.gui.UIManager and registers the corresponding handlers to the current window.

The UIManager has to be created, before arcade.Window.show_view() has been called.

To support multiple views a singleton UIManager should be passed to all views. As an alternative you can remove all registered handlers of a UIManager by calling arcade.gui.UIManager.unregister_handlers() within arcade.View.on_hide_view().

Parameters
add_ui_element(ui_element: arcade.gui.core.UIElement)[source]

Adds a arcade.gui.UIElement to the arcade.gui.UIManager. arcade.gui.UIElement.id has to be unique.

The arcade.gui.UIElement will be drawn by the arcade.gui.UIManager. :param UIElement ui_element: element to add.

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

Dispatches a arcade.gui.UIEvent to all added arcade.gui.UIElements.

Parameters

event (UIEvent) – event to dispatch

Returns

find_by_id(ui_element_id: str) → Optional[arcade.gui.core.UIElement][source]

Finds an arcade.gui.UIElement by its ID.

Parameters

ui_element_id (str) – id of the arcade.gui.UIElement

Returns

arcade.gui.UIElement if available else None

property focused_element
Returns

focused UIElement, only one UIElement can be focused at a time

property hovered_element
Returns

hovered UIElement, only one UIElement can be focused at a time

on_draw()[source]

Draws all added arcade.gui.UIElement.

on_key_press(symbol: int, modifiers: int)[source]

Dispatches arcade.View.on_key_press() as arcade.gui.UIElement with type arcade.gui.KEY_PRESS

on_key_release(symbol: int, modifiers: int)[source]

Dispatches arcade.View.on_key_release() as arcade.gui.UIElement with type arcade.gui.KEY_RELEASE

on_mouse_motion(x: float, y: float, dx: float, dy: float)[source]

Dispatches arcade.View.on_mouse_motion() as arcade.gui.UIElement with type arcade.gui.MOUSE_MOTION

on_mouse_press(x: float, y: float, button: int, modifiers: int)[source]

Dispatches arcade.View.on_mouse_press() as arcade.gui.UIElement with type arcade.gui.MOUSE_PRESS

on_mouse_release(x: float, y: float, button: int, modifiers: int)[source]

Dispatches arcade.View.on_mouse_release() as arcade.gui.UIElement with type arcade.gui.MOUSE_RELEASE

on_mouse_scroll(x: int, y: int, scroll_x: int, scroll_y: int)[source]

Dispatches arcade.View.on_mouse_scroll() as arcade.gui.UIElement with type arcade.gui.MOUSE_SCROLL

on_text(text)[source]

Dispatches arcade.View.on_text() as arcade.gui.UIElement with type arcade.gui.TEXT_INPUT

on_text_motion(motion)[source]

Dispatches arcade.View.on_text_motion() as arcade.gui.UIElement with type arcade.gui.TEXT_MOTION

on_text_motion_select(selection)[source]

Dispatches arcade.View.on_text_motion_select() as arcade.gui.UIElement with type arcade.gui.TEXT_MOTION_SELECT

on_ui_event(event: arcade.gui.core.UIEvent)[source]

Processes UIEvents, forward events to added elements and manages focused and hovered elements

purge_ui_elements()[source]

Removes all UIElements which where added to the arcade.gui.UIManager.

register_handlers()[source]

Registers handler functions (on_…) to arcade.gui.UIElement

unregister_handlers()[source]

Remove handler functions (on_…) from arcade.Window

Every arcade.View uses its own arcade.gui.UIManager, this method should be called in arcade.View.on_hide_view().

class arcade.gui.UIToggle(center_x: int = 0, center_y: int = 0, height: int = 0, value: bool = True, id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]

Bases: arcade.gui.elements.UIClickable

A toggle which can be true or false.

Style attributes: * color_true: color of the lever when value is true * bg_color_true: color of the background when value is true * color_false: color of the lever when value is false * bg_color_false: color of the background when value is false

__init__(center_x: int = 0, center_y: int = 0, height: int = 0, value: bool = True, id: Optional[str] = None, style: arcade.gui.ui_style.UIStyle = None, **kwargs)[source]
Parameters
  • center_x – center X of element

  • center_y – center y of element

  • height – height of element, width depends on height

  • value – initial value

  • id – id of arcade.gui.UIElement

  • style – style of arcade.gui.UIElement

  • kwargs – catches unsupported named parameters

on_click()[source]
on_toggle(value)[source]

Called if value changes through programmatic change or user interaction.

render()[source]
set_proper_texture()[source]
toggle()[source]

Toggles current value (True => False, False => True)

property value

current value