earwax.menus.menu module

Provides the Menu class.

class earwax.menus.menu.Menu(game: Game, title: Union[str, TitleFunction], dismissible: bool = True, item_select_sound_path: Optional[pathlib.Path] = None, item_activate_sound_path: Optional[pathlib.Path] = None, position: int = -1, search_timeout: float = 0.5, search_time: float = 0.0)

Bases: earwax.level.Level, earwax.mixins.TitleMixin, earwax.mixins.DismissibleMixin

A menu of MenuItem instances.

Menus hold multiple menu items which can be activated using actions.

As menus are simply Level subclasses, they can be pushed, popped, and replaced.

To add items to a menu, you can either use the item() decorator, or the add_item() function.

Here is an example of both methods:

from earwax import Game, Level, Menu
from pyglet.window import key, Window
w = Window(caption='Test Game')
g = Game()
l = Level()
@l.action('Show menu', symbol=key.M)
def menu():
    '''Show a menu with 2 items.'''
    m = Menu(g, 'Menu')
    @m.item(title='First Item')
    def first_item():
        g.output('First menu item.')
        g.pop_level()
    def second_item():
        g.output('Second menu item.')
        g.pop_level()
    m.add_item(second_item, title='Second Item')
    g.push_level(m)

g.push_level(l)
g.run(w)

To override the default actions that are added to a menu, subclass earwax.Menu, and override __attrs_post_init__().

Variables:

• item_sound_path –

  The default sound to play when moving through the menu.

  If the selected item’s sound_path attribute is not None, then that value takes precedence.

• items – The list of MenuItem instances for this menu.
• position – The user’s position in this menu.
• search_timeout – The maximum time between menu searches.
• search_time – The time the last menu search was performed.
• search_string – The current menu search search string.

activate() → Optional[Generator[None, None, None]]

Activate the currently focused menu item.

Usually triggered by the enter key.

add_item(func: Callable[[], Optional[Generator[None, None, None]]], **kwargs) → earwax.menus.menu_item.MenuItem

Add an item to this menu.

For example:

m = Menu(game, 'Example Menu')
def f():
    game.output('Menu item activated.')
m.add_item(f, title='Test Item')
m.add_item(f, sound_path=Path('sound.wav'))

If you would rather use decorators, use the item() method instead.

Parameters:

• func – The function which will be called when the menu item is selected.
• kwargs – Extra arguments to be passed to the constructor of earwax.MenuItem.

add_submenu(menu: earwax.menus.menu.Menu, replace: bool, **kwargs) → earwax.menus.menu_item.MenuItem

Add a submenu to this menu.

Parameters:

• menu – The menu to show when the resulting item is activated.
• replace – If True, then the new menu will replace this one in the levels stack.
• kwargs – The additional arguments to pass to add_item().

current_item

Return the currently selected menu item.

If position is -1, return None.

end() → None

Move to the end of a menu.

Usually triggered by the end key.

classmethod from_credits(game: Game, credits: List[earwax.credit.Credit], title: str = 'Game Credits') → Menu

Return a menu for showing credits.

Parameters:

• game – The game to use.
• credits – The credits to show.
• title – The title of the new menu.

home() → None

Move to the start of a menu.

Usually triggered by the home key.

item(**kwargs) → Callable[[Callable[[], Optional[Generator[None, None, None]]]], earwax.menus.menu_item.MenuItem]

Decorate a function to be used as a menu item.

For example:

@menu.item(title='Title')
def func():
    pass

@menu.item(sound_path=Path('sound.wav'))
def item_with_sound():
    pass

If you don’t want to use a decorator, you can use the add_item() method instead.

Parameters:kwargs – Extra arguments to be passed to the constructor of earwax.MenuItem.

make_sound(item: earwax.menus.menu_item.MenuItem, path: pathlib.Path) → earwax.sound.Sound

Return a sound object.

Parameters:

• item –

  The menu item to make the sound for.

  This value is probably current_item.

• path –

  The path to load the sound from.

  This value will have been determined by show_selection(), and may have been loaded from the menu item itself, or the main earwax configuration.

move_down() → None

Move down in this menu.

Usually triggered by the down arrow key.

move_up() → None

Move up in this menu.

Usually triggered by the up arrow key.

on_pop() → None

Destroy select_sound if necessary.

on_push() → None

Handle this menu being pushed.

This method is called when this object has been pushed onto a Game instance.

By default, show the current selection. That will be the same as speaking the title, unless self.position has been set to something other than -1..

on_reveal() → None

Show selection again.

on_text(text: str) → None

Handle sent text.

By default, performs a search of this menu.

Parameters:text – The text that has been sent.

show_selection() → None

Speak the menu item at the current position.

If self.position is -1, this method speaks self.title.

This function performs no error checking, so it will happily throw errors if position is something stupid.

classmethod yes_no(game: Game, yes_action: Callable[[], Optional[Generator[None, None, None]]], no_action: Callable[[], Optional[Generator[None, None, None]]], title: str = 'Are you sure?', yes_label: str = 'Yes', no_label: str = 'No', **kwargs) → Menu

Create and return a yes no menu.

Parameters:

• game – The game to bind the new menu to.
• yes_action – The function to be called if the yes item is selected.
• no_action – The action to be performed if no is selected.
• title – The title of the menu.
• yes_label – The label of the yes item.
• no_label – The title of the no label.
• kwargs – Extra keyword arguments to be passed to the Menu constructor.