gov.sns.application
Class XalDocument

java.lang.Object
  |
  +--gov.sns.application.XalDocument

All Implemented Interfaces:

java.awt.print.Pageable

Direct Known Subclasses:

AcceleratorDocument, MyDocument, ShowcaseDocument, ShowcaseDocument

public abstract class XalDocument

extends java.lang.Object

implements java.awt.print.Pageable

The base class for custom documents. Subclasses of this class need to define the logic for their document. Every document has a main window and a URL source that provides persistent storage.

Field Summary

protected XalDocumentListener	documentListenerProxy
protected boolean	hasChanges
protected XalWindow	mainWindow
protected MessageCenter	messageCenter
static int	NO_OPTION
protected java.net.URL	source
protected java.lang.String	title
static int	YES_OPTION

Fields inherited from interface java.awt.print.Pageable

UNKNOWN_NUMBER_OF_PAGES

Constructor Summary

XalDocument()
Constructor for new documents

Method Summary

void	addXalDocumentListener(XalDocumentListener listener) Add the listener for events from this document.
protected boolean	closeDocument() This method is a request to close a document.
protected void	customizeCommands(Commander commander) Override this method to register custom document commands if any.
int	displayConfirmDialog(java.lang.String title, java.lang.String message) Display a confirmation dialog with a title and message
void	displayError(java.lang.Exception exception) Display an error dialog box with information about the exception and provide an audible alert.
void	displayError(java.lang.String title, java.lang.String message) Display an error dialog box and provide an audible alert.
void	displayError(java.lang.String title, java.lang.String prefix, java.lang.Exception exception) Display an error dialog box with information about the exception and provide an audible alert.
void	displayWarning(java.lang.Exception exception) Display a warning dialog box with information about the exception and provide an audible alert.
void	displayWarning(java.lang.String title, java.lang.String message) Display a warning dialog box and provide an audible alert.
void	displayWarning(java.lang.String title, java.lang.String prefix, java.lang.Exception exception) Display a warning dialog box with information about the exception and provide an audible alert.
protected void	freeCustomResources() Dispose of custom document resources.
protected void	freeResources() Free document resources.
protected void	generateDocumentTitle() Generate and set the title for this document.
protected java.lang.String	getCustomMenuDefinitionPath() Subclasses should override this method if this document should use a menu definition other than the default specified in application adaptor.
protected java.lang.String	getDisplayFilePath() By default the file path to display for this document is set to the file path of the document or the default empty document file path if the document does not yet have a file store.
protected java.lang.String	getEmptyDocumentPath() Get the default file path to use for empty documents
XalWindow	getMainWindow() Get the main window for this document.
int	getNumberOfPages() Implement the Pageable interface.
java.awt.print.PageFormat	getPageFormat(int pageIndex) Implement the Pageable interface.
java.awt.print.Printable	getPrintable(int pageIndex) Implement the Pageable interface.
java.net.URL	getSource() Get the URL of the persistent storage for this document.
java.lang.String	getTitle() Get the document title.
boolean	hasChanges() Indicates if there are changes that need saving.
void	hideDocument() Hide this document.
boolean	isEmpty() Check if the document is empty.
protected abstract void	makeMainWindow() Subclasses must implement this method to make their custom main window.
protected void	registerEvents() Register this document as a source of DocumentListener events.
void	removeXalDocumentListener(XalDocumentListener listener) Remove the listener from event from this document.
void	saveDocument() Save this document to its persistent storage source.
abstract void	saveDocumentAs(java.net.URL url) Subclasses need to implement this method for saving the document to a URL.
void	setHasChanges(boolean changeStatus) Set the whether this document has changes.
void	setSource(java.net.URL url) Set the URL of the persistent storage for this document.
void	setTitle(java.lang.String newTitle) Set the document title.
void	showDocument() Make this document's window visible.
boolean	warnUserOfUnsavedChangesWhenClosing() Determine whether the user should be warned when closing a document with unsaved changes.
protected void	willClose() Called when the document will be closed.
java.lang.String[]	writableDocumentTypes() Subclasses should implement this method to return the array of file suffixes identifying the files that can be written by the document.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

YES_OPTION

public static final int YES_OPTION

See Also:

Constant Field Values

NO_OPTION

public static final int NO_OPTION

See Also:

Constant Field Values

mainWindow

protected XalWindow mainWindow

hasChanges

protected boolean hasChanges

title

protected java.lang.String title

source

protected java.net.URL source

messageCenter

protected MessageCenter messageCenter

documentListenerProxy

protected XalDocumentListener documentListenerProxy

Constructor Detail

XalDocument

public XalDocument()

Constructor for new documents

Method Detail

writableDocumentTypes

public java.lang.String[] writableDocumentTypes()

Subclasses should implement this method to return the array of file suffixes identifying the files that can be written by the document. By default this method returns the same types as specified by the application adaptor.

Returns:

An array of file suffixes corresponding to writable files

registerEvents

protected void registerEvents()

Register this document as a source of DocumentListener events.

addXalDocumentListener

public void addXalDocumentListener(XalDocumentListener listener)

Add the listener for events from this document.

removeXalDocumentListener

public void removeXalDocumentListener(XalDocumentListener listener)

Remove the listener from event from this document.

makeMainWindow

protected abstract void makeMainWindow()

Subclasses must implement this method to make their custom main window.

customizeCommands

protected void customizeCommands(Commander commander)

Override this method to register custom document commands if any. You do so by registering actions with the commander. Those action instances should have a reference to this document so the action is executed on the document when the action is activated. The default implementation of this method does nothing.

Parameters:

commander - The commander that manages commands.

See Also:

Commander.registerAction(Action)

getCustomMenuDefinitionPath

protected java.lang.String getCustomMenuDefinitionPath()

Subclasses should override this method if this document should use a menu definition other than the default specified in application adaptor. The document menu inherits the application menu definition. This custom path allows the document to modify the application wide definitions for this document. By default this method returns null.

Returns:

The menu definition properties file path in classpath notation

See Also:

ApplicationAdaptor.getPathToResource(java.lang.String)

getTitle

public java.lang.String getTitle()

Get the document title.

Returns:

The title of the document.

setTitle

public void setTitle(java.lang.String newTitle)

Set the document title.

Parameters:

newTitle - The new title for this document.

getSource

public java.net.URL getSource()

Get the URL of the persistent storage for this document.

Returns:

The URL of this document's persistent storage.

setSource

public void setSource(java.net.URL url)

Set the URL of the persistent storage for this document.

Parameters:

url - The URL of the persistent storage to set for this document.

isEmpty

public boolean isEmpty()

Check if the document is empty. An empty document has no source file and has not been edited.

Returns:

true if this document is empty and false if not

generateDocumentTitle

protected void generateDocumentTitle()

Generate and set the title for this document. By default the title is set to the file path of the document or the default empty document file path if the document does not have a file store.

getDisplayFilePath

protected java.lang.String getDisplayFilePath()

By default the file path to display for this document is set to the file path of the document or the default empty document file path if the document does not yet have a file store.

Returns:

the file path of the document or the default empty document file path as appropriate

getEmptyDocumentPath

protected java.lang.String getEmptyDocumentPath()

Get the default file path to use for empty documents

Returns:

"Untitled." + the first writable document type or simply "Untitled" if there are none

hasChanges

public boolean hasChanges()

Indicates if there are changes that need saving.

Returns:

Status of whether this document has changes that need saving.

setHasChanges

public void setHasChanges(boolean changeStatus)

Set the whether this document has changes.

Parameters:

changeStatus - Status to set whether this document has changes that need saving.

saveDocumentAs

public abstract void saveDocumentAs(java.net.URL url)

Subclasses need to implement this method for saving the document to a URL.

Parameters:

url - The URL to which this document should be saved.

saveDocument

public void saveDocument()

Save this document to its persistent storage source.

closeDocument

protected boolean closeDocument()

This method is a request to close a document. It may be called when, for example, the user selects "Close" from the File menu, or when the user closes the window with the close button, or when the application quits. This request starts a series of events which closes the document. Xal document listeners are notified that the document will close. They may perform any cleanup as necessary before the document closes. Then the listeners are informed that the document has closed. The application removes the document from its list of open documents and informs its listeners that the document has been closed. If there are any unsaved changes, the user is given an opportunity to not close the document so they can save the changes.

warnUserOfUnsavedChangesWhenClosing

public boolean warnUserOfUnsavedChangesWhenClosing()

Determine whether the user should be warned when closing a document with unsaved changes. The default behavior is to warn the user if they have unsaved changes. Override this method if you don't want the user to be warned of unsaved changes.

Returns:

true if the user should be warned and false if not.

freeResources

protected final void freeResources()

Free document resources.

freeCustomResources

protected void freeCustomResources()

Dispose of custom document resources. Subclasses should override this method to provide custom disposal of resources. The default implementation does nothing.

willClose

protected void willClose()

Called when the document will be closed. The default implementation does nothing. Subclasses should override this method if they need to handle this event.

getMainWindow

public XalWindow getMainWindow()

Get the main window for this document.

Returns:

The main window for this document.

showDocument

public void showDocument()

Make this document's window visible.

hideDocument

public void hideDocument()

Hide this document.

displayConfirmDialog

public int displayConfirmDialog(java.lang.String title,
                                java.lang.String message)

Display a confirmation dialog with a title and message

Parameters:

title - The title of the dialog

message - The message to display

Returns:

YES_OPTION or NO_OPTION

displayWarning

public void displayWarning(java.lang.String title,
                           java.lang.String message)

Display a warning dialog box and provide an audible alert.

Parameters:

title - Title of the warning dialog box.

message - The warning message to appear in the warning dialog box.

displayWarning

public void displayWarning(java.lang.Exception exception)

Display a warning dialog box with information about the exception and provide an audible alert.

Parameters:

exception - The exception about which the warning dialog is displayed.

displayWarning

public void displayWarning(java.lang.String title,
                           java.lang.String prefix,
                           java.lang.Exception exception)

Display a warning dialog box with information about the exception and provide an audible alert. This method allows clarification about the consequences of the exception (e.g. "Save Failed:").

Parameters:

title - Title of the warning dialog box.

prefix - Text that should appear in the dialog box before the exception messasge.

exception - The exception about which the warning dialog is displayed.

displayError

public void displayError(java.lang.String title,
                         java.lang.String message)

Display an error dialog box and provide an audible alert.

Parameters:

title - Title of the warning dialog box.

message - The warning message to appear in the warning dialog box.

displayError

public void displayError(java.lang.Exception exception)

Display an error dialog box with information about the exception and provide an audible alert.

Parameters:

exception - The exception about which the warning dialog is displayed.

displayError

public void displayError(java.lang.String title,
                         java.lang.String prefix,
                         java.lang.Exception exception)

Display an error dialog box with information about the exception and provide an audible alert. This method allows clarification about the consequences of the exception (e.g. "Save Failed:").

Parameters:

title - Title of the warning dialog box.

prefix - Text that should appear in the dialog box before the exception messasge.

exception - The exception about which the warning dialog is displayed.

getNumberOfPages

public int getNumberOfPages()

Implement the Pageable interface. Subclasses may override this implementation to support custom document printing. Returns the number of pages to print. This default implementation simply returns one for printing a single page.

Specified by:

getNumberOfPages in interface java.awt.print.Pageable

Returns:

The number of pages to print

getPageFormat

public java.awt.print.PageFormat getPageFormat(int pageIndex)
                                        throws java.lang.IndexOutOfBoundsException

Implement the Pageable interface. Subclasses may override this implementation to support custom document printing. This default implementation gets the page format from the default print manager.

Specified by:

getPageFormat in interface java.awt.print.Pageable

Parameters:

pageIndex - The page number corresponding to the page format to return

Returns:

PageFormat for printing the specified page

Throws:

java.lang.IndexOutOfBoundsException - when the page index is out of range

See Also:

PrintManager.getPageFormat()

getPrintable

public java.awt.print.Printable getPrintable(int pageIndex)
                                      throws java.lang.IndexOutOfBoundsException

Implement the Pageable interface. Subclasses may override this implementation to support custom document printing. This default implementation simply returns a printable object that prints one page of the document's main window.

Specified by:

getPrintable in interface java.awt.print.Pageable

Parameters:

pageIndex - The page to print

Returns:

The printable object responsible for printing the main window

Throws:

java.lang.IndexOutOfBoundsException - when the page index is out of range