Actor > Widgets

Use Button when a widget should simply send a message.

Use SaveButton and LoadButton when a world should be saved to or restored from an SQLite database file with one click.

API Reference

Button

class miniworlds.actors.widgets.button.Button(text='', image='')

A clickable button widget for use inside a Toolbar.

When clicked, the button broadcasts its label text as a message to the world. The world (or any actor) can react to this message via on_message.

Parameters:

• text – The label text shown on the button. This same text is sent as a message when the button is clicked.

• image – Optional path to an image shown on the button.

Examples

from miniworlds import *
world = World(200, 300)
toolbar = Toolbar()
start_btn = Button("Start")
toolbar.add(start_btn)
world.camera.add_right(toolbar)

@world.register
def on_message(self, message):
    if message == "Start":
        print("Game started!")

world.run()

Public Data Attributes:

Inherited from SingleWidget

padding_left
padding_right
padding_top
padding_bottom
position	The position of the actor as Position(x, y)
topleft	Top-left position of the actor in world coordinates.
center	Center position of the actor in world coordinates.
row_height
text_align	Defines how text is aligned.
text	The text which is displayed on the widget.

Inherited from BaseWidget

padding_left
padding_right
padding_top
padding_bottom
position	The position of the actor as Position(x, y)
topleft	Top-left position of the actor in world coordinates.
center	Center position of the actor in world coordinates.
row_height

Inherited from ParentActor

visible	Whether the actor is currently visible.
layer	Defines the layer on which the actor is drawn if several actors overlap.

Inherited from Actor

actor_count
class_image
origin	Current origin mode used for size and position operations.
collision_type	collision_type specifies how collisions should be checked:
is_blockable	A actor with the property is_blockable cannot move through actors with the property is_blocking.
is_blocking	A actor with the property is_blockable cannot move through actors with the property is_blocking.
layer	Defines the layer on which the actor is drawn if several actors overlap.
last_position	Actor position in last frame
last_direction	Direction value from the previous frame.
costume_count	Returns number of costumes of actor, 0 if actor has no costume
is_flipped	Whether the actor costume is mirrored on the horizontal axis.
costume	Gets the costume of the actor, if available.
costumes	Gets the costume manager
orientation	Costume orientation offset in degrees.
direction	Directions are handled exactly as in the Scratch programming language, see: Scratch Wiki
direction_at_unit_circle	Gets the direction as value in unit circle (0° right, 90° top, 180° left...)
size	Size of the actor
width	The width of the actor in pixels.
height	The height of the actor in pixels.
x	The x-value of a actor
y	The y-value of a actor
class_name	Class name of this actor instance.
topleft_x	x-value of actor topleft-position
topleft_y	y-value of actor topleft-position
topleft	Top-left position of the actor in world coordinates.
local_center	x-value of actor center-position inside the current camera-screen
center_x	x-value of actor center-position
center_y	y-value of actor center-position
center	Center position of the actor in world coordinates.
is_rotatable	Defines if the costume of a actor should be rotatable.
static	Should actor react to events? You can turn this option off for additional performance boost.
fill_color	Fill color of the actor as RGBA tuple.
color	Fill color of the actor as RGBA tuple.
is_filled	Is actor filled with color?
border_color	Border color as RGBA tuple.
stroke_color	Border color as RGBA tuple.
border	Border width of the actor.
visible	Whether the actor is currently visible.
world	World this actor belongs to.
image	The image of the actor:
position	The position of the actor as Position(x, y)

Inherited from ActorBase

dirty	If actor is dirty, it will be repainted.
rect	The surrounding Rectangle as pygame.Rect.
position_manager
sensor_manager
costume_manager

Inherited from DirtySprite

visible	You can make this sprite disappear without removing it from the group assign 0 for invisible and 1 for visible
layer	Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Inherited from Sprite

image
rect
layer	Dynamic, read only property for protected _layer attribute.

Public Methods:

__init__([text, image])	Creates a toolbar button.
on_clicked_left(mouse_pos)	Called when the button is clicked.
act()	Counts down the short click cooldown.

Inherited from SingleWidget

__init__([position])
resize()
cut_widget_text()
update_positions()
get_local_pos(position)
set_row_height([value])
set_border([color, width])	Sets the widget border color and width.
set_position(value)	Set actor position in world coordinates.
set_world(new_world)	Move the actor to another world and return the actor.
get_widget_text()
set_image(_img_source)	sets image of widget
set_text(text)	Sets text of widget.
get_text()

Inherited from BaseWidget

__init__([position])
new_costume()	Create and attach a new empty costume to this actor.
resize()
update_positions()
get_local_pos(position)
set_row_height(value)
set_border([color, width])	Sets the widget border color and width.
set_world(new_world)	Move the actor to another world and return the actor.
set_position(value)	Set actor position in world coordinates.

Inherited from ParentActor

__init__(position[, children])
add_child(actor)
set_layer(value)
set_world(new_world)	Move the actor to another world and return the actor.
reset_costumes()	Remove all costumes and reset appearance state.
before_remove()	Hook called immediately before the actor is removed from the world.

Inherited from Actor

__init__([position])
switch_origin(value)	Switch actor origin while preserving the visual on-screen position.
create_on_world(world)	Creates a actor to a specific world
from_topleft(topleft_position, *args, **kwargs)	Create an actor whose origin is interpreted as top-left.
from_center(center_position, *args, **kwargs)	Create an actor whose origin is interpreted as center.
flip_x()	Flips the actor by 180° degrees.
add_costume([source])	Adds a new costume to actor.
add_costumes(sources)	Adds multiple costumes
remove_costume([source])	Removes a costume from actor
switch_costume(source)	Switches the costume of actor
set_costume(costume)	Set the current costume from an index, source, or appearance object.
reset_costumes()	Remove all costumes and reset appearance state.
set_background_color(color)	Set a background color behind the actor costume image.
next_costume()	Switches to the next costume of actor
has_costume()	Return True when the actor currently has a costume.
turn_left([degrees])	Turns actor by degrees degrees left :rtype: int
turn_right([degrees])	Turns actor by degrees degrees right
set_direction(direction)	Actor points in given direction.
point_towards_position(destination)	Actor points towards a given position
point_towards_actor(other)	Actor points towards another actor.
set_size(value)	Set actor size as (width, height) in pixels.
scale_width(value)	Scale actor width by a factor.
scale_height(value)	Scale actor height by a factor.
move([distance, direction])	Moves actor distance steps in current direction
move_vector(vector)	Moves actor in direction defined by the vector
move_back(distance)	Moves the actor backward by distance steps (opposite of current direction).
undo_move()	Undo the last move.
move_towards(target)	Move one step toward a target actor or position.
move_in_direction(direction[, distance])	Moves actor distance steps into a direction or towards a position
move_to(position)	Moves actor distance to a specific world_posiition
remove([kill])	Removes this actor from world
before_remove()	Hook called immediately before the actor is removed from the world.
bounce_from_border(borders)	The actor "bounces" from a border.
detect_all([actors, direction, distance])	Detects if actors are on actor position.
detect(*args, **kwargs)	Detects if actors are on actor position.
detect_borders([distance])	Detects borders
detect_left_border()	Does the actor touch the left border?
detect_right_border()	Does the actor touch the right border?
detect_top_border()	Does the actor touch the top border?
detecting_bottom_border()	Does the actor touch the lower border?
detect_color([color])	Detects colors in world-background at actor center-position
detect_color_at([direction, distance])	Detects colors in world-background at actor-position
detect_actors_at([direction, distance, actors])	Detects a actor in given direction and distance.
detect_actor_at([direction, distance, actors])	Detect and return the first actor at a given direction and distance.
detect_actors_in_front([actors, distance])	Detect all actors directly in front of this actor.
detect_actor_in_front([actors, distance])	Detect and return the first actor directly in front.
detect_point(position)	Is the actor colliding with a specific (global) point?
detect_pixel(position)	Is the actor colliding with a pixel?
detect_rect(rect)	Is the actor colliding with a static rect?
is_inside_world()	Checks whether the actor is completely inside the world boundaries.
bounce_from_actor(other)	Reflect movement direction when colliding with another actor.
animate([speed])	Animate the current costume with the given speed.
animate_costume(costume[, speed])	Animate a specific costume with the given speed.
animate_loop([speed])	Animates a costume with a looping animation
stop_animation()	Stops current animation.
send_message(message)	Sends a message to world.
on_key_down(key)	Called once when a key is pressed.
on_key_pressed(key)	Called repeatedly every frame while a key is held down.
on_key_up(key)	Called once when a previously pressed key is released.
on_mouse_over(position)	Called when the mouse cursor enters or moves over the actor area.
on_mouse_leave(position)	Called when the mouse cursor leaves the actor area.
on_mouse_left_down(position)	Called when the left mouse button is pressed down.
on_mouse_right_down(position)	Called when the right mouse button is pressed down.
on_mouse_left(position)	Called when the left mouse button is clicked.
on_mouse_right(position)	Called when the right mouse button is clicked.
on_mouse_motion(position)	Called when the mouse moves.
on_mouse_left_released(position)	Method is called when left mouse key is released.
on_mouse_right_released(position)	Method is called when right mouse key is released.
on_clicked_left(position)	The mouse is on top of a actor and mouse was clicked.
on_clicked_right(position)	The mouse is on top of a actor and mouse was clicked.
on_detecting_world()	on_detecting_world is called, when actor is on the world
on_not_detecting_world()	Called when the actor is not touching the world (i.e. outside world bounds).
on_detecting_actor(actor)	on_detecting_actor is called, when actor is detects a actor on same position
on_detecting_borders(borders)	on_detecting_border is called, when actor is near a border
fill(value)	Set fill color for borders and lines
hide()	Hides a actor (the actor will be invisible)
show()	Displays a actor ( an invisible actor will be visible)
register_sensor(*args, **kwargs)	This method is used for the @register_sensor decorator.
get_local_rect()	Return actor rect in camera-local coordinates.
set_world(new_world)	Move the actor to another world and return the actor.
new_costume()	Create and attach a new empty costume to this actor.
set_position(value)	Set actor position in world coordinates.
get_distance_to(obj)	Gets the distance to another actor or a position
on_shape_change()	Hook called when actor shape-related properties change.

Inherited from ActorBase

register(method[, force, name])	This method is used for the @register decorator.
register_message(*args, **kwargs)	Registers a method to an object to handle specific on_message events.
__str__()	Return str(self).
get_costume_class()

Inherited from DirtySprite

__init__(*groups)
__repr__()	Return repr(self).

Inherited from Sprite

__init__(*groups)
add(*groups)	add the sprite to groups
remove(*groups)	remove the sprite from groups
add_internal(group)	For adding this sprite to a group internally.
remove_internal(group)	For removing this sprite from a group internally.
update(*args, **kwargs)	method to control sprite behavior
kill()	remove the Sprite from all Groups
groups()	list of Groups that contain this Sprite
alive()	does the sprite belong to any groups
__repr__()	Return repr(self).

Private Data Attributes:

_abc_impl

Inherited from SingleWidget

_abc_impl

Inherited from BaseWidget

_abc_impl

Inherited from ParentActor

_abc_impl

Inherited from Actor

_abc_impl
__image
__rect

Inherited from ActorBase

_abc_impl
__image
__rect

Private Methods:

Inherited from Actor

_get_initialization_facade()
_get_appearance_facade()
_get_event_facade()
_get_sensor_facade()
_get_movement_facade()
_get_size_facade()
_validate_arguments(position, *args, **kwargs)

Inherited from ActorBase

_is_actor_repainted()

Inherited from DirtySprite

_set_visible(val)	set the visible value (0 or 1) and makes the sprite dirty
_get_visible()	return the visible value of that sprite

---

__init__(text='', image='')

Creates a toolbar button.

Parameters:

• text – The button label and the message that will be sent on click.

• image – Optional image path for the button.

act()

Counts down the short click cooldown.

The cooldown prevents the button from sending the same message several times in a few frames while the mouse button is still held down.

Return type:

None

on_clicked_left(mouse_pos)

Called when the button is clicked.

By default, a message with the button text is then sent to the world.

Examples: :rtype: None

Send a event on button-click:

toolbar = Toolbar()
button = Button("Start Rocket")
button.world = toolbar
world.camera.add_right(toolbar)

@world.register
def on_message(self, message):
    if message == "Start Rocket":
        rocket.started = True

SaveButton

class miniworlds.actors.widgets.save.SaveButton(world, text, filename=None, img_path=None)

Button widget that saves the active world to a sqlite database file.

Public Data Attributes:

Inherited from Button

fixed_width
children
actor_count
class_image

Inherited from SingleWidget

padding_left
padding_right
padding_top
padding_bottom
position	The position of the actor as Position(x, y)
topleft	Top-left position of the actor in world coordinates.
center	Center position of the actor in world coordinates.
row_height
text_align	Defines how text is aligned.
text	The text which is displayed on the widget.
fixed_width
children
actor_count
class_image

Inherited from BaseWidget

padding_left
padding_right
padding_top
padding_bottom
position	The position of the actor as Position(x, y)
topleft	Top-left position of the actor in world coordinates.
center	Center position of the actor in world coordinates.
row_height
fixed_width
children
actor_count
class_image

Inherited from ParentActor

visible	Whether the actor is currently visible.
layer	Defines the layer on which the actor is drawn if several actors overlap.
children
actor_count
class_image

Inherited from Actor

actor_count
class_image
origin	Current origin mode used for size and position operations.
collision_type	collision_type specifies how collisions should be checked:
is_blockable	A actor with the property is_blockable cannot move through actors with the property is_blocking.
is_blocking	A actor with the property is_blockable cannot move through actors with the property is_blocking.
layer	Defines the layer on which the actor is drawn if several actors overlap.
last_position	Actor position in last frame
last_direction	Direction value from the previous frame.
costume_count	Returns number of costumes of actor, 0 if actor has no costume
is_flipped	Whether the actor costume is mirrored on the horizontal axis.
costume	Gets the costume of the actor, if available.
costumes	Gets the costume manager
orientation	Costume orientation offset in degrees.
direction	Directions are handled exactly as in the Scratch programming language, see: Scratch Wiki
direction_at_unit_circle	Gets the direction as value in unit circle (0° right, 90° top, 180° left...)
size	Size of the actor
width	The width of the actor in pixels.
height	The height of the actor in pixels.
x	The x-value of a actor
y	The y-value of a actor
class_name	Class name of this actor instance.
topleft_x	x-value of actor topleft-position
topleft_y	y-value of actor topleft-position
topleft	Top-left position of the actor in world coordinates.
local_center	x-value of actor center-position inside the current camera-screen
center_x	x-value of actor center-position
center_y	y-value of actor center-position
center	Center position of the actor in world coordinates.
is_rotatable	Defines if the costume of a actor should be rotatable.
static	Should actor react to events? You can turn this option off for additional performance boost.
fill_color	Fill color of the actor as RGBA tuple.
color	Fill color of the actor as RGBA tuple.
is_filled	Is actor filled with color?
border_color	Border color as RGBA tuple.
stroke_color	Border color as RGBA tuple.
border	Border width of the actor.
visible	Whether the actor is currently visible.
world	World this actor belongs to.
image	The image of the actor:
position	The position of the actor as Position(x, y)

Inherited from ActorBase

dirty	If actor is dirty, it will be repainted.
rect	The surrounding Rectangle as pygame.Rect.
position_manager
sensor_manager
costume_manager

Inherited from DirtySprite

visible	You can make this sprite disappear without removing it from the group assign 0 for invisible and 1 for visible
layer	Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Inherited from Sprite

image
rect
layer	Dynamic, read only property for protected _layer attribute.

Public Methods:

__init__(world, text[, filename, img_path])	Creates a toolbar button.
on_mouse_left_down(mouse_pos)	Open a save dialog if needed and store the active world in a database file.

Inherited from Button

__init__([text, image])	Creates a toolbar button.
on_clicked_left(mouse_pos)	Called when the button is clicked.
act()	Counts down the short click cooldown.

Inherited from SingleWidget

__init__([position])
resize()
cut_widget_text()
update_positions()
get_local_pos(position)
set_row_height([value])
set_border([color, width])	Sets the widget border color and width.
set_position(value)	Set actor position in world coordinates.
set_world(new_world)	Move the actor to another world and return the actor.
get_widget_text()
set_image(_img_source)	sets image of widget
set_text(text)	Sets text of widget.
get_text()

Inherited from BaseWidget

__init__([position])
new_costume()	Create and attach a new empty costume to this actor.
resize()
update_positions()
get_local_pos(position)
set_row_height(value)
set_border([color, width])	Sets the widget border color and width.
set_world(new_world)	Move the actor to another world and return the actor.
set_position(value)	Set actor position in world coordinates.

Inherited from ParentActor

__init__(position[, children])
add_child(actor)
set_layer(value)
set_world(new_world)	Move the actor to another world and return the actor.
reset_costumes()	Remove all costumes and reset appearance state.
before_remove()	Hook called immediately before the actor is removed from the world.

Inherited from Actor

__init__([position])
switch_origin(value)	Switch actor origin while preserving the visual on-screen position.
create_on_world(world)	Creates a actor to a specific world
from_topleft(topleft_position, *args, **kwargs)	Create an actor whose origin is interpreted as top-left.
from_center(center_position, *args, **kwargs)	Create an actor whose origin is interpreted as center.
flip_x()	Flips the actor by 180° degrees.
add_costume([source])	Adds a new costume to actor.
add_costumes(sources)	Adds multiple costumes
remove_costume([source])	Removes a costume from actor
switch_costume(source)	Switches the costume of actor
set_costume(costume)	Set the current costume from an index, source, or appearance object.
reset_costumes()	Remove all costumes and reset appearance state.
set_background_color(color)	Set a background color behind the actor costume image.
next_costume()	Switches to the next costume of actor
has_costume()	Return True when the actor currently has a costume.
turn_left([degrees])	Turns actor by degrees degrees left :rtype: int
turn_right([degrees])	Turns actor by degrees degrees right
set_direction(direction)	Actor points in given direction.
point_towards_position(destination)	Actor points towards a given position
point_towards_actor(other)	Actor points towards another actor.
set_size(value)	Set actor size as (width, height) in pixels.
scale_width(value)	Scale actor width by a factor.
scale_height(value)	Scale actor height by a factor.
move([distance, direction])	Moves actor distance steps in current direction
move_vector(vector)	Moves actor in direction defined by the vector
move_back(distance)	Moves the actor backward by distance steps (opposite of current direction).
undo_move()	Undo the last move.
move_towards(target)	Move one step toward a target actor or position.
move_in_direction(direction[, distance])	Moves actor distance steps into a direction or towards a position
move_to(position)	Moves actor distance to a specific world_posiition
remove([kill])	Removes this actor from world
before_remove()	Hook called immediately before the actor is removed from the world.
bounce_from_border(borders)	The actor "bounces" from a border.
detect_all([actors, direction, distance])	Detects if actors are on actor position.
detect(*args, **kwargs)	Detects if actors are on actor position.
detect_borders([distance])	Detects borders
detect_left_border()	Does the actor touch the left border?
detect_right_border()	Does the actor touch the right border?
detect_top_border()	Does the actor touch the top border?
detecting_bottom_border()	Does the actor touch the lower border?
detect_color([color])	Detects colors in world-background at actor center-position
detect_color_at([direction, distance])	Detects colors in world-background at actor-position
detect_actors_at([direction, distance, actors])	Detects a actor in given direction and distance.
detect_actor_at([direction, distance, actors])	Detect and return the first actor at a given direction and distance.
detect_actors_in_front([actors, distance])	Detect all actors directly in front of this actor.
detect_actor_in_front([actors, distance])	Detect and return the first actor directly in front.
detect_point(position)	Is the actor colliding with a specific (global) point?
detect_pixel(position)	Is the actor colliding with a pixel?
detect_rect(rect)	Is the actor colliding with a static rect?
is_inside_world()	Checks whether the actor is completely inside the world boundaries.
bounce_from_actor(other)	Reflect movement direction when colliding with another actor.
animate([speed])	Animate the current costume with the given speed.
animate_costume(costume[, speed])	Animate a specific costume with the given speed.
animate_loop([speed])	Animates a costume with a looping animation
stop_animation()	Stops current animation.
send_message(message)	Sends a message to world.
on_key_down(key)	Called once when a key is pressed.
on_key_pressed(key)	Called repeatedly every frame while a key is held down.
on_key_up(key)	Called once when a previously pressed key is released.
on_mouse_over(position)	Called when the mouse cursor enters or moves over the actor area.
on_mouse_leave(position)	Called when the mouse cursor leaves the actor area.
on_mouse_left_down(position)	Called when the left mouse button is pressed down.
on_mouse_right_down(position)	Called when the right mouse button is pressed down.
on_mouse_left(position)	Called when the left mouse button is clicked.
on_mouse_right(position)	Called when the right mouse button is clicked.
on_mouse_motion(position)	Called when the mouse moves.
on_mouse_left_released(position)	Method is called when left mouse key is released.
on_mouse_right_released(position)	Method is called when right mouse key is released.
on_clicked_left(position)	The mouse is on top of a actor and mouse was clicked.
on_clicked_right(position)	The mouse is on top of a actor and mouse was clicked.
on_detecting_world()	on_detecting_world is called, when actor is on the world
on_not_detecting_world()	Called when the actor is not touching the world (i.e. outside world bounds).
on_detecting_actor(actor)	on_detecting_actor is called, when actor is detects a actor on same position
on_detecting_borders(borders)	on_detecting_border is called, when actor is near a border
fill(value)	Set fill color for borders and lines
hide()	Hides a actor (the actor will be invisible)
show()	Displays a actor ( an invisible actor will be visible)
register_sensor(*args, **kwargs)	This method is used for the @register_sensor decorator.
get_local_rect()	Return actor rect in camera-local coordinates.
set_world(new_world)	Move the actor to another world and return the actor.
new_costume()	Create and attach a new empty costume to this actor.
set_position(value)	Set actor position in world coordinates.
get_distance_to(obj)	Gets the distance to another actor or a position
on_shape_change()	Hook called when actor shape-related properties change.

Inherited from ActorBase

register(method[, force, name])	This method is used for the @register decorator.
register_message(*args, **kwargs)	Registers a method to an object to handle specific on_message events.
__str__()	Return str(self).
get_costume_class()

Inherited from DirtySprite

__init__(*groups)
__repr__()	Return repr(self).

Inherited from Sprite

__init__(*groups)
add(*groups)	add the sprite to groups
remove(*groups)	remove the sprite from groups
add_internal(group)	For adding this sprite to a group internally.
remove_internal(group)	For removing this sprite from a group internally.
update(*args, **kwargs)	method to control sprite behavior
kill()	remove the Sprite from all Groups
groups()	list of Groups that contain this Sprite
alive()	does the sprite belong to any groups
__repr__()	Return repr(self).

Private Data Attributes:

_abc_impl

Inherited from Button

_abc_impl
_visible
_layer
__image
__rect

Inherited from SingleWidget

_abc_impl
_visible
_layer
__image
__rect

Inherited from BaseWidget

_abc_impl
_visible
_layer
__image
__rect

Inherited from ParentActor

_abc_impl
_visible
_layer
__image
__rect

Inherited from Actor

_abc_impl
__image
__rect

Inherited from ActorBase

_abc_impl
__image
__rect

Private Methods:

Inherited from Actor

_get_initialization_facade()
_get_appearance_facade()
_get_event_facade()
_get_sensor_facade()
_get_movement_facade()
_get_size_facade()
_validate_arguments(position, *args, **kwargs)

Inherited from ActorBase

_is_actor_repainted()

Inherited from DirtySprite

_set_visible(val)	set the visible value (0 or 1) and makes the sprite dirty
_get_visible()	return the visible value of that sprite

---

on_mouse_left_down(mouse_pos)

Open a save dialog if needed and store the active world in a database file.

Return type:

None

LoadButton

class miniworlds.actors.widgets.load.LoadButton(world, text, filename=None, img_path=None)

Button widget that loads a world from a sqlite database file.

Public Data Attributes:

Inherited from Button

fixed_width
children
actor_count
class_image

Inherited from SingleWidget

padding_left
padding_right
padding_top
padding_bottom
position	The position of the actor as Position(x, y)
topleft	Top-left position of the actor in world coordinates.
center	Center position of the actor in world coordinates.
row_height
text_align	Defines how text is aligned.
text	The text which is displayed on the widget.
fixed_width
children
actor_count
class_image

Inherited from BaseWidget

padding_left
padding_right
padding_top
padding_bottom
position	The position of the actor as Position(x, y)
topleft	Top-left position of the actor in world coordinates.
center	Center position of the actor in world coordinates.
row_height
fixed_width
children
actor_count
class_image

Inherited from ParentActor

visible	Whether the actor is currently visible.
layer	Defines the layer on which the actor is drawn if several actors overlap.
children
actor_count
class_image

Inherited from Actor

actor_count
class_image
origin	Current origin mode used for size and position operations.
collision_type	collision_type specifies how collisions should be checked:
is_blockable	A actor with the property is_blockable cannot move through actors with the property is_blocking.
is_blocking	A actor with the property is_blockable cannot move through actors with the property is_blocking.
layer	Defines the layer on which the actor is drawn if several actors overlap.
last_position	Actor position in last frame
last_direction	Direction value from the previous frame.
costume_count	Returns number of costumes of actor, 0 if actor has no costume
is_flipped	Whether the actor costume is mirrored on the horizontal axis.
costume	Gets the costume of the actor, if available.
costumes	Gets the costume manager
orientation	Costume orientation offset in degrees.
direction	Directions are handled exactly as in the Scratch programming language, see: Scratch Wiki
direction_at_unit_circle	Gets the direction as value in unit circle (0° right, 90° top, 180° left...)
size	Size of the actor
width	The width of the actor in pixels.
height	The height of the actor in pixels.
x	The x-value of a actor
y	The y-value of a actor
class_name	Class name of this actor instance.
topleft_x	x-value of actor topleft-position
topleft_y	y-value of actor topleft-position
topleft	Top-left position of the actor in world coordinates.
local_center	x-value of actor center-position inside the current camera-screen
center_x	x-value of actor center-position
center_y	y-value of actor center-position
center	Center position of the actor in world coordinates.
is_rotatable	Defines if the costume of a actor should be rotatable.
static	Should actor react to events? You can turn this option off for additional performance boost.
fill_color	Fill color of the actor as RGBA tuple.
color	Fill color of the actor as RGBA tuple.
is_filled	Is actor filled with color?
border_color	Border color as RGBA tuple.
stroke_color	Border color as RGBA tuple.
border	Border width of the actor.
visible	Whether the actor is currently visible.
world	World this actor belongs to.
image	The image of the actor:
position	The position of the actor as Position(x, y)

Inherited from ActorBase

dirty	If actor is dirty, it will be repainted.
rect	The surrounding Rectangle as pygame.Rect.
position_manager
sensor_manager
costume_manager

Inherited from DirtySprite

visible	You can make this sprite disappear without removing it from the group assign 0 for invisible and 1 for visible
layer	Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Inherited from Sprite

image
rect
layer	Dynamic, read only property for protected _layer attribute.

Public Methods:

__init__(world, text[, filename, img_path])	Creates a toolbar button.
on_mouse_left_down(mouse_pos)	Open a file dialog if needed and load the selected database file.

Inherited from Button

__init__([text, image])	Creates a toolbar button.
on_clicked_left(mouse_pos)	Called when the button is clicked.
act()	Counts down the short click cooldown.

Inherited from SingleWidget

__init__([position])
resize()
cut_widget_text()
update_positions()
get_local_pos(position)
set_row_height([value])
set_border([color, width])	Sets the widget border color and width.
set_position(value)	Set actor position in world coordinates.
set_world(new_world)	Move the actor to another world and return the actor.
get_widget_text()
set_image(_img_source)	sets image of widget
set_text(text)	Sets text of widget.
get_text()

Inherited from BaseWidget

__init__([position])
new_costume()	Create and attach a new empty costume to this actor.
resize()
update_positions()
get_local_pos(position)
set_row_height(value)
set_border([color, width])	Sets the widget border color and width.
set_world(new_world)	Move the actor to another world and return the actor.
set_position(value)	Set actor position in world coordinates.

Inherited from ParentActor

__init__(position[, children])
add_child(actor)
set_layer(value)
set_world(new_world)	Move the actor to another world and return the actor.
reset_costumes()	Remove all costumes and reset appearance state.
before_remove()	Hook called immediately before the actor is removed from the world.

Inherited from Actor

__init__([position])
switch_origin(value)	Switch actor origin while preserving the visual on-screen position.
create_on_world(world)	Creates a actor to a specific world
from_topleft(topleft_position, *args, **kwargs)	Create an actor whose origin is interpreted as top-left.
from_center(center_position, *args, **kwargs)	Create an actor whose origin is interpreted as center.
flip_x()	Flips the actor by 180° degrees.
add_costume([source])	Adds a new costume to actor.
add_costumes(sources)	Adds multiple costumes
remove_costume([source])	Removes a costume from actor
switch_costume(source)	Switches the costume of actor
set_costume(costume)	Set the current costume from an index, source, or appearance object.
reset_costumes()	Remove all costumes and reset appearance state.
set_background_color(color)	Set a background color behind the actor costume image.
next_costume()	Switches to the next costume of actor
has_costume()	Return True when the actor currently has a costume.
turn_left([degrees])	Turns actor by degrees degrees left :rtype: int
turn_right([degrees])	Turns actor by degrees degrees right
set_direction(direction)	Actor points in given direction.
point_towards_position(destination)	Actor points towards a given position
point_towards_actor(other)	Actor points towards another actor.
set_size(value)	Set actor size as (width, height) in pixels.
scale_width(value)	Scale actor width by a factor.
scale_height(value)	Scale actor height by a factor.
move([distance, direction])	Moves actor distance steps in current direction
move_vector(vector)	Moves actor in direction defined by the vector
move_back(distance)	Moves the actor backward by distance steps (opposite of current direction).
undo_move()	Undo the last move.
move_towards(target)	Move one step toward a target actor or position.
move_in_direction(direction[, distance])	Moves actor distance steps into a direction or towards a position
move_to(position)	Moves actor distance to a specific world_posiition
remove([kill])	Removes this actor from world
before_remove()	Hook called immediately before the actor is removed from the world.
bounce_from_border(borders)	The actor "bounces" from a border.
detect_all([actors, direction, distance])	Detects if actors are on actor position.
detect(*args, **kwargs)	Detects if actors are on actor position.
detect_borders([distance])	Detects borders
detect_left_border()	Does the actor touch the left border?
detect_right_border()	Does the actor touch the right border?
detect_top_border()	Does the actor touch the top border?
detecting_bottom_border()	Does the actor touch the lower border?
detect_color([color])	Detects colors in world-background at actor center-position
detect_color_at([direction, distance])	Detects colors in world-background at actor-position
detect_actors_at([direction, distance, actors])	Detects a actor in given direction and distance.
detect_actor_at([direction, distance, actors])	Detect and return the first actor at a given direction and distance.
detect_actors_in_front([actors, distance])	Detect all actors directly in front of this actor.
detect_actor_in_front([actors, distance])	Detect and return the first actor directly in front.
detect_point(position)	Is the actor colliding with a specific (global) point?
detect_pixel(position)	Is the actor colliding with a pixel?
detect_rect(rect)	Is the actor colliding with a static rect?
is_inside_world()	Checks whether the actor is completely inside the world boundaries.
bounce_from_actor(other)	Reflect movement direction when colliding with another actor.
animate([speed])	Animate the current costume with the given speed.
animate_costume(costume[, speed])	Animate a specific costume with the given speed.
animate_loop([speed])	Animates a costume with a looping animation
stop_animation()	Stops current animation.
send_message(message)	Sends a message to world.
on_key_down(key)	Called once when a key is pressed.
on_key_pressed(key)	Called repeatedly every frame while a key is held down.
on_key_up(key)	Called once when a previously pressed key is released.
on_mouse_over(position)	Called when the mouse cursor enters or moves over the actor area.
on_mouse_leave(position)	Called when the mouse cursor leaves the actor area.
on_mouse_left_down(position)	Called when the left mouse button is pressed down.
on_mouse_right_down(position)	Called when the right mouse button is pressed down.
on_mouse_left(position)	Called when the left mouse button is clicked.
on_mouse_right(position)	Called when the right mouse button is clicked.
on_mouse_motion(position)	Called when the mouse moves.
on_mouse_left_released(position)	Method is called when left mouse key is released.
on_mouse_right_released(position)	Method is called when right mouse key is released.
on_clicked_left(position)	The mouse is on top of a actor and mouse was clicked.
on_clicked_right(position)	The mouse is on top of a actor and mouse was clicked.
on_detecting_world()	on_detecting_world is called, when actor is on the world
on_not_detecting_world()	Called when the actor is not touching the world (i.e. outside world bounds).
on_detecting_actor(actor)	on_detecting_actor is called, when actor is detects a actor on same position
on_detecting_borders(borders)	on_detecting_border is called, when actor is near a border
fill(value)	Set fill color for borders and lines
hide()	Hides a actor (the actor will be invisible)
show()	Displays a actor ( an invisible actor will be visible)
register_sensor(*args, **kwargs)	This method is used for the @register_sensor decorator.
get_local_rect()	Return actor rect in camera-local coordinates.
set_world(new_world)	Move the actor to another world and return the actor.
new_costume()	Create and attach a new empty costume to this actor.
set_position(value)	Set actor position in world coordinates.
get_distance_to(obj)	Gets the distance to another actor or a position
on_shape_change()	Hook called when actor shape-related properties change.

Inherited from ActorBase

register(method[, force, name])	This method is used for the @register decorator.
register_message(*args, **kwargs)	Registers a method to an object to handle specific on_message events.
__str__()	Return str(self).
get_costume_class()

Inherited from DirtySprite

__init__(*groups)
__repr__()	Return repr(self).

Inherited from Sprite

__init__(*groups)
add(*groups)	add the sprite to groups
remove(*groups)	remove the sprite from groups
add_internal(group)	For adding this sprite to a group internally.
remove_internal(group)	For removing this sprite from a group internally.
update(*args, **kwargs)	method to control sprite behavior
kill()	remove the Sprite from all Groups
groups()	list of Groups that contain this Sprite
alive()	does the sprite belong to any groups
__repr__()	Return repr(self).

Private Data Attributes:

_abc_impl

Inherited from Button

_abc_impl
_visible
_layer
__image
__rect

Inherited from SingleWidget

_abc_impl
_visible
_layer
__image
__rect

Inherited from BaseWidget

_abc_impl
_visible
_layer
__image
__rect

Inherited from ParentActor

_abc_impl
_visible
_layer
__image
__rect

Inherited from Actor

_abc_impl
__image
__rect

Inherited from ActorBase

_abc_impl
__image
__rect

Private Methods:

Inherited from Actor

_get_initialization_facade()
_get_appearance_facade()
_get_event_facade()
_get_sensor_facade()
_get_movement_facade()
_get_size_facade()
_validate_arguments(position, *args, **kwargs)

Inherited from ActorBase

_is_actor_repainted()

Inherited from DirtySprite

_set_visible(val)	set the visible value (0 or 1) and makes the sprite dirty
_get_visible()	return the visible value of that sprite

---

on_mouse_left_down(mouse_pos)

Open a file dialog if needed and load the selected database file.

Return type:

None

Label

class miniworlds.actors.widgets.label.Label(position: Tuple[float, float] | None = (0, 0), *args, **kwargs)

A text label for use in a Toolbar.

Label is usually used for headings, status text, scores, or other information that should be shown inside a toolbar.

Parameters:

• text – The text to display in the label.

• image – Optional path to an image to show instead of (or alongside) text.

Examples

Add a label to a toolbar:

from miniworlds import *
world = World(200, 200)
toolbar = Toolbar()
score_label = Label("Score: 0")
toolbar.add(score_label)
world.camera.add_right(toolbar)
world.run()

Public Data Attributes:

Inherited from Button

fixed_width
children
actor_count
class_image

Inherited from SingleWidget

padding_left
padding_right
padding_top
padding_bottom
position	The position of the actor as Position(x, y)
topleft	Top-left position of the actor in world coordinates.
center	Center position of the actor in world coordinates.
row_height
text_align	Defines how text is aligned.
text	The text which is displayed on the widget.
fixed_width
children
actor_count
class_image

Inherited from BaseWidget

padding_left
padding_right
padding_top
padding_bottom
position	The position of the actor as Position(x, y)
topleft	Top-left position of the actor in world coordinates.
center	Center position of the actor in world coordinates.
row_height
fixed_width
children
actor_count
class_image

Inherited from ParentActor

visible	Whether the actor is currently visible.
layer	Defines the layer on which the actor is drawn if several actors overlap.
children
actor_count
class_image

Inherited from Actor

actor_count
class_image
origin	Current origin mode used for size and position operations.
collision_type	collision_type specifies how collisions should be checked:
is_blockable	A actor with the property is_blockable cannot move through actors with the property is_blocking.
is_blocking	A actor with the property is_blockable cannot move through actors with the property is_blocking.
layer	Defines the layer on which the actor is drawn if several actors overlap.
last_position	Actor position in last frame
last_direction	Direction value from the previous frame.
costume_count	Returns number of costumes of actor, 0 if actor has no costume
is_flipped	Whether the actor costume is mirrored on the horizontal axis.
costume	Gets the costume of the actor, if available.
costumes	Gets the costume manager
orientation	Costume orientation offset in degrees.
direction	Directions are handled exactly as in the Scratch programming language, see: Scratch Wiki
direction_at_unit_circle	Gets the direction as value in unit circle (0° right, 90° top, 180° left...)
size	Size of the actor
width	The width of the actor in pixels.
height	The height of the actor in pixels.
x	The x-value of a actor
y	The y-value of a actor
class_name	Class name of this actor instance.
topleft_x	x-value of actor topleft-position
topleft_y	y-value of actor topleft-position
topleft	Top-left position of the actor in world coordinates.
local_center	x-value of actor center-position inside the current camera-screen
center_x	x-value of actor center-position
center_y	y-value of actor center-position
center	Center position of the actor in world coordinates.
is_rotatable	Defines if the costume of a actor should be rotatable.
static	Should actor react to events? You can turn this option off for additional performance boost.
fill_color	Fill color of the actor as RGBA tuple.
color	Fill color of the actor as RGBA tuple.
is_filled	Is actor filled with color?
border_color	Border color as RGBA tuple.
stroke_color	Border color as RGBA tuple.
border	Border width of the actor.
visible	Whether the actor is currently visible.
world	World this actor belongs to.
image	The image of the actor:
position	The position of the actor as Position(x, y)

Inherited from ActorBase

dirty	If actor is dirty, it will be repainted.
rect	The surrounding Rectangle as pygame.Rect.
position_manager
sensor_manager
costume_manager

Inherited from DirtySprite

visible	You can make this sprite disappear without removing it from the group assign 0 for invisible and 1 for visible
layer	Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Inherited from Sprite

image
rect
layer	Dynamic, read only property for protected _layer attribute.

Public Methods:

__init__(text[, image])

Creates a label widget.

Inherited from Button

__init__([text, image])	Creates a toolbar button.
on_clicked_left(mouse_pos)	Called when the button is clicked.
act()	Counts down the short click cooldown.

Inherited from SingleWidget

__init__([position])
resize()
cut_widget_text()
update_positions()
get_local_pos(position)
set_row_height([value])
set_border([color, width])	Sets the widget border color and width.
set_position(value)	Set actor position in world coordinates.
set_world(new_world)	Move the actor to another world and return the actor.
get_widget_text()
set_image(_img_source)	sets image of widget
set_text(text)	Sets text of widget.
get_text()

Inherited from BaseWidget

__init__([position])
new_costume()	Create and attach a new empty costume to this actor.
resize()
update_positions()
get_local_pos(position)
set_row_height(value)
set_border([color, width])	Sets the widget border color and width.
set_world(new_world)	Move the actor to another world and return the actor.
set_position(value)	Set actor position in world coordinates.

Inherited from ParentActor

__init__(position[, children])
add_child(actor)
set_layer(value)
set_world(new_world)	Move the actor to another world and return the actor.
reset_costumes()	Remove all costumes and reset appearance state.
before_remove()	Hook called immediately before the actor is removed from the world.

Inherited from Actor

__init__([position])
switch_origin(value)	Switch actor origin while preserving the visual on-screen position.
create_on_world(world)	Creates a actor to a specific world
from_topleft(topleft_position, *args, **kwargs)	Create an actor whose origin is interpreted as top-left.
from_center(center_position, *args, **kwargs)	Create an actor whose origin is interpreted as center.
flip_x()	Flips the actor by 180° degrees.
add_costume([source])	Adds a new costume to actor.
add_costumes(sources)	Adds multiple costumes
remove_costume([source])	Removes a costume from actor
switch_costume(source)	Switches the costume of actor
set_costume(costume)	Set the current costume from an index, source, or appearance object.
reset_costumes()	Remove all costumes and reset appearance state.
set_background_color(color)	Set a background color behind the actor costume image.
next_costume()	Switches to the next costume of actor
has_costume()	Return True when the actor currently has a costume.
turn_left([degrees])	Turns actor by degrees degrees left :rtype: int
turn_right([degrees])	Turns actor by degrees degrees right
set_direction(direction)	Actor points in given direction.
point_towards_position(destination)	Actor points towards a given position
point_towards_actor(other)	Actor points towards another actor.
set_size(value)	Set actor size as (width, height) in pixels.
scale_width(value)	Scale actor width by a factor.
scale_height(value)	Scale actor height by a factor.
move([distance, direction])	Moves actor distance steps in current direction
move_vector(vector)	Moves actor in direction defined by the vector
move_back(distance)	Moves the actor backward by distance steps (opposite of current direction).
undo_move()	Undo the last move.
move_towards(target)	Move one step toward a target actor or position.
move_in_direction(direction[, distance])	Moves actor distance steps into a direction or towards a position
move_to(position)	Moves actor distance to a specific world_posiition
remove([kill])	Removes this actor from world
before_remove()	Hook called immediately before the actor is removed from the world.
bounce_from_border(borders)	The actor "bounces" from a border.
detect_all([actors, direction, distance])	Detects if actors are on actor position.
detect(*args, **kwargs)	Detects if actors are on actor position.
detect_borders([distance])	Detects borders
detect_left_border()	Does the actor touch the left border?
detect_right_border()	Does the actor touch the right border?
detect_top_border()	Does the actor touch the top border?
detecting_bottom_border()	Does the actor touch the lower border?
detect_color([color])	Detects colors in world-background at actor center-position
detect_color_at([direction, distance])	Detects colors in world-background at actor-position
detect_actors_at([direction, distance, actors])	Detects a actor in given direction and distance.
detect_actor_at([direction, distance, actors])	Detect and return the first actor at a given direction and distance.
detect_actors_in_front([actors, distance])	Detect all actors directly in front of this actor.
detect_actor_in_front([actors, distance])	Detect and return the first actor directly in front.
detect_point(position)	Is the actor colliding with a specific (global) point?
detect_pixel(position)	Is the actor colliding with a pixel?
detect_rect(rect)	Is the actor colliding with a static rect?
is_inside_world()	Checks whether the actor is completely inside the world boundaries.
bounce_from_actor(other)	Reflect movement direction when colliding with another actor.
animate([speed])	Animate the current costume with the given speed.
animate_costume(costume[, speed])	Animate a specific costume with the given speed.
animate_loop([speed])	Animates a costume with a looping animation
stop_animation()	Stops current animation.
send_message(message)	Sends a message to world.
on_key_down(key)	Called once when a key is pressed.
on_key_pressed(key)	Called repeatedly every frame while a key is held down.
on_key_up(key)	Called once when a previously pressed key is released.
on_mouse_over(position)	Called when the mouse cursor enters or moves over the actor area.
on_mouse_leave(position)	Called when the mouse cursor leaves the actor area.
on_mouse_left_down(position)	Called when the left mouse button is pressed down.
on_mouse_right_down(position)	Called when the right mouse button is pressed down.
on_mouse_left(position)	Called when the left mouse button is clicked.
on_mouse_right(position)	Called when the right mouse button is clicked.
on_mouse_motion(position)	Called when the mouse moves.
on_mouse_left_released(position)	Method is called when left mouse key is released.
on_mouse_right_released(position)	Method is called when right mouse key is released.
on_clicked_left(position)	The mouse is on top of a actor and mouse was clicked.
on_clicked_right(position)	The mouse is on top of a actor and mouse was clicked.
on_detecting_world()	on_detecting_world is called, when actor is on the world
on_not_detecting_world()	Called when the actor is not touching the world (i.e. outside world bounds).
on_detecting_actor(actor)	on_detecting_actor is called, when actor is detects a actor on same position
on_detecting_borders(borders)	on_detecting_border is called, when actor is near a border
fill(value)	Set fill color for borders and lines
hide()	Hides a actor (the actor will be invisible)
show()	Displays a actor ( an invisible actor will be visible)
register_sensor(*args, **kwargs)	This method is used for the @register_sensor decorator.
get_local_rect()	Return actor rect in camera-local coordinates.
set_world(new_world)	Move the actor to another world and return the actor.
new_costume()	Create and attach a new empty costume to this actor.
set_position(value)	Set actor position in world coordinates.
get_distance_to(obj)	Gets the distance to another actor or a position
on_shape_change()	Hook called when actor shape-related properties change.

Inherited from ActorBase

register(method[, force, name])	This method is used for the @register decorator.
register_message(*args, **kwargs)	Registers a method to an object to handle specific on_message events.
__str__()	Return str(self).
get_costume_class()

Inherited from DirtySprite

__init__(*groups)
__repr__()	Return repr(self).

Inherited from Sprite

__init__(*groups)
add(*groups)	add the sprite to groups
remove(*groups)	remove the sprite from groups
add_internal(group)	For adding this sprite to a group internally.
remove_internal(group)	For removing this sprite from a group internally.
update(*args, **kwargs)	method to control sprite behavior
kill()	remove the Sprite from all Groups
groups()	list of Groups that contain this Sprite
alive()	does the sprite belong to any groups
__repr__()	Return repr(self).

Private Data Attributes:

_abc_impl

Inherited from Button

_abc_impl
_visible
_layer
__image
__rect

Inherited from SingleWidget

_abc_impl
_visible
_layer
__image
__rect

Inherited from BaseWidget

_abc_impl
_visible
_layer
__image
__rect

Inherited from ParentActor

_abc_impl
_visible
_layer
__image
__rect

Inherited from Actor

_abc_impl
__image
__rect

Inherited from ActorBase

_abc_impl
__image
__rect

Private Methods:

Inherited from Actor

_get_initialization_facade()
_get_appearance_facade()
_get_event_facade()
_get_sensor_facade()
_get_movement_facade()
_get_size_facade()
_validate_arguments(position, *args, **kwargs)

Inherited from ActorBase

_is_actor_repainted()

Inherited from DirtySprite

_set_visible(val)	set the visible value (0 or 1) and makes the sprite dirty
_get_visible()	return the visible value of that sprite

---

__init__(text, image=None)

Creates a label widget.

Parameters:

• text – The text displayed by the label.

• image – Optional image path.