KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > armedbear > j > Mode


1 /*
2  * Mode.java
3  *
4  * Copyright (C) 1998-2003 Peter Graves
5  * $Id: Mode.java,v 1.9 2003/06/30 17:00:41 piso Exp $
6  *
7  * This program is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License
9  * as published by the Free Software Foundation; either version 2
10  * of the License, or (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
20  */
21
22 package org.armedbear.j;
23
24 import java.awt.Color JavaDoc;
25 import java.awt.event.MouseEvent JavaDoc;
26 import javax.swing.JPopupMenu JavaDoc;
27
28 /**
29  * Mode is an interface for defining modes. A mode is a set of rules that
30  * define how the editor behaves. Different behaviors are desireable when
31  * editing different kinds of files. As an example, a user expects
32  * different behavior/functionality when editing a C++ file than what she
33  * expects when editing a Lisp file.
34  * <p>
35  * Users should not implement Mode directly, they should instead extend
36  * {@link AbstractMode AbstractMode}.
37  *
38  * @see AbstractMode
39  */
40 public interface Mode
41 {
42     /**
43      * Returns the unique identifier of this mode. All identifiers should
44      * be defined in <code>Constants</code>.
45      *
46      * @return the unique identifier for this mode
47      * @see Constants
48      */
49     public int getId();
50
51     /**
52      * Returns the display name of this mode. All display names should be
53      * defined in <code>Constants</code>.
54      *
55      * @return the display name of this mode
56      * @see Constants
57      */
58     public String JavaDoc getDisplayName();
59
60     public Buffer createBuffer(File file);
61
62     /**
63      * Returns a <code>Formatter</code> for the given <code>Buffer</code>.
64      *
65      * @param buffer the <code>Buffer</code> that is to be formatted
66      * according to this mode
67      * @return a <code>Formatter</code> for the given mode.
68      */
69     public Formatter getFormatter(Buffer buffer);
70
71     /**
72      * Returns a non-null <code>KeyMap</code> that may define custom
73      * <code>KeyMapping</code>s for this Mode. If there are no custom
74      * <code>KeyMapping</code>s for this Mode, then an empty
75      * <code>KeyMap</code> is returned.
76      *
77      * @return a non-null KeyMap
78      * @see KeyMapping
79      */
80     public KeyMap getKeyMap();
81
82     /**
83      * Returns the file that defines a custom <code>KeyMap</code> for
84      * this Mode, if any.
85      *
86      * @return the <code>KeyMap</code> file, or <code>null</code> if there is
87      * none.
88      * @see #getKeyMap
89      * @see KeyMap
90      * @see KeyMapping
91      */
92     public File getKeyMapFile();
93
94     public void useDefaultKeyMap();
95
96     public void deleteKeyMap();
97
98     /**
99      * Returns an identifier for the <code>MenuBar</code> that is to
100      * be used for this mode.
101      * Override this method to return a unique name if you override
102      * {@link #createMenuBar(Frame) createMenuBar} to have a
103      * custom menu.
104      *
105      * @return an identifier for the <code>MenuBar</code> that is returned
106      * by calling <code>createMenuBar</code>.
107      */
108     public String JavaDoc getMenuName();
109
110     /**
111      * Returns the MenuBar that is to be used for this mode.
112      * Override to return a custom <code>MenuBar</code> for this mode.
113      * If this method is overriden, then you must also override
114      * {@link #getMenuName() getMenuName} to return a unique identifier,
115      * otherwise the default is fine.
116      *
117      * @param frame the frame that the <code>MenuBar</code> will be
118      * attached to
119      * @return a <code>MenuBar</code> for the specified frame
120      */
121     public MenuBar createMenuBar(Frame frame);
122
123     /**
124      * Populates the given <code>Menu</code> with appropriate menu items.
125      * Unless there is a compelling reason not to, classes that override
126      * this method should call <code>super.createMenuBar(editor, menu)</code>
127      * when they are done putting in their own entries.
128      *
129      * @param editor the current <code>Editor</code>.
130      * @param menu the <code>Menu</code> that is to be populated with
131      * entries for this mode.
132      */
133     public void populateMenu(Editor editor, Menu menu);
134
135     public void populateModeMenu(Editor editor, Menu menu);
136
137     /**
138      * Returns a context menu populated with entries specific to the given
139      * mode and the current location in the specified <code>Editor</code>.
140      *
141      * @param editor the current <code>Editor</code>
142      * @return a menu filled with context sensitive goodies.
143      */
144     public JPopupMenu JavaDoc getContextMenu(Editor editor);
145
146     /**
147      * Returns a <code>ToolBar</code> for the specified <code>Frame</code>.
148      *
149      * @param frame the <code>Frame</code>
150      * @return the <code>ToolBar</code>
151      */
152     public ToolBar getToolBar(Frame frame);
153
154     /**
155      * Returns a navigation component for the specified <code>Editor</code>,
156      * or <code>null</code> if there is no navigation component for this mode.
157      * <p>
158      * The navigation component appears in the lower pane of the sidebar.
159      *
160      * @param editor the <code>Editor</code>
161      * @return the navigation component, or <code>null</code>
162      */
163     public NavigationComponent getSidebarComponent(Editor editor);
164
165     /**
166      * Most useful for programming language modes, this method returns
167      * either a <code>Tagger</code> for this mode, or <code>null</code>. If a
168      * <code>Tagger</code> is returned, then
169      * {@link #isTaggable() isTaggable()} must return <code>true</code>.
170      * Otherwise it should return <code>false</code>.
171      *
172      * @param buffer the current buffer
173      * @return a <code>Tagger</code> specific for this mode or
174      * <code>null</code> if a <code>Tagger</code> is not
175      * applicable.
176      */
177     public Tagger getTagger(SystemBuffer buffer);
178
179     /**
180      * Returns whether or not this mode has a {@link Tagger Tagger}
181      * associated with it. This returns <code>false</code> if
182      * {@link #getTagger(SystemBuffer) getTagger()} returns <code>null</code>,
183      * and <code>true</code> otherwise.
184      *
185      * @return Whether or not this mode is taggable. Which is the same as
186      * whether or not <code>getTagger</code> returns <code>null</code>.
187      */
188     public boolean isTaggable();
189
190     /**
191      * Returns <code>true</code> if the mode's underlying programming language
192      * supports qualified names. (For example, Java, C++ and Perl do; C does
193      * not.)
194      *
195      * @return <code>true</code> if the mode supports qualified names.
196      * @since 0.16.1
197      */
198     public boolean hasQualifiedNames();
199
200     /**
201      * Returns <code>true</code> if the string in question is a qualified name
202      * in the mode's underlying programming language.
203      *
204      * @return <code>true</code> if the string is a qualified name.
205      * @since 0.16.1
206      */
207     public boolean isQualifiedName(String JavaDoc s);
208
209     /**
210      * Returns whether or not this mode will potentially perform context
211      * sensitive indentation on a given <code>Line</code> in a given
212      * <code>Buffer</code>. This returns <code>true</code> if
213      * {@link #getCorrectIndentation(Line, Buffer) getCorrectIndentation()}
214      * might return something other than zero, <code>false</code> otherwise.
215      *
216      * @return <code>true</code> if this mode supports context-sensitive
217      * indentation.
218      *
219      */
220     public boolean canIndent();
221
222     /**
223      * Returns whether or not this mode will potentially perform context
224      * sensitive indentation for a paste operation. This returns
225      * <code>true</code> if
226      * {@link #getCorrectIndentation(Line, Buffer) getCorrectIndentation()}
227      * might return something other than zero, <code>false</code> otherwise.
228      *
229      * @return <code>true<code> if this mode supports context-sensitive
230      * indentation of pasted text.
231      */
232     public boolean canIndentPaste();
233
234     public boolean acceptsLinePaste(Editor editor);
235
236     /**
237      * Returns the amount of indentation (in columns) needed to indent the
238      * specified <code>Line</code> in the context of the given
239      * <code>Buffer</code>.
240      * <p>
241      * If this mode does not support automatic context-sensitive indentation,
242      * that is if {@link #canIndent() canIndent()} returns <code>false</code>,
243      * then this method returns zero.
244      *
245      * @param line the line to be indented
246      * @param buffer the buffer which contains the line
247      * @return the amount of indentation required, in columns.
248      */
249     public int getCorrectIndentation(Line line, Buffer buffer);
250
251     /**
252      * Returns a <code>SyntaxIterator</code> specific for this mode that
253      * is situated at the given <code>Position</code>.
254      *
255      * @param pos where to situate the <code>SyntaxIterator</code>.
256      * @return a <code>SyntaxIterator</code> for this mode.
257      */
258     public SyntaxIterator getSyntaxIterator(Position pos);
259
260     /**
261      * Returns a string that signifies the start of a comment for the
262      * given mode, or <code>null</code> if the concept of comments is
263      * not applicable to this mode.
264      *
265      * @return the token to start a comment, or <code>null<code> if not
266      * applicable.
267      */
268     public String JavaDoc getCommentStart();
269
270     /**
271      * Returns a string that signifies the end of a comment for the
272      * given mode, or <code>null</code> if the concept of comments is
273      * not applicable to this mode or the comment does not require an
274      * end token.
275      *
276      * @return the token to end a comment, or <code>null<code> if not
277      * applicable.
278      */
279     public String JavaDoc getCommentEnd();
280
281     /**
282      * Looks in all mode and non-mode specific properties/preferences and
283      * returns the value attached to the given key, or the default value
284      * given in <code>property</code> if the key is not found. The property
285      * and preferences lists are searched in an manner which gives precedence
286      * in the following order: mode specific preferences, mode specific
287      * properties, global preferences.
288      *
289      * @param property the key to look for with the default value to return
290      * if the key is not found.
291      * @return the value of the given property, or the default in the
292      * given <code>Property</code> if the property's key is
293      * not found.
294      */
295     public boolean getBooleanProperty(Property property);
296
297     /**
298      * Looks in all mode and non-mode specific properties/preferences and
299      * returns the value attached to the given key, or the default value
300      * given in <code>property</code> if the key is not found. The property
301      * and preferences lists are searched in an manner which gives precedence
302      * in the following order: mode specific preferences, mode specific
303      * properties, global preferences.
304      *
305      * @param property the key to look for with the default value to return
306      * if the key is not found.
307      * @return the value of the given property, or the default in the
308      * given <code>Property</code> if the property's key is
309      * not found.
310      */
311     public int getIntegerProperty(Property property);
312
313     /**
314      * Looks in all mode and non-mode specific properties/preferences and
315      * returns the value attached to the given key, or the default value
316      * given in <code>property</code> if the key is not found. The property
317      * and preferences lists are searched in an manner which gives precedence
318      * in the following order: mode specific preferences, mode specific
319      * properties, global preferences.
320      *
321      * @param property the key to look for with the default value to return
322      * if the key is not found.
323      * @return the value of the given property, or the default in the
324      * given <code>Property</code> if the property's key is
325      * not found.
326      */
327     public String JavaDoc getStringProperty(Property property);
328
329     /**
330      * Looks in all mode and non-mode specific properties/preferences and
331      * returns the value attached to the given key, or the default value
332      * given in <code>property</code> if the key is not found. The property
333      * and preferences lists are searched in an manner which gives precedence
334      * in the following order: mode specific preferences, mode specific
335      * properties, global preferences.
336      *
337      * @param property the key to look for with the default value to return
338      * if the key is not found.
339      * @return the value of the given property, or the default in the
340      * given <code>Property</code> if the property's key is
341      * not found.
342      */
343     public Color JavaDoc getColorProperty(Property property);
344
345     public void setProperty(Property property, String JavaDoc value);
346
347     public void setProperty(Property property, boolean value);
348
349     public void setProperty(Property property, int value);
350
351     /**
352      * Returns whether or not this mode is willing to accept the given
353      * file name.
354      *
355      * @param filename the name of the file that is to be checked for
356      * validity for this mode.
357      * @return <code>true</code> if the given filename can be handled
358      * by this mode.
359      */
360     public boolean accepts(String JavaDoc filename);
361
362     /**
363      * Checks the given character against a list of characters that are
364      * legal identifier starts. Some languages have different requirements
365      * for the beginning of an identifier than the rest of that identifier.
366      * Such a case is Java which allows digits in an identifier name, but
367      * does not allow them to be the first character.
368      *
369      * @param char the character to be checked for validity.
370      * @return <code>true</code> if <code>c</code> is one of the
371      * legal identifier start characters for this mode.
372      */
373     public boolean isIdentifierStart(char c);
374
375     /**
376      * Checks the given character against a list of characters that are
377      * legal identifier parts (not the first character). Some languages
378      * have different requirements for the beginning of an identifier than
379      * the rest of that identifier. Such a case is Java which allows digits
380      * in an identifier part, but does not allow a digit to be the first
381      * character.
382      *
383      * @param char the character to be checked for validity.
384      * @return <code>true</code> if <code>c</code> is one of the
385      * legal identifier parts for this mode.
386      */
387     public boolean isIdentifierPart(char c);
388
389     /**
390      * Returns <code>true</code> if the specified position is inside a quoted
391      * string.
392      *
393      * @param buffer the <code>Buffer</code> containing the specified
394      * position
395      * @param pos the position
396      * @return <code>true</code> if <code>pos</code> is inside a
397      * quoted string.
398      */
399     public boolean isInQuote(Buffer buffer, Position pos);
400
401     /**
402      * Returns <code>true</code> if the specified position is inside a comment.
403      *
404      * @param buffer the <code>Buffer</code> containing the specified
405      * position
406      * @param pos the position
407      * @return <code>true</code> if <code>pos</code> is inside a
408      * comment.
409      */
410     public boolean isInComment(Buffer buffer, Position pos);
411
412     /**
413      * Returns whether or not the given <code>Line</code> is a comment.
414      *
415      * @param line the <code>Line</code> to check to see if it is a
416      * comment.
417      * @return <code>true</code> if <code>line</code> qualifies as
418      * a comment for this mode.
419      */
420     public boolean isCommentLine(Line line);
421
422     /**
423      * Examines <code>c</code> and returns the equivalent character but
424      * possibly with a different case (upper or lower) as the rules of
425      * this mode dictate. This is primarily used in programming language
426      * modes where the language is case-insensitive and the user wants
427      * certain identifiers to have a certain casing style (all upper, all
428      * lower).
429      *
430      * @param editor the <code>Editor</code> for context.
431      * @param c the character in question.
432      * @return the character represented by <code>c</code> as the
433      * proper case given the context of <code>editor</code>
434      * and the case rules of this mode.
435      */
436     public char fixCase(Editor editor, char c);
437
438     /**
439      * Returns a string that describes something about the current caret
440      * position that is suitable to be displayed in the <code>StatusBar</code>.
441      *
442      * @param editor the <code>Editor</code> for context.
443      * @param verbose whether or not to return more information.
444      * @return information relevant to the current caret position.
445      */
446     public String JavaDoc getContextString(Editor editor, boolean verbose);
447
448     /**
449      * Returns a string that describes something about the current mouse
450      * position that is suitable to be displayed in the <code>StatusBar</code>,
451      * or <code>null</code> if there is none.
452      *
453      * @param editor the <code>Editor</code> for context.
454      * @return information relevant to the current mouse position.
455      */
456     public String JavaDoc getMouseMovedContextString(Editor editor, Position pos);
457
458     /**
459      * Returns a string that describes something about the current mouse
460      * position that is suitable to be displayed as a tool tip, or
461      * <code>null</code> if there is none.
462      *
463      * @param editor the <code>Editor</code> for context.
464      * @return information relevant to the current mouse position.
465      */
466     public String JavaDoc getToolTipText(Editor editor, MouseEvent JavaDoc e);
467
468     /**
469      * If this mode needs to do any special processing on a file in order to
470      * load it into the buffer, e.g. the file is an archive, that
471      * processing is to be done here. This method is called from the
472      * protected {@link Buffer#loadFile(File) loadFile} method in
473      * <code>Buffer</code> when loading a file. It is also called from
474      * the {@link Buffer#reload() reload} method in <code>Buffer</code>.
475      *
476      * @param buffer the <code>Buffer</code> that the file is to be loaded
477      * into.
478      * @param file the input source.
479      */
480     public void loadFile(Buffer buffer, File file);
481
482     /**
483      * Allows this mode to confirm the closing of a <code>Buffer</code>, and
484      * can cancel it by returning <code>false</code>. <code>confirmClose</code>
485      * allows for this mode to do things such as make sure the user wants to
486      * close a <code>Buffer</code> even though it has been modified.
487      *
488      * @param editor the <code>Editor</code> for context.
489      * @param buffer the <code>Buffer</code> that is to be closed.
490      * @return <code>true</code> to allow the <code>Buffer</code> to
491      * close.
492      */
493     public boolean confirmClose(Editor editor, Buffer buffer);
494
495     /**
496      * Checks the given string against a list of keywords for this mode, and
497      * returns <code>true</code> if the string is on that list.
498      *
499      * @param s the keyword to test.
500      * @return <code>true</code> if <code>s</code> is a valid keyword
501      * for this mode.
502      */
503     public boolean isKeyword(String JavaDoc s);
504
505     /**
506      * Returns the expression at the current location of the caret in the
507      * specified editor.
508      *
509      * @param editor the editor in question
510      * @param exact a hint to the implementation: if true, return the
511      * expression at the exact location of the caret; if
512      * false, look for a suitable expression on the same line
513      * @return the expression, or <code>null</code> if no expression
514      * is found.
515      * @since 0.16.1
516      */
517     public Expression getExpressionAtDot(Editor editor, boolean exact);
518
519     /**
520      * Returns the identifier at the specified position.
521      *
522      * @param pos the position
523      * @return the identifier at the specified position, or
524      * <code>null</code> if no identifier is found.
525      * @since 0.16.1
526      */
527     public String JavaDoc getIdentifier(Position pos);
528
529     /**
530      * Returns the identifier at the specified line and offset.
531      *
532      * @param line the line
533      * @param offset the offset
534      * @return the identifier at the specified line and offset, or
535      * <code>null</code> if no identifier is found.
536      * @since 0.16.1
537      */
538     public String JavaDoc getIdentifier(Line line, int offset);
539
540     /**
541      * Returns the position of the start of the identifier at the specified
542      * line and offset.
543      *
544      * @param line the line
545      * @param offset the offset
546      * @return the position of the start of the identifier at the
547      * specified line and offset or <code>null</code> if no
548      * identifier is found.
549      * @since 0.16.1
550      */
551     public Position findIdentifierStart(Line line, int offset);
552 }
553
Popular Tags