GUI Widgets
- class arcade.gui.UIWidget(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, children: Iterable[UIWidget] = (), size_hint: Tuple[float | None, float | None] | None = None, size_hint_min: Tuple[float | None, float | None] | None = None, size_hint_max: Tuple[float | None, float | None] | None = 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 aUILayout
: it will not change the position or the size of its children. If you want control over positioning or sizing, use aUILayout
.
- 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
- add(child: W, **kwargs) W [source]
Add a widget 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.
This is a convenience method for simple centering of widgets without using a layout.
In general, it is recommended to use layouts for more complex UIs.
- property content_height: float
Returns the height of the content area, which is the height of the widget minus padding and border.
- property content_rect: Rect
Returns the content area as a rect. The content area is the area of the widget minus padding and border.
- property content_size: Tuple[float, float]
Returns the size of the content area, which is the size of the widget minus padding and border.
- property content_width: float
Returns the width of the content area, which is the width of the widget minus padding and border.
- 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.
- move(dx=0, dy=0)[source]
Move the widget by dx and dy.
- Parameters:
dx – x axis difference
dy – y axis difference
- property padding
Returns padding as tuple (top, right, bottom, left)
- 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
- 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
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
- remove(child: UIWidget) dict | None [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.
- Returns:
kwargs which were used when child was added
- resize(*, width=None, height=None, anchor: Vec2 = (0.5, 0.5))[source]
Resizes the widget.
- Parameters:
width (optional) – new width
height (optional) – new height
anchor (optional) – anchor point for resizing, default is center
- scale(factor: float | int, anchor: Vec2 = (0.5, 0.5))[source]
Scales the size of the widget (x,y,width, height) by factor.
- Parameters:
factor – scale factor
anchor – anchor point
- size_hint
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
- size_hint_max
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
- size_hint_min
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
- 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.
- visible
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
- with_background(*, color: None | Color = Ellipsis, texture: None | Texture | NinePatchTexture = Ellipsis) Self [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
- class arcade.gui.UIInteractiveWidget(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, size_hint=None, size_hint_min=None, size_hint_max=None, interaction_buttons=(1,), **kwargs)[source]
Bases:
UIWidget
Base class for widgets which use mouse interaction (hover, pressed, clicked)
It provides properties for hovered, pressed and disabled states.
- 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
interaction_buttons – defines, which mouse buttons should trigger the interaction (default: left mouse button)
- disabled
True if the widget is disabled
- hovered
True if the mouse is over the widget
- on_click(event: UIOnClickEvent)[source]
Triggered when the widget is clicked.
- on_event(event: UIEvent) bool | None [source]
Handles mouse events and triggers on_click event if the widget is clicked.
This also sets the hovered and pressed state of the widget.
- pressed
True if the widget is pressed
- 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.
Starts with a random color. 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
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
**kwargs – passed to UIWidget
- on_click(event: UIOnClickEvent)[source]
Prints the rect and changes the 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
- class arcade.gui.UILayout(*, x: float = 0, y: float = 0, width: float = 100, height: float = 100, children: Iterable[UIWidget] = (), size_hint: Tuple[float | None, float | None] | None = None, size_hint_min: Tuple[float | None, float | None] | None = None, size_hint_max: Tuple[float | None, float | None] | None = 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 – 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
- do_layout()[source]
- do_layout is triggered by the UIManager before rendering.
UILayout
should position their children. Afterward, do_layout of child widgets will be triggered.
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.
- class arcade.gui.UISpace(*, x=0, y=0, width=1, height=1, color=None, 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, if None, it will be transparent (this will set the background color)
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
**kwargs – passed to UIWidget
- property color
Color of the widget, alias for background color
- class arcade.gui.UITextureButtonStyle(font_size: int = 12, font_name: str | tuple[str, ...] = ('Kenney Future', 'arial', 'calibri'), font_color: tuple[int, int, int, int] = (255, 255, 255, 255))[source]
Bases:
UIStyleBase
Used to style the texture button. Below is its use case.
button = UITextureButton(style={"normal": UITextureButton.UIStyle(...),})
- 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
- DEFAULT_STYLE = {'disabled': UITextureButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=189, g=195, b=199, a=255)), 'hover': UITextureButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255)), 'normal': UITextureButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255)), 'press': UITextureButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=44, g=62, b=80, a=255))}
- UIStyle
alias of
UITextureButtonStyle
- get_current_state() str [source]
Returns the current state of the button i.e.disabled, press, hover or normal.
- property texture
Returns the normal texture for the face of the button.
- property texture_hovered
Returns the hover texture for the face of the button.
- property texture_pressed
Returns the pressed texture for the face of the button.
- class arcade.gui.widgets.buttons.UIFlatButtonStyle(font_size: int = 12, font_name: str | tuple[str, ...] = ('Kenney Future', 'arial', 'calibri'), font_color: tuple[int, int, int, int] = (255, 255, 255, 255), bg: tuple[int, int, int, int] = (44, 62, 80, 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(...),})
- 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
[UIFlatButtonStyle
],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
- DEFAULT_STYLE = {'disabled': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=189, g=195, b=199, a=255), bg=Color(r=127, g=140, b=141, a=255), border=None, border_width=0), 'hover': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=52, g=73, b=94, a=255), border=Color(r=149, g=165, b=166, a=255), border_width=0), 'normal': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=44, g=62, b=80, a=255), border=None, border_width=0), 'press': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=44, g=62, b=80, a=255), bg=Color(r=236, g=240, b=241, a=255), border=Color(r=149, g=165, b=166, a=255), border_width=0)}
- STYLE_BLUE = {'disabled': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=127, g=140, b=141, a=255), border=None, border_width=0), 'hover': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=41, g=128, b=185, a=255), border=Color(r=189, g=195, b=199, a=255), border_width=2), 'normal': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=52, g=152, b=219, a=255), border=None, border_width=0), 'press': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=44, g=62, b=80, a=255), border=Color(r=189, g=195, b=199, a=255), border_width=2)}
- STYLE_RED = {'disabled': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=255, g=255, b=255, a=255), bg=Color(r=127, g=140, b=141, a=255), border=None, border_width=0), 'hover': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=231, g=76, b=60, a=255), border=Color(r=189, g=195, b=199, a=255), border_width=2), 'normal': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=231, g=76, b=60, a=255), border=Color(r=192, g=57, b=43, a=255), border_width=0), 'press': UIFlatButtonStyle(font_size=12, font_name=('Kenney Future', 'arial', 'calibri'), font_color=Color(r=236, g=240, b=241, a=255), bg=Color(r=192, g=57, b=43, a=255), border=Color(r=189, g=195, b=199, a=255), border_width=2)}
- UIStyle
alias of
UIFlatButtonStyle
- class arcade.gui.UIDropdown(*, x: float = 0, y: float = 0, width: float = 150, height: float = 30, default: str | None = None, options: list[str | None] | None = 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.
- DIVIDER = None
- do_layout()[source]
Position the overlay, this is not a common thing to do in do_layout, but is required for the dropdown.
- on_change(event: UIOnChangeEvent)[source]
To be implemented by the user, triggered when the current selected value is changed to a different option.
- 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
, andsize_hint_max
. Children are allowed to overlap.Child are resized based on
size_hint
.size_hint_min/max
only take effect if asize_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
= 0Horizontal alignment for the layout.
align_y
:float
= 0Vertical alignement for the layout.
- Parameters:
x –
x
coordinate of the bottom left corner.y –
y
coordinate of the bottom left corner.width – Width of the layout.
height – Height of the layout.
children – Initial list of children. More can be added later.
size_hint – Size hint for
UILayout
size_hint_min – Minimum width and height in pixels.
size_hint_max – Maximum width and height in pixels.
**kwargs – Additional keyword arguments passed to UILayout.
- 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
, andcenter
.align_x – Offset or padding for the horizontal anchor.
anchor_y – Vertical anchor. Valid options are
top
,center
, andbottom
.align_y – Offset or padding for the vertical anchor.
- Returns:
Given child that was just added to the layout.
- 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 aUIManager
or aUIAnchorLayout
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 ofsize_hint_min
andsize_hint_max
(unrestricted if not given). If the parametervertical
is True, any available space (layout size - min_size
of children) will be distributed to the child widgets based on theirsize_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
, andright
-y
:top
,center
, andbottom
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 to0, 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]
Add a widget to this layout
- Parameters:
child – The widget to add to the layout.
- do_layout()[source]
Executes the layout algorithm.
This method is called by the parent layout to place the children, after the rect was set.
The layout algorithm will place the children based on the size hints next to each other. Depending on the vertical attribute, the children are placed top to bottom or left to right.
- class arcade.gui.UIGridLayout(*, x=0, y=0, width=1, height=1, 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, **kwargs)[source]
Bases:
UILayout
Place widgets in a grid.
Widgets can span multiple columns and rows. By default, the layout will only use the minimal required space (
size_hint = (0, 0)
).Widgets can provide a
size_hint
to request dynamic space relative to the layout size. A size_hint of(1, 1)
will fill the available space, while(0.1, 0.1)
will use maximum 10% of the layouts total size.Children are resized based on
size_hint
. Maximum and minimumsize_hint``s only take effect if a ``size_hint
is given.The layouts
size_hint_min
is automatically updated based on the minimal required space by children, after layouting.The width of columns and height of rows are calculated based on the size hints of the children. The highest size_hint_min of a child in a column or row is used. If a child has no size_hint, the actual size is considered.
- Parameters:
x –
x
coordinate of bottom left corner.y –
y
coordinate of bottom left corner.width – Width of the layout.
height – Height of the layout.
align_horizontal – Align children in orthogonal direction. Options include
left
,center
, andright
.align_vertical – Align children in orthogonal direction. Options include
top
,center
, andbottom
.children – Initial list of children. More can be added later.
size_hint – A size hint for
UILayout
, if theUIWidget
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, column: int = 0, row: int = 0, column_span: int = 1, row_span: int = 1, **kwargs) W [source]
Add a widget to the grid layout.
- Parameters:
child – Specified widget to add as a child of the layout.
column – Column index in which the widget is to be added. The first column at the left of the widget starts at 0.
row – The row number in which the widget is to be added. The first row at the top of the layout is numbered 0.
column_span – Number of columns the widget will stretch for.
row_span – Number of rows the widget will stretch for.
- do_layout()[source]
Executes the layout algorithm.
Children are placed in a grid layout based on the size hints.
Algorithm
generate list for all rows and columns
per column, collect max of size_hint_min and max size_hint (widths)
per row, collect max of size_hint_min and max size_hint (heights)
use box layout algorithm to distribute space
place widgets in grid layout
- 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.
- 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.
size_hint – Size hint of the slider.
size_hint_min – Minimum size hint of the slider.
size_hint_max – Maximum size hint of the slider.
style – Used to style the slider for different states.
**kwargs – Passed to UIInteractiveWidget.
- property norm_value
Normalized value between 0.0 and 1.0
- on_change(event: UIOnChangeEvent)[source]
To be implemented by the user, triggered when the cursor’s value is changed.
- Parameters:
event – Event containing the old and new value of the cursor.
- on_click(event: UIOnClickEvent)[source]
Handle click events to set the value of the slider.
A new value is calculated based on the click position and the slider’s width and the on_change event is dispatched.
- Parameters:
event – Click event.
- on_event(event: UIEvent) bool | None [source]
- Parameters:
event – Event to handle.
Returns: True if event was handled, False otherwise.
- 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
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.UISliderStyle(bg: tuple[int, int, int, int] = (189, 195, 199, 255), border: tuple[int, int, int, int] = (44, 62, 80, 255), border_width: int = 2, filled_track: tuple[int, int, int, int] = (44, 62, 80, 255), unfilled_track: tuple[int, int, int, int] = (189, 195, 199, 255))[source]
Bases:
UIStyleBase
Used to style the slider for different states. Below is its use case.
button = UITextureButton(style={"normal": UITextureButton.UIStyle(...),})
- Parameters:
bg – Background color.
border – Border color.
border_width – Width of the border.
filled_track – Color of the filled track.
unfilled_track – Color of the unfilled track.
- 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 = 25, size_hint=None, size_hint_min=None, size_hint_max=None, style: dict[str, UISliderStyle] | None = None, **kwargs)[source]
Bases:
UIStyledWidget
[UISliderStyle
],UIBaseSlider
A simple slider.
A slider consists 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 cursor 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 – Used to style the slider for different states.
- DEFAULT_STYLE = {'disabled': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=44, g=62, b=80, a=255), border_width=1, filled_track=Color(r=127, g=140, b=141, a=255), unfilled_track=Color(r=189, g=195, b=199, a=255)), 'hover': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=52, g=152, b=219, a=255), border_width=2, filled_track=Color(r=52, g=152, b=219, a=255), unfilled_track=Color(r=189, g=195, b=199, a=255)), 'normal': UISliderStyle(bg=Color(r=189, g=195, b=199, a=255), border=Color(r=44, g=62, b=80, a=255), border_width=2, filled_track=Color(r=44, g=62, b=80, a=255), unfilled_track=Color(r=189, g=195, b=199, a=255)), 'press': UISliderStyle(bg=Color(r=52, g=152, b=219, a=255), border=Color(r=52, g=73, b=94, a=255), border_width=3, filled_track=Color(r=52, g=152, b=219, a=255), unfilled_track=Color(r=189, g=195, b=199, a=255))}
- UIStyle
alias of
UISliderStyle
- class arcade.gui.UITextureSlider(track_texture: Texture | NinePatchTexture, thumb_texture: 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.
- Parameters:
track_texture – Texture for the track, should be a NinePatchTexture.
thumb_texture – Texture for the thumb.
style – Used to style the slider for different states.
**kwargs – Passed to UISlider.
- class arcade.gui.UILabel(text: str = '', *, x: float = 0, y: float = 0, width: float | None = None, height: float | None = None, font_name=('calibri', 'arial'), font_size: float = 12, text_color: tuple[int, int, int] | tuple[int, int, int, int] = (255, 255, 255, 255), bold: str | bool = False, italic=False, align='left', multiline: bool = False, size_hint=(0, 0), 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.If the text changes frequently, ensure to set a background color or texture, which will prevent a full rendering of the whole UI and only render the label itself.
- 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. Changing text or font will require a manual call offit_content()
to prevent text line wrap.size_hint – A tuple of floats between 0 and 1 defining the amount of space of the parent should be requested. Default (0, 0) which fits the content.
size_hint_max – Maximum size hint width and height in pixel.
- ADAPTIVE_MULTILINE_WIDTH = 999999
- property bold: bool | str
Return if the label is in bold style. Use
update_font()
to change.
- fit_content()[source]
Manually set the width and height of the label to contain the whole text. Based on the size_hint_min.
If multiline is enabled, the width will be calculated based on longest line of the text. And size_hint_min will be updated.
- property font_color: Color
Font color of the label. Use
update_font()
to change.
- property font_name: str | tuple[str, ...]
Font name of the label. Use
update_font()
to change.
- property font_size: float
Font size of the label. Use
update_font()
to change.
- property italic: bool | str
Return if the label is in italic style. Use
update_font()
to change.
- property text
Text of the label.
- update_font(font_name: str | tuple[str, ...] | None = None, font_size: float | None = None, font_color: Color | None = None, bold: bool | str | None = None, italic: bool | None = None)[source]
Update font of the label.
- Parameters:
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.
font_color – Color of the text.
bold – May be any value in
pyglet.text.Weight
,True
(converts to"bold"
), orFalse
(converts to"regular"
).italic – If enabled, the label’s text will be in an italic
- 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 withplace_text()
.The widget holds reference to one primary
UILabel
, which is placed in the widget’s layout. This label can be accessed viaui_label
.To change font, font size, or text color, use py:meth:~arcade.gui.UILabel.update_font.
- Parameters:
text – Text displayed on the label.
multiline – If enabled, a
\n
will start a new line.**kwargs – passed to
UIWidget
.
- property multiline
Get or set the multiline mode.
Newline characters (
"\n"
) will only be honored when this is set toTrue
. If you want a scrollable text widget, please useUITextArea
instead.
- place_text(anchor_x: str | None = None, align_x: float = 0, anchor_y: str | None = None, align_y: float = 0, **kwargs) UILabel [source]
Place widget’s text within the widget using
UIAnchorLayout
parameters.- Parameters:
anchor_x – Horizontal anchor. Valid options are
left
,right
, andcenter
.align_x – Offset or padding for the horizontal anchor.
anchor_y – Vertical anchor. Valid options are
top
,center
, andbottom
.align_y – Offset or padding for the vertical anchor.
**kwargs – Additional keyword arguments passed to the layout function.
- property text
Text of the widget. Modifying this repeatedly will cause significant lag; calculating glyph position is very expensive.
- class arcade.gui.UIInputText(*, 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:
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.
By default, a border is drawn around the input field.
The widget emits a
UIOnChangeEvent
event when the text changes.- 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. AUITextWidget
multiline
of True is the same thing as aUITextArea
.caret_color – An RGBA or RGB color for the caret with each channel between 0 and 255, inclusive.
border_color – An RGBA or RGB color for the border with each channel between 0 and 255, inclusive, can be None to remove border.
border_width – Width of the border in pixels.
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.
**kwargs – passed to
UIWidget
.
- LAYOUT_OFFSET = 1
- property active: bool
Return if the text input field is active.
An active text input field will show a caret and accept text input.
- on_change(event: UIOnChangeEvent)[source]
Event handler for text change.
- on_event(event: UIEvent) bool | None [source]
Handle events for the text input field.
Text input is only active when the user clicks on the input field.
- property text
Text of the input field.
- class arcade.gui.UITextArea(*, x: float = 0, y: float = 0, width: float = 400, height: float = 40, text: str = '', font_name=('arial', 'calibri'), font_size: float = 12, bold=False, italic=False, 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, document_mode: Literal['PLAIN', 'ATTRIBUTED', 'HTML'] = 'PLAIN', **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.
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
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.
document_mode – Mode of the document. Can be “PLAIN”, “ATTRIBUTED”, or “HTML”. PLAIN will decode the text as plain text, ATTRIBUTED and HTML will decode the text as pyglet documents here https://pyglet.readthedocs.io/en/latest/programming_guide/text.html
**kwargs – passed to
UIWidget
.
- property text
Text of the text area.
- 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).
- Parameters:
x – x coordinate of bottom left
y – y coordinate of bottom left
width – Width of the button.
height – Height of the button.
on_texture – Texture to show when the button is on.
off_texture – Texture to show when the button is off.
value – Initial value of the button.
size_hint – Size hint for the layout.
size_hint_min – Minimum size hint for the layout.
size_hint_max – Maximum size hint for the layout.
- on_change(event: UIOnChangeEvent)[source]
To be implemented by the user, triggered when the cursor’s value is changed.
- Parameters:
event – Event containing the old and new value of the cursor.
- on_click(event: UIOnClickEvent)[source]
Change the value of the button on click.
- 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
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.UIImage(*, texture: Texture | NinePatchTexture, width: float | None = None, height: float | None = None, angle: int = 0, alpha: int = 255, **kwargs)[source]
Bases:
UIWidget
UIWidget showing a texture.
If no size given, the texture size is used.
The UIImage supports rotation and alpha values, which only apply to the texture. Border, and background color are not affected by this. The size of the image is reduced when rotated to stay within bounce of the widget.
- Parameters:
texture – Texture to show
width – width of widget
height – height of widget
angle – angle of the texture in degrees
alpha – alpha value of the texture, value between 0 and 255
**kwargs – passed to UIWidget
- alpha
Alpha value of the texture, value between 0 and 255. 0 is fully transparent, 255 is fully visible.
- angle
Angle of the texture in degrees. The image will be rotated around its center and fitted into the widget size.
- texture
Texture to show