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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL