home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / SourceFile.java < prev    next >
Text File  |  1998-10-25  |  8KB  |  225 lines
  1. /*
  2.  * Copyright 1998 Symantec Corporation, All Rights Reserved.
  3.  */
  4.  
  5. package com.symantec.itools.vcafe.openapi;
  6.  
  7. import java.io.File;
  8.  
  9. /**
  10.  * The API used to represent and access a Visual Cafe source file.
  11.  *
  12.  * @see     VisualProject
  13.  * @see     ProjectFile
  14.  * @see        Range
  15.  *
  16.  * @author Symantec Internet Tools Division
  17.  * @version 1.0
  18.  * @since VCafe 3.0
  19.  */
  20. public abstract class SourceFile
  21. {
  22.     /**
  23.      * Gets the <code>ProjectFile</code> associated with this <code>SourceFile</code>.  If this file
  24.      * is not in a project, returns <code>null</code>.
  25.      * @return The <code>ProjectFile</code>, or <code>null</code> if this file is not in a project.
  26.      * @see ProjectFile
  27.      */
  28.     public abstract ProjectFile getProjectFile();
  29.  
  30.     /**
  31.      * Gets the <code>File</code> associated with this <code>SourceFile</code>.
  32.      * This method never returns <code>null</code>, but the actual file may not exist on disk 
  33.      * (i.e. <code>File.exists() == false</code>).
  34.      * @return the <code>File</code> associated with this <code>SourceFile</code>.
  35.      */
  36.     public abstract File getFile();
  37.  
  38.     /**
  39.      * Gets the base name of the <code>File</code> associated with this <code>SourceFile</code>.
  40.      * The base name is everything in the pathname after the last occurrence of the
  41.      * separator character (i.e. no directory information).
  42.      * @return this file's base filename.
  43.      */
  44.     public abstract String getName();
  45.  
  46.     /**
  47.      * Gets the pathname of the <code>File</code> associated with this <code>SourceFile</code>.
  48.      * @return the complete filename of this <code>SourceFile</code>.
  49.      */
  50.     public abstract String getFullName();
  51.  
  52.     /**
  53.      * Gets the current insertion point, in zero-based bytes.
  54.      * @return the current insertion point, in zero-based bytes, or 0 if the <code>SourceFile</code> is not
  55.      *  currently open.
  56.      */
  57.     public abstract int getInsertionPoint();
  58.  
  59.     /**
  60.      * Gets the <code>Range</code> of the currently selected text.
  61.      * @return the current text selection range, or <code>null</code> if the <code>SourceFile</code> is not
  62.      *  currently open.
  63.      */
  64.     public abstract Range getSelectionRange();
  65.  
  66.     /**
  67.      * Sets the range of the currently selected text.
  68.      * @param the new text selection range.
  69.      */
  70.     public abstract void setSelectionRange(Range newRange);
  71.  
  72.     /**
  73.      * Gets this <code>SourceFile</code>'s entire contents.
  74.      * @return a <code>StringBuffer</code> containing the entire <code>SourceFile</code> contents.
  75.      */
  76.     public abstract StringBuffer getText();
  77.  
  78.     /**
  79.      * Gets this <code>SourceFile</code>'s entire contents as a <code>String</code>.
  80.      * @return a <code>String</code> containing the entire <code>SourceFile</code> contents.
  81.      */
  82.     public abstract String getTextString();
  83.  
  84.     /**
  85.      * Replaces the <code>SourceFile</code>'s entire contents.
  86.      * @param newText the new contents of this <code>SourceFile</code>.
  87.      */
  88.     public abstract void setText(StringBuffer newText);
  89.  
  90.     /**
  91.      * Replaces the <code>SourceFile</code>'s entire contents with the contents of a <code>String</code>.
  92.      * @param newText the new contents of this <code>SourceFile</code>.
  93.      */
  94.     public abstract void setText(String newText);
  95.  
  96.     /**
  97.      * Gets the text within the specified <code>Range</code>.
  98.      * The current selection range of this <code>SourceFile</code> is not changed by this method.
  99.      * @param theRange the <code>Range</code> from which to get the text.
  100.      * @return a <code>StringBuffer</code> containing the in-range text.
  101.      */
  102.     public abstract StringBuffer getRangeText(Range theRange);
  103.  
  104.     /**
  105.      * Gets the text within the specified <code>Range</code> as a <code>String</code>.
  106.      * The current selection range of this <code>SourceFile</code> is not changed by this method.
  107.      * @param theRange the <code>Range</code> from which to get the text.
  108.      * @return a <code>String</code> containing the in-range text.
  109.      */
  110.     public abstract String getRangeTextString(Range theRange);
  111.  
  112.     /**
  113.      * Replaces the text in the given <code>Range</code> with the new text. The resulting new <code>Range</code> is then
  114.      * returned in theRange.
  115.      * @param newText the new replacement text.
  116.      * @param theRange on input, the range of text to be replaced.  On output, the
  117.      * newly resulting range.
  118.      */
  119.     public abstract void setRangeText(StringBuffer newText, Range theRange);
  120.  
  121.     /**
  122.      * Replaces the text in the given <code>Range</code> with the new text <code>String</code>.
  123.      * The resulting new <code>Range</code> is then returned in theRange.
  124.      * @param newText the new replacement text.
  125.      * @param theRange on input, the range of text to be replaced.  On output, the
  126.      * newly resulting range.
  127.      */
  128.     public abstract void setRangeText(String newText, Range theRange);
  129.  
  130.     /**
  131.      * Determines if this <code>SourceFile</code> is open in an editor window.
  132.      * @return <code>true</code> if the file is open, <code>false</code> otherwise.
  133.      */
  134.     public abstract boolean isOpen();
  135.  
  136.     /**
  137.      * Activates this <code>SourceFile</code>'s editor window.
  138.      * If this <code>SourceFile</code> isn't open yet, it is opened.
  139.      */
  140.     public abstract void edit();
  141.  
  142.     /**
  143.      * Saves the contents of this <code>SourceFile</code> to disk.
  144.      */
  145.     public abstract void save();
  146.  
  147.     /**
  148.      * Closes this <code>SourceFile</code>'s editor window, and optionally save its contents.
  149.      * @param saveChanges <code>true</code> to save this file's contents, <code>false</code> to discard any changes made to
  150.      * this <code>SourceFile</code>.
  151.      */
  152.     public abstract void close(boolean saveChanges);
  153.  
  154.     /**
  155.      * Refreshes this <code>SourceFile</code>'s editor window with the contents on disk.
  156.      */
  157.     public abstract void revertToSaved();
  158.  
  159.     /**
  160.      * Determines whether this <code>SourceFile</code> is locked (on disk, or locked in source control).
  161.      * @return <code>true</code> if locked either on disk or in source control, <code>false</code> if it is not locked.
  162.      */
  163.     public abstract boolean isLocked();
  164.  
  165.     /**
  166.      * Determines whether this <code>SourceFile</code> has been modified.
  167.      * @return <code>true</code> if it has been modified, <code>false</code> otherwise.
  168.      */
  169.     public abstract boolean isModified();
  170.  
  171.     /**
  172.      * Set the modified flag of this <code>SourceFile</code>.
  173.      * 
  174.      * Note: Use this method ONLY for marking the <code>SourceFile</code> as modified when
  175.      * the changes haven't been set with <code>setRangeText()</code> or <code>setText()</code>.
  176.      * Note: Use of this method does <i>not</i> result in listeners being notified of the change.
  177.      *
  178.      * This can be useful when making a change that hasn't been committed, so
  179.      * that if the user closes the <code>SourceFile</code>'s editor window, the user is
  180.      * prompted to save the changes.  You can then flush or commit your changes.
  181.      * You should listen for other changes to the <code>SourceFile</code>, so you don't inadvertantly
  182.      * set the <code>SourceFile</code> as unmodified, when it has been modified elsewhere.
  183.      *
  184.      * @param modified the new modified state of this <code>SourceFile</code>.
  185.      * @return the previous modified state of the <code>SourceFile</code>.
  186.      * @see SourceFileListener
  187.      */
  188.     public abstract boolean setModified(boolean modified);
  189.  
  190.     /**
  191.      * Add a listener to this <code>SourceFile</code>.
  192.      * All changes to this <code>SourceFile</code> are broadcast to the listeners registered with it.
  193.      * @param listener the object that receives notifications of changes to the <code>SourceFile</code>.
  194.      *
  195.      * @see SourceFileListener
  196.      * @see    removeSourceFileListener
  197.      * @see VisualCafe#addSourceFileListener
  198.      */
  199.     public abstract void addSourceFileListener(SourceFileListener listener);
  200.  
  201.     /**
  202.      * Remove a listener from this <code>SourceFile</code>.
  203.      * The listener stops receiving notifications of changes to this <code>SourceFile</code>.
  204.      * @param listener the object that was receiving notifications.
  205.      *
  206.      * @see SourceFileListener
  207.      * @see    addSourceFileListener
  208.      * @see VisualCafe#removeSourceFileListener
  209.      */
  210.     public abstract void removeSourceFileListener(SourceFileListener listener);
  211.  
  212.     /**
  213.      * Gets a <code>String</code> that represents this object.
  214.      * @return the <code>String</code>.
  215.      */
  216.     public String toString() {
  217.         return "SourceFile[" + getFile() + "]";
  218.     }
  219.     
  220.     /**
  221.      * Determine if two <code>SourceFile</code> objects represent the same file.
  222.      */
  223.     public abstract boolean equals(SourceFile sourceFile);
  224. }
  225.