Actor > Widgets

Use Button when a widget should simply send a message.

API Reference

Button

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

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 with 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

toolbar = Toolbar()
start_button = Button("Start")
toolbar.add(start_button)
world.camera.add_right(toolbar)

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

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

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

Return type:

None

Examples

button = Button("Start Rocket")

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

Label

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

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

toolbar = Toolbar()
score_label = Label("Score: 0")
toolbar.add(score_label)
world.camera.add_right(toolbar)

__init__(text, image=None)

Create a label widget.

Parameters:

• text – The text displayed by the label.

• image – Optional image path.

Input

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

Text input field for use inside a Toolbar.

Click into the field to focus it, then type to enter text. The text cursor can be moved with the arrow keys; BACKSPACE deletes the character left of the cursor and DELETE the character right of the cursor. At most max_chars characters can be entered.

While the input has focus, the text cursor blinks; without focus, the cursor is hidden.

Examples

toolbar = Toolbar()
name_input = Input((0, 0))
name_input.max_chars = 20
toolbar.add(name_input)
world.camera.add_right(toolbar)

property cursor_position

property max_chars

on_focus()

on_focus_lost()

on_key_down(keys)

Called once when a key is pressed.

Register on_key_down_<letter> (for example on_key_down_a) if you want to react to a specific letter only.

For arrow keys use on_key_down_left, on_key_down_right, on_key_down_up, or on_key_down_down.

Parameters:

key – List of key name variants, for example [“A”, “a”] or [“left”].

Examples

@player.register
def on_key_down(self, key):
    if "left" in key:
        self.direction = "left"
    elif "right" in key:
        self.direction = "right"
    self.move()

@player.register
def on_key_down_space(self):
    self.send_message("jump")

on_text_input(text)

Inserts composed text (including umlauts and spaces) at the cursor.

Printable characters arrive through the text_input event, so key names like “SPACE” are never inserted as literal text.

set_text(text)

Sets text of widget.

int and float values are converted to string.

update_cursor()

YesNoButton

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

A widget with a yes and a no button side by side.

Use get_yes_button() and get_no_button() to access the two buttons, e.g. to style them or to register custom click handlers.

Parameters:

• yes_text – Label of the yes button.

• no_text – Label of the no button.

Examples

toolbar = Toolbar()
choice = YesNoButton("Yes", "No")
choice.get_yes_button().background_color = (0, 255, 0)
toolbar.add(choice)

get_no_button()

get_yes_button()

CounterLabel

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

A counter label contains a description and a counter.

The counter starts with value 0 and can be modified with add and sub.

add(value)

Increase the counter by value.

get_value()

set(value)

sub(value)

Decrease the counter by value.

update_text()

FPSLabel

class miniworlds.actors.widgets.fps.FPSLabel(world=None, text='FPS', img_path=None)

Label that displays the measured frames per second.

The label measures the time between two frames itself; no clock object is required. Add it to a Toolbar so that it is updated once per frame.

Parameters:

• world – Optional world (ignored; kept for backward compatibility).

• text – Prefix displayed before the measured value.

• img_path – Optional path to an image shown alongside the text.

Examples

toolbar = Toolbar()
toolbar.add(FPSLabel(text="FPS"))
world.camera.add_right(toolbar)

TimeLabel

class miniworlds.actors.widgets.time.TimeLabel(world=None, text='Time', img_path=None)

Label that displays the current frame number of a world.

Parameters:

• world – The world whose frame counter is displayed. If no world is given, the world the widget is added to is used.

• text – Prefix displayed before the frame number.

• img_path – Optional path to an image shown alongside the text.

Examples

toolbar = Toolbar()
toolbar.add(TimeLabel(world, text="Frame"))
world.camera.add_right(toolbar)