001: // Copyright (c) 2000, 2005 BlueJ Group, Deakin University
002: //
003: // This software is made available under the terms of the "MIT License"
004: // A copy of this license is included with this source distribution
005: // in "license.txt" and is also available at:
006: // http://www.opensource.org/licenses/mit-license.html
007: // Any queries should be directed to Michael Kolling mik@bluej.org
008: package bluej.editor;
009:
010: import java.awt.Rectangle;
011: import java.awt.print.PrinterJob;
012: import java.io.IOException;
013:
014: import javax.swing.text.BadLocationException;
015:
016: /**
017: * Interface between an editor and the rest of BlueJ
018: *
019: * @version $Id: Editor.java 5390 2007-11-21 05:06:41Z davmac $
020: * @author Michael Cahill
021: * @author Michael Kolling
022: */
023: public interface Editor {
024: /**
025: * Read a file into the editor buffer and show the editor. If the editor
026: * already contains text, it is cleared first.
027: *
028: * @param filename the file to be read
029: * @param compiled true if this is a compiled class
030: *
031: * @return false is there was a problem, true otherwise
032: */
033: boolean showFile(String filename, boolean compiled,
034: String docFilename, Rectangle bounds);
035:
036: /**
037: * Reload and display the same file that was displayed before.
038: * This should generated a modificationEvent followed by a saveEvent.
039: */
040: void reloadFile();
041:
042: /**
043: * Clear the current buffer. The editor is not redisplayed after a call to
044: * this function. It is typically used in a sequence "clear; [insertText];
045: * show".
046: */
047: void clear();
048:
049: /**
050: * Insert a string into the buffer. The editor is not immediately
051: * redisplayed. This function is typically used in a sequence "clear;
052: * [insertText]; show".
053: *
054: * @param text the text to be inserted
055: * @param caretBack move the caret to the beginning of the inserted text
056: */
057: void insertText(String text, boolean caretBack);
058:
059: /**
060: * Set the selection of the editor to be a len characters on the line
061: * lineNumber, starting with column columnNumber
062: *
063: * @param lineNumber the line to select characters on
064: * @param column the column to start selection at (1st column is 1 - not 0)
065: * @param len the number of characters to select
066: */
067: void setSelection(int lineNumber, int column, int len);
068:
069: /**
070: * Set the selection of the editor to be a len characters on the line
071: * lineNumber, starting with column columnNumber
072: *
073: * @param lineNumber the line to select characters on
074: * @param column the column to start selection at (1st column is 1 - not 0)
075: * @param len the number of characters to select
076: */
077: void setSelection(int firstlineNumber, int firstColumn,
078: int secondLineNumber, int SecondColumn);
079:
080: /**
081: * Show the editor window. This includes whatever is necessary of the
082: * following: make visible, de-iconify, bring to front of window stack.
083: *
084: * @param vis DOCUMENT ME!
085: */
086: void setVisible(boolean vis);
087:
088: /**
089: * True is the editor is on screen.
090: *
091: * @return true if editor is on screen
092: */
093: boolean isShowing();
094:
095: /**
096: * Save the buffer to disk under the current file name. This is an error if
097: * the editor has not been given a file name (ie. if readFile was not
098: * executed).
099: *
100: * If save() is called on an unmodified file, it returns immediately without
101: * re-writing the file to disk.
102: */
103: void save() throws IOException;
104:
105: /**
106: * Close the editor window.
107: */
108: void close();
109:
110: /**
111: * Refresh the editor display (needed if font size has changed)
112: */
113: void refresh();
114:
115: /**
116: * Display a message (used for compile/runtime errors). An editor must
117: * support at least two lines of message text, so the message can contain
118: * a newline character.
119: *
120: * @param message the message to be displayed
121: * @param lineNumber the line to move the cursor to (the line is also
122: * highlighted)
123: * @param column the column to move the cursor to
124: * @param beep if true, do a system beep
125: * @param setStepMark if true, set step mark (for single stepping)
126: * @param help name of help group (may be null)
127: */
128: void displayMessage(String message, int lineNumber, int column,
129: boolean beep, boolean setStepMark, String help);
130:
131: /**
132: * Display a message into the info area.
133: * The message will be cleared when the caret is moved.
134: *
135: * @param msg the message to display
136: */
137: public void writeMessage(String msg);
138:
139: /**
140: * Remove the step mark (the mark that shows the current line when
141: * single-stepping through code). If it is not currently displayed, do
142: * nothing.
143: */
144: void removeStepMark();
145:
146: /**
147: * Change class name.
148: *
149: * @param title new window title
150: * @param filename new file name
151: * @param docFileName new documentation file name
152: */
153: void changeName(String title, String filename, String docFileName);
154:
155: /**
156: * Set the "compiled" status
157: *
158: * @param compiled true if the class has been compiled
159: */
160: void setCompiled(boolean compiled);
161:
162: /**
163: * All breakpoints have been cleared for this class, update the
164: * editor display to reflect this.
165: */
166: void removeBreakpoints();
167:
168: /**
169: * Breakpoints have been reset due to compilation or
170: * similar. Re-initialize the breakpoints by re-setting them via the
171: * EditorWatcher interface.
172: */
173: void reInitBreakpoints();
174:
175: /**
176: * Determine whether this editor has been modified from the version on disk
177: *
178: * @return a boolean indicating whether the file is modified
179: */
180: boolean isModified();
181:
182: /**
183: * Prints the contents of the editor
184: */
185: void print(PrinterJob printerJob);
186:
187: /**
188: * Set the 'read-only' property of this editor.
189: * @param readOnlyStatus If true, editor is non-editable.
190: */
191: void setReadOnly(boolean readOnly);
192:
193: /**
194: * Test if this editor is 'read-only'.
195: * @return the readOnlyStatus. If true, editor is non-editable.
196: */
197: boolean isReadOnly();
198:
199: /**
200: * Set the view of this editor to display either the source or the interface
201: * of the class.
202: * @param interfaceStatus If true, display class interface, otherwise source.
203: */
204: void showInterface(boolean interfaceStatus);
205:
206: /**
207: * Tell whether the editor is currently displaying the interface or the
208: * source of the class.
209: * @return True, if interface is currently shown, false otherwise.
210: */
211: boolean isShowingInterface();
212:
213: /**
214: * Gets the bounds for this editor window.
215: * This method is used to store the bounds between sessions.
216: *
217: * @return The bounds
218: */
219: Rectangle getBounds();
220:
221: /**
222: * Returns the current caret location within the edited text.
223: *
224: * @return the LineColumn object.
225: */
226: public LineColumn getCaretLocation();
227:
228: /**
229: * Sets the current Caret location within the edited text.
230: *
231: * @param location The location in the text to set the Caret to.
232: * @throws IllegalArgumentException if the specified TextLocation represents a position which does not exist in the text.
233: */
234: public void setCaretLocation(LineColumn location);
235:
236: /**
237: * Returns the location at which current selection begins.
238: *
239: * @return the current beginning of the selection or null if no text is selected.
240: */
241: public LineColumn getSelectionBegin();
242:
243: /**
244: * Returns the location where the current selection ends.
245: *
246: * @return the current end of the selection or null if no text is selected.
247: */
248: public LineColumn getSelectionEnd();
249:
250: /**
251: * Returns the text which lies between the two LineColumn.
252: *
253: * @param begin The beginning of the text to get
254: * @param end The end of the text to get
255: * @return The text value
256: * @throws IllegalArgumentException if either of the specified TextLocations represent a position which does not exist in the text.
257: */
258: public String getText(LineColumn begin, LineColumn end);
259:
260: /**
261: * Request to the editor to replace the text between beginning and end with the given newText
262: * If begin and end points to the same location, the text is inserted.
263: *
264: * @param begin where to start to replace
265: * @param end where to end to replace
266: * @param newText The new text value
267: * @throws IllegalArgumentException if either of the specified LineColumn
268: * represent a position which does not exist in the text.
269: * @throws BadLocationException if internally the text points outside a location in the text.
270: */
271: public void setText(LineColumn begin, LineColumn end, String newText)
272: throws BadLocationException;
273:
274: /**
275: * Request to the editor to mark the text between begin and end as selected.
276: *
277: * @param begin where to start the selection
278: * @param end where to end the selection
279: * @throws IllegalArgumentException if either of the specified TextLocations
280: * represent a position which does not exist in the text.
281: */
282: public void setSelection(LineColumn begin, LineColumn end);
283:
284: /**
285: * Returns the LineColumn object from the given offset in the text.
286: *
287: * @return the LineColumn object or null if the offset points outside the text.
288: */
289: public LineColumn getLineColumnFromOffset(int offset);
290:
291: /**
292: * Translates a LineColumn into an offset into the text held by the editor.
293: *
294: * @param location position to be translated
295: * @return the offset into the content of this editor
296: * @throws IllegalArgumentException if the specified LineColumn
297: * represent a position which does not exist in the text.
298: */
299: public int getOffsetFromLineColumn(LineColumn location);
300:
301: /**
302: * Returns a property of the current editor.
303: *
304: * @param propertyKey The propertyKey of the property to retrieve.
305: * @return the property value or null if it is not found
306: */
307: public Object getProperty(String propertyKey);
308:
309: /**
310: * Set a property for the current editor. Any existing property with
311: * this key will be overwritten.
312: *
313: * @param propertyKey The property key of the new property
314: * @param value The new property value
315: */
316: public void setProperty(String propertyKey, Object value);
317:
318: /**
319: * Returns the length of the line indicated in the edited text.
320: *
321: * @param line the line in the text for which the length should be calculated, starting from 0
322: * @return the length of the line, -1 if line is invalid
323: */
324: public int getLineLength(int line);
325:
326: /**
327: * Return the number of lines in the documant.
328: */
329: public int numberOfLines();
330:
331: /**
332: * Returns the length of the data. This is the number of
333: * characters of content that represents the users data.
334: *
335: * It is possible to obtain the line and column of the last character of text by using
336: * the getLineColumnFromOffset() method.
337: *
338: * @return the length >= 0
339: */
340: public int getTextLength();
341:
342: } // end interface Editor
|