Documentation ¶
Overview ¶
Package event propagates events through entities with given caller IDs. It sets up a subscribe-publish model with the Bind and Trigger functions. In a slight change to the sub-pub model, event allows bindings to occur in an explicit order through assigning priority to individual bind calls.
Index ¶
- Constants
- Variables
- func Bind(fn Bindable, name string, callerID int)
- func BindPriority(fn Bindable, opt BindingOption)
- func DestroyEntity(i int)
- func Flush() error
- func FramesElapsed() int
- func GetEntity(i int) interface{}
- func GlobalBind(fn Bindable, name string)
- func HasEntity(i int) bool
- func Reset()
- func ResetEntities()
- func ResolvePending()
- func ScanForEntity(by func(interface{}) bool) (int, interface{})
- func SetTick(framerate int) error
- func Stop() error
- func Trigger(eventName string, data interface{})
- func TriggerBack(eventName string, data interface{}) chan bool
- func UnbindAll(opt BindingOption)
- func UnbindAllAndRebind(bo BindingOption, binds []Bindable, cid int, events []string)
- func UnbindBindable(opt UnbindOption)
- func Update() error
- func UpdateLoop(framerate int, updateCh chan bool) error
- type Bindable
- type BindingOption
- type BindingSet
- type Bus
- func (eb *Bus) Bind(fn Bindable, name string, callerID int)
- func (eb *Bus) BindPriority(fn Bindable, opt BindingOption)
- func (eb *Bus) Flush() error
- func (eb *Bus) FramesElapsed() int
- func (eb *Bus) GlobalBind(fn Bindable, name string)
- func (eb *Bus) Pause()
- func (eb *Bus) Reset()
- func (eb *Bus) ResolvePending()
- func (eb *Bus) Resume()
- 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 bool
- func (eb *Bus) UnbindAll(opt BindingOption)
- func (eb *Bus) UnbindAllAndRebind(bo BindingOption, binds []Bindable, cid int, events []string)
- func (eb *Bus) UnbindBindable(opt UnbindOption)
- func (eb *Bus) Update() error
- func (eb *Bus) UpdateLoop(framerate int, updateCh chan bool) error
- type CID
- func (cid CID) Bind(fn Bindable, name string)
- func (cid CID) BindPriority(fn Bindable, name string, priority int)
- 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) UnbindAll()
- func (cid CID) UnbindAllAndRebind(binds []Bindable, events []string)
- type Caller
- type ConfigHandler
- type Entity
- type Event
- type FullHandler
- type Handler
- type Mapping
- type Pauser
- 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 // Error should be returned by events that in some way // caused an error to happen, but this does not do anything // in the engine right now. Error // 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(int, interface{}) int is easier to write than func(int, interface{}) event.Response. This may yet change.
const ( // Enter : the beginning of every logical frame. // Payload: (int) frames passed since this scene started 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 fo of the viewport changes // Payload: []float64{viewportX, viewportY} ViewportUpdate = "ViewportUpdate" // OnStop: Triggered when the engine is stopped. // Payload: nil OnStop = "OnStop" )
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: (string) the key pressed
- KeyUp, KeyUp$a: when any key is released, when key $a is released. Payload: (string) 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() )
Functions ¶
func BindPriority ¶
func BindPriority(fn Bindable, opt BindingOption)
BindPriority calls BindPriority on the DefaultBus
func DestroyEntity ¶
func DestroyEntity(i int)
DestroyEntity sets the index within the caller list to nil. Note that this does not reduce the size of the caller list, a potential change in the future would be to A) use a map or B) reassign caller ids to not directly correspond to indices within callers
func GetEntity ¶
func GetEntity(i int) interface{}
GetEntity either returns callers[i-1] or nil, if there is nothing at that index.
func GlobalBind ¶
GlobalBind calls GlobalBind on the DefaultBus
func ResetEntities ¶
func ResetEntities()
ResetEntities resets callers and highestID, effectively dropping the remaining entities from accessible memory.
func ScanForEntity ¶
ScanForEntity returns the first created entity that returns true for the given comparator function. If no entity satisfying the condition is found, this returns (-1, nil).
func Trigger ¶
func Trigger(eventName string, data interface{})
Trigger calls Trigger on the DefaultBus
func TriggerBack ¶
TriggerBack calls TriggerBack on the DefaultBus
func UnbindAllAndRebind ¶
func UnbindAllAndRebind(bo BindingOption, binds []Bindable, cid int, events []string)
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 BindingOption ¶
BindingOption is all the information required to bind something. Priority must be between -32 and 32, inclusive.
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 ¶
type Bus struct { Ticker *timing.DynamicTicker // contains filtered or unexported fields }
A Bus stores bindables to be triggered by events
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) BindPriority ¶
func (eb *Bus) BindPriority(fn Bindable, opt BindingOption)
BindPriority is called by entities. Entities pass in a bindable function, and a set of options which are parsed out. Returns a binding that can used to unbind this binding later. The priority given to a binding must be between 32 and -32, inclusive.
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) ResolvePending ¶
func (eb *Bus) ResolvePending()
ResolvePending 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. Todo: this should have a better name 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) SetRefreshRate ¶ added in v2.5.0
SetRefreshRate on the event bus detailing the time to wait per attempt to ResolvePending.
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) UnbindAll ¶
func (eb *Bus) UnbindAll(opt BindingOption)
UnbindAll removes all events that match the given bindingOption from the default event bus
func (*Bus) UnbindAllAndRebind ¶
func (eb *Bus) UnbindAllAndRebind(bo BindingOption, binds []Bindable, cid int, events []string)
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.
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 (always incrementing) and returns it, after adding the given entity to the slice of callers at the returned index.
func (CID) BindPriority ¶
BindPriority on a CID is shorthand for bus.BindPriority(fn, ...), on the default bus.
func (CID) E ¶
func (cid CID) E() interface{}
E is shorthand for GetEntity(int(cid)) But we apparently forgot we added this shorthand, because this isn't used anywhere.
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) 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(Bindable, string) BindPriority(Bindable, string, int) UnbindAll() UnbindAllAndRebind([]Bindable, []string) E() interface{} Parse(Entity) CID }
A Caller can bind, unbind and trigger events.
type ConfigHandler ¶ added in v2.5.0
type ConfigHandler interface { // SetRefreshRate configures how often a running handler will check // for new binding and unbinding requests. SetRefreshRate(time.Duration) }
ConfigHandler contains methods for configuring a running handler. ConfigHandler is a new interface for backwards compatability. TODO: v3: compress this interface into the main handler
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.
type FullHandler ¶
A FullHandler will receive TriggerBack events from the engine when sent (currently only OnStop, when the engine closes)
type Handler ¶
type Handler interface { UpdateLoop(framerate int, updateCh chan bool) error FramesElapsed() int SetTick(framerate int) error Update() error Flush() error Stop() error Reset() Trigger(event string, data interface{}) }
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 ¶
type UnbindOption struct { BindingOption Fn Bindable }
UnbindOption stores information necessary to unbind a bindable