### Navigation

- index
- modules |
- next |
- previous |
- Grease v0.2 documentation »

# `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.

    Parameter: | 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.

    Parameter: | 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

    Parameter: | 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.

    Parameter: | 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.

    Parameter: | 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.

    Parameter: | mode – The `Mode` object just popped from the manager

class `grease.mode.``Mode`(step_rate=60, master_clock=<pyglet._ModuleProxy object at 0x1b482f0>, 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.

    Parameter: | dt (float) – The time delta since the last time step

  `tick`(dt)

    Tick the mode’s clock.

    Parameter: | 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.

    Parameter: | 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.

    Parameter: | 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.

    Parameter: | 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.

    Parameter: | dt (float) – The time delta since the last tick

  `active_submode`
    The currently active submode

### Navigation

- index
- modules |
- next |
- previous |
- Grease v0.2 documentation »