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