XalDocument

java.lang.Object
- xal.extension.application.XalDocument

All Implemented Interfaces:

java.awt.print.Pageable

Direct Known Subclasses:

AcceleratorDocument
```
public abstract class XalDocument
extends java.lang.Object
```
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

Fields
Modifier and Type	Field and Description
`XalWindow`	`mainWindow`
`protected MessageCenter`	`MESSAGE_CENTER` Local message center
`static int`	`NO_OPTION`
`protected java.net.URL`	`source` The persistent storage URL for the document
`static java.lang.String`	`WILDCARD_FILE_EXTENSION` wildcard file extension
`static int`	`YES_OPTION`

Fields inherited from interface java.awt.print.Pageable
UNKNOWN_NUMBER_OF_PAGES

Constructor Summary

Constructors
Constructor and Description

XalDocument()
Constructor for new documents

Constructors
Constructor and Description
`XalDocument()` Constructor for new documents

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addXalDocumentListener(XalDocumentListener listener)` Add the listener for events from this document.
`boolean`	`closeDocument()` This method is a request to close a document.
`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.
`void`	`freeCustomResources()` Dispose of custom document resources.
`void`	`freeResources()` Free document resources.
`void`	`generateDocumentTitle()` Generate and set the title for this document.
`java.lang.String`	`getCustomMenuDefinitionResource()` Subclasses should override this method if this document should use a menu definition other than the default specified in application adaptor.
`java.io.File`	`getDefaultFolder()` Get the default document folder.
`java.net.URL`	`getDefaultFolderURL()` Get the default document folder as a URL.
`static WindowReference`	`getDefaultWindowReference(java.lang.String tag, java.lang.Object... parameters)` Get the window reference from the resource if any
`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.
`XalDocumentView`	`getDocumentView()` Implement the method for XalAbstractDocument.
`java.lang.String`	`getEmptyDocumentPath()` Get the default file path to use for empty documents
`java.lang.String`	`getFileNameForSaving()` Get the base file name to use when saving a new file.
`XalWindow`	`getMainWindow()` Get the main window for this document.
`java.lang.String`	`getNewDocumentName(java.lang.String baseName)` Get the default file path to use for empty documents
`java.lang.String`	`getNewFileName()` Get the file name (including extension but without path) for a new file.
`java.lang.String`	`getNewFileNamePrefix()` Get the prefix for a new file (precedes timestamp) defaulting to the application name.
`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.
`void`	`handleDataWrittenTo(DataListener dataRoot, java.net.URL url)` Subclasses may override this empty method to implement custom code called by writeDataTo() after data has been successfully written to the specified URL.
`boolean`	`hasChanges()` Indicates if there are changes that need saving.
`void`	`hideDocument()` Hide this document.
`boolean`	`isEmpty()` Check if the document is empty.
`abstract void`	`makeMainWindow()` Subclasses must implement this method to make their custom main window.
`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.
`void`	`willClose()` Called when the document will be closed.
`void`	`windowOpened()` Hook indicating that the window was opened.
`void`	`windowWillOpen()` Hook indicating that the window will be opened.
`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.
`void`	`writeDataTo(DataListener dataRoot, java.net.URL url)` Convenience method typically called in saveDocumentAs() to save a document rooted in a data listener source.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - WILDCARD_FILE_EXTENSION
```
public static final java.lang.String WILDCARD_FILE_EXTENSION
```
    wildcard file extension
    
    See Also:
    
    Constant Field Values
  - 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
```
public XalWindow mainWindow
```
  - MESSAGE_CENTER
```
protected MessageCenter MESSAGE_CENTER
```
    Local message center
  - source
```
protected java.net.URL source
```
    The persistent storage URL for the document
- Constructor Detail
  - XalDocument
```
public XalDocument()
```
    Constructor for new documents
- Method Detail
  - registerEvents
```
public 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.
  - getDefaultWindowReference
```
public static WindowReference getDefaultWindowReference(java.lang.String tag,
                                                        java.lang.Object... parameters)
```
    Get the window reference from the resource if any
  - setTitle
```
public void setTitle(java.lang.String newTitle)
```
    Set the document title.
    
    Parameters:
    
    newTitle - The new title for this document.
  - 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.
  - closeDocument
```
public 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.
  - freeResources
```
public final void freeResources()
```
    Free document resources.
  - getMainWindow
```
public XalWindow getMainWindow()
```
    Get the main window for this document.
    
    Returns:
    
    The main window for this document.
  - getDocumentView
```
public XalDocumentView getDocumentView()
```
    Implement the method for XalAbstractDocument.
    
    Returns:
    
    The main window for this document.
  - 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
  - makeMainWindow
```
public abstract void makeMainWindow()
```
    Subclasses must implement this method to make their custom main window.
  - customizeCommands
```
public 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)
  - getCustomMenuDefinitionResource
```
public java.lang.String getCustomMenuDefinitionResource()
```
    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 name
  - getTitle
```
public java.lang.String getTitle()
```
    Get the document title.
    
    Returns:
    
    The title of the 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.
  - getDefaultFolder
```
public java.io.File getDefaultFolder()
```
    Get the default document folder.
    
    Returns:
    
    the default folder for documents or null if none has been set.
  - getDefaultFolderURL
```
public java.net.URL getDefaultFolderURL()
```
    Get the default document folder as a URL.
    
    Returns:
    
    the default folder for documents as a URL or null if none has been set.
  - 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
```
public 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
```
public 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
  - getFileNameForSaving
```
public java.lang.String getFileNameForSaving()
```
    Get the base file name to use when saving a new file.
    
    Returns:
    
    the new file name for new documents and the source's file path for existing documents
  - getNewFileNamePrefix
```
public java.lang.String getNewFileNamePrefix()
```
    Get the prefix for a new file (precedes timestamp) defaulting to the application name. Subclasses can override this method to provide an alternative prefix.
    
    Returns:
    
    prefix for a new file
  - getNewFileName
```
public java.lang.String getNewFileName()
```
    Get the file name (including extension but without path) for a new file. Subclasses can override this method to provide an alternative name.
    
    Returns:
    
    file name for a new file
  - getNewDocumentName
```
public java.lang.String getNewDocumentName(java.lang.String baseName)
```
    Get the default file path to use for empty documents
    
    Parameters:
    
    baseName - the base name to use for an empty document
    
    Returns:
    
    "{baseName}." + the first writable document type or simply "{baseName}" if there are none
  - getEmptyDocumentPath
```
public 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.
  - 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.
  - writeDataTo
```
public void writeDataTo(DataListener dataRoot,
                        java.net.URL url)
```
    Convenience method typically called in saveDocumentAs() to save a document rooted in a data listener source.
    
    Parameters:
    
    dataRoot - DataListener root of the document to save
    
    url - The URL to which the document should be saved.
  - handleDataWrittenTo
```
public void handleDataWrittenTo(DataListener dataRoot,
                                java.net.URL url)
```
    Subclasses may override this empty method to implement custom code called by writeDataTo() after data has been successfully written to the specified URL.
    
    Parameters:
    
    dataRoot - DataListener root of the document to save
    
    url - The URL to which the document should be saved.
  - 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.
  - freeCustomResources
```
public void freeCustomResources()
```
    Dispose of custom document resources. Subclasses should override this method to provide custom disposal of resources. The default implementation does nothing.
  - willClose
```
public 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.
  - windowWillOpen
```
public void windowWillOpen()
```
    Hook indicating that the window will be opened. Called after the window is created but before it is displayed by the document.
  - windowOpened
```
public void windowOpened()
```
    Hook indicating that the window was opened.
  - 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

Class XalDocument

Field Summary

Fields inherited from interface java.awt.print.Pageable

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

WILDCARD_FILE_EXTENSION

YES_OPTION

NO_OPTION

mainWindow

MESSAGE_CENTER

source

Constructor Detail

XalDocument

Method Detail

registerEvents

addXalDocumentListener

removeXalDocumentListener

getDefaultWindowReference

setTitle

setHasChanges

closeDocument

freeResources

getMainWindow

getDocumentView

writableDocumentTypes

makeMainWindow

customizeCommands

getCustomMenuDefinitionResource

getTitle

getSource

getDefaultFolder

getDefaultFolderURL

setSource

isEmpty

generateDocumentTitle

getDisplayFilePath

getFileNameForSaving

getNewFileNamePrefix

getNewFileName

getNewDocumentName

getEmptyDocumentPath

hasChanges

saveDocumentAs

saveDocument

writeDataTo

handleDataWrittenTo

warnUserOfUnsavedChangesWhenClosing

freeCustomResources

willClose

windowWillOpen

windowOpened

showDocument

hideDocument

displayConfirmDialog

displayWarning

displayWarning

displayWarning

displayError

displayError

displayError

getNumberOfPages

getPageFormat

getPrintable