Documentation ¶
Overview ¶
Package event provides structures to propagate event occurences to subscribed system entities.
Index ¶
- Constants
- Variables
- func Bind(name string, callerID CID, fn Bindable)
- func DestroyEntity(id CID)
- func Flush() error
- func FramesElapsed() int
- func GlobalBind(name string, fn Bindable)
- func HasEntity(id CID) bool
- func Reset()
- func ResetCallerMap()
- func ResolveChanges()
- func SetTick(framerate int) error
- func Stop() error
- func Trigger(eventName string, data interface{})
- func TriggerBack(eventName string, data interface{}) chan struct{}
- func UnbindAll(opt Event)
- func UnbindAllAndRebind(bo Event, binds []Bindable, cid CID, events []string)
- func UnbindBindable(opt UnbindOption)
- func Update() error
- func UpdateLoop(framerate int, updateCh chan struct{}) error
- type Bindable
- type BindingSet
- type Bus
- func (eb *Bus) Bind(name string, callerID CID, fn Bindable)
- func (eb *Bus) Flush() error
- func (eb *Bus) FramesElapsed() int
- func (eb *Bus) GlobalBind(name string, fn Bindable)
- func (eb *Bus) Pause()
- func (eb *Bus) Reset()
- func (eb *Bus) ResolveChanges()
- func (eb *Bus) Resume()
- func (b *Bus) SetCallerMap(cm *CallerMap)
- func (eb *Bus) SetRefreshRate(refreshRate time.Duration)
- func (eb *Bus) SetTick(framerate int) error
- func (eb *Bus) Stop() error
- func (eb *Bus) Trigger(eventName string, data interface{})
- func (eb *Bus) TriggerBack(eventName string, data interface{}) chan struct{}
- func (eb *Bus) TriggerCIDBack(cid CID, eventName string, data interface{}) chan struct{}
- func (eb *Bus) UnbindAll(opt Event)
- func (eb *Bus) UnbindAllAndRebind(bo Event, binds []Bindable, cid CID, events []string)
- func (eb *Bus) UnbindBindable(opt UnbindOption)
- func (eb *Bus) Update() error
- func (eb *Bus) UpdateLoop(framerate int, updateCh chan struct{}) error
- func (eb *Bus) WaitForEvent(name string) <-chan interface{}
- type CID
- func (cid CID) Bind(name string, fn Bindable)
- func (cid CID) E() interface{}
- func (cid CID) Parse(e Entity) CID
- func (cid CID) RebindMapping(mapping Mapping)
- func (cid CID) Trigger(eventName string, data interface{})
- func (cid CID) TriggerBus(eventName string, data interface{}, bus Handler) chan struct{}
- func (cid CID) UnbindAll()
- func (cid CID) UnbindAllAndRebind(binds []Bindable, events []string)
- type Caller
- type CallerMap
- type CallerMapper
- type EnterPayload
- type Entity
- type Event
- type Handler
- type Mapping
- type UnbindAllOption
- type UnbindOption
Constants ¶
const ( // NoResponse or 0, is returned by events that // don't want the event bus to do anything with // the event after they have been evaluated. This // is the usual behavior. NoResponse = iota // UnbindEvent unbinds everything for a specific // event name from an entity at the bindable's // priority. UnbindEvent // UnbindSingle just unbinds the one binding that // it is returned from UnbindSingle )
Response types from bindables reponses are not their own type because func(event.CID, interface{}) int is easier to write than func(event.CID, interface{}) event.Response. This may yet change.
const ( // Enter : the beginning of every logical frame. // Payload: (EnterPayload) details on the frame and time since last tick Enter = "EnterFrame" // AnimationEnd: Triggered on animations CIDs when they loop from the last to the first frame // Payload: nil AnimationEnd = "AnimationEnd" // ViewportUpdate: Triggered when the position of of the viewport changes // Payload: intgeom.Point2 ViewportUpdate = "ViewportUpdate" // OnStop: Triggered when the engine is stopped. // Payload: nil OnStop = "OnStop" // FocusGain: Triggered when the window gains focus // Payload: nil FocusGain = "FocusGain" // FocusLoss: Triggered when the window loses focus // Payload: nil FocusLoss = "FocusLoss" // InputChange: triggered when the most recent input device changes (e.g. keyboard to joystick or vice versa) // Payload: oak.InputType InputChange = "InputChange" )
Oak uses the following built in events:
- CollisionStart/Stop: when a PhaseCollision entity starts/stops touching some label. Payload: (collision.Label) the label the entity has started/stopped touching
- MouseCollisionStart/Stop: as above, for mouse collision Payload: (*mouse.Event)
- Mouse events: MousePress, MouseRelease, MouseScrollDown, MouseScrollUp, MouseDrag Payload: (*mouse.Event) details on the mouse event
- KeyDown, KeyDown$a: when any key is pressed down, when key $a is pressed down. Payload: (key.Event) the key pressed
- KeyUp, KeyUp$a: when any key is released, when key $a is released. Payload: (key.Event) the key released
And the following:
Variables ¶
var ( // DefaultBus is a bus that has additional operations for CIDs, and can // be called via event.Call as opposed to bus.Call DefaultBus = NewBus(DefaultCallerMap) )
var DefaultCallerMap = NewCallerMap()
DefaultCallerMap is the caller map used by all event package caller functions.
Functions ¶
func DestroyEntity ¶
func DestroyEntity(id CID)
DestroyEntity removes an entity from the default caller map.
func GlobalBind ¶
GlobalBind calls GlobalBind on the DefaultBus
func HasEntity ¶
HasEntity returns whether the given caller id is an initialized entity within the default caller map.
func Trigger ¶
func Trigger(eventName string, data interface{})
Trigger calls Trigger on the DefaultBus
func TriggerBack ¶
func TriggerBack(eventName string, data interface{}) chan struct{}
TriggerBack calls TriggerBack on the DefaultBus
func UnbindAllAndRebind ¶
UnbindAllAndRebind calls UnbindAllAndRebind on the DefaultBus
func UnbindBindable ¶
func UnbindBindable(opt UnbindOption)
UnbindBindable calls UnbindBindable on the DefaultBus
func UpdateLoop ¶
UpdateLoop calls UpdateLoop on the DefaultBus
Types ¶
type Bindable ¶
Bindable is a way of saying "Any function that takes a generic struct of data and returns an error can be bound".
type BindingSet ¶
A BindingSet stores sets of event mappings bound to string names. The use case for a BindingSet is for a character that can exist in multiple states, so that they can swiftly switch between the event bindings that define those states.
func (BindingSet) Set ¶
func (b BindingSet) Set(setName string, mappingSets ...map[string]Bindable) BindingSet
Set makes a new EventMapping for BindingSet
type Bus ¶
A Bus stores bindables to be triggered by events
func NewBus ¶
NewBus returns an empty event bus with an assigned caller map. If nil is provided, the caller map used will be DefaultCallerMap
func (*Bus) Bind ¶
Bind adds a function to the event bus tied to the given callerID to be called when the event name is triggered. It is equivalent to calling BindPriority with a zero Priority.
func (*Bus) FramesElapsed ¶
FramesElapsed returns how many frames have elapsed since UpdateLoop was last called.
func (*Bus) GlobalBind ¶
GlobalBind binds on the bus to the cid 0, a non entity.
func (*Bus) Pause ¶
func (eb *Bus) Pause()
Pause stops the event bus from running any further enter events
func (*Bus) Reset ¶
func (eb *Bus) Reset()
Reset empties out all transient portions of the bus. It will not stop an ongoing loop.
func (*Bus) ResolveChanges ¶
func (eb *Bus) ResolveChanges()
ResolveChanges is a constant loop that tracks slices of bind or unbind calls and resolves them individually such that they don't break the bus. Each section of the loop waits for the predetermined refreshrate prior to attempting to flush.
If you ask "Why does this not use select over channels, share memory by communicating", the answer is we tried, and it was cripplingly slow.
func (*Bus) SetCallerMap ¶ added in v3.0.1
SetCallerMap updates a bus to use a specific set of callers.
func (*Bus) SetRefreshRate ¶
SetRefreshRate on the event bus detailing the time to wait per attempt to ResolveChanges.
func (*Bus) SetTick ¶
SetTick optionally updates the Logical System’s tick rate (while it is looping) to be frameRate. If this operation is not supported, it should return an error.
func (*Bus) Trigger ¶
Trigger will scan through the event bus and call all bindables found attached to the given event, with the passed in data.
func (*Bus) TriggerBack ¶
TriggerBack is a version of Trigger which returns a channel that informs on when all bindables have been called and returned from the input event. It is dangerous to use this unless you have a very good idea how things will synchronize, as if a triggered bindable itself makes a TriggerBack call, this will cause the engine to freeze, as the function will never end because the first TriggerBack has control of the lock for the event bus, and the first TriggerBack won't give up that lock until the function ends.
This inherently means that when you call Trigger, the event will almost almost never be immediately triggered but rather will be triggered sometime soon in the future.
TriggerBack is right now used by the primary logic loop to dictate logical framerate, so EnterFrame events are called through TriggerBack.
func (*Bus) TriggerCIDBack ¶
TriggerCIDBack acts like trigger back, but triggers for a specific cid only.
func (*Bus) UnbindAll ¶
UnbindAll removes all events that match the given bindingOption from the default event bus
func (*Bus) UnbindAllAndRebind ¶
UnbindAllAndRebind is a way to reset the bindings on a CID efficiently, given a new set of equal length binding and event slices. This is equivalent to calling UnbindAll and then looping over Bind calls for the pairs of bindables and event names, but uses less mutex time.
func (*Bus) UnbindBindable ¶
func (eb *Bus) UnbindBindable(opt UnbindOption)
UnbindBindable is a manual way to unbind a function Bindable. Use of this with closures will result in undefined behavior.
func (*Bus) UpdateLoop ¶
UpdateLoop is expected to internally call Update() or do something equivalent at the given frameRate, sending signals to the sceneCh after each Update(). Any flushing should be done as needed. This should not be called with `go`, if this requires goroutines it should create them itself. UpdateLoop is expected separately from Update() and Flush() because it will be more efficient for a Logical System to perform its own Updates outside of it’s exposed interface.
func (*Bus) WaitForEvent ¶
WaitForEvent will return a single payload from the given event. This makes an internal binding, but that binding will clean itself up regardless of how this is used. This should be used in a select clause to ensure the signal is captured, if the signal comes and the output channel is not being waited on, the channel will be closed.
type CID ¶
type CID int
A CID is a caller ID that entities use to trigger and bind functionality
func NextID ¶
NextID finds the next available caller id and returns it, after adding the given entity to the default caller map.
func (CID) Parse ¶
Parse returns the given cid, or the entity's cid if the given cid is 0. This way, multiple entities can be composed together by passing 0 down to lower tiered constructors, so that the topmost entity is stored once and bind functions will bind to the topmost entity.
func (CID) RebindMapping ¶
RebindMapping resets the entity controlling this cid to only have the bindings in the passed in event mapping
func (CID) TriggerBus ¶
TriggerBus triggers an event with some payload for this cid against the provided bus.
func (CID) UnbindAll ¶
func (cid CID) UnbindAll()
UnbindAll removes all events with the given cid from the event bus
func (CID) UnbindAllAndRebind ¶
UnbindAllAndRebind on a CID is equivalent to bus.UnbindAllAndRebind(..., cid)
type Caller ¶
type Caller interface { Trigger(string, interface{}) Bind(string, Bindable) UnbindAll() UnbindAllAndRebind([]Bindable, []string) E() interface{} Parse(Entity) CID }
A Caller can bind, unbind and trigger events.
type CallerMap ¶
type CallerMap struct {
// contains filtered or unexported fields
}
A CallerMap tracks CID mappings to Entities. Its intended use is to be a source of truth within event bindings for what entity the binding is triggering on:
var cm *event.CallerMap func(cid event.CID, payload interface{}) int { ent := cm.GetEntity(cid) f, ok := ent.(*Foo) if !ok { // bound to an unexpected entity type! return event.UnbindSingle } // ... }
This is an alternative to passing in the entity via closure scoping, and allows for more general bindings as simple top level functions.
func NewCallerMap ¶
func NewCallerMap() *CallerMap
NewCallerMap creates a caller map. A CallerMap is not valid for use if not created via this function.
func (*CallerMap) DestroyEntity ¶
DestroyEntity removes an entity from the caller map.
func (*CallerMap) GetEntity ¶
GetEntity returns the entity corresponding to the given ID within the caller map. If no entity is found, it returns nil.
type CallerMapper ¶ added in v3.0.1
type CallerMapper interface {
SetCallerMap(*CallerMap)
}
A CallerMapper has an internal caller map that can be set.
type EnterPayload ¶
EnterPayload is the payload sent down to Enter bindings
type Entity ¶
type Entity interface {
Init() CID
}
An Entity is an element which can be bound to, in that it has a CID. All Entities need to implement is an Init function which should call NextID(e) and return that id:
func (f *Foo) Init() event.CID { f.CID = event.NextID(f) return f.CID }
In a multi-window setup each window may have its own callerMap, in which case event.NextID should be replaced with a NextID call on the appropriate callerMap.
type Handler ¶
type Handler interface { WaitForEvent(name string) <-chan interface{} // <Handler> UpdateLoop(framerate int, updateCh chan struct{}) error FramesElapsed() int SetTick(framerate int) error Update() error Flush() error Stop() error Reset() SetRefreshRate(time.Duration) // <Triggerer> Trigger(event string, data interface{}) TriggerBack(event string, data interface{}) chan struct{} TriggerCIDBack(cid CID, eventName string, data interface{}) chan struct{} // <Pauser> Pause() Resume() // <Binder> Bind(string, CID, Bindable) GlobalBind(string, Bindable) UnbindAll(Event) UnbindAllAndRebind(Event, []Bindable, CID, []string) UnbindBindable(UnbindOption) }
Handler represents the necessary exported functions from an event.Bus for use in oak internally, and thus the functions that need to be replaced by alternative event handlers.
type Mapping ¶
type Mapping struct {
// contains filtered or unexported fields
}
A Mapping stores a slice of event names and bindings
type UnbindAllOption ¶
type UnbindAllOption struct {
// contains filtered or unexported fields
}
UnbindAllOption stores information needed to unbind and rebind
type UnbindOption ¶
UnbindOption stores information necessary to unbind a bindable