com.samskivert.swing
Class Controller

java.lang.Object
  com.samskivert.swing.Controller

All Implemented Interfaces:

ActionListener, EventListener

public abstract class Controller
extends Object
implements ActionListener

The controller class provides a basis for the separation of user interface code into display code and control code. The display code lives in a panel class (javax.swing.JPanel or something conceptually similar) and the control code lives in an associated controller class.

The controller philosophy is thus: The panel class (and its UI components) convert basic user interface actions into higher level actions that more cleanly encapsulate the action desired by the user and they pass those actions on to their controller. The controller then performs abstract processing based on the users desires and the changing state of the application and calls back to the panel to affect changes to the display.

Controllers also support the notion of scope. When a panel wishes to post an action, it doesn't do it directly to the controller. Instead it does it using a controller utility function called postAction(java.awt.event.ActionEvent), which searches up the user interface hierarchy looking for a component that implements ControllerProvider which it will use to obtain the controller "in scope" for that component. That controller is requested to handle the action, but if it cannot handle the action, the next controller up the chain is located and requested to process the action.

In this manner, a hierarchy of controllers (often just two: one application wide and one for whatever particular mode the application is in at the moment) can provide a set of services that are available to all user interface elements in the entire application and in a way that doesn't require tight connectedness between the UI elements and the controllers.

Field Summary

static ActionListener

DISPATCHER This action listener can be wired up to any action event generator and it will take care of forwarding that event on to the controller in scope for the component that generated the action event.

Constructor Summary

Controller()

Method Summary

void	actionPerformed(ActionEvent event)
static void	configureAction(AbstractButton button, String action) Configures the supplied button with the DISPATCHER action listener and the specified action command (which, if it is a method name will be looked up dynamically on the matching controller).
static JButton	createActionButton(String label, String command) Creates a button and configures it with the specified label and action command and adds DISPATCHER as an action listener.
boolean	handleAction(ActionEvent action) Instructs this controller to process this action event.
boolean	handleAction(Component source, String command) A convenience method for constructing and immediately handling an event on this controller (via handleAction(ActionEvent)).
boolean	handleAction(Component source, String command, Object arg) A convenience method for constructing and immediately handling an event on this controller (via handleAction(ActionEvent)).
boolean	handleAction(Object source, String action, Object arg) A version of handleAction(ActionEvent) with the parameters broken out so that it can be used by non-Swing interface toolkits.
static void	postAction(ActionEvent action) Posts the specified action to the nearest controller in scope.
static void	postAction(Component source, String command) Like postAction(ActionEvent) except that it constructs the action event for you with the supplied source component and string command.
static void	postAction(Component source, String command, Object argument) Like postAction(ActionEvent) except that it constructs a CommandEvent with the supplied source component, string command and argument.
void	setControlledPanel(JComponent panel) Lets this controller know about the panel that it is controlling.
void	wasAdded() Called when the panel controlled by this controller was added to the user interface hierarchy.
void	wasRemoved() Called when the panel controlled by this controller was removed from the user interface hierarchy.

Methods inherited from class java.lang.Object

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

Field Detail

DISPATCHER

public static final ActionListener DISPATCHER

This action listener can be wired up to any action event generator and it will take care of forwarding that event on to the controller in scope for the component that generated the action event.

For example, wiring a button up to a dispatcher would look like so:

 JButton button = new JButton("Do thing");
 button.setActionCommand("dothing");
 button.addActionListener(Controller.DISPATCHER);
 

or, use the provided convenience function:

 JButton button =
     Controller.createActionButton("Do thing", "dothing");
 

The controllers in scope would then be requested (in order) to process the dothing action whenever the button was clicked.

Constructor Detail

Controller

public Controller()

Method Detail

postAction

public static void postAction(ActionEvent action)

Posts the specified action to the nearest controller in scope. The controller search begins with the source component of the action and traverses up the component tree looking for a controller to handle the action. The controller location and action event processing is guaranteed to take place on the AWT thread regardless of what thread calls postAction and that processing will not occur immediately but is instead appended to the AWT event dispatch queue for processing.

postAction

public static void postAction(Component source,
                              String command)

Like postAction(ActionEvent) except that it constructs the action event for you with the supplied source component and string command. The id of the event will always be set to zero.

postAction

public static void postAction(Component source,
                              String command,
                              Object argument)

Like postAction(ActionEvent) except that it constructs a CommandEvent with the supplied source component, string command and argument.

createActionButton

public static JButton createActionButton(String label,
                                         String command)

Creates a button and configures it with the specified label and action command and adds DISPATCHER as an action listener.

configureAction

public static void configureAction(AbstractButton button,
                                   String action)

Configures the supplied button with the DISPATCHER action listener and the specified action command (which, if it is a method name will be looked up dynamically on the matching controller).

setControlledPanel

public void setControlledPanel(JComponent panel)

Lets this controller know about the panel that it is controlling.

wasAdded

public void wasAdded()

Called when the panel controlled by this controller was added to the user interface hierarchy. This assumes that the controlled panel made itself known to the controller via setControlledPanel(javax.swing.JComponent) (which is done automatically by ControlledPanel and derived classes).

wasRemoved

public void wasRemoved()

Called when the panel controlled by this controller was removed from the user interface hierarchy. This assumes that the controlled panel made itself known to the controller via setControlledPanel(javax.swing.JComponent) (which is done automatically by ControlledPanel and derived classes).

handleAction

public boolean handleAction(ActionEvent action)

Instructs this controller to process this action event. When an action is posted by a user interface element, it will be posted to the controller in closest scope for that element. If that controller handles the event, it should return true from this method to indicate that processing should stop. If it cannot handle the event, it can return false to indicate that the event should be propagated to the next controller up the chain.

This method will be called on the AWT thread, so the controller can safely manipulate user interface components while handling an action. However, this means that action handling cannot block and should not take an undue amount of time. If the controller needs to perform complicated, lengthy processing it should do so with a separate thread, for example via TaskMaster.

The default implementation of this method will reflect on the controller class, looking for a method that matches the name of the action event. For example, if the action was "exit" a method named "exit" would be sought. A handler method must provide one of three signatures: one accepting no arguments, one including only a reference to the source object, or one including the source object and an extra argument (which can be used only if the action event is an instance of CommandEvent). For example:

 public void cancelClicked (Object source);
 public void textEntered (Object source, String text);
 

The arguments to the method can be as specific or as generic as desired and reflection will perform the appropriate conversions at runtime. For example, a method could be declared like so:

 public void cancelClicked (JButton source);
 

One would have to ensure that the only action events generated with the action command string "cancelClicked" were generated by JButton instances if such a signature were used.

Parameters:

action - the action to be processed.

Returns:

true if the action was processed, false if it should be propagated up to the next controller in scope.

handleAction

public boolean handleAction(Object source,
                            String action,
                            Object arg)

A version of handleAction(ActionEvent) with the parameters broken out so that it can be used by non-Swing interface toolkits.

handleAction

public boolean handleAction(Component source,
                            String command)

A convenience method for constructing and immediately handling an event on this controller (via handleAction(ActionEvent)).

Returns:

true if the controller knew how to handle the action, false otherwise.

handleAction

public boolean handleAction(Component source,
                            String command,
                            Object arg)

A convenience method for constructing and immediately handling an event on this controller (via handleAction(ActionEvent)).

Returns:

true if the controller knew how to handle the action, false otherwise.

actionPerformed

public void actionPerformed(ActionEvent event)

Specified by:

actionPerformed in interface ActionListener