org.jhotdraw.app
Interface Application

All Known Implementing Classes:

AbstractApplication, AppletApplication, MDIApplication, OSXApplication, SDIApplication

public interface Application

An application handles the lifecycle of View objects and provides windows to present them on screen.

An application owns a ApplicationModel which provides meta-data about the application, actions and factory methods for creating the views.

Depending on the document interface style used by the application, an application can handle multiple views at the same time, or only one.

Typical document interface styles are the Single Document Interface (SDI), the Multiple Document Interface (MDI) and the Mac OS X Application Interface (OSX). Typically, for each of these styles an implementation of Application exists.

Some applications have to decorate all opened windows and dialogs with user interface elements and special behaviors. To make this work, it is essential that all code which opens JFrame's, JDialog's or JWindow's calls the addWindow/Palette and removeWindow/Palette methods on the application object.

Unless stated otherwise all methods must be called from the AWT Event Dispatcher Thread.

Typical usage of this class:

 public class MyMainClass {
     public static void main(String[] args) {
         Application app = new SDIApplication(); // or OSXApplication(), MDIApplication().
         DefaultApplicationModel model = new DefaultApplicationModel();
         model.setName("MyApplication");
         model.setVersion("1.0");
         model.setCopyright("Copyright 2006 (c) Werner Randelshofer. All Rights Reserved.");
         model.setViewClassName("org.jhotdraw.myapplication.MyView");
         app.setModel(model);
         app.launch(args);
     } 
 

Features

Open last URI on launch
When the application is launched, it opens the last opened URI in a view.
Application also provides an API for data suppliers in addRecentURI(java.net.URI), getRecentURIs(), clearRecentURIs().
See org.jhotdraw.app for a description of the feature.

Design Patterns

Framework
The interfaces and classes listed below together with the Action classes in the org.jhotddraw.app.action package define the contracts of a framework for document oriented applications:
Contract: Application, ApplicationModel, View.

Abstract Factory
MenuBuilder is used by Application for creating menu items. The MenuBuilder is provided by ApplicationModel.
Abstract Factory: MenuBuilder
Client: Application.

Version:

$Id: Application.java 748 2011-08-01 10:01:44Z rawcoder $

Author:

Werner Randelshofer

Field Summary

static java.lang.String	ACTIVE_VIEW_PROPERTY The property name of the activeView property.
static java.lang.String	RECENT_URIS_PROPERTY The property name of the recentURIs property.

Method Summary

void	add(View p) Adds a view to this application.
void	addPalette(java.awt.Window palette) Adds a palette window to the application.
void	addPropertyChangeListener(java.beans.PropertyChangeListener l) Adds a property change listener.
void	addRecentURI(java.net.URI uri) Adds an URI to the start of the list of recent URIs.
void	addWindow(java.awt.Window window, View view) Adds a (non-palette) window to the application.
void	clearRecentURIs() Clears the list of recent URIs.
void	configure(java.lang.String[] args) Configures the application using the provided arguments array.
javax.swing.JMenu	createEditMenu(View v) Creates an edit menu for the specified view or for the entire application.
javax.swing.JMenu	createFileMenu(View v) Creates a file menu for the specified view or for the entire application.
javax.swing.JMenu	createHelpMenu(View v) Creates a help menu for the specified view of for the entire application.
View	createView() Creates a new view for this application and initializes it, by calling View.init().
javax.swing.JMenu	createViewMenu(View v) Creates a view menu for the specified view or for the entire application.
javax.swing.JMenu	createWindowMenu(View v) Creates a window menu for the specified view or for the entire application.
void	destroy() Stops the application and then calls System.exit(0).
void	dispose(View p) This is a convenience method for removing a view and disposing it.
javax.swing.ActionMap	getActionMap(View v) Gets an action map for the specified view or for the entire application.
View	getActiveView() Returns the active view.
java.awt.Component	getComponent() Returns the application component.
java.lang.String	getCopyright() Returns the copyright of the application.
URIChooser	getExportChooser(View v) Gets an export chooser for the specified view or for the entire application.
URIChooser	getImportChooser(View v) Gets an import chooser for the specified view or for the entire application.
ApplicationModel	getModel() Returns the application model.
java.lang.String	getName() Returns the name of the application.
URIChooser	getOpenChooser(View v) Gets an open chooser for the specified view or for the entire application.
java.util.List<java.net.URI>	getRecentURIs() Returns the recently opened URIs.
URIChooser	getSaveChooser(View v) Gets a save chooser for the specified view or for the entire application.
java.lang.String	getVersion() Returns the version of the application.
java.util.List<View>	getViews() Returns an unmodifiable list of all views of the application.
void	hide(View p) Hides a view.
void	init() Initializes the application.
boolean	isEnabled() Returns the enabled state of the application.
boolean	isSharingToolsAmongViews() Returns true, if this application shares tools among multiple views.
void	launch(java.lang.String[] args) Launches the application from the main method.
void	remove(View p) Removes a view from this application and removes it from the users view.
void	removePalette(java.awt.Window palette) Removes a palette window from the application.
void	removePropertyChangeListener(java.beans.PropertyChangeListener l) Removes a property change listener.
void	removeWindow(java.awt.Window window) Removes a (non-palette) window from the application.
void	setEnabled(boolean newValue) Sets the enabled state of the application.
void	setModel(ApplicationModel newValue) Sets the application model.
void	show(View p) Shows a view.
void	start(java.util.List<java.net.URI> uris) Starts the application.
void	stop() Stops the application without saving any unsaved views.
java.util.Collection<View>	views() Returns a read only collection view of the views of this application.

Field Detail

ACTIVE_VIEW_PROPERTY

static final java.lang.String ACTIVE_VIEW_PROPERTY

The property name of the activeView property.

See Also:

Constant Field Values

RECENT_URIS_PROPERTY

static final java.lang.String RECENT_URIS_PROPERTY

The property name of the recentURIs property.

See Also:

Constant Field Values

Method Detail

launch

void launch(java.lang.String[] args)

Launches the application from the main method.

This method must be called from the main thread of the application.

Implementations of this method must invoke configure() on the current thread and then init(); applicationModel.initApplication(this); start(); on the AWT Event Dispatcher Thread.

The launch method determines which URI's it wants to supply to the start() method. Typically, if URI's have been passed in the args parameter, they are passed on to the start() method. Otherwise, if the property openLastURIOnLaunch of the application model is true, the last opened URI is passed to the start method.

This method implements behavior for the following features: Launch application, Open last URI on launch. See org.jhotdraw.app.

configure

void configure(java.lang.String[] args)

Configures the application using the provided arguments array.

This method must be called from the main thread of the application.

This method implements behavior for the following feature: Open URIs from command line on launch. See org.jhotdraw.app.

init

void init()

Initializes the application.

By convention this method is only called after configure(java.lang.String[]) has been called.

start

void start(java.util.List<java.net.URI> uris)

Starts the application.

This method creates a view for each supplied URI, and adds it to the application. If no URI has been supplied, this method may open an empty view.

By convention this method is only called after init() has been called.

This method implements behavior for the following feature: Open URI on launch. See org.jhotdraw.app.

Parameters:

uris - Upon launch, the application may be requested to open views for a given list of URI's.

stop

void stop()

Stops the application without saving any unsaved views.

By convention this method is only called after init() has been called.

This method must be called from AWT Event Dispatcher Thread.

destroy

void destroy()

Stops the application and then calls System.exit(0).

By convention this method is only called after init() has been called.

This method must be called from AWT Event Dispatcher Thread.

createView

View createView()

Creates a new view for this application and initializes it, by calling View.init(). The view has not been added to the application yet. To make the view usable with this application, call add(View). To make it visible, first call add(View), then show(View).

add

void add(View p)

Adds a view to this application. Fires a "documentCount" property change event. Invokes method setApplication(this) on the view object.

remove

void remove(View p)

Removes a view from this application and removes it from the users view. Fires a "documentCount" property change event. Invokes method setApplication(null) on the view object.

show

void show(View p)

Shows a view.

hide

void hide(View p)

Hides a view.

dispose

void dispose(View p)

This is a convenience method for removing a view and disposing it.

views

java.util.Collection<View> views()

Returns a read only collection view of the views of this application.

getActiveView

@Nullable
View getActiveView()

Returns the active view. This is used for OSXApplication and MDIApplication which share actions among multiple View instances. Active view may be become null, if the application has no view.

This is a bound property.

isEnabled

boolean isEnabled()

Returns the enabled state of the application.

setEnabled

void setEnabled(boolean newValue)

Sets the enabled state of the application. The enabled state is used to prevent parallel invocation of actions on the application. If an action consists of a sequential part and a concurrent part, it must disable the application only for the sequential part. Actions that act on the application must check in their actionPerformed method whether the application is enabled. If the application is disabled, they must do nothing. If the application is enabled, they must disable the application, perform the action and then enable the application again. This is a bound property.

addPropertyChangeListener

void addPropertyChangeListener(java.beans.PropertyChangeListener l)

Adds a property change listener.

removePropertyChangeListener

void removePropertyChangeListener(java.beans.PropertyChangeListener l)

Removes a property change listener.

getName

java.lang.String getName()

Returns the name of the application.

getVersion

java.lang.String getVersion()

Returns the version of the application.

getCopyright

java.lang.String getCopyright()

Returns the copyright of the application.

setModel

void setModel(ApplicationModel newValue)

Sets the application model.

getModel

ApplicationModel getModel()

Returns the application model.

isSharingToolsAmongViews

boolean isSharingToolsAmongViews()

Returns true, if this application shares tools among multiple views.

getComponent

@Nullable
java.awt.Component getComponent()

Returns the application component. This may return null, if the application is not represented by a component of its own on the user interface.

addPalette

void addPalette(java.awt.Window palette)

Adds a palette window to the application.

removePalette

void removePalette(java.awt.Window palette)

Removes a palette window from the application.

addWindow

void addWindow(java.awt.Window window,
               @Nullable
               View view)

Adds a (non-palette) window to the application.

Parameters:

window - The window.

view - The View to which this window is associated, or null if the window is associated to the application.

removeWindow

void removeWindow(java.awt.Window window)

Removes a (non-palette) window from the application.

getRecentURIs

java.util.List<java.net.URI> getRecentURIs()

Returns the recently opened URIs. By convention, this is an unmodifiable list. The first item in the list is the most recently opened URI.

The most recent URI is used by the Open last URI on launch feature. See org.jhotdraw.app.

addRecentURI

void addRecentURI(java.net.URI uri)

Adds an URI to the start of the list of recent URIs.

This fires a property change event for the property "recentURIs".

The recent URIs are persisted (for example using the Java Preferences API) so that they are available on the next launch of the application.

The most recent URI is used by the Open last URI on launch feature. See org.jhotdraw.app.

clearRecentURIs

void clearRecentURIs()

Clears the list of recent URIs. This fires a property change event for the property "recentURIs".

The recent URIs are persisted (for example using the Java Preferences API) so that they are available on the next launch of the application.

The most recent URI is used by the Open last URI on launch feature. See org.jhotdraw.app.

createFileMenu

@Nullable
javax.swing.JMenu createFileMenu(@Nullable
                                          View v)

Creates a file menu for the specified view or for the entire application.

Parameters:

v - A view or null.

Returns:

A JMenu or null, if the menu is empty.

createEditMenu

@Nullable
javax.swing.JMenu createEditMenu(@Nullable
                                          View v)

Creates an edit menu for the specified view or for the entire application.

Parameters:

v - A view or null.

Returns:

A JMenu or null, if the menu is empty.

createViewMenu

@Nullable
javax.swing.JMenu createViewMenu(@Nullable
                                          View v)

Creates a view menu for the specified view or for the entire application.

Parameters:

v - A view or null.

Returns:

A JMenu or null, if the menu is empty.

createWindowMenu

@Nullable
javax.swing.JMenu createWindowMenu(@Nullable
                                            View v)

Creates a window menu for the specified view or for the entire application.

Parameters:

v - A view or null.

Returns:

A JMenu or null, if the menu is empty.

createHelpMenu

@Nullable
javax.swing.JMenu createHelpMenu(@Nullable
                                          View v)

Creates a help menu for the specified view of for the entire application.

Parameters:

v - A view or null.

Returns:

A JMenu or null, if the menu is empty.

getOpenChooser

URIChooser getOpenChooser(@Nullable
                          View v)

Gets an open chooser for the specified view or for the entire application.

Parameters:

v - A view or null.

Returns:

A chooser.

getSaveChooser

URIChooser getSaveChooser(@Nullable
                          View v)

Gets a save chooser for the specified view or for the entire application.

Parameters:

v - A view or null.

Returns:

A chooser.

getExportChooser

URIChooser getExportChooser(@Nullable
                            View v)

Gets an export chooser for the specified view or for the entire application.

Parameters:

v - A view or null.

Returns:

A chooser.

getImportChooser

URIChooser getImportChooser(@Nullable
                            View v)

Gets an import chooser for the specified view or for the entire application.

Parameters:

v - A view or null.

Returns:

A chooser.

getActionMap

javax.swing.ActionMap getActionMap(@Nullable
                                   View v)

Gets an action map for the specified view or for the entire application.

Parameters:

v - A view or null

getViews

java.util.List<View> getViews()

Returns an unmodifiable list of all views of the application.

The list of views is used by the Allow multiple views per URI feature. See org.jhotdraw.app.