org.esa.beam.framework.ui
Class BasicApp

java.lang.Object
  org.esa.beam.framework.ui.BasicApp

Direct Known Subclasses:

ProcessorApp, VisatApp

public class BasicApp
extends Object

The BasicApp can be used as a base class for applications which use a single main frame as user interface.

This class provides several useful capabilites as there are:

Action (command) management

Automatic user preferences loading and saving

Logfile support

Status bar support

Splash screen support

And last but not least BasicApp automatically stores the file pathes a user visited in open- or save dialog boxes.

Version:

$Revision$ $Date$

Author:

Norman Fomferra

See Also:

Command, ExecCommand, CommandGroup, CommandManager

Nested Class Summary

static class

BasicApp.MainFrame

Field Summary

static String	MESSAGE_STATUS_BAR_ITEM_KEY
static String	POSITION_STATUS_BAR_ITEM_KEY
static String	PROPERTY_KEY_APP_DEBUG_ENABLED
static String	PROPERTY_KEY_APP_LAST_OPEN_DIR
static String	PROPERTY_KEY_APP_LAST_OPEN_FORMAT
static String	PROPERTY_KEY_APP_LAST_SAVE_DIR
static String	PROPERTY_KEY_APP_LOG_ECHO
static String	PROPERTY_KEY_APP_LOG_ENABLED
static String	PROPERTY_KEY_APP_LOG_LEVEL
static String	PROPERTY_KEY_APP_LOG_PREFIX
static String	PROPERTY_KEY_APP_UI_FONT_NAME
static String	PROPERTY_KEY_APP_UI_FONT_SIZE
static String	PROPERTY_KEY_APP_UI_LAF
static String	PROPERTY_KEY_APP_UI_USE_SYSTEM_FONT_SETTINGS

Constructor Summary

	BasicApp(ApplicationDescriptor applicationDescriptor)
protected	BasicApp(String appName, String appSymbolicName, String appVersion, String appCopyrightInfo, String appResource, String appLoggerName) Constructs a new application frame and creates the GUI.

Method Summary

void	addHelp(ClassLoader classLoader, String helpsetResourcePath) Adds a new JavaHelp HelpSet to the existing help.
protected void	applyLookAndFeelPreferences() This method should be called after prefernces that affect the current look & feel have changed.
protected void	applyPreferences()
void	center() Centers this application frame within the screen area.
void	clearStatusBarMessage() Clears the status bar message.
protected void	configureCommandsByResourceBundle()
protected ImageIcon	createFrameIcon() Creates a default frame icon for this application.
protected JMenu	createJMenu(String name, String text, char mnemonic, String... cmdIds)
protected com.jidesoft.action.CommandBar	createMainMenuBar()
protected JComponent	createMainPane()
protected com.jidesoft.action.CommandBar	createMainToolBar()
protected com.jidesoft.status.StatusBar	createStatusBar()
protected com.jidesoft.action.CommandBar	createToolBar(String toolBarId, String title)
JMenu	findMainMenu(String name)
JMenu	findMenu(String name)
protected JMenu	findMenu(String name, boolean deepSearch)
String	getAppBuildInfo()
String	getAppCopyright()
ApplicationDescriptor	getApplicationDescriptor()
String	getAppName()
String	getAppSymbolicName()
String	getAppVersion()
ActionListener	getCloseHandler()
CommandManager	getCommandManager() Returns the command manager used for this application.
CommandUIFactory	getCommandUIFactory()
FileHistory	getFileHistory()
String	getImageResourcePath()
Logger	getLogger()
BasicApp.MainFrame	getMainFrame()
com.jidesoft.action.CommandBar	getMainToolBar()
MouseListener	getMouseOverActionHandler()
PropertyMap	getPreferences()
File	getPreferencesFile()
ResourceBundle	getResourceBundle() Returns the resource bundle used by this application.
com.jidesoft.status.StatusBar	getStatusBar()
String	getStatusBarMessage()
SuppressibleOptionPane	getSuppressibleOptionPane()
com.jidesoft.action.CommandBar	getToolBar(String toolBarId)
String[]	getToolBarGroups()
protected void	handleImminentExit() Called by the exit method.
void	handleUnknownException(Throwable e)
protected void	historyPush(File file)
protected void	initClient(com.bc.ceres.core.ProgressMonitor pm) Starts up the client application.
protected void	initClientUI(com.bc.ceres.core.ProgressMonitor pm) Initializes the client user interface.
protected void	insertCommandMenuItem(Command command)
protected void	insertCommandMenuItems()
protected void	insertCommandToolBarButtons(JToolBar toolbar)
boolean	isFrameBoundsRestored()
boolean	isShuttingDown()
boolean	isStartedUp()
boolean	isStatusBarVisible()
boolean	isToolBarVisible(String toolBarId)
protected void	loadPreferences()
boolean	promptForOverwrite(File file) Prompts a question dialog asking the user whether or not he/she wants to overwrite an existing file.
void	registerJob(Object job) Deprecated. No longer used
protected void	savePreferences()
void	setCloseHandler(ActionListener closeHandler)
void	setCommandManager(CommandManager commandManager) Sets the command manager to be used for this application.
void	setCurrentDocTitle(String currentDocTitle) Sets the current document title which appears in this frame's title bar.
protected void	setPreferences()
protected void	setShuttingDown(boolean shuttingDown)
void	setStatusBarMessage(String message) Sets the status bar message to the given message string.
void	setStatusBarVisible(boolean visible)
void	setToolBarVisible(String toolBarId, boolean visbile)
void	showErrorDialog(String message)
void	showErrorDialog(String title, String message)
File	showFileOpenDialog(String title, boolean dirsOnly, FileFilter fileFilter) Opens a standard file-open dialog box.
File	showFileOpenDialog(String title, boolean dirsOnly, FileFilter fileFilter, String lastDirPropertyKey) Opens a standard file-open dialog box.
File	showFileSaveDialog(String title, boolean dirsOnly, FileFilter fileFilter, String defaultExtension, String fileName) Opens a standard file-safe dialog box.
File	showFileSaveDialog(String title, boolean dirsOnly, FileFilter fileFilter, String defaultExtension, String fileName, String lastDirPropertyKey) Opens a standard file-safe dialog box.
void	showInfoDialog(String message, String preferencesKey)
void	showInfoDialog(String title, String message, String preferencesKey)
void	showMessageDialog(String title, String message, int messageType, String preferencesKey)
void	showOutOfMemoryErrorDialog(String message)
int	showQuestionDialog(String message, String preferencesKey)
int	showQuestionDialog(String title, String message, boolean allowCancel, String preferencesKey)
int	showQuestionDialog(String title, String message, String preferencesKey)
void	showWarningDialog(String message)
void	showWarningDialog(String title, String message)
void	showWarningsDialog(String message, String[] warnings)
void	shutDown() Exits the application.
void	startUp(com.bc.ceres.core.ProgressMonitor pm) Starts up the application.
void	unregisterJob(Object job) Deprecated. No longer used
protected void	updateComponentTreeUI() Called after the look & feel has changed.
void	updateState() Updates the appication's (UI-) state.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_KEY_APP_LAST_OPEN_DIR

public static final String PROPERTY_KEY_APP_LAST_OPEN_DIR

See Also:

Constant Field Values

PROPERTY_KEY_APP_LAST_OPEN_FORMAT

public static final String PROPERTY_KEY_APP_LAST_OPEN_FORMAT

See Also:

Constant Field Values

PROPERTY_KEY_APP_LAST_SAVE_DIR

public static final String PROPERTY_KEY_APP_LAST_SAVE_DIR

See Also:

Constant Field Values

PROPERTY_KEY_APP_LOG_ENABLED

public static final String PROPERTY_KEY_APP_LOG_ENABLED

See Also:

Constant Field Values

PROPERTY_KEY_APP_LOG_PREFIX

public static final String PROPERTY_KEY_APP_LOG_PREFIX

See Also:

Constant Field Values

PROPERTY_KEY_APP_LOG_LEVEL

public static final String PROPERTY_KEY_APP_LOG_LEVEL

See Also:

Constant Field Values

PROPERTY_KEY_APP_LOG_ECHO

public static final String PROPERTY_KEY_APP_LOG_ECHO

See Also:

Constant Field Values

PROPERTY_KEY_APP_DEBUG_ENABLED

public static final String PROPERTY_KEY_APP_DEBUG_ENABLED

See Also:

Constant Field Values

PROPERTY_KEY_APP_UI_LAF

public static final String PROPERTY_KEY_APP_UI_LAF

See Also:

Constant Field Values

PROPERTY_KEY_APP_UI_FONT_NAME

public static final String PROPERTY_KEY_APP_UI_FONT_NAME

See Also:

Constant Field Values

PROPERTY_KEY_APP_UI_FONT_SIZE

public static final String PROPERTY_KEY_APP_UI_FONT_SIZE

See Also:

Constant Field Values

PROPERTY_KEY_APP_UI_USE_SYSTEM_FONT_SETTINGS

public static final String PROPERTY_KEY_APP_UI_USE_SYSTEM_FONT_SETTINGS

See Also:

Constant Field Values

MESSAGE_STATUS_BAR_ITEM_KEY

public static final String MESSAGE_STATUS_BAR_ITEM_KEY

See Also:

Constant Field Values

POSITION_STATUS_BAR_ITEM_KEY

public static final String POSITION_STATUS_BAR_ITEM_KEY

See Also:

Constant Field Values

Constructor Detail

BasicApp

public BasicApp(ApplicationDescriptor applicationDescriptor)

BasicApp

protected BasicApp(String appName,
                   String appSymbolicName,
                   String appVersion,
                   String appCopyrightInfo,
                   String appResource,
                   String appLoggerName)

Constructs a new application frame and creates the GUI.

Parameters:

appName - the application base name, appears in the frame's title bar

appSymbolicName - the symbolic name of the application

appVersion - the version string

appCopyrightInfo - the copyright information text

appResource - the resource path of the application's resource bundle, can be null if the application does not use resource bundles

appLoggerName - the logger name for the application logging, can be null if the application does not use logging

See Also:

ResourceBundle

Method Detail

getApplicationDescriptor

public ApplicationDescriptor getApplicationDescriptor()

getMouseOverActionHandler

public MouseListener getMouseOverActionHandler()

Returns:

the handler used if the user moves the mouse over a menu item or toolbar button

isFrameBoundsRestored

public boolean isFrameBoundsRestored()

getStatusBar

public com.jidesoft.status.StatusBar getStatusBar()

Returns:

the application's status bar

getMainToolBar

public com.jidesoft.action.CommandBar getMainToolBar()

Returns:

the application's main tool bar

getPreferencesFile

public File getPreferencesFile()

Returns:

the user's preferences file

getLogger

public Logger getLogger()

Returns:

the application logger

isStartedUp

public boolean isStartedUp()

isShuttingDown

public boolean isShuttingDown()

setShuttingDown

protected void setShuttingDown(boolean shuttingDown)

startUp

public void startUp(com.bc.ceres.core.ProgressMonitor pm)
             throws Exception

Starts up the application.

The startup sequence is as follows:

1. The method createSplashScreen is called. If it returns non-null
the splash screen is shown.
2. The method loadPreferences is called in order to load user preferences.
3. The method startUp is called with the splash screen. Clients can override this method in order to implement application specific initialisation code.
4. The method applyPreferences is called.
5. The main frame is shown.
6. The splash screen (if any) is closed.

Parameters:

pm - a progress monitor, e.g. for splash-screen

Throws:

Exception - if an error occurs

getAppCopyright

public String getAppCopyright()

handleImminentExit

protected void handleImminentExit()

Called by the exit method. The default implementation first saves the user preferences. You should not call this method directly. If you override this method, make sure to call the base class version as well.

See Also:

savePreferences()

createMainToolBar

protected com.jidesoft.action.CommandBar createMainToolBar()

Returns:

the tool bar for this application.

createMainPane

protected JComponent createMainPane()

Returns:

the main pane for this application.

createMainMenuBar

protected com.jidesoft.action.CommandBar createMainMenuBar()

Returns:

the menu bar for this application.

createStatusBar

protected com.jidesoft.status.StatusBar createStatusBar()

Returns:

a standard status bar for this application.

createFrameIcon

protected ImageIcon createFrameIcon()

Creates a default frame icon for this application.

Override this method if you want another behaviour.

Returns:

the frame icon, or null if no icon is used

initClient

protected void initClient(com.bc.ceres.core.ProgressMonitor pm)
                   throws Exception

Starts up the client application.

Called from startUp(com.bc.ceres.core.ProgressMonitor) before initClientUI(com.bc.ceres.core.ProgressMonitor) is called.

Clients should override this method in order to initialize non-UI components, e.g. load plugins.

The default implementation does nothing.

Parameters:

pm - a progress monitor, can be used to signal progress

Throws:

Exception - if an error occurs

initClientUI

protected void initClientUI(com.bc.ceres.core.ProgressMonitor pm)
                     throws Exception

Initializes the client user interface.

Called from startUp(com.bc.ceres.core.ProgressMonitor) after initClient(com.bc.ceres.core.ProgressMonitor) is called.

Clients should override this method in order to initialize their UI components.

The default implementation does nothing.

Parameters:

pm - a progress monitor, can be used to signal progress

Throws:

Exception - if an error occurs

getMainFrame

public BasicApp.MainFrame getMainFrame()

createToolBar

protected com.jidesoft.action.CommandBar createToolBar(String toolBarId,
                                                       String title)

getToolBar

public com.jidesoft.action.CommandBar getToolBar(String toolBarId)

isToolBarVisible

public boolean isToolBarVisible(String toolBarId)

setToolBarVisible

public void setToolBarVisible(String toolBarId,
                              boolean visbile)

isStatusBarVisible

public boolean isStatusBarVisible()

setStatusBarVisible

public void setStatusBarVisible(boolean visible)

getAppName

public String getAppName()

Returns:

The (display) name of this application.

getAppSymbolicName

public String getAppSymbolicName()

Returns:

The symbolic name of this application.

getAppVersion

public String getAppVersion()

Returns:

The version string of this application.

getAppBuildInfo

public String getAppBuildInfo()

Returns:

The build information string.

getResourceBundle

public ResourceBundle getResourceBundle()

Returns the resource bundle used by this application.

Returns:

the resource bundle, or null if a bundle does not exist

getImageResourcePath

public String getImageResourcePath()

Returns:

The path where application images such as toolbar icons are stored. The returned path is relative to this application's class path.

getCommandManager

public CommandManager getCommandManager()

Returns the command manager used for this application. In order to use another command manager than the default manager, override this method to return an alternative command manager, or call setCommandManager with your alternative implementation.

Returns:

the command manager, never null

setCommandManager

public void setCommandManager(CommandManager commandManager)

Sets the command manager to be used for this application.

Parameters:

commandManager - he command manager, must not be null

getCommandUIFactory

public CommandUIFactory getCommandUIFactory()

updateState

public final void updateState()

Updates the appication's (UI-) state. The default implementation calls updateState on each registered command.

setStatusBarMessage

public final void setStatusBarMessage(String message)

Sets the status bar message to the given message string.

Parameters:

message - the message to display

clearStatusBarMessage

public void clearStatusBarMessage()

Clears the status bar message. Simply calls setStatusBarMessage(" Ready.").

getStatusBarMessage

public final String getStatusBarMessage()

Returns:

The current status bar message string.

findMainMenu

public final JMenu findMainMenu(String name)

findMenu

public final JMenu findMenu(String name)

getToolBarGroups

public final String[] getToolBarGroups()

insertCommandToolBarButtons

protected final void insertCommandToolBarButtons(JToolBar toolbar)

insertCommandMenuItems

protected void insertCommandMenuItems()

configureCommandsByResourceBundle

protected final void configureCommandsByResourceBundle()

insertCommandMenuItem

protected final void insertCommandMenuItem(Command command)

findMenu

protected final JMenu findMenu(String name,
                               boolean deepSearch)

createJMenu

protected final JMenu createJMenu(String name,
                                  String text,
                                  char mnemonic,
                                  String... cmdIds)

shutDown

public void shutDown()

Exits the application.

The base class implementation calls setShuttingDown(true), calls handleImminentExit() and disposes the main frame.

When this method is overridden, this base class's implementation should always be called last. However, the preferred way to change the shutdown behaviour is to override the handleImminentExit() method.

loadPreferences

protected final void loadPreferences()

savePreferences

protected final void savePreferences()

setPreferences

protected final void setPreferences()

applyPreferences

protected void applyPreferences()

applyLookAndFeelPreferences

protected final void applyLookAndFeelPreferences()

This method should be called after prefernces that affect the current look & feel have changed.

updateComponentTreeUI

protected void updateComponentTreeUI()

Called after the look & feel has changed. The method simply calls SwingUtilities.updateComponentTreeUI(getMainFrame()) in order to reflect changes of the look-and-feel.

You might want to override this method in order to call SwingUtilities.updateComponentTreeUI() on other top-level containers beside the main frame.

setCurrentDocTitle

public final void setCurrentDocTitle(String currentDocTitle)

Sets the current document title which appears in this frame's title bar.

Parameters:

currentDocTitle - the title

center

public final void center()

Centers this application frame within the screen area.

showFileOpenDialog

public final File showFileOpenDialog(String title,
                                     boolean dirsOnly,
                                     FileFilter fileFilter)

Opens a standard file-open dialog box.

Parameters:

title - a dialog-box title

dirsOnly - whether or not to select only directories

fileFilter - the file filter to be used, can be null

Returns:

the file selected by the user or null if the user canceled file selection

showFileOpenDialog

public final File showFileOpenDialog(String title,
                                     boolean dirsOnly,
                                     FileFilter fileFilter,
                                     String lastDirPropertyKey)

Opens a standard file-open dialog box.

Parameters:

title - a dialog-box title

dirsOnly - whether or not to select only directories

fileFilter - the file filter to be used, can be null

lastDirPropertyKey - the key under which the last directory the user visited is stored

Returns:

the file selected by the user or null if the user canceled file selection

showFileSaveDialog

public final File showFileSaveDialog(String title,
                                     boolean dirsOnly,
                                     FileFilter fileFilter,
                                     String defaultExtension,
                                     String fileName)

Opens a standard file-safe dialog box.

Parameters:

title - a dialog-box title

dirsOnly - whether or not to select only directories

fileFilter - the file filter to be used, can be null

defaultExtension - the extension used as default

fileName - the initial filename

Returns:

the file selected by the user or null if the user canceled file selection

showFileSaveDialog

public final File showFileSaveDialog(String title,
                                     boolean dirsOnly,
                                     FileFilter fileFilter,
                                     String defaultExtension,
                                     String fileName,
                                     String lastDirPropertyKey)

Opens a standard file-safe dialog box.

Parameters:

title - a dialog-box title

dirsOnly - whether or not to select only directories

fileFilter - the file filter to be used, can be null

defaultExtension - the extension used as default

fileName - the initial filename

lastDirPropertyKey - the key under which the last directory the user visited is stored

Returns:

the file selected by the user or null if the user canceled file selection

historyPush

protected void historyPush(File file)

registerJob

public final void registerJob(Object job)

Deprecated. No longer used

Registers a job (any job-like object). The application will not exit, unless all registered jobs have been deregistered using the unregisterJob(java.lang.Object) method.

Parameters:

job - any job-like object

unregisterJob

public final void unregisterJob(Object job)

Deprecated. No longer used

Deregisters a job (any job-like object). The application will not exit, unless all job registrations using the registerJob(java.lang.Object) method have been deregistered.

Parameters:

job - any job-like object

handleUnknownException

public final void handleUnknownException(Throwable e)

getSuppressibleOptionPane

public final SuppressibleOptionPane getSuppressibleOptionPane()

showErrorDialog

public final void showErrorDialog(String message)

showErrorDialog

public final void showErrorDialog(String title,
                                  String message)

showWarningDialog

public final void showWarningDialog(String message)

showWarningDialog

public final void showWarningDialog(String title,
                                    String message)

showInfoDialog

public final void showInfoDialog(String message,
                                 String preferencesKey)

showInfoDialog

public final void showInfoDialog(String title,
                                 String message,
                                 String preferencesKey)

showOutOfMemoryErrorDialog

public final void showOutOfMemoryErrorDialog(String message)

showMessageDialog

public final void showMessageDialog(String title,
                                    String message,
                                    int messageType,
                                    String preferencesKey)

showQuestionDialog

public final int showQuestionDialog(String message,
                                    String preferencesKey)

showQuestionDialog

public final int showQuestionDialog(String title,
                                    String message,
                                    String preferencesKey)

showQuestionDialog

public final int showQuestionDialog(String title,
                                    String message,
                                    boolean allowCancel,
                                    String preferencesKey)

showWarningsDialog

public final void showWarningsDialog(String message,
                                     String[] warnings)

promptForOverwrite

public final boolean promptForOverwrite(File file)

Prompts a question dialog asking the user whether or not he/she wants to overwrite an existing file. If the given file does not exists, the question dialog does not comes up.

Parameters:

file - the file to check for existance

Returns:

true if the user confirmes the dialog with 'yes' or the given file does not exist.

Throws:

IllegalArgumentException - if file is null

getPreferences

public final PropertyMap getPreferences()

getFileHistory

public final FileHistory getFileHistory()

getCloseHandler

public ActionListener getCloseHandler()

setCloseHandler

public void setCloseHandler(ActionListener closeHandler)

addHelp

public final void addHelp(ClassLoader classLoader,
                          String helpsetResourcePath)

Adds a new JavaHelp HelpSet to the existing help. The helpset is as a resource path to the JavaHelp helpset XML file (*.hs). The helpset and associated resources must be accessible by the given class-loader.

Note that you also can add help-set instances directly to the BEAM help system by using the static HelpSys.add(javax.help.HelpSet) method.

For more information on the JavaHelp architecture and API please refer to the JavaHelp home page.

Parameters:

classLoader - the class loader used to load the help resources

helpsetResourcePath - the resource path to the helpset file (*.hs)