/*
* @(#)Application.java
*
* Copyright (c) 1996-2010 by the original authors of JHotDraw and all its
* contributors. All rights reserved.
*
* You may not use, copy or modify this file, except in compliance with the
* license agreement you entered into with the copyright holders. For details
* see accompanying license terms.
*/
package org.jhotdraw.app;
import edu.umd.cs.findbugs.annotations.Nullable;
import java.awt.Component;
import java.awt.Window;
import java.beans.PropertyChangeListener;
import java.net.URI;
import java.util.Collection;
import java.util.List;
import javax.swing.ActionMap;
import javax.swing.JMenu;
import org.jhotdraw.gui.URIChooser;
/**
* An application handles the lifecycle of {@link View} objects and
* provides windows to present them on screen.
*
* An application owns a {@link 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
* {@code 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.
*
* 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);
* }
*
*
* Design Patterns
*
* Framework
* The interfaces and classes listed below together with the {@code Action}
* classes in the org.jhotddraw.app.action package define the contracts of a
* framework for document oriented applications:
* Contract: {@link Application}, {@link ApplicationModel}, {@link View}.
*
*
Abstract Factory
* {@code MenuBuilder} is used by {@code Application} for creating menu items.
* The {@code MenuBuilder} is provided by {@code ApplicationModel}.
* Abstract Factory: {@link MenuBuilder}
* Client: {@link Application}.
*
*
* @author Werner Randelshofer
* @version $Id: Application.java 722 2010-11-26 08:49:25Z rawcoder $
*/
public interface Application {
/**
* The property name of the activeView property.
*/
public final static String ACTIVE_VIEW_PROPERTY = "activeView";
/**
* The property name of the recentURIs property.
*/
public final static String RECENT_URIS_PROPERTY = "recentURIs";
/**
* Launches the application from the main method.
* This method is typically invoked on the main Thread.
* This will invoke configure() on the current thread and then
* init() and start() on the AWT Event Dispatcher Thread.
*/
public void launch(String[] args);
/**
* Configures the application using the provided arguments array.
*/
public void configure(String[] args);
/**
* Initializes the application.
* configure() should have been invoked before the application
* is inited. Alternatively an application can be configured using setter
* methods.
*/
public void init();
/**
* Starts the application.
* This usually creates at least one view, and adds it to the application.
* init() must have been invoked before the application is started.
*
* @param uris Upon launch, the application may be requested to open views
* for a given list of URI's.
*/
public void start(List uris);
/**
* Stops the application without saving any unsaved views.
* init() must have been invoked before the application is stopped.
*/
public void stop();
/**
* Destroys the application and calls System.exit(0).
*/
public void destroy();
/**
* Creates a new view for this application and initializes it, by calling
* {@link View#init}.
*/
public View createView();
/**
* Adds a view to this application.
* Fires a "documentCount" property change event.
* Invokes method setApplication(this) on the view object.
*/
public void add(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.
*/
public void remove(View p);
/**
* Shows a view.
*/
public void show(View p);
/**
* Hides a view.
*/
public void hide(View p);
/**
* This is a convenience method for removing a view and disposing it.
*/
public void dispose(View p);
/**
* Returns a read only collection view of the views of this application.
*/
public Collection views();
/**
* 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.
*/
@Nullable public View getActiveView();
/**
* Returns the enabled state of the application.
*/
public boolean isEnabled();
/**
* 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.
*/
public void setEnabled(boolean newValue);
/**
* Adds a property change listener.
*/
public void addPropertyChangeListener(PropertyChangeListener l);
/**
* Removes a property change listener.
*/
public void removePropertyChangeListener(PropertyChangeListener l);
/**
* Returns the name of the application.
*/
public String getName();
/**
* Returns the version of the application.
*/
public String getVersion();
/**
* Returns the copyright of the application.
*/
public String getCopyright();
/**
* Sets the application model.
*/
public void setModel(ApplicationModel newValue);
/**
* Returns the application model.
*/
public ApplicationModel getModel();
/**
* Returns true, if this application shares tools among multiple views.
*/
public boolean isSharingToolsAmongViews();
/**
* Returns the application component.
* This may return null, if the application is not represented by a component
* of its own on the user interface.
*/
@Nullable public Component getComponent();
/**
* Adds a palette window to the application.
*/
public void addPalette(Window palette);
/**
* Removes a palette window from the application.
*/
public void removePalette(Window palette);
/**
* Adds a (non-palette) window to the application.
*
* @param window The window.
* @param view The View to which this window is associated, or null
* if the window is associated to the application.
*/
public void addWindow(Window window, @Nullable View view);
/**
* Removes a (non-palette) window from the application.
*/
public void removeWindow(Window window);
/**
* Returns the recently opened URIs.
* By convention, this is an immutable list.
*/
public java.util.List getRecentURIs();
/**
* Appends a URI to the list of recent URIs.
* This fires a property change event for the property "recentURIs".
*/
public void addRecentURI(URI uri);
/**
* Clears the list of recent URIs.
* This fires a property change event for the property "recentURIs".
*/
public void clearRecentURIs();
/**
* Creates a file menu for the specified view or for the entire application.
*
* @param v A view or null.
* @return A JMenu or null, if the menu is empty.
*/
@Nullable public JMenu createFileMenu(@Nullable View v);
/**
* Creates an edit menu for the specified view or for the entire application.
*
* @param v A view or null.
* @return A JMenu or null, if the menu is empty.
*/
@Nullable public JMenu createEditMenu(@Nullable View v);
/**
* Creates a view menu for the specified view or for the entire application.
*
* @param v A view or null.
* @return A JMenu or null, if the menu is empty.
*/
@Nullable public JMenu createViewMenu(@Nullable View v);
/**
* Creates a window menu for the specified view or for the entire application.
*
* @param v A view or null.
* @return A JMenu or null, if the menu is empty.
*/
@Nullable public JMenu createWindowMenu(@Nullable View v);
/**
* Creates a help menu for the specified view of for the entire application.
*
* @param v A view or null.
* @return A JMenu or null, if the menu is empty.
*/
@Nullable public JMenu createHelpMenu(@Nullable View v);
/**
* Gets an open chooser for the specified view or for the entire application.
*
* @param v A view or null.
* @return A chooser.
*/
public URIChooser getOpenChooser(@Nullable View v);
/**
* Gets a save chooser for the specified view or for the entire application.
*
* @param v A view or null.
* @return A chooser.
*/
public URIChooser getSaveChooser(@Nullable View v);
/**
* Gets an export chooser for the specified view or for the entire application.
*
* @param v A view or null.
* @return A chooser.
*/
public URIChooser getExportChooser(@Nullable View v);
/**
* Gets an import chooser for the specified view or for the entire application.
*
* @param v A view or null.
* @return A chooser.
*/
public URIChooser getImportChooser(@Nullable View v);
/**
* Gets an action map for the specified view or for the entire application.
*
* @param v A view or null
*/
public ActionMap getActionMap(@Nullable View v);
}
Ads help maintain this website.