Package 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$
    Author:
    John Reekie
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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.