Package xal.extension.application

Class XalInternalDocument

java.lang.Object
xal.extension.application.XalInternalDocument
All Implemented Interfaces:
Pageable
public abstract class XalInternalDocument extends 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.
Author:
t6p

  • Field Details

    • mainWindow

      protected XalInternalWindow mainWindow
      this document's associated window

    • windowEventHandler

      protected xal.extension.application.XalInternalDocument.WindowEventHandler windowEventHandler
      this document's window event handler

    • WILDCARD_FILE_EXTENSION

      public static final String WILDCARD_FILE_EXTENSION
      wildcard file extension
      See Also:

    • YES_OPTION

      public static final int YES_OPTION
      See Also:

    • NO_OPTION

      public static final int NO_OPTION
      See Also:

    • SAVE_FAILED_TITLE

      protected static final String SAVE_FAILED_TITLE
      See Also:

    • messageCenter

      protected MessageCenter messageCenter
      Local message center

    • source

      protected URL source
      The persistent storage URL for the document

  • Constructor Details

    • XalInternalDocument

      protected XalInternalDocument()
      Constructor for new documents

  • Method Details

    • registerEvents

      public void registerEvents()
      Register this document as a source of DocumentListener events.

    • addXalInternalDocumentListener

      public void addXalInternalDocumentListener(XalInternalDocumentListener listener)
      Add the listener for events from this document.

    • removeXalInternalDocumentListener

      public void removeXalInternalDocumentListener(XalInternalDocumentListener listener)
      Remove the listener from event from this document.

    • makeCommander

      protected Commander makeCommander()
      Subclasses may override this method to provide a custom Commander.

    • setTitle

      public void setTitle(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 XalInternalWindow 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.

    • customizeDesktopCommands

      protected void customizeDesktopCommands(Commander commander)
      Subclasses should override this method to register custom document commands (if any) for the desktop menu. 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:

    • getCustomInternalMenuDefinitionResource

      protected String getCustomInternalMenuDefinitionResource()
      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

    • writableDocumentTypes

      public 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:

    • getCustomMenuDefinitionResource

      public 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 String getTitle()
      Get the document title.
      Returns:
      The title of the document.

    • getSource

      public URL getSource()
      Get the URL of the persistent storage for this document.
      Returns:
      The URL of this document's persistent storage.

    • getDefaultFolder

      public File getDefaultFolder()
      Get the default document folder.
      Returns:
      the default folder for documents or null if none has been set.

    • getDefaultFolderURL

      public 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(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 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 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 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 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 String getNewDocumentName(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 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(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, 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, 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(String title, 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(String title, 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(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(String title, String prefix, 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(String title, 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(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(String title, String prefix, 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 Pageable
      Returns:
      The number of pages to print

    • getPageFormat

      public PageFormat getPageFormat(int pageIndex) throws 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 Pageable
      Parameters:
      pageIndex - The page number corresponding to the page format to return
      Returns:
      PageFormat for printing the specified page
      Throws:
      IndexOutOfBoundsException - when the page index is out of range
      See Also:
      • PrintManager.getPageFormat()

    • getPrintable

      public Printable getPrintable(int pageIndex) throws 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 Pageable
      Parameters:
      pageIndex - The page to print
      Returns:
      The printable object responsible for printing the main window
      Throws:
      IndexOutOfBoundsException - when the page index is out of range