🍄 docs: Add specification for LCB widget signals and events.

[peter-b]

Initial draft of specification for revised LiveCode Builder signal and event subsystem.

Rendered version

Unresolved issues:

• [x] What happens when an event handler blocks/waits in the "dispatch" phase (possibly indefinitely)?
• [x] Relationship with LCS before and after handlers
• [ ] More / better examples

[peter-b]

@trevordevore @montegoulding @livecodeali @livecodefraser @runrevmark

I'd appreciate some prompt feedback, please, since getting this sorted is blocking LiveCode 8 RC 1.

[peter-b]

@montegoulding @trevordevore I've been thinking about the possibility (and was discussing with @livecodeali earlier today) the possibility of simplifying the events & signals stuff a bit more.

At the moment, we’re assuming that signal and event handling is based on a textual match between handler name and signal name. However, there are going to be a whole host of “standard” signals that widgets are going to want to reuse, such as clicked and selectionChanged

If we make signals and events first-class types, then it could simplify everything quite a lot.

We can create a library that provides definitions for “standard” signals:

module com.livecode.signals
public signal type Clicked()
…
end module

Widgets that want to emit the signal can then emit it by name in almost exactly the same way:

widget org.example.SignallingWidget
use com.livecode.signals
private handler synthesizeClick()
   emit signal Clicked()
end handler
end widget

And widgets that need to handle the signal can do so in an unambiguous and type-checked fashion, knowing that they’re handling the specific signal that they want to:

widget org.example.ClickReporter
use com.livecode.signals
signal handler for Clicked is ConsumeClick
private handler ConsumeClick()
   log "%@ was clicked!" with [the signal source]
end handler
end widget

Finally, having a standard library of well-known signals provides a useful place to document best practice, and lets composed widget authors more easily know how child widgets are expected to behave.

And so on for events.

[trevordevore]

@peter-b I like this improvement. The lesson work that has to be done for each individual widget the better.

[peter-b]

@trevordevore @montegoulding @runrevmark Here's a new revision, which addresses many of the issues mentioned above. In particular, behaviour w.r.t. blocking operations is now well-defined, and signals and events are now type definitions.