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 bepushed
,popped
, andreplaced
.To add items to a menu, you can either use the
item()
decorator, or theadd_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 notNone
, 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.
- item –
-
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 speaksself.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.
- item_sound_path –