com.codename1.rad.controllers

Class FormController

java.lang.Object

com.codename1.rad.controllers.Controller

com.codename1.rad.controllers.ViewController

com.codename1.rad.controllers.FormController

All Implemented Interfaces:

ActionListener<ControllerEvent>, Runnable

Direct Known Subclasses:

FieldEditorFormController, LoginFormController

public class FormController
extends ViewController
implements Runnable

A controller for handling application logic related to a Form.

Controller Hierarchy

Controllers have a hierarchy similar to UI components. The ApplicationController is generally the "root" controller. The top-level form controller is a "child" of the application controller. If the user navigates to another form from which they should be able to navigate back, then the new FormController is a "child" of the previous FormController.

Back Navigation

If a FormController’s parent controller is also a FormController, then "back" functionality will automatically be connected to its Form. When the user clicks "back", they will automatically navigate to the parent controller’s form.

Views may also request a "back" navigation by firing a FormController.FormBackEvent, which will propagate up the controller hierarchy to the first FormController, where it will be handled.

Event Propagation

Events which are dispatched to a Controller will be propagated to the controller’s parent, and its parent, and so on… until the event is consumed, or until it reaches the root. In this way, it is possible to create a catch-all event handler in the ApplicationController that will catch all events in the application that haven’t been consumed by another controller.

Example

A FormController for the ChatRoomView. Excerpt from this tutorial,window=top.

public class ChatFormController extends FormController {

   // Define the "SEND" action for the chat room
   public static final ActionNode send = action(
       enabledCondition(entity-> {
           return !entity.isEmpty(ChatRoom.inputBuffer);
       }),
       icon(FontImage.MATERIAL_SEND)
   );
   public ChatFormController(Controller parent) {
       super(parent);
       Form f = new Form("My First Chat Room", new BorderLayout());

       // Create a "view node" as a UI descriptor for the chat room.
       // This allows us to customize and extend the chat room.
       ViewNode viewNode = new ViewNode(
           actions(ChatRoomView.SEND_ACTION, send)
       );

       // Add the viewNode as the 2nd parameter
       ChatRoomView view = new ChatRoomView(createViewModel(), viewNode, f);
       f.add(CENTER, view);
       setView(f);

       addActionListener(send, evt->{
           evt.consume();
           // ... handle send event

       });
   }
   //...
}

Author:

shannah

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FormController.CloneableFormController<T extends FormController> Interface that can be implemented by FormController subclasses that support Cloning and replacing themselves.
static class	FormController.FormBackEvent Event that can be fired by any view to request that the current form go back to the previous form.
static class	FormController.FormControllerEvent Base class for FormController events.
static class	FormController.FormShownEvent

Nested classes/interfaces inherited from class com.codename1.rad.controllers.ViewController

ViewController.DidSetViewEvent, ViewController.DidUnSetViewEvent, ViewController.ViewDecorator

Nested classes/interfaces inherited from class com.codename1.rad.controllers.Controller

Controller.CreateObjectRequest<T>, Controller.ObjectFactory

Constructor Summary

Constructors

Constructor and Description
FormController(Controller parent)

Method Summary

Modifier and Type	Method and Description
void	actionPerformed(ControllerEvent evt) Handles Controller event.
void	back() Goes back to previous form.
static <T extends FormController> T	cloneAndReplace(T controller) Clones a form controller and replaces it.
static FormController	getCurrentFormController()
static FormController	getFormController(ActionEvent event)
static FormController	getFormController(Component source)
static FormController	getFormController(Form form)
String	getPathName() Gets the pathName for this controller.
String	getPathString(String separator) Gets the full path string to this controller.
Form	getView() Gets form associated with this controller.
boolean	hasBackCommand()
boolean	isAddTitleBar()
boolean	isTitleSet()
void	refresh() Refreshes the controller.
void	run()
void	setAddTitleBar(boolean add)
void	setPathName(String name) Sets the path name for this controller whih will be used by getPathString(String).
void	setTitle(String title)
void	setTitleComponent(Component cmp)
void	setView(Component cmp) Overrides parent setView().
void	setView(Form form) Sets the form associated with this controller.
void	setView(ViewController viewController)
void	show()
void	showBack() Shows this controller’s form using the "back" animation.
static boolean	tryCloneAndReplaceCurrentForm() Tries to cloneAndReplace(FormController) the current FormController

Methods inherited from class com.codename1.rad.controllers.ViewController

addViewDecorator, createViewContext, decorateView, deinitialize, getNearestViewModel, getTitle, getViewController, getViewController, getViewModel, initController, removeViewDecorator

Methods inherited from class com.codename1.rad.controllers.Controller

addAction, addAction, addActionListener, addActions, addActions, addEventListener, addLookup, addLookup, addObjectFactory, createObjectWithFactory, createViewNode, dispatchEvent, extendAction, extendAction, fillSlot, getAction, getActions, getActionsNode, getApplicationController, getFormController, getFormController, getInheritedAction, getInheritedActions, getParent, getSectionController, getSingleActionsNode, getViewController, getViewNode, initControllerActions, isStarted, lookup, lookupEntity, onStartController, onStopController, parentLookup, parentLookupEntity, removeActionListener, removeEventListener, setParent, start, startController, withLookup, withLookupEntity, withParentLookup, withParentLookupEntity

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FormController

public FormController(Controller parent)

Method Detail

setView

public void setView(ViewController viewController)

setView

public void setView(Form form)

Sets the form associated with this controller. This will automatically set the back command of the form to call back() on this controller.

Parameters:

form -

setTitle

public void setTitle(String title)

Overrides:

setTitle in class ViewController

isTitleSet

public boolean isTitleSet()

setTitleComponent

public void setTitleComponent(Component cmp)

setAddTitleBar

public void setAddTitleBar(boolean add)

isAddTitleBar

public boolean isAddTitleBar()

setView

public void setView(Component cmp)

Overrides parent setView(). Delegates to setView(com.codename1.ui.Form) if cmp is a form. Throws IllegalArgumentException otherwise.

Overrides:

setView in class ViewController

Parameters:

cmp -

getView

public Form getView()

Gets form associated with this controller.

Overrides:

getView in class ViewController

Returns:

back

public void back()

Goes back to previous form. The previous form is always the parent controller’s form, if the parent controller is a FormController.

If the current controller is an instance of AutoCloseable, then this will first attempt to call AutoCloseable.close() on the current form first. If it throws an exception, then that exception will be swallowed, but the showBack() action will be cancelled.

show

public void show()

showBack

public void showBack()

Shows this controller’s form using the "back" animation. If the current controller is an instance of AutoCloseable, then this will first attempt to call AutoCloseable.close() on the current form first. If it throws an exception, then that exception will be swallowed, but the showBack() action will be cancelled.

hasBackCommand

public boolean hasBackCommand()

actionPerformed

public void actionPerformed(ControllerEvent evt)

Handles Controller event. This implementation consumes FormController.FormBackEvent events.

Specified by:

actionPerformed in interface ActionListener<ControllerEvent>

Overrides:

actionPerformed in class Controller

Parameters:

evt -

getPathName

public String getPathName()

Gets the pathName for this controller.

Returns:

setPathName

public void setPathName(String name)

Sets the path name for this controller whih will be used by getPathString(String).

Parameters:

name - The path name for this controller.

getPathString

public String getPathString(String separator)

Gets the full path string to this controller. This allows the controller hierarchy to be described as a path, like a filesystem path.

1. If the pathName of any controller in the controller hierarchy is null, then that controller is omitted from the path.

2. Only FormController controllers are included in the path.

3. If this FormController has no pathName set, then this will return the same path string as the parent controller.

4. If none of the controllers in the hierarchy (including this one) have a pathName set then this will return an empty string.

Parameters:

separator - The path separator

Returns:

The path string to this controller.

getFormController

public static FormController getFormController(Form form)

getCurrentFormController

public static FormController getCurrentFormController()

refresh

public void refresh()

Description copied from class: Controller

Refreshes the controller. This calls Controller.onStopController() and Controller.startController() and is useful for reloading the application when changes are made to the classes or resources.

Overrides:

refresh in class Controller

run

public void run()

Specified by:

run in interface Runnable

getFormController

public static FormController getFormController(Component source)

getFormController

public static FormController getFormController(ActionEvent event)

cloneAndReplace

public static <T extends FormController> T cloneAndReplace(T controller)

Clones a form controller and replaces it. The provided FormController must implement FormController.CloneableFormController.

Type Parameters:

T - The type of FormController

Parameters:

controller - The controller to clone and replace.

Returns:

The new FormController. show() method would already have been called.

tryCloneAndReplaceCurrentForm

public static boolean tryCloneAndReplaceCurrentForm()

Tries to cloneAndReplace(FormController) the current FormController

Returns:

True if it succeeds. False if it fails. It will fail either the current form doesn’t have a form controller, or there is no current form.