GUI Widgets#

arcade.gui.UIImage#

class arcade.gui.UIImage(texture: Union[Texture, NinePatchTexture], **kwargs)[source]#: UIWidget showing a texture.

arcade.gui.UIDropdown#

class arcade.gui.UIDropdown(default: Optional[str] = None, options: Optional[List[str]] = None, style=None, **kwargs)[source]#

arcade.gui.UITextureToggle#

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

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

on_texture and off_texture are required.

arcade.gui.UIAnchorLayout#

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

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. Maximum and minimum size_hint``s only take effect if a ``size_hint is given.

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: Optional[str] = None, align_x: float = 0, anchor_y: Optional[str] = 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.

arcade.gui.UIBoxLayout#

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

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.

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.

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 (float) – x coordinate of the bottom left corner.
y (float) – 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_min – Minimum width and height in pixels.
size_hint_max – Maximum width and height in pixels.
space_between – Space in pixels between the children.

fit_content()[source]#

Resize to fit content, using the size_hint_min attribute.

Returns:: self

arcade.gui.UIGridLayout#

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

Places widget in a grid layout. :param float x: x coordinate of bottom left :param float y: y coordinate of bottom left :param str align_horizontal: Align children in orthogonal direction (x: left, center, right) :param str align_vertical: Align children in orthogonal direction (y: top, center, bottom) :param Iterable[UIWidget] children: Initial children, more can be added :param size_hint: A hint for UILayout, if this UIWidget would like to grow :param size_hint_min: Min width and height in pixel :param size_hint_max: Max width and height in pixel :param horizontal_spacing: Space between columns :param vertical_spacing: Space between rows :param int column_count: Number of columns in the grid, can be changed :param int row_count: Number of rows in the grid, can be changed

add(child: W, col_num: int = 0, row_num: int = 0, col_span: int = 1, row_span: int = 1, **kwargs) → W[source]#

Adds widgets in the grid.

Parameters:

child (UIWidget) – The widget which is to be added in the grid
col_num (int) – The column number in which the widget is to be added (first column is numbered 0; left)
row_num (int) – The row number in which the widget is to be added (first row is numbered 0; top)
col_span (int) – Number of columns the widget will stretch for.
row_span (int) – Number of rows the widget will stretch for.

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

class UIStyle(font_size: int = 12, font_name: Union[str, Tuple[str, ...]] = ('calibri', 'arial'), font_color: Union[Tuple[int, int, int], Tuple[int, int, int, int]] = (255, 255, 255, 255), bg: Union[Tuple[int, int, int], Tuple[int, int, int, int]] = (21, 19, 21), border: Union[Tuple[int, int, int], Tuple[int, int, int, int], NoneType] = None, border_width: int = 0)[source]#

apply_style(style: UIStyleBase)[source]#: Callback which is called right before rendering to apply changes for rendering.

arcade.gui.UITextureButton#

class arcade.gui.UITextureButton(x: float = 0, y: float = 0, width: Optional[float] = None, height: Optional[float] = None, texture: Union[None, Texture, NinePatchTexture] = None, texture_hovered: Union[None, Texture, NinePatchTexture] = None, texture_pressed: Union[None, Texture, NinePatchTexture] = None, texture_disabled: Union[None, Texture, NinePatchTexture] = None, text: str = '', scale: Optional[float] = None, style: Optional[Dict[str, UIStyleBase]] = None, size_hint=None, size_hint_min=None, size_hint_max=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

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

apply_style(style: UIStyleBase)[source]#: Callback which is called right before rendering to apply changes for rendering.

arcade.gui.Rect#

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

Representing a rectangle for GUI module. Rect is idempotent.

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

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

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

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

align_center_y(value: float) → 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) → 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

height: float#: Alias for field number 3

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

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

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

property position#: Bottom left coordinates

resize(width=None, height=None)[source]#: Returns a rect with changed width and height. Fix x and y coordinate.

scale(scale: float) → Rect[source]#: Returns a new rect with scale applied

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

width: float#: Alias for field number 2

x: float#: Alias for field number 0

y: float#: Alias for field number 1

arcade.gui.UIDummy#

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

Solid color widget, used for testing. Prints own rect on click.

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.UIInteractiveWidget#

class arcade.gui.UIInteractiveWidget(*, x=0, y=0, width=100, height=100, size_hint=None, size_hint_min=None, size_hint_max=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.UILayout#

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

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.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[Sprite] = None, size_hint=None, size_hint_min=None, size_hint_max=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.UIWidget#

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

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

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) → Optional[bool][source]#: Passes UIEvent s through the widget tree.

on_update(dt)[source]#: Custom logic which will be triggered.

property position#: 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

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.

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=Ellipsis, texture: Union[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 (arcade.Color) – A color used as background
texture (arcade.Texture) – A texture or ninepatch texture used as background

Returns:

self

with_border(width=2, color=(0, 0, 0)) → UIWidget[source]#: Sets border properties :param width: border width :param color: border color :return: self

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

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.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], Tuple[int, int, int, int]] = (0, 0, 0, 255), multiline=False, size_hint=None, size_hint_min=None, size_hint_max=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.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], Tuple[int, int, int, int]] = (255, 255, 255, 255), bold=False, italic=False, stretch=False, align='left', dpi=None, multiline: bool = False, size_hint=None, size_hint_min=None, size_hint_max=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.
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.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], 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, **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.UITextWidget#

class arcade.gui.UITextWidget(text: str = '', **kwargs)[source]#

Adds the ability to add text to a widget. The text can be placed within the widget using UIAnchorLayout parameters with place_text().

place_text(anchor_x: Optional[str] = None, align_x: float = 0, anchor_y: Optional[str] = None, align_y: float = 0, **kwargs)[source]#: This allows to place widgets text within the widget using UIAnchorLayout parameters.

arcade.gui.UISlider#

class arcade.gui.UISlider(*, value=0, min_value=0, max_value=100, x=0, y=0, width=300, height=20, size_hint=None, size_hint_min=None, size_hint_max=None, style: Optional[Mapping[str, UIStyleBase]] = None, **kwargs)[source]#

class UIStyle(bg: Union[Tuple[int, int, int], Tuple[int, int, int, int]] = (94, 104, 117), border: Union[Tuple[int, int, int], Tuple[int, int, int, int]] = (77, 81, 87), border_width: int = 1, filled_bar: Union[Tuple[int, int, int], Tuple[int, int, int, int]] = (50, 50, 50), unfilled_bar: Union[Tuple[int, int, int], Tuple[int, int, int, int]] = (116, 125, 123))[source]#

property norm_value#: Normalized value between 0.0 and 1.0