Events

<<JerryI`Misc`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

_String

To create an empty EventObject one can also use

ev = EventObject[]

which is equivalent to

ev = EventObject[<|"Id" -> CreateUUID[]|>]

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

An implementation depends on the executing environment. On WLX pages, or inside notebook this field will represent how an event object will be displayed. Usually if it has been generated by some UI component, a button or a slider is displayed on output, that fires this event remotely 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_}]

warning

Only a single handler function can be assign to an event object per pattern. If you need multiple handlers (chain) to be assigned to the same event and pattern - clone your event firstly using EventClone

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!"];

note

Patterns do not have to be strings only. Any Wolfram Expression is valid

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]

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.