event

package
v2.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 25, 2021 License: Apache-2.0 Imports: 6 Imported by: 4

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

View Source 
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.

View Source 
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

View Source 
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 Bind 

func Bind(fn Bindable, name string, callerID int)

Bind calls Bind on the DefaultBus

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 Flush 

func Flush() error

Flush calls Flush on the DefaultBus

func FramesElapsed 

func FramesElapsed() int

FramesElapsed calls FramesElapsed on the DefaultBus

func GetEntity 

func GetEntity(i int) interface{}

GetEntity either returns callers[i-1] or nil, if there is nothing at that index.

func GlobalBind 

func GlobalBind(fn Bindable, name string)

GlobalBind calls GlobalBind on the DefaultBus

func HasEntity 

func HasEntity(i int) bool

HasEntity returns whether the given caller id is an initialized entity

func Reset 

func Reset()

Reset calls Reset on the DefaultBus

func ResetEntities 

func ResetEntities()

ResetEntities resets callers and highestID, effectively dropping the remaining entities from accessible memory.

func ResolvePending 

func ResolvePending()

ResolvePending calls ResolvePending on the DefaultBus

func ScanForEntity 

func ScanForEntity(by func(interface{}) bool) (int, interface{})

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 SetTick 

func SetTick(framerate int) error

SetTick calls SetTick on the DefaultBus

func Stop 

func Stop() error

Stop calls Stop on the DefaultBus

func Trigger 

func Trigger(eventName string, data interface{})

Trigger calls Trigger on the DefaultBus

func TriggerBack 

func TriggerBack(eventName string, data interface{}) chan bool

TriggerBack calls TriggerBack on the DefaultBus

func UnbindAll 

func UnbindAll(opt BindingOption)

UnbindAll calls UnbindAll 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 Update 

func Update() error

Update calls Update on the DefaultBus

func UpdateLoop 

func UpdateLoop(framerate int, updateCh chan bool) error

UpdateLoop calls UpdateLoop on the DefaultBus

Types

type Bindable 

type Bindable func(int, interface{}) int

Bindable is a way of saying "Any function that takes a generic struct of data and returns an error can be bound".

type BindingOption 

type BindingOption struct {
	Event
	Priority int
}

BindingOption is all the information required to bind something. Priority must be between -32 and 32, inclusive.

type BindingSet 

type BindingSet map[string]Mapping

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 NewBus 

func NewBus() *Bus

NewBus returns an empty event bus

func (*Bus) Bind 

func (eb *Bus) Bind(fn Bindable, name string, callerID int)

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) Flush 

func (eb *Bus) Flush() error

Flush refreshes any changes to the Handler’s bindings.

func (*Bus) FramesElapsed 

func (eb *Bus) FramesElapsed() int

FramesElapsed returns how many frames have elapsed since UpdateLoop was last called.

func (*Bus) GlobalBind 

func (eb *Bus) GlobalBind(fn Bindable, name string)

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) Resume 

func (eb *Bus) Resume()

Resume will resume emitting enter events

func (*Bus) SetRefreshRate added in v2.5.0 

func (eb *Bus) SetRefreshRate(refreshRate time.Duration)

SetRefreshRate on the event bus detailing the time to wait per attempt to ResolvePending.

func (*Bus) SetTick 

func (eb *Bus) SetTick(framerate int) error

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) Stop 

func (eb *Bus) Stop() error

Stop ceases anything spawned by an ongoing UpdateLoop

func (*Bus) Trigger 

func (eb *Bus) Trigger(eventName string, data interface{})

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 

func (eb *Bus) TriggerBack(eventName string, data interface{}) chan bool

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) Update 

func (eb *Bus) Update() error

Update updates all entities bound to this handler

func (*Bus) UpdateLoop 

func (eb *Bus) UpdateLoop(framerate int, updateCh chan bool) error

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 

func NextID(e Entity) CID

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) Bind 

func (cid CID) Bind(fn Bindable, name string)

Bind on a CID is shorthand for bus.Bind(fn, name, cid), on the default bus.

func (CID) BindPriority 

func (cid CID) BindPriority(fn Bindable, name string, priority int)

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 

func (cid CID) Parse(e Entity) CID

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 

func (cid CID) RebindMapping(mapping Mapping)

RebindMapping resets the entity controlling this cid to only have the bindings in the passed in event mapping

func (CID) Trigger 

func (cid CID) Trigger(eventName string, data interface{})

Trigger an event, but only for one ID, on the default bus

func (CID) UnbindAll 

func (cid CID) UnbindAll()

UnbindAll removes all events with the given cid from the event bus

func (CID) UnbindAllAndRebind 

func (cid CID) UnbindAllAndRebind(binds []Bindable, events []string)

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 Event 

type Event struct {
	Name     string
	CallerID int
}

An Event is an event name and an associated caller id

type FullHandler 

type FullHandler interface {
	Handler
	TriggerBack(event string, data interface{}) chan bool
}

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 Pauser 

type Pauser interface {
	Pause()
	Resume()
}

A Pauser is a handler that can be paused.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.