Package xal.extension.application.smf

Class AcceleratorDocument

java.lang.Object
xal.extension.application.XalDocument
xal.extension.application.smf.AcceleratorDocument
All Implemented Interfaces:
Pageable
public abstract class AcceleratorDocument extends XalDocument
AcceleratorDocument is a subclass of XalDocument for accelerator based applications.
Author:
tap

  • Field Details

  • Constructor Details

    • AcceleratorDocument

      protected AcceleratorDocument()
      Creates a new instance of AcceleratorDocument

  • Method Details

    • nextChannelFactory

      public ChannelFactory nextChannelFactory()
      Get the channel factory which is used to instantiate the NEXT accelerator within this document. Note that this channel factory does not necessarily match the channel factory of the current accelerator in this document. The base AcceleratorDocument class returns ChannelFactory.defaultFactory(). Subclasses may override this method to provide a custom channel factory if desired.
      Returns:
      the channel factory to initialize a new accelerator

    • getAcceleratorWindow

      public AcceleratorWindow getAcceleratorWindow()
      Get the accelerator window managed by this document
      Returns:
      this document's accelerator window

    • generateDocumentTitle

      public void generateDocumentTitle()
      Generate and set the title for this document.

    • getNewFileNamePrefix

      public String getNewFileNamePrefix()
      Get the prefix for a new file (precedes timestamp) defaulting to the selected sequence ID if any or the super class's default if no sequence is selected.
      Returns:
      prefix for a new file

    • applySelectedAcceleratorWithDefaultPath

      public Accelerator applySelectedAcceleratorWithDefaultPath(String filePath)
      Attempt to load the accelerator with the specified path and if none exists, then request a substitute accelerator from the user.
      Parameters:
      filePath - file path to the accelerator for which to first attempt to load

    • setAccelerator

      public void setAccelerator(Accelerator newAccelerator, String newPath)
      Set the accelerator managed by the document. Every document manages one accelerator (or possibly null).
      Parameters:
      newAccelerator - The accelerator managed by this document.
      newPath - The path to the accelerator managed by this document.

    • getAccelerator

      public Accelerator getAccelerator()
      Get the accelerator managed by this document.
      Returns:
      The accelerator managed by this document.

    • setAcceleratorFilePath

      public void setAcceleratorFilePath(String newPath)
      Set the accelerator file path. Every document manages one accelerator (or possibly null).
      Parameters:
      newPath - The path to the accelerator managed by this document.

    • getAcceleratorFilePath

      public String getAcceleratorFilePath()
      Get the path to the xml file of the accelerator managed by this document.
      Returns:
      path to the xml file of the accelerator managed by this document.

    • loadDefaultAccelerator

      protected boolean loadDefaultAccelerator()
      Attempt to load the user's default accelerator. If no default accelerator is specified, then prompt the user to specify the default optics path. The document's accelerator file is set to the user's default accelerator.
      Returns:
      true if the default accelerator was successfully loaded

    • setSelectedSequence

      public void setSelectedSequence(AcceleratorSeq selection)
      Set the selected accelerator sequence managed by this document.
      Parameters:
      selection - The accelerator sequence to be managed by this document.

    • setSelectedSequenceList

      public void setSelectedSequenceList(List<AcceleratorSeq> seqList)
      Set a list of selected sequences
      Parameters:
      seqList - The list of selected sequences

    • getSelectedSequence

      public AcceleratorSeq getSelectedSequence()
      Get the selected accelerator sequence managed by this document.
      Returns:
      The sequence managed by this document.

    • getSelectedSequenceList

      public List<AcceleratorSeq> getSelectedSequenceList()
      Get the selected sequence list
      Returns:
      the selected sequence list

    • isSelectedSequenceRing

      public boolean isSelectedSequenceRing()
      Is the sequence selected a ring?

    • acceleratorChanged

      public void acceleratorChanged()
      Hook for handling the accelerator change event. Subclasses should override this method to provide custom handling. The default handler does nothing.

    • selectedSequenceChanged

      public void selectedSequenceChanged()
      Hook for handling the selected sequence change event. Subclasses should override this method to provide custom handling. The default handler does nothing.

    • acceleratorFilePathChanged

      public void acceleratorFilePathChanged()
      Hook for handling the accelerator file path change event. Subclasses should override this method to provide custom handling. The default handler does nothing.

    • catchXmlDataAdaptorException

      protected void catchXmlDataAdaptorException(XmlDataAdaptor.WriteException exception)
      Standard way of catching XML Write exceptions

    • 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

    • 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

    • 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