KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > bluej > editor > 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 JavaDoc;
11 import java.awt.print.PrinterJob JavaDoc;
12 import java.io.IOException JavaDoc;
13
14 import javax.swing.text.BadLocationException JavaDoc;
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 JavaDoc filename, boolean compiled, String JavaDoc docFilename, Rectangle JavaDoc 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 JavaDoc 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 JavaDoc;
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 JavaDoc message, int lineNumber, int column,
131                         boolean beep, boolean setStepMark, String JavaDoc 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 JavaDoc 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 JavaDoc title, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc newText )
269         throws BadLocationException JavaDoc;
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 JavaDoc getProperty(String JavaDoc 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 JavaDoc propertyKey, Object JavaDoc 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
Popular Tags