org.jhotdraw.app
Interface View

All Superinterfaces:

Disposable

All Known Subinterfaces:

PrintableView

All Known Implementing Classes:

AbstractView, DrawView, NetView, ODGView, PertView, SVGView, TeddyView

@NotNull
public interface View
extends Disposable

A view paints a document on a JComponent within an Application.

The document is identified by an URI (for example a text document which is identified by the URI "file://home/readme.txt"). If the same URI is opened in multiple views, the application sets a 'multiple open ID' on the view, so that the user can distinguish between the views.

The life of view objects is managed by an application. See the class comment of Application on how to launch an application.

The lifecycle of a view consists of the following steps:

1. Creation
   The application instantiates the view object by calling newInstance() on the class of the view.
2. Initialisation
   The application calls the following methods: setActionMap(); setApplication(); init(). Then it either calls clear() or read() on a worker thread.
3. Start
   The application adds the component of the view to a container (for example a JFrame) and then calls start().
4. Activation
   When a view becomes the active view of the application, application calls activate().
5. Deactivation
   When a view is not anymore the active view of the application, application calls deactivate(). At a later time, the view may become activated again.
6. Stop
   The application calls stop() on the view and then removes the component from its container. At a later time, the view may be started again.
7. Dispose
   When the view is no longer needed, application calls dispose() on the view, followed by setApplication(null) and then removes all references to it, so that it can be garbage collected.

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.

Version:

$Id: View.java 667 2010-07-28 19:51:42Z rawcoder $

Author:

Werner Randelshofer

Field Summary

static java.lang.String	APPLICATION_PROPERTY The name of the application property.
static java.lang.String	ENABLED_PROPERTY The name of the enabled property.
static java.lang.String	HAS_UNSAVED_CHANGES_PROPERTY The name of the hasUnsavedChanges property.
static java.lang.String	MULTIPLE_OPEN_ID_PROPERTY The name of the multipleOpenId property.
static java.lang.String	SHOWING_PROPERTY The name of the showing property.
static java.lang.String	TITLE_PROPERTY The name of the title property.
static java.lang.String	URI_PROPERTY The name of the uri property.

Method Summary

void	activate() Activates the view.
void	addDisposable(Disposable disposable) Adds a disposable object, which will be disposed when the view is disposed.
void	addPropertyChangeListener(java.beans.PropertyChangeListener l) Adds a property change listener.
boolean	canSaveTo(java.net.URI uri) Returns true, if this view can be saved to the specified URI.
void	clear() Clears the view, for example by emptying the contents of the view, or by reading a template contents from a file.
void	deactivate() Deactivates the view.
void	dispose() Gets rid of all the resources of the view.
void	execute(java.lang.Runnable worker) Executes the specified runnable on the worker thread of the view.
javax.swing.ActionMap	getActionMap() Gets the action map of the view.
Application	getApplication() Gets the application to which this view belongs.
javax.swing.JComponent	getComponent() Returns the visual component of the view.
int	getMultipleOpenId() Returns the multiple open id.
java.lang.String	getTitle() Gets the title of the view.
java.net.URI	getURI() Returns the uri which holds the document of the view.
boolean	hasUnsavedChanges() Returns true, if the view has unsaved changes.
void	init() Initializes the view.
boolean	isEnabled() Returns the enabled state of the view.
boolean	isShowing() This is used by Application to keep track if a view is showing.
void	markChangesAsSaved() Marks all changes as saved.
void	read(java.net.URI uri, URIChooser chooser) Reads the view from the specified URI.
void	removeDisposable(Disposable disposable) Removes a disposable object, which was previously added.
void	removePropertyChangeListener(java.beans.PropertyChangeListener l) Removes a property change listener.
void	setActionMap(javax.swing.ActionMap m) Sets the action map for the view.
void	setApplication(Application newValue) Sets the application of the view.
void	setEnabled(boolean newValue) Sets the enabled state of the view.
void	setMultipleOpenId(int newValue) Sets the multiple open id.
void	setShowing(boolean newValue) This is used by Application to keep track if a view is showing.
void	setTitle(java.lang.String newValue) Sets the title of the view.
void	setURI(java.net.URI newValue) Sets the uri of the view.
void	start() Starts the view.
void	stop() Stops the view.
void	write(java.net.URI uri, URIChooser chooser) Writes the view to the specified URI.

Field Detail

URI_PROPERTY

static final java.lang.String URI_PROPERTY

The name of the uri property.

See Also:

Constant Field Values

APPLICATION_PROPERTY

static final java.lang.String APPLICATION_PROPERTY

The name of the application property.

See Also:

Constant Field Values

TITLE_PROPERTY

static final java.lang.String TITLE_PROPERTY

The name of the title property.

See Also:

Constant Field Values

ENABLED_PROPERTY

static final java.lang.String ENABLED_PROPERTY

The name of the enabled property.

See Also:

Constant Field Values

HAS_UNSAVED_CHANGES_PROPERTY

static final java.lang.String HAS_UNSAVED_CHANGES_PROPERTY

The name of the hasUnsavedChanges property.

See Also:

Constant Field Values

MULTIPLE_OPEN_ID_PROPERTY

static final java.lang.String MULTIPLE_OPEN_ID_PROPERTY

The name of the multipleOpenId property.

See Also:

Constant Field Values

SHOWING_PROPERTY

static final java.lang.String SHOWING_PROPERTY

The name of the showing property.

See Also:

Constant Field Values

Method Detail

getApplication

Application getApplication()

Gets the application to which this view belongs.

setApplication

void setApplication(Application newValue)

Sets the application of the view. By convention, this is only invoked by Application.add() and Application.remove(). This is a bound property.

getComponent

javax.swing.JComponent getComponent()

Returns the visual component of the view.

isEnabled

boolean isEnabled()

Returns the enabled state of the view.

setEnabled

void setEnabled(boolean newValue)

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

clear

void clear()

Clears the view, for example by emptying the contents of the view, or by reading a template contents from a file. By convention this method is never invoked on the AWT Event Dispatcher Thread.

hasUnsavedChanges

boolean hasUnsavedChanges()

Returns true, if the view has unsaved changes. This is a bound property.

markChangesAsSaved

void markChangesAsSaved()

Marks all changes as saved. This changes the state of hasUnsavedChanges to false.

execute

void execute(java.lang.Runnable worker)

Executes the specified runnable on the worker thread of the view. Execution is performed sequentially in the same sequence as the runnables have been passed to this method.

Use this method for long running tasks which affect the contents of the view as a whole. For example for loading and saving a document.

init

void init()

Initializes the view. This is invoked right before the application shows the view. A view must not consume many resources before method init() is called. This is crucial for the responsivenes of an application.

After a view has been initialized using init(), either method clear() must be called or method read, in order to fully initialize a View.

start

void start()

Starts the view. Invoked after a view has been made visible to the user. Multiple view can be visible at the same time.

activate

void activate()

Activates the view. This occurs, when the user activated the parent window of the view. Only one view can be active at any given time. This method is only invoked on a started view.

deactivate

void deactivate()

Deactivates the view. This occurs, when the user closes the view, or activated another view. This method is only invoked on a started view.

stop

void stop()

Stops the view. Invoked after a view window has been minimized or made invisible.

dispose

void dispose()

Gets rid of all the resources of the view. No other methods should be invoked on the view afterwards. A view must not consume many resources after method dispose() has been called. This is crucial for the responsivenes of an application.

Specified by:

dispose in interface Disposable

getActionMap

javax.swing.ActionMap getActionMap()

Gets the action map of the view.

setActionMap

void setActionMap(javax.swing.ActionMap m)

Sets the action map for the view.

addPropertyChangeListener

void addPropertyChangeListener(java.beans.PropertyChangeListener l)

Adds a property change listener.

removePropertyChangeListener

void removePropertyChangeListener(java.beans.PropertyChangeListener l)

Removes a property change listener.

setMultipleOpenId

void setMultipleOpenId(int newValue)

Sets the multiple open id. The id is used to help distinguish multiply opened views. The id should be displayed in the title of the view.

getMultipleOpenId

int getMultipleOpenId()

Returns the multiple open id. If a view is open only once this should be 1.

isShowing

boolean isShowing()

This is used by Application to keep track if a view is showing.

setShowing

void setShowing(boolean newValue)

This is used by Application to keep track if a view is showing.

setTitle

void setTitle(java.lang.String newValue)

Sets the title of the view.

The title is generated by the application, based on the current URI of the view. The application ensures that the title uniquely identifies each open view.

The application displays the title in the title bar of the view window and in all windows which are associated to the view.

This is a bound property.

getTitle

java.lang.String getTitle()

Gets the title of the view.

addDisposable

void addDisposable(Disposable disposable)

Adds a disposable object, which will be disposed when the view is disposed.

Parameters:

disposable -

removeDisposable

void removeDisposable(Disposable disposable)

Removes a disposable object, which was previously added.

Parameters:

disposable -

getURI

java.net.URI getURI()

Returns the uri which holds the document of the view.

setURI

void setURI(java.net.URI newValue)

Sets the uri of the view. This is a bound property.

canSaveTo

boolean canSaveTo(java.net.URI uri)

Returns true, if this view can be saved to the specified URI. A reason why the view can't be saved to a URI, is that the view is unable to write to a file-URI with the given filename extension without losing data.

The SaveAction uses this method to decide, whether to display a save dialog before saving the URI.

Parameters:

uri - An URI. If this parameter is null, a NullPointerException is thrown.

write

void write(java.net.URI uri,
           @Nullable
           URIChooser chooser)
           throws java.io.IOException

Writes the view to the specified URI.

By convention this method is never invoked on the AWT Event Dispatcher Thread.

Parameters:

uri - The location where to write the view.

chooser - The chooser which was used for selecting the URI. This parameter is null if no chooser was used.

Throws:

java.io.IOException

read

void read(java.net.URI uri,
          @Nullable
          URIChooser chooser)
          throws java.io.IOException

Reads the view from the specified URI.

By convention this method is never invoked on the AWT Event Dispatcher Thread.

Parameters:

uri - The location where to write the view.

chooser - The chooser which was used for selecting the URI. This parameter is null if no chooser was used.

Throws:

java.io.IOException