bear_hug.event module

An event system.

Contains a base event class (BearEvent) and a queue.

All events are added to the queue and passed around to listeners’ on_event methods according to their event_type subscriptions. This happens when dispatcher.dispatch_events() is called, normally every tick. on_event callback may return either nothing, a BearEvent, or a list of BearEvents. If any events are returned, they are added to the queue (preserving the order, if there were multiple events within a single return list).

In order to be processed, an event needs to have a correct event_type. Builtin types are the following:

‘tick’, emitted every tick. event_value stores time since the previous such event.

‘service’, emitted for various events related to the queue or loop functioning. Example event_types are ‘tick_over’ and ‘shutdown’, emitted during the end of tick and for shutting down the queue.

‘key_down’, emitted whenever a key or mouse button is pressed. event_value stores TK code for the button.

‘key_up’, emitted whenever a key or mouse button is released. event_value stores TK code for the button.

‘misc_input’, emitted whenever there is some non-keyboard input, for example mouse movement or game window closed via OS UI. event_value stores TK code for the input event.

‘text_input’, emitted when InputField widget wants to return something. event_value stores the user-entered string.

‘play_sound’, emitted when someone has requested a sound to be played. event_value stores the sound ID.

ECS events:

‘ecs_create’, ‘ecs_add’, ‘ecs_move’,’ecs_collision’, ‘ecs_destroy’, ‘ecs_remove’, ‘ecs_scroll_by’, ‘ecs_scroll_to’, ‘ecs_update’. These are described in detail within bear_hug.ecs_widgets docs.

Any user-defined event_type needs to be registered before use via dispatcher.register_event_type(). Unknown event types can not be added to the queue. Event values, on the other hand, are not validated at all.

class bear_hug.event.BearEvent(event_type='tick', event_value=None)

Bases: object

Event data class.

class bear_hug.event.BearEventDispatcher

Bases: object

The BearEvent queue and dispatcher class.

Stores the events sent to it, then emits them to subscribers in chronological order. To start getting events, a Listener needs to subscribe via dispatcher.register_listener().

register_listener(listener, event_types='all')

Add a listener to this event_dispatcher.

Any object with an on_event method can be added as a listener. This method should accept BearEvent as a single argument and return either nothing, or a single BearEvent, or a list of BearEvents.

To choose event types to subscribe to, event_types kwarg can be set to a string or an iterable of strings. If an iterable, its elements should be event types the listener subscribes to.

If a string, the following rules apply:

1. If a string equals ‘all’, the listener is subscribed to all currently registered event types.

2. Elif a string starts with ‘*’, the listener is subscribed to all currently registered event types for whose type event_types[1:] is a substring (regardless of its position). For example, ‘*ecs’ subscribes to all ECS events, like ‘ecs_add’, ‘ecs_move’, ‘ecs_remove’ and so on; ‘*move’ would subscribe only to ‘ecs_move’ and ‘ecs_remove’.

  1. Else a string is interpreted as a single event type.

Whether in list or string, unregistered event types raise BearLoopException.

Parameters:
  • listener – a listener to add.
  • event_types – event types to which it wants to subscribe
unregister_listener(listener, event_types='all')

Unsubscribe a listener from all or some of its event types.

Parameters:
  • listener – listener to unsubscribe
  • event_types – a list of event types to unsubscribe from or ‘all’. Defaults to ‘all’
register_event_type(event_type)

Add a new event type to be processed by queue.

This makes passing (and subscribing to) a new event type possible. No listeners are automatically subscribed to it, even those that were initially registered with ‘all’ or fitting ‘*’-types.

Parameters:event_type – A string to be used as an event type.
add_event(event)

Add a BearEvent to the queue.

Parameters:event
Returns:
start_queue()

Send the queue initialization event. :return:

dispatch_events()

Dispatch all the events to their listeners.

Whatever they return is added to the queue.

dump_queue()

Remove all events from queue without sending them to their recipients

Returns: