event

package
v3.4.0 Latest Latest
Warning

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

 Go to latest Published: Mar 12, 2022 License: Apache-2.0 Imports: 6 Imported by: 4

Documentation

Overview

Package event provides structures to propagate event occurences to subscribed system entities.

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
	// 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.

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

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(DefaultCallerMap)
)
View Source 
var DefaultCallerMap = NewCallerMap()

DefaultCallerMap is the caller map used by all event package caller functions.

Functions

func Bind 

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

Bind calls Bind on the DefaultBus

func DestroyEntity 

func DestroyEntity(id CID)

DestroyEntity removes an entity from the default caller map.

func Flush 

func Flush() error

Flush calls Flush on the DefaultBus

func FramesElapsed 

func FramesElapsed() int

FramesElapsed calls FramesElapsed on the DefaultBus

func GlobalBind 

func GlobalBind(name string, fn Bindable)

GlobalBind calls GlobalBind on the DefaultBus

func HasEntity 

func HasEntity(id CID) bool

HasEntity returns whether the given caller id is an initialized entity within the default caller map.

func Reset 

func Reset()

Reset calls Reset on the DefaultBus

func ResetCallerMap 

func ResetCallerMap()

ResetCallerMap resets the DefaultCallerMap to be empty.

func ResolveChanges 

func ResolveChanges()

ResolveChanges calls ResolveChanges on the DefaultBus

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 struct{}

TriggerBack calls TriggerBack on the DefaultBus

func UnbindAll 

func UnbindAll(opt Event)

UnbindAll calls UnbindAll on the DefaultBus

func UnbindAllAndRebind 

func UnbindAllAndRebind(bo Event, binds []Bindable, cid CID, 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 struct{}) error

UpdateLoop calls UpdateLoop on the DefaultBus

Types

type Bindable 

type Bindable func(CID, interface{}) int

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

func Empty 

func Empty(f func()) Bindable

Empty is a helper to convert a func() into a Bindable function signature.

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 *time.Ticker
	// contains filtered or unexported fields
}

A Bus stores bindables to be triggered by events

func NewBus 

func NewBus(callerMap *CallerMap) *Bus

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 

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

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) ClearPersistentBindings added in v3.4.0 

func (eb *Bus) ClearPersistentBindings()

ClearPersistentBindings removes all persistent bindings. It will not unbind them from the bus, but they will not be bound following the next bus reset.

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(name string, fn Bindable)

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) PersistentBind added in v3.4.0 

func (eb *Bus) PersistentBind(name string, callerID CID, fn Bindable)

PersistentBind acts like Bind, but persists the binding such that if the event bus is reset, the binding will still trigger. Thes bindings should likely be global bindings, using a CID of 0, or be tolerant to the CID bound not being present after such a clear.

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

func (eb *Bus) Resume()

Resume will resume emitting enter events

func (*Bus) SetCallerMap added in v3.0.1 

func (b *Bus) SetCallerMap(cm *CallerMap)

SetCallerMap updates a bus to use a specific set of callers.

func (*Bus) SetRefreshRate 

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

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

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 struct{}

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 

func (eb *Bus) TriggerCIDBack(cid CID, eventName string, data interface{}) chan struct{}

TriggerCIDBack acts like trigger back, but triggers for a specific cid only.

func (*Bus) UnbindAll 

func (eb *Bus) UnbindAll(opt Event)

UnbindAll removes all events that match the given bindingOption from the default event bus

func (*Bus) UnbindAllAndRebind 

func (eb *Bus) UnbindAllAndRebind(bo Event, binds []Bindable, cid CID, 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 struct{}) 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.

func (*Bus) WaitForEvent 

func (eb *Bus) WaitForEvent(name string) <-chan interface{}

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 

func NextID(e Entity) CID

NextID finds the next available caller id and returns it, after adding the given entity to the default caller map.

func (CID) Bind 

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

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

func (CID) E 

func (cid CID) E() interface{}

E is shorthand for GetEntity(int(cid))

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

func (cid CID) TriggerBus(eventName string, data interface{}, bus Handler) chan struct{}

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 

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(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 

func (cm *CallerMap) DestroyEntity(id CID)

DestroyEntity removes an entity from the caller map.

func (*CallerMap) GetEntity 

func (cm *CallerMap) GetEntity(id CID) Entity

GetEntity returns the entity corresponding to the given ID within the caller map. If no entity is found, it returns nil.

func (*CallerMap) HasEntity 

func (cm *CallerMap) HasEntity(id CID) bool

HasEntity returns whether the given caller id is an initialized entity within the caller map.

func (*CallerMap) NextID 

func (cm *CallerMap) NextID(e Entity) CID

NextID finds the next available caller id and returns it, after adding the given entity to the caller map.

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 

type EnterPayload struct {
	FramesElapsed  int
	SinceLastFrame time.Duration
	TickPercent    float64
}

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.

func GetEntity 

func GetEntity(id CID) Entity

GetEntity returns the entity corresponding to the given ID within the default caller map. If no entity is found, it returns nil.

type Event 

type Event struct {
	Name     string
	CallerID CID
}

An Event is an event name and an associated caller id

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 PersistentBinder added in v3.4.0 

type PersistentBinder interface {
	PersistentBind(string, CID, Bindable)
	ClearPersistentBindings()
}

A PersistentBinder can persist bindings through bus resets

type UnbindAllOption 

type UnbindAllOption struct {
	// contains filtered or unexported fields
}

UnbindAllOption stores information needed to unbind and rebind

type UnbindOption 

type UnbindOption struct {
	Event
	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.