com.ehsbe.commons.gui
Class AbstractAppController

java.lang.Object
  com.ehsbe.commons.gui.AbstractAppController

All Implemented Interfaces:

ActionListener, EventListener

public abstract class AbstractAppController
extends Object
implements ActionListener

The controller for an application frame. Contains methods for wiring the standard stuff needed in almost every rich client application.

So a complete working example to start with might look like this:

package my.do.main;

import ... ;

public class MyApp extends AbstractAppController {

        // requires my/do/main/res/"main_actions".properties
        public MyApp() {
                super(MyApp.class, new MyVersion());
        }

        // handles the actions configured in my/do/main/res/"main_actions".xml
        public void actionPerformed(ActionEvent e) {
                if (frame == null) {
                        return;
                }
                String cmd = e.getActionCommand();
                if (cmd == null) {
                        log.warn("Null command received");
                        return;
                }
                if (cmd == AppFrame.ACTION_FILE_QUIT) {
                        if (!action_QuitApplication()) {
                                ((ManagedActionEvent) e).stopDispatching();
                        }
                } else if (cmd == "A_HELP_ABOUT") {
                        action_About();
                } else if (cmd == "A_HELP_CONTENT") {
                        action_ShowHelp(((ManagedActionEvent) e).getOriginalEvent());
                } else if (cmd.startsWith(LnF.LNF_ACTION_PREFIX)) {
                        action_LookAndFeel(e);

                // add others here ...

                } else {
                        log.warn("Software bug - uncaught event: " + e.toString());
                        if (e instanceof ManagedActionEvent) {
                                ManagedActionEvent me = (ManagedActionEvent) e;
                                log.debug("Original event:" + me.getOriginalEvent().toString());
                        }
                }
        }

        public static void main(String[] args) {
                System.setProperty("swing.boldMetal", "false");
                Locale.setDefault(Locale.GERMAN);
                LnF.setAppLookAndFeel(Preferences.userNodeForPackage(MyApp.class));
                EventQueue.invokeLater(new Runnable() {
                        public void run() {
                                try {
                                        MyApp ctrl = new MyApp();
                                        ctrl.frame.validate();
                                        ctrl.frame.setSize(ctrl.prefs);
                                        ctrl.frame.setLocation(ctrl.prefs);
                                        ctrl.frame.setVisible(true);
                                } catch (Exception e) {
                                        System.err.println(e.getLocalizedMessage());
                                }
                        }
                });             
        }
}

Version:

$Revision: 465 $

Author:

Jens Elkner

Field Summary

protected AppFrame	frame the current AppFrame controlled by this instance
protected JxHelpFrame	helpFrame the frame which will be used to display helpsets
protected ResourceBundle	i18n resource bundle which will be used for message translation etc.
static String	MENU_LIST_ID the default ID of the action list, which will be used to create the frame's menubar.
protected Class<?>	owner class used to determine the default path for resource and action config files by using its package_name + /res/ as well as for getting the default user preference node for this application.
protected Preferences	prefs user preference node to use
static String	RES_FILE_BASENAME the basename without extension for application specific resource files
protected String	resPath the default path to use for finding resource files
static String	TOOLBAR_LIST_ID the default ID of the action list, which will be used to create the frame's toolbar
protected VersionInfo	versionInfo the version infos to be displayed in the default about dialog

Constructor Summary

	AbstractAppController() Default constructor.
	AbstractAppController(AppFrame frame, Class<?> owner, VersionInfo info) Convinience method to create and initialize an application frame.
protected	AbstractAppController(AppFrame frame, Class<?> owner, VersionInfo info, Locale locale) Convinience method to create and initialize an application frame.
	AbstractAppController(Class<?> owner, VersionInfo info) Convinience method to create and initialize an application frame with the default locale.
	AbstractAppController(Locale locale, Class<?> owner, VersionInfo info) Convinience method to create and initialize an application frame.

Method Summary

protected void	action_About() Shows a standard about dialog.
protected void	action_LookAndFeel(ActionEvent e) Change the Look and Feel of the application frame.
protected boolean	action_QuitApplication() Disposes the helpFrame, saves the frame's location and size on the screen to the default user preference node (see owner), disposes the application frame and notifies all other threads to catch up (see Object.notifyAll()).
protected void	action_ShowHelp(ActionEvent e) Show the help associated with the source of the action event in a separate, application independend dialog window.
abstract void	actionPerformed(ActionEvent e) Handles the action event fired by an action in the action manager's map.
protected void	configureFrame(Class<?> owner) Configures the frame wrt. to message bundles, actions, menu, toolbar, statusbar, the Look-and-Feel of the controlled AppFrame.
void	control(AppFrame frame, Class<?> owner, VersionInfo info, boolean init) Ask this controller to control the given application frame.
protected javax.help.HelpSet	getHelpSet() Get the help set to use for this application frame.

Methods inherited from class java.lang.Object

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

Field Detail

frame

protected AppFrame frame

the current AppFrame controlled by this instance

i18n

protected ResourceBundle i18n

resource bundle which will be used for message translation etc.

resPath

protected String resPath

the default path to use for finding resource files

helpFrame

protected JxHelpFrame helpFrame

the frame which will be used to display helpsets

versionInfo

protected VersionInfo versionInfo

the version infos to be displayed in the default about dialog

prefs

protected Preferences prefs

user preference node to use

owner

protected Class<?> owner

class used to determine the default path for resource and action config files by using its package_name + /res/ as well as for getting the default user preference node for this application.

RES_FILE_BASENAME

public static final String RES_FILE_BASENAME

the basename without extension for application specific resource files

See Also:

Constant Field Values

TOOLBAR_LIST_ID

public static final String TOOLBAR_LIST_ID

the default ID of the action list, which will be used to create the frame's toolbar

See Also:

Constant Field Values

MENU_LIST_ID

public static final String MENU_LIST_ID

the default ID of the action list, which will be used to create the frame's menubar.

See Also:

Constant Field Values

Constructor Detail

AbstractAppController

public AbstractAppController()

Default constructor. Does nothing.

AbstractAppController

public AbstractAppController(Class<?> owner,
                             VersionInfo info)

Convinience method to create and initialize an application frame with the default locale.

Parameters:

owner - the anchor for the default resource path to use.

info - infos, which should be displayed in the default about dialog

See Also:

control(AppFrame, Class, VersionInfo, boolean)

AbstractAppController

public AbstractAppController(Locale locale,
                             Class<?> owner,
                             VersionInfo info)

Convinience method to create and initialize an application frame.

Parameters:

locale - locale to use for the new AppFrame. If null the default locale will be used.

owner - the anchor for the default resource path to use.

info - infos, which should be displayed in the default about dialog

See Also:

control(AppFrame, Class, VersionInfo, boolean)

AbstractAppController

public AbstractAppController(AppFrame frame,
                             Class<?> owner,
                             VersionInfo info)

Convinience method to create and initialize an application frame.

Parameters:

frame - frame to control. If null, a new AppFrame gets created using the given locale and used for initializing this instance.

owner - the anchor for the default resource path to use.

info - infos, which should be displayed in the default about dialog

See Also:

control(AppFrame, Class, VersionInfo, boolean)

AbstractAppController

protected AbstractAppController(AppFrame frame,
                                Class<?> owner,
                                VersionInfo info,
                                Locale locale)

Convinience method to create and initialize an application frame.

Parameters:

frame - frame to control. If null, a new AppFrame gets created using the given locale and used for initializing this instance.

owner - the anchor for the default resource path to use.

info - infos, which should be displayed in the default about dialog

locale - locale to use, if a new AppFrame needs to be created.

See Also:

control(AppFrame, Class, VersionInfo, boolean)

Method Detail

control

public void control(AppFrame frame,
                    Class<?> owner,
                    VersionInfo info,
                    boolean init)

Ask this controller to control the given application frame. If the this controller is currently attached to another frame, it will detach from it.

Parameters:

frame - frame to control. Might be null to release control.

owner - the application owner.

info - info used to populate the appropriate fields in the about dialog (see action_About()).

init - if true, initialize the given frame by calling configureFrame(Class) with the given owner.

configureFrame

protected void configureFrame(Class<?> owner)

Configures the frame wrt. to message bundles, actions, menu, toolbar, statusbar, the Look-and-Feel of the controlled AppFrame.

First the default resource path {resPath and user preference node prefs gets initialized using the package name of the given owner (see Misc.getResourcePath(Object)).

Than the default PropertyResourceBundle i18n, usually used for i18n translation and message formatting gets loaded from the file "main_actions"*.properties in (resPath).

Now the default Look-and-Feel change actions are placed into the frame's action manager with the action list ID LnF.LNF_MENU_LIST (see LnF.createActions(HashMap, HashMap)).

After that, the application specific action config file "main_actions" gets loaded from the default resource path resPath and placed into the frame's action manager (see ActionFactory.load(javax.xml.transform.stream.StreamSource, Translator, String, HashMap, HashMap)).

Now the menubar of the frame gets populated and set from the action list with the ID "L_MENU", the toolbar gets populated and set from the action list with the ID "L_TOOLBAR" as well as the JxStatusBar and the empty white content JPanel. So to a minimal action config file may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE set SYSTEM "jar:/com/ehsbe/commons/action/action.dtd">
<set id="APP_FRAME">
        <action id="A_FILE_OPEN" accel="control O" large_icon="24x24/open.png" />
        <action id="A_FILE_QUIT" accel="control Q" large_icon="24x24/quit.png"/>
        <action id="A_HELP_CONTENT" accel="F1"/>
        <action id="A_HELP_ABOUT"/>
        <list id="L_MENU">
                <list id="L_MENU_FILE"><action id="MENU_FILE"/>
                        <ref idref="A_FILE_OPEN"/>
                        <none/>
                        <ref idref="A_FILE_QUIT"/>
                </list>
                <list id="L_MENU_VIEW"><action id="MENU_VIEW"/>
                        <ref idref="L_LNF_MENU"/> <!-- L&F gets automatically generated -->
                </list>
                <list id="L_MENU_HELP"><action id="MENU_HELP"/>
                        <ref idref="A_HELP_CONTENT"/>
                        <none/>
                        <ref idref="A_HELP_ABOUT"/>
                </list>
        </list>
        <list id="L_TOOLBAR">
                <ref idref="A_FILE_OPEN"/>
                <none/>
                <ref idref="A_FILE_QUIT"/>
        </list>
</set>

To get the menu item names translated, the used id should have an appropriate value at least in the i18n resource bundle loaded before. E.g. "main_actions".properties:

MENU_FILE.name = File
MENU_FILE.short_desc =
MENU_FILE.long_desc =
MENU_FILE.mnemonic = F

A_FILE_OPEN.name = Open
A_FILE_OPEN.short_desc = Open/Load a file
A_FILE_OPEN.long_desc = 
A_FILE_OPEN.mnemonic = O

A_FILE_QUIT.name = Quit
A_FILE_QUIT.short_desc = Quit the application
A_FILE_QUIT.long_desc = 
A_FILE_QUIT.mnemonic = Q

MENU_VIEW.name = View
MENU_VIEW.short_desc =
MENU_VIEW.long_desc =
MENU_VIEW.mnemonic = V

MENU_HELP.name = Help
MENU_HELP.short_desc =
MENU_HELP.long_desc =
MENU_HELP.mnemonic = H

A_HELP_CONTENT.name = Content
A_HELP_CONTENT.short_desc = User Manual
A_HELP_CONTENT.long_desc =
A_HELP_CONTENT.mnemonic = C

A_HELP_ABOUT.name = About
A_HELP_ABOUT.short_desc = Product informationen
A_HELP_ABOUT.long_desc =
A_HELP_ABOUT.mnemonic = A

If you want to support other languages/locales, one should create such a property file for each supported language, e.g. "main_actions"_de.properties etc..

Parameters:

owner - class used to determine the package name and path to application specific resource and action config files.

See Also:

owner, Misc.getResourcePath(Object), resPath, RES_FILE_BASENAME, MENU_LIST_ID, TOOLBAR_LIST_ID, LnF.LNF_MENU_LIST, VersionInfo

action_QuitApplication

protected boolean action_QuitApplication()

Disposes the helpFrame, saves the frame's location and size on the screen to the default user preference node (see owner), disposes the application frame and notifies all other threads to catch up (see Object.notifyAll()). Finally a System.exit(int) is done, if the system property jnlpx.remove is set (value doesn't matter). Otherwise the method returns normally.

Returns:

true.

action_About

protected void action_About()

Shows a standard about dialog.

See Also:

VersionInfo

getHelpSet

protected javax.help.HelpSet getHelpSet()

Get the help set to use for this application frame.

Returns:

null if there is no helpset available (the default), the helpset otherwise.

action_ShowHelp

protected void action_ShowHelp(ActionEvent e)

Show the help associated with the source of the action event in a separate, application independend dialog window. Uses Util.getHelpID(Object) to jump to the right help section.

Parameters:

e - event, which triggered this call

See Also:

Util.setHelpID(Object, String), JxHelpFrame.showID(String), Dialog.ModalExclusionType.APPLICATION_EXCLUDE

action_LookAndFeel

protected void action_LookAndFeel(ActionEvent e)

Change the Look and Feel of the application frame.

Parameters:

e - action, which determines the new L&F.

See Also:

LnF.setAppLookAndFeel(Action)

actionPerformed

public abstract void actionPerformed(ActionEvent e)

Handles the action event fired by an action in the action manager's map. A default implementation is described above.

Specified by:

actionPerformed in interface ActionListener

Parameters:

e - the triggering action event