JHotDraw 7.4.1

org.jhotdraw.app
Interface View

All Known Subinterfaces:
PrintableView
All Known Implementing Classes:
AbstractView, DrawView, NetView, ODGView, PertView, SVGView, TeddyView

public interface View

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 610 2010-01-11 19:40:13Z 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 perfomred sequentially in the same sequence as the runnables have been passed to this method.


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.


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,
           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,
          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

Copyright 1996-2010 (c) by the authors and contributors of the JHotDraw project.
Some rights reserved.