Event

Minigui's event model is based on the web browser. An event has a name, a target, and an associated data object. It starts from the window and works its way down through the target through all intermediate Widgets, triggering capture phase handlers as it goes, then goes back up again all the way back to the window, triggering bubble phase handlers. At the end, if Event.preventDefault has not been called, it calls the target widget's default handlers for the event (please note that default handlers will be called even if Event.stopPropagation was called; that just stops it from calling other handlers in the widget tree, but the default happens whenever propagation is done, not only if it gets to the end of the chain).

This model has several nice points:

• It is easy to delegate dynamic handlers to a parent. You can have a parent container with event handlers set, then add/remove children as much as you want without needing to manage the event handlers on them - the parent alone can manage everything.
• It is easy to create new custom events in your application.
• It is familiar to many web developers.

There's a few downsides though:

• There's not a lot of type safety.
• You don't get a static list of what events a widget can emit.
• Tracing where an event got cancelled along the chain can get difficult; the downside of the central delegation benefit is it can be lead to debugging of action at a distance.

In May 2021, I started to adjust this model to minigui takes better advantage of D over Javascript while keeping the benefits - and most compatibility with - the existing model. The main idea is to simply use a D object type which provides a static interface as well as a built-in event name. Then, a new static interface allows you to see what an event can emit and attach handlers to it similarly to C#, which just forwards to the JS style api. They're fully compatible so you can still delegate to a parent and use custom events as well as using the runtime dynamic access, in addition to having a little more help from the D compiler and documentation generator.

Your code would change like this:

// old
widget.addEventListener("keydown", (Event ev) { ... }, /* optional arg */ useCapture );

// new
widget.addEventListener((KeyDownEvent ev) { ... }, /* optional arg */ useCapture );

The old-style code will still work, but using certain members of the Event class will generate deprecation warnings. Changing handlers to the new style will silence all those warnings at once without requiring any other changes to your code.

All you have to do is replace the string with a specific Event subclass. It will figure out the event string from the class.

Alternatively, you can cast the Event yourself to the appropriate subclass, but it is easier to let the library do it for you!

Thus the family of functions are:

Widget.addEventListener is the fully-flexible base method. It has two main overload families: one with the string and one without. The one with the string takes the Event object, the one without determines the string from the type you pass. The string "*" matches ALL events that pass through.

Widget.addDirectEventListener is addEventListener, but only calls the handler if target == this. Useful for something you can't afford to delegate.

Widget.setDefaultEventHandler is what is called if no preventDefault was called. This should be called in the widget's constructor to set default behaivor. Default event handlers are only called on the event target.

Let's implement a custom widget that can emit a ChangeEvent describing its checked property:

class MyCheckbox : Widget {
	/// This gives a chance to document it and generates a convenience function to send it and attach handlers.
	/// It is NOT actually required but should be used whenever possible.
	mixin Emits!(ChangeEvent!bool);

	this(Widget parent) {
		super(parent);
		setDefaultEventHandler((ClickEvent) { checked = !checked; });
	}

	private bool _checked;
	@property bool checked() { return _checked; }
	@property void checked(bool set) {
		_checked = set;
		emit!(ChangeEvent!bool)(&checked);
	}
}

Creating Your Own Events

To avoid clashing in the string namespace, your events should use your module and class name as the event string. The simple code mixin Register; in your Event subclass will do this for you.

class MyEvent : Event {
	this(Widget target) { super(EventString, target); }
	mixin Register; // adds EventString and other reflection information
}

Then declare that it is sent with the Emits mixin, so you can use Widget.emit to dispatch it.