1.06 - Menus

To display various information such as a title screen, a dialog box, a HUD (head-up display) or a pause screen, you can use one or several menus.

A menu is an arbitrary Lua table. A menu belongs to a context that may be the current map, the current game, the sol.main table or even another menu. This context is the lifetime of your menu. As long as your menu is active, the engine will call events that are defined in your table, i.e. callback methods like menu:on_started() menu:on_draw(), menu:on_key_pressed(), etc., to notify your menu of something (the player pressed a key, your menu needs to be redrawn, etc.).

If you prefer, you can also make menus without this API. Indeed, the map, game and sol.main APIs already have everything you need, so you can do what you want from there manually. But menus built with the API described on this page are just handy, because they automatically receive events whenever they need to be notified.

Functions of sol.menu

sol.menu.start(context, menu, [on_top])

Starts a menu in a context.

The Solarus engine will then call the appropriate events on your menu until it is stopped.

sol.menu.stop(menu)

Stops a menu previously activated with sol.menu.start().

After this call, the Solarus engine will no longer call events on your menu. But you can restart it later if you want.

Nothing happens is the menu was already stopped or never started.

sol.menu.stop_all(context)

Stops all menus that are currently running in a context.

This function is not often needed since menus are already automatically stopped when their context is closed.

sol.menu.is_started(menu)

Returns whether a table is a currently active menu.

Events of a menu

Events are callback methods automatically called by the engine if you define them.

menu:on_started()

Called when your menu is started.

This event is triggered when you call sol.menu.start().

menu:on_finished()

Called when your menu is stopped.

This event is triggered when you call sol.menu.stop() or when the context of your menu finishes.

menu:on_update()

Called at each cycle of the main loop while your menu is active.

Menus of are updated in the following order:

  1. Map menus (only during a game).
  2. Game menus (only during a game).
  3. Main menus (the more general ones).

When several menus exist in the same context, they are updated from the back one to the front one. You can control this order thanks to the on_top parameter of menu:start() when you start a menu.

Remarks
As this function is called at each cycle, it is recommended to use other solutions when possible, like timers and other events.

menu:on_draw(dst_surface)

Called when your menu has to be redrawn.

Use this event to draw your menu.

Menus of are drawn in the following order:

  1. Map menus (only during a game).
  2. Game menus (only during a game).
  3. Main menus (the more general ones).

When several menus exist in the same context, they are updated from the back one to the front one. You can control this order thanks to the on_top parameter of menu:start() when you start a menu.

menu:on_key_pressed(key, modifiers)

Called when the user presses a keyboard key while your menu is active.

For all keyboard and joypad events, most recent menus are notified first. For example, if some dialog box is shown during the pause menu and appears above that pause menu, it will naturally receive keyboard and joypad events first.

When a menu handles the event, it should return true to make the event stop being propagated. Menus (and other objects) below it won't be not notified. On the contrary, if no script has handled the event, then the engine can handle it with a built-in behavior.

Remarks
This event indicates the raw key pressed. If you want the corresponding character instead (if any), see menu:on_character_pressed().

menu:on_key_released(key, modifiers)

Called when the user releases a keyboard key while your menu is active. Menus on top are notified first.

menu:on_character_pressed(character)

Called when the user enters text while your menu is active. Menus on top are notified first.

Remarks
When a character key is pressed, two events are called: menu:on_key_pressed() (indicating the raw key) and menu:on_character_pressed() (indicating the utf-8 character). If your menu needs to input text from the user, menu:on_character_pressed() is what you want because it considers the keyboard's layout and gives you international utf-8 strings.

menu:on_joypad_button_pressed(button)

Called when the user presses a joypad button while your menu is active. Menus on top are notified first.

menu:on_joypad_button_released(button)

Called when the user releases a joypad button while your menu is active. Menus on top are notified first.

menu:on_joypad_axis_moved(axis, state)

Called when the user moves a joypad axis while your menu is active. Menus on top are notified first.

menu:on_joypad_hat_moved(hat, direction8)

Called when the user moves a joypad hat while your menu is active. Menus on top are notified first.

menu:on_command_pressed(command)

Called during a game when the player presses a game command (a keyboard key or a joypad action mapped to a built-in game behavior). You can use this event to override the normal built-in behavior of the game command. Menus on top are notified first.

Remarks
As the notion of game commands only exist during a game, this event is only called for game menus and map menus.
This event is not triggered if you already handled the underlying low-level keyboard or joypad event.

menu:on_command_released(command)

Called during a game when the player released a game command (a keyboard key or a joypad action mapped to a built-in game behavior). You can use this event to override the normal built-in behavior of the game command. Menus on top are notified first.

Remarks
As the notion of game commands only exist during a game, this event is only called for game menus and map menus.
This event is not triggered if you already handled the underlying low-level keyboard or joypad event.

menu:on_mouse_pressed(button, x, y)

Called when the user presses a mouse button while this menu is active. Menus on top are notified first.

menu:on_mouse_released(button, x, y)

Called when the user releases a mouse button while this menu is active.

menu:on_finger_pressed(finger, x, y, pressure)

Called when the user presses a finger while the menu is running.

menu:on_finger_released(finger, x, y, pressure)

Called when the user releases a finger while the menu is running.

menu:on_finger_moved(finger, x, y, dx, dy, pressure)

Called when the user moves a finger while the menu is running.