diva.gui
Interface Document

All Known Implementing Classes:

AbstractDocument, MultipageDocument, TextDocument

public interface Document

Document is an interface that captures the notion of a document in a graphical application. Typically, documents are associated with files, although this is not necessarily so. Each application will typically create one or more implementations of this interface for the types of documents it can work with.

Version:

$Id: Document.java 38798 2005-07-08 20:00:01Z cxh $

Author:

John Reekie

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Add a property change listener to this document.
void	close() Close the document.
Application	getApplication() Get the application that this document belongs to.
javax.swing.undo.UndoableEditSupport	getEditSupport() Return the undoable edit support.
java.io.File	getFile() Get the file object that this document is associated with.
java.lang.String	getShortTitle() Get the short title of this document.
java.lang.String	getTitle() Get the title of this document
javax.swing.undo.UndoManager	getUndoManager() Return the undo manager of this document.
java.net.URL	getURL() Get the URL that this document is associated with.
boolean	isDirty() Test the "dirty" flag.
boolean	isEditable() Test the "editable" flag.
boolean	isWritable() Test the "writable" flag.
void	open() Open the document from its current file or URL.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Remove a property change listener from this document.
void	save() Save the document to its current file or URL.
void	saveAs(java.io.File file) Save the document to the given file.
void	saveAs(java.net.URL url) Save the document to the given URL.
void	setDirty(boolean flag) Set the "dirty" flag.
void	setEditable(boolean flag) Set the "editable" flag.
void	setFile(java.io.File file) Set the file that this document saves itself to.
void	setURL(java.net.URL url) Set the URL that this document saves itself to.
void	setWritable(boolean flag) Set the "writable" flag.

Method Detail

addPropertyChangeListener

void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a property change listener to this document. Changes to certain elements of the state of the Document require that registered property change listeners be notified of the change.

close

void close()
           throws java.lang.Exception

Close the document. Do not attempt to save the document first or do any other user-interface things like that. This method can thrown an exception if there is a failure, but it should only do so if there is no way it can recover. Note that actions such as querying the user to save a modified document and so on are the responsibility of the application, not the Document implementation.

Throws:

java.lang.Exception - If the close operation fails.

getApplication

Application getApplication()

Get the application that this document belongs to.

getEditSupport

javax.swing.undo.UndoableEditSupport getEditSupport()

Return the undoable edit support. You need this to post edits.

getUndoManager

javax.swing.undo.UndoManager getUndoManager()

Return the undo manager of this document.

getFile

java.io.File getFile()

Get the file object that this document is associated with. If the document has multiple file objects, then get the one that can be considered the "primary" one. This field may be null.

See Also:

getURL()

getTitle

java.lang.String getTitle()

Get the title of this document

getShortTitle

java.lang.String getShortTitle()

Get the short title of this document. The short title is used in situations where the regular title is likely to be too long, such as iconified windows, menus, and so on.

getURL

java.net.URL getURL()

Get the URL that this document is associated with. If the document has multiple URL objects, then get the one that can be considered the "primary" one. This field may be null.

See Also:

getFile()

isDirty

boolean isDirty()

Test the "dirty" flag. If changes made to a document haven't been saved, this flag is set to true.

isEditable

boolean isEditable()

Test the "editable" flag. In general, editors should only allow a document's data to be changed if this flag is set.

isWritable

boolean isWritable()

Test the "writable" flag. In general, editors should only allow a document's data to be written to storage if this flag is set.

open

void open()
          throws java.lang.Exception

Open the document from its current file or URL. Throw an exception if the operation failed.

Throws:

java.lang.Exception - If the close operation fails.

removePropertyChangeListener

void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Remove a property change listener from this document.

save

void save()
          throws java.lang.Exception

Save the document to its current file or URL. Throw an exception if the operation failed. Reasons for failure might include the fact that the file is not writable, or that the document has a URL but we haven't implemented HTTP-DAV support yet...

Throws:

java.lang.Exception - If the save operation fails.

saveAs

void saveAs(java.io.File file)
            throws java.lang.Exception

Save the document to the given file. Throw an exception if the operation failed. Return true if successful, false if not. Do not change the file attribute to the new File object as that is the responsibility of the application, which it will do according to its storage policy.

Throws:

java.lang.Exception - If the save-as operation fails.

See Also:

save()

saveAs

void saveAs(java.net.URL url)
            throws java.lang.Exception

Save the document to the given URL. Throw an exception if the operation failed. Do not change the URL attribute to the new URL object as that is the responsibility of the application, which it will do according to its storage policy.

Throws:

java.lang.Exception - If the save-as operation fails.

See Also:

save()

setEditable

void setEditable(boolean flag)

Set the "editable" flag. Fire a property change event to registered listeners.

setFile

void setFile(java.io.File file)

Set the file that this document saves itself to. This is a low-level method and should only be used by storage policy classes. Fire a property change listener to registered listeners.

setDirty

void setDirty(boolean flag)

Set the "dirty" flag. Fire a property change event to registered listeners.

setURL

void setURL(java.net.URL url)

Set the URL that this document saves itself to. This is a low-level method and should only be used by storage policy classes. Fire a property change listener to registered listeners.

setWritable

void setWritable(boolean flag)

Set the "writable" flag. Fire a property change event to registered listeners.