grease.mode – Modal Framework

Modes manage the state and transition between different application modes. Typically such modes are presented as different screens that the user can navigate between, similar to the way a browser navigates web pages. Individual modes may be things like:

• Title screen
• Options dialog
• About screen
• In-progress game
• Inventory interface

The modal framework provides a simple mechanism to ensure that modes are activated and deactivated properly. An activated mode is running and receives events. A deactivated mode is paused and does not receive events.

Modes may be managed as a last-in-first-out stack, or as a list, or ring of modes in sequence, or some combination of all.

For example usage see: the mode section of the tutorial.

class grease.mode.BaseManager

Mode manager abstract base class.

The mode manager keeps a stack of modes where a single mode is active at one time. As modes are pushed on and popped from the stack, the mode at the top is always active. The current active mode receives events from the manager’s event dispatcher.

on_last_mode_pop(mode)

Hook executed when the last mode is popped from the manager. Implementing this method is optional for subclasses.

Parameters:

• mode – The Mode object just popped from the manager

pop_mode()

Pop the current mode off the top of the stack and deactivate it. The mode now at the top of the stack, if any is then activated.

Parameters:

• mode – The Mode object popped from the stack

push_mode(mode)

Push a mode to the top of the mode stack and make it active

Parameters:

• mode – The Mode object to make active

remove_mode(mode)

Remove the specified mode. If the mode is at the top of the stack, this is equivilent to pop_mode(). If not, no other modes are affected. If the mode is not in the manager, do nothing.

Parameters:

• mode – The Mode object to remove from the manager.

swap_modes(mode)

Exchange the specified mode with the mode at the top of the stack. This is similar to popping the current mode and pushing the specified one, but without activating the previous mode on the stack or executing on_last_mode_pop() if there is no previous mode.

Parameters:

• mode – The Mode object that was deactivated and replaced.

current_mode

The current active mode or None. Read-only

event_dispatcher

pyglet.event.EventDispatcher object that the active mode receive events from.

modes

The mode stack sequence. The last mode in the stack is the current active mode. Read-only.

class grease.mode.Manager(event_dispatcher)

A basic mode manager that wraps a single pyglet.event.EventDispatcher object for use by its modes.

class grease.mode.ManagerWindow(*args, **kw)

An integrated mode manager and pyglet window for convenience. The window is the event dispatcher used by modes pushed to this manager.

Constructor arguments are identical to pyglet.window.Window

on_key_press(symbol, modifiers)

Default on_key_press handler(), pops the current mode on ESC

on_last_mode_pop(mode)

Hook executed when the last mode is popped from the manager. When the last mode is popped from a window, an on_close() event is dispatched.

Parameters:

• mode – The Mode object just popped from the manager

class grease.mode.Mode(step_rate=60, master_clock=<pyglet._ModuleProxy object at 0x24cf6b0>, clock_factory=<class 'pyglet.clock.Clock'>)

Application mode abstract base class

Subclasses must implement the step() method

Parameters:

• step_rate – The rate of step() calls per second.
• master_clock – The pyglet.clock.Clock interface used as the master clock that ticks the world’s clock. This defaults to the main pyglet clock.

activate(mode_manager)

Activate the mode for the given mode manager, if the mode is already active, do nothing

The default implementation schedules time steps at step_rate per second, sets the manager and sets the active flag to True.

deactivate(mode_manager)

Deactivate the mode, if the mode is not active, do nothing

The default implementation unschedules time steps for the mode and sets the active flag to False.

step(dt)

Execute a timestep for this mode. Must be defined by subclasses.

Parameters:

• dt (float) – The time delta since the last time step

tick(dt)

Tick the mode’s clock.

Parameters:

• dt (float) – The time delta since the last tick

clock

The pyglet.clock.Clock instance used as this mode’s clock. You should use this clock to schedule tasks for this mode, so they properly respect when the mode is active or inactive

Example:

my_mode.clock.schedule_once(my_cool_function, 4)

manager

The BaseManager that manages this mode

class grease.mode.Multi(*submodes)

A mode with multiple submodes. One submode is active at one time. Submodes can be switched to directly or switched in sequence. If the Multi is active, then one submode is always active.

Multis are useful when modes can switch in an order other than a LIFO stack, such as in “hotseat” multiplayer games, a “wizard” style ui, or a sequence of slides.

Note unlike a normal Mode, a Multi doesn’t have it’s own clock and step_rate. The active submode’s are used instead.

activate(mode_manager)

Activate the Multi for the specified manager. The previously active submode of the Multi is activated. If there is no previously active submode, then the first submode is made active. A Multi with no submodes cannot be activated

activate_next(loop=True)

Activate the submode after the current submode in order. If there is no current submode, the first submode is activated.

Note if there is only one submode, it’s active, and loop is True (the default), then this method does nothing and the subnode remains active.

Parameters:

• loop (bool) – When activate_next() is called when the last submode is active, a True value for loop will cause the first submode to be activated. Otherwise the Multi is removed from its manager.

Returns:

The submode that was activated or None if there is no other submode to activate.

activate_previous(loop=True)

Activate the submode before the current submode in order. If there is no current submode, the last submode is activated.

Note if there is only one submode, it’s active, and loop is True (the default), then this method does nothing and the subnode remains active.

Parameters:

• loop (bool) – When activate_previous() is called when the first submode is active, a True value for loop will cause the last submode to be activated. Otherwise the Multi is removed from its manager.

Returns:

The submode that was activated or None if there is no other submode to activate.

activate_subnode(mode, before=None, index=None)

Activate the specified mode, adding it as a subnode if it is not already. If the mode is already the active submode, do nothing.

Parameters:

• mode – The mode to activate, and add as necesary.
• before – The existing mode to insert the mode before if it is not already a submode. If the mode specified is not a submode, raise ValueError.
• index –

  The place to insert the mode in the mode list if it is not already a submode. Only one of before or index may be specified.

  If the mode is already a submode, the before and index arguments are ignored.

add_submode(mode, before=None, index=None)

Add the submode, but do not make it active.

Parameters:

• mode – The Mode object to add.
• before – The existing mode to insert the mode before. If the mode specified is not a submode, raise ValueError.
• index –

  The place to insert the mode in the mode list. Only one of before or index may be specified.

  If neither before or index are specified, the mode is appended to the end of the list.

deactivate(mode_manager)

Deactivate the Multi for the specified manager. The active_submode, if any, is deactivated.

remove_submode(mode=None)

Remove the submode.

Parameters:

• mode – The submode to remove, if omitted the active submode is removed. If the mode is not present, do nothing. If the mode is active, it is deactivated, and the next mode, if any is activated. If the last mode is removed, the Multi is removed from its manager.

step(dt)

No-op, only the active submode is actually stepped

tick(dt)

Tick the active submode’s clock.

Parameters:

• dt (float) – The time delta since the last tick

active_submode

The currently active submode