Editor


1   // Copyright (c) 2000, 2005 BlueJ Group, Deakin University
2   //
3   // This software is made available under the terms of the "MIT License"
4   // A copy of this license is included with this source distribution
5   // in "license.txt" and is also available at:
6   // http://www.opensource.org/licenses/mit-license.html 
7   // Any queries should be directed to Michael Kolling mik@bluej.org
8   package bluej.editor;
9   
10  import java.awt.Rectangle  ;
11  import java.awt.print.PrinterJob  ;
12  import java.io.IOException  ;
13  
14  import javax.swing.text.BadLocationException  ;
15  
16  
17  /**
18   * Interface between an editor and the rest of BlueJ
19   * 
20   * @version $Id: Editor.java,v 1.32 2005/10/05 00:56:31 davmac Exp $
21   * @author Michael Cahill
22   * @author Michael Kolling
23   */
24  public interface Editor
25  {
26      /**
27       * Read a file into the editor buffer and show the editor. If the editor
28       * already contains text, it is cleared first.
29       * 
30       * @param filename    the file to be read
31       * @param compiled    true if this is a compiled class
32       * 
33       * @return false is there was a problem, true otherwise
34       */
35      boolean showFile(String   filename, boolean compiled, String   docFilename, Rectangle   bounds);
36  
37      /**
38       * Reload and display the same file that was displayed before.
39       * This should generated a modificationEvent followed by a saveEvent.
40       */
41      void reloadFile();
42  
43      /**
44       * Clear the current buffer. The editor is not redisplayed after a call to
45       * this function. It is typically used in a sequence "clear; [insertText];
46       * show".
47       */
48      void clear();
49  
50      /**
51       * Insert a string into the buffer. The editor is not immediately
52       * redisplayed. This function is typically used in a sequence "clear;
53       * [insertText]; show".
54       * 
55       * @param text        the text to be inserted
56       * @param caretBack    move the caret to the beginning of the inserted text
57       */
58      void insertText(String   text, boolean caretBack);
59  
60      /**
61       * Set the selection of the editor to be a len characters on the line
62       * lineNumber, starting with column columnNumber
63       * 
64       * @param lineNumber the line to select characters on
65       * @param column the column to start selection at (1st column is 1 - not 0)
66       * @param len the number of characters to select
67       */
68      void setSelection(int lineNumber, int column, int len);
69  
70      /**
71       * Set the selection of the editor to be a len characters on the line
72       * lineNumber, starting with column columnNumber
73       * 
74       * @param lineNumber the line to select characters on
75       * @param column the column to start selection at (1st column is 1 - not 0)
76       * @param len the number of characters to select
77       */
78      void setSelection(int firstlineNumber, int firstColumn,
79                        int secondLineNumber, int SecondColumn);
80  
81  
82      /**
83       * Show the editor window. This includes whatever is necessary of the
84       * following: make visible, de-iconify, bring to front of window stack.
85       * 
86       * @param vis DOCUMENT ME!
87       */
88      void setVisible(boolean vis);
89  
90      /**
91       * True is the editor is on screen.
92       * 
93       * @return true if editor is on screen
94       */
95      boolean isShowing();
96  
97      /**
98       * Save the buffer to disk under the current file name. This is an error if
99       * the editor has not been given a file name (ie. if readFile was not
100      * executed).
101      * 
102      * If save() is called on an unmodified file, it returns immediately without
103      * re-writing the file to disk.
104      */
105     void save() throws IOException  ;
106 
107     /**
108      * Close the editor window.
109      */
110     void close();
111 
112     /**
113      * Refresh the editor display (needed if font size has changed)
114      */
115     void refresh();
116 
117     /**
118      * Display a message (used for compile/runtime errors). An editor must
119      * support at least two lines of message text, so the message can contain
120      * a newline character.
121      * 
122      * @param message    the message to be displayed
123      * @param lineNumber    the line to move the cursor to (the line is also
124      *        highlighted)
125      * @param column        the column to move the cursor to
126      * @param beep        if true, do a system beep
127      * @param setStepMark    if true, set step mark (for single stepping)
128      * @param help        name of help group (may be null)
129      */
130     void displayMessage(String   message, int lineNumber, int column, 
131                         boolean beep, boolean setStepMark, String   help);
132 
133     /**
134      *  Display a message into the info area.
135      *  The message will be cleared when the caret is moved.
136      *  
137      *  @param msg the message to display
138      */
139     public void writeMessage(String   msg);
140 
141 
142     /**
143      * Remove the step mark (the mark that shows the current line when
144      * single-stepping through code). If it is not currently displayed, do
145      * nothing.
146      */
147     void removeStepMark();
148 
149     /**
150      * Change class name.
151      * 
152      * @param title        new window title
153      * @param filename    new file name
154      */
155     void changeName(String   title, String   filename);
156 
157     /**
158      * Set the "compiled" status
159      * 
160      * @param compiled    true if the class has been compiled
161      */
162     void setCompiled(boolean compiled);
163 
164     /**
165      * Remove all breakpoints in this editor.
166      */
167     void removeBreakpoints();
168 
169     /**
170      * Determine whether this editor has been modified from the version on disk
171      * 
172      * @return a boolean indicating whether the file is modified
173      */
174     boolean isModified();
175 
176     /**
177      * Prints the contents of the editor
178      */
179     void print(PrinterJob   printerJob);
180 
181     /**
182      * Set the 'read-only' property of this editor.
183      * @param readOnlyStatus  If true, editor is non-editable.
184      */
185     void setReadOnly(boolean readOnly);
186 
187     /**
188      * Test if this editor is 'read-only'.
189      * @return the readOnlyStatus. If true, editor is non-editable.
190      */
191     boolean isReadOnly();
192 
193     
194     /**
195      * Set the view of this editor to display either the source or the interface
196      * of the class.
197      * @param interfaceStatus If true, display class interface, otherwise source.
198      */
199     void showInterface(boolean interfaceStatus);
200 
201     /**
202      *  Tell whether the editor is currently displaying the interface or the
203      *  source of the class.
204      *  @return  True, if interface is currently shown, false otherwise.
205      */
206     boolean isShowingInterface();
207 
208     /**
209      * Gets the bounds for this editor window.
210      * This method is used to store the bounds between sessions.
211      * 
212      * @return The bounds
213      */
214     Rectangle   getBounds();
215 
216 
217    /**
218      * Returns the current caret location within the edited text.
219      *
220      * @return    the LineColumn object.
221      */
222     public LineColumn getCaretLocation();
223     
224     /**
225      * Sets the current Caret location within the edited text.
226      *
227      * @param  location                   The location in the text to set the Caret to.
228      * @throws  IllegalArgumentException  if the specified TextLocation represents a position which does not exist in the text.
229      */
230     public void setCaretLocation(LineColumn location);
231 
232 
233     /**
234      * Returns the location at which current selection begins.
235      *
236      * @return    the current beginning of the selection or null if no text is selected.
237      */
238     public LineColumn getSelectionBegin();
239     
240     /**
241      * Returns the location where the current selection ends.
242      *
243      * @return    the current end of the selection or null if no text is selected.
244      */
245     public LineColumn getSelectionEnd();
246 
247     /**
248      * Returns the text which lies between the two LineColumn.
249      *
250      * @param  begin                      The beginning of the text to get
251      * @param  end                        The end of the text to get
252      * @return                            The text value
253      * @throws  IllegalArgumentException  if either of the specified TextLocations represent a position which does not exist in the text.
254      */
255     public String   getText( LineColumn begin, LineColumn end );    
256 
257     /**
258      * Request to the editor to replace the text between beginning and end with the given newText
259      * If begin and end points to the same location, the text is inserted.
260      *
261      * @param  begin                      where to start to replace
262      * @param  end                        where to end to replace
263      * @param  newText                    The new text value
264      * @throws  IllegalArgumentException  if either of the specified LineColumn
265      * represent a position which does not exist in the text.
266      * @throws  BadLocationException  if internally the text points outside a location in the text.
267      */
268     public void setText( LineColumn begin, LineColumn end, String   newText )
269         throws BadLocationException  ;
270     
271     /**
272      * Request to the editor to mark the text between begin and end as selected.
273      *
274      * @param  begin                      where to start the selection
275      * @param  end                        where to end the selection
276      * @throws  IllegalArgumentException  if either of the specified TextLocations
277      * represent a position which does not exist in the text.
278      */
279     public void setSelection(LineColumn begin, LineColumn end);
280     
281     /**
282      * Returns the LineColumn object from the given offset in the text.
283      *
284      * @return    the LineColumn object or null if the offset points outside the text.
285      */
286     public LineColumn getLineColumnFromOffset(int offset);
287     
288     /**
289      * Translates a LineColumn into an offset into the text held by the editor.
290      *
291      * @param  location  position to be translated
292      * @return           the offset into the content of this editor
293      * @throws  IllegalArgumentException  if the specified LineColumn
294      * represent a position which does not exist in the text.
295      */
296     public int getOffsetFromLineColumn( LineColumn location );
297     
298     /**
299      * Returns a property of the current editor.
300      *
301      * @param  propertyKey  The propertyKey of the property to retrieve.
302      * @return              the property value or null if it is not found
303      */
304     public Object   getProperty(String   propertyKey);
305 
306     /**
307      * Set a property for the current editor. Any existing property with
308      * this key will be overwritten.
309      *
310      * @param  propertyKey  The property key of the new property
311      * @param  value        The new property value
312      */
313     public void setProperty(String   propertyKey, Object   value);
314     
315     /**
316      * Returns the length of the line indicated in the edited text.
317      *
318      * @param  line  the line in the text for which the length should be calculated, starting from 0
319      * @return       the length of the line, -1 if line is invalid
320      */
321     public int getLineLength(int line);
322     
323     /**
324      * Return the number of lines in the documant.
325      */
326     public int numberOfLines();
327     
328     /**
329      * Returns the length of the data.  This is the number of
330      * characters of content that represents the users data.
331      *
332      * It is possible to obtain the line and column of the last character of text by using
333      * the getLineColumnFromOffset() method.
334      *
335      * @return the length >= 0
336      */
337     public int getTextLength ();    
338     
339     
340 } // end interface Editor
341
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags