Controllers

Controllers

Controllers are in "control" of your application’s flow control. They are informed of all pertinent "events" in your application (both user-triggered and otherwise), and they decide what to do in response to them.

There are four main types of controllers in CodeRAD, and all extend the base Controller class.

Figure 1. Class hierarchy of controller types.

ApplicationController

The root controller for the application. All events that don’t get consumed by a child controller will flow through this controller.

FormController

Each form in the app will have an associated FormController.

ViewController

A component within a form may have its own ViewController.

AppSectionController

In larger apps, you may want to group multiple forms together into sections, as children of a common AppSectionController.

Every CodeRAD application has at least one controller: The ApplicationController; which responds to at least one event: The Start event, which is fired whenever the app opens.

When you create a new CodeRAD starter project in Codename One initializr, the application controller will include the following actionPerformed() method:

public void actionPerformed(ControllerEvent evt) {
    with(evt, StartEvent.class, startEvent -> { (1)
        if (!startEvent.isShowingForm()) { (2)
            startEvent.setShowingForm(true); (3)
            new StartPageController(this).show(); (4)
        }
    });
    super.actionPerformed(evt);
}

1. with(evt, StartEvent.class, startEvent →{…​}) Is an alternate way of saying "if (evt instanceof StartEvent.class) {…​}".

2. if (!startEvent.isShowingForm()) checks to see if a form has already been shown in response to the start event. If the app was just reopened, it may display the "current" form that was showing before the app was closed, in which case we don’t want to display a different form usually.

3. startEvent.setShowingForm(true) tells event listeners who process this event after us, that we have already shown a form in response to this event.

4. new StartPageController(this).show() creates a new FormController and shows its form.

The Controller Hierarchy

Every controller (except for the ApplicationController) has a parent controller. This creates a hierarchy among controllers (not to be confused with the class hierarchy).

Figure 2. The controller hierachy formed by following the parent association of each controller.

This hierarchy is leveraged throughout CodeRAD to get features for "free". Some examples include:

Events

Events are propagated up through the controller hierarchy until they are consumed, or until they reach the "top" of the hierarchy (the ApplicationController). This allows you to "handle" events at whatever level of specificity makes the most sense for your app. E.g. You can handle events in the view controller for a specific component, or you can handle them in the Application Controller.

Figure 3. An example of event propagation.

Navigation

If a FormController has a parent FormController, then it will include a Back button which, when pressed, navigates "back" to the parent controller.

Lookups

A "lookup" can be added to a controller, and looked up by any "child" controller or view.

Actions

You can define actions inside any controller. When a view is querying for actions to include in its UI, it effectively crawls up the controller hierarchy to find all applicable registered actions.

See Also

Controllers

The Controllers chapter from the CodeRAD developers guide.

Custom View Controllers

The Custom View Controllers section of the Getting Started tutorial.