Recommended Event Propagation module

Overview

The GUI application consumes all OS events such as keyboard, mouse, system, etc. In general, the application code tends to grow. Typically, the MVC (Model-View-Controller) pattern or its variants are useful for splitting the logic of a GUI application into modules.

Model modules (letter M in the pattern name) must handle application data. Typically, the model code is the simplest part of the GUI application. For example, in a mind map editor, this code keeps the current contents of the mind map (nodes of tree, a selected node, etc.) and implements methods to change the content (insert a new node, add a new letter to node, etc).

View modules (V letter) should display the current state of the model to the user. For example, the View module in the mind map editor draws node text, borders, lines between nodes, cursor, etc. View modules can be complex because the graphic design style is a valuable part of a GUI application. But the core logic of View modules is simple - to display the current state of the model to the user.

Controller modules (C letter) must receive user events, call Model to change its state, and call View to display the model's new state to the user. For example, the control module in the mind map editor draws a mind map, waits for a new event, and in a switch statement for each possible type of event changes the contents of the mind map. And again.

If your application contains two or more controller modules, you must use additional rules to separate events between different application windows.

Some of an options:

• Add some attributes to the window (e.g. "active", "modal", etc.) to highlight the default controller and launch an invisible super controller.
• Pass the event to each controller in a specific order until the event is marked as handled.

Recommended option:

• Pass an event to only one controller, but all controllers must route the event using the same rules.

Recommended event propagation rules

• Controllers maintain hierarchical order. Each controller has child controllers.
• In the case when several windows work in parallel, the parent controller keeps a list of parallel controllers in its own way.
• Each controller routes events differently. Some events will be forwarded to the child controller, while others will be handled itself.

For example, a mouse click can be handled by itself or by a child controller. The controller can get the child window rectangle from the child controller and compare it to the click point. If a mouse click occurs in a child window, the controller can pass the event to the child controller and ignore its own event handler.

Basic use of event propagation module

The core of the module is the event channel between parent and child controller. The parent controller must create an eventlink.EventLink variable:

    eventLink := eventlink.New()

and link the child controller to run its Action method as a goroutine:

    eventLink.Link(ctx, appFramer, childController)

The child controller must implement Actor interface to work with eventlink.EventLink:

type Actor interface {
    Action(ctx context.Context, app App)
    Wait()
}

Then at any time the parent controller can put an event to the child channel:

    eventLink.Chan() <- receivedEvent

On the childs side, the eternal Action method of the child controller receives the event from the channel, handles or ignores it and redraws the child state in its or any other window. The eventlink.App is a interface to get events, create child window, etc.

The eventlink.AppFramer is a wrapper from impress.Application at the beginning:

    var appFramer eventlink.AppFramer = eventlink.MainApp(application)

eventlink.App may be used as eventlink.AppFramer parameter of eventlink.Link to create a new link inside the child controller.

See the module documentation and example for details.

Shutdown scenarios

In a typical usecases, child controllers creates on start and run until parent Controller are still alive.

More complex scenarios of parent and child controller coexistence are possible:

• Creating a new child controller to replace the old child controller.
• Closing a child controller due to some event on the parent or child side.

To implement complex shutdown scenarios:

• The child controller should wait for ctx.Done in parallel with event waiting. If the context is canceled, the Action method must exit immediately. If some background child goroutines are still alive, the place to wait is the Wait method.
• The child controller can exit the Action method in case of any event. A parent can check the status of a child using the childActor, isAlive := eventLink.Actor() method.
• The ctx parameter of Link must be combined from the grandfathers context and can be canceled at any time.
• The parent controller can replace the child controller using the Link method with a new controller. Then the context of the replaced controller will be canceled.
• A parent controller can cancel a child controller's context via a call to func (c *EventLink) Cancel().