World > Toolbar

Toolbars are regular worlds that are usually docked beside the main world with world.camera.add_right(toolbar) or world.camera.add_bottom(toolbar).

They are especially useful together with buttons, because the active world can react to toolbar actions in on_message.

API Reference

class miniworlds.worlds.gui.toolbar.Toolbar(*args, **kwargs)

A panel that holds buttons, labels, and other widgets.

Toolbars are usually docked beside the main world using world.camera.add_right(toolbar) or world.camera.add_bottom(toolbar). Widgets are added with toolbar.add(widget) (or by simply creating them - they register themselves automatically when their world is set to the toolbar).

When a button inside a toolbar is clicked it broadcasts its label text as a message. The main world responds via on_message.

Examples

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

@world.register
def on_message(self, message):
    if message == "Restart":
        world.reset()

__init__()

Create a toolbar.

Examples

toolbar = Toolbar()
toolbar.add(Button("Start Rocket"))
world.camera.add_right(toolbar)
rocket.started = False

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

@rocket.register
def act(self):
    if self.started:
        self.move()

property background_color

Toolbar background color.

Examples

toolbar.background_color = (255, 255, 255)

Type:

tuple

can_scroll_down(value)

Returns True if the toolbar can scroll downward by value pixels.

Parameters:

value – Number of pixels to scroll by.

Returns:

True if scrolling is possible, False otherwise.

Return type:

bool

can_scroll_up(value)

Returns True if the toolbar can scroll upward by value pixels.

Parameters:

value – Number of pixels to scroll by.

Returns:

True if upward scrolling is possible, otherwise False.

Return type:

bool

dialog

get_widget(key)

Gets widget by key

Return type:

BaseWidget

Parameters:

key – The key of the widget (integer auto key or custom string key).

Returns:

The widget stored under key.

Raises:

KeyError – If no widget with the given key exists.

has_widget(key)

Checks whether the toolbar contains a widget under key.

Parameters:

key – The widget key (integer auto key or custom string key).

Returns:

True if the widget exists, otherwise False.

Return type:

bool

on_change()

Reflows all widgets after the toolbar size or layout has changed.

This keeps widgets aligned when the toolbar is resized or docked in a different place.

on_new_actor(actor)

Handles actors that are added to this toolbar world.

Widget actors are registered in the internal widget list and then resized/reordered so the layout stays consistent.

A widget that is already registered is not registered again: a world transfer can remove and re-add a widget in the same toolbar, and a duplicate entry would render the widget twice and inflate the computed toolbar height.

Parameters:

actor – The actor that has been added.

on_remove_actor(actor)

Handles actors that are removed from this toolbar world.

Widgets can also be removed directly via widget.remove() (not only through Toolbar.remove()); this keeps the internal widget list consistent in that case.

Parameters:

actor – The actor that has been removed.

property padding_bottom

Defines bottom margin

property padding_left

Defines left margin

property padding_right

Defines right margin

property padding_top

Defines top margin

remove(item)

Removes a widget from the toolbar.

The widget is also removed from the toolbar world, so it is no longer rendered and no longer receives events. The camera is clamped to the remaining content, so the view does not stay scrolled past the removed widget.

Parameters:

item – The widget to remove – either the widget object itself, its integer index, or its string key.

Returns:

True if the widget was removed, False if no matching widget or key was found.

Return type:

bool

Warning

Be careful when calling this inside a loop over self.widgets.

remove_all_widgets()

Removes all widgets from the toolbar at once.

The widgets are also removed from the toolbar world. Use this when rebuilding a menu or replacing all controls. The camera is reset to the top of the (now empty) toolbar.

reorder()

Recomputes the positions of all toolbar widgets.

Widgets are stacked from top to bottom with the configured paddings and margins.

scroll_down(value)

Scrolls the toolbar view downward by value pixels.

Parameters:

value – Number of pixels to scroll.

scroll_up(value)

Scrolls the toolbar view upward by value pixels.

Parameters:

value – Number of pixels to scroll.

send_message(text)

Sends a broadcast message to the world and all actors.

The message is dispatched through the event system and can be handled by any registered method in the world or its actors.

Return type:

None

Parameters:

text – The name of the message/event to send.

Example

>>> toolbar.send_message("open_menu")