Events

EventObject

A complete representation of event-object with its initial data and possible decorative representation

EventObject[<|"Id"->_String, "Initial"->_, "View"->_|>]

Actual binding happens with only "Id" field, therefore a string equivalent is also valid to use. To generate a new unique object, one can also use this constructor

newEvent = EventObject[]

string equivalent

newEvent = CreateUUID[]

To define EventObject with a provided Id

existingEvent = EventObject["eventId"]

string equivalent

existingEvent = "eventId"

"Initial"

Stores initial data, which makes sense if an event object was produced by some sliders, toggle switches or other UI elements.

If an event was joined with other event, "Initial" data will be merged as well depending on its original structure.

If an event object is used in EventFire with no data provided, "Initial" field will be used instead as a payload.

"View"

Provides a view-component which is rendered on output. Usually if it has been generated by some UI component, a button or a slider is displayed on output, that fires event using a provided "Id".

Inheritable properties

There is only a single field "Initial" that can be merged or copied under EventClone and Join or EventJoin operations.

Non-inheritable properties

"Id", "View" cannot be copied under EventJoin, EventClone and Join operations.

EventHandler

Binds an event object represented as a string or EventObject or anything compatible with this type to a single or multiple handling functions (multiple - only if patterns do not intersect)

EventHandler[ev_String | _EventObject, {handlers___Rule | handlers___RuleDelayed}]

where handlers is a sequence of rules (straight or delayed), which are applied to any incoming message. Each rule represents a normal WL pattern to mach a message generated by EventFire.

There is a simpler version as well, which is indifferent to patterns

EventHandler[ev_String | _EventObject, handler_]

which is effectively

EventHandler[ev_String | _EventObject, {_ -> handler_}]

Return value

It is optional, but any handler can return any non-Null expression, which will be presented as a return value of EventFire expression.

Example

The simples case scenario

EventHandler["ev", Print];
EventFire["ev", "Hello World!"];

or using different patterns

EventHandler["ev", {
	"Case 1" -> Print,
	"Case 2" -> Echo,
	any_String :> Function[data, Echo[StringJoin["Undefined case: ", any]]]
}];

EventFire["ev", "Case 1", "Hello World!"];
EventFire["ev", "Case 2", "Hello World!"];
EventFire["ev", "Case 3", "Hello World!"];

EventClone

Clones event object and returns a new one, keeping all previous assigned handlers on another copy of it

EventClone[ev_String | _EventObject] _EventObject

Multiple calls on the same ev makes a chain of new event objects connected to it. Once EventFire is called on ev, it will sequentially fire all cloned events in a chain.

EventRemove

Removes all handlers from a given event object

EventRemove[ev_String | _EventObject]

or

Delete[ev_EventObject]

Remove a specific pattern:

EventRemove[ev_String | _EventObject, pattern_]

is also valid. Removing a cloned event only removes handlers from the cloned event object

EventJoin

Joins two independent events into a new one merging their "Initial" values as well

EventJoin[ev__String | __EventObject] _EventObject

however

Join[ev__EventObject] _EventObject

is also valid.

EventFire

Fires an event with provided data and pattern

EventFire[ev_String | _EventObject, data_] _
EventFire[ev_String | _EventObject, pattern_, data_] _

or for a complete event object representation

EventFire[ev_EventObject] _

it takes "Initial" field as data. Effectively if pattern is not provided "Default" pattern is used instead.