001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041: package org.netbeans.modules.gsf.api;
042:
043: import java.util.List;
044: import javax.swing.text.BadLocationException;
045: import javax.swing.text.Document;
046: import javax.swing.text.JTextComponent;
047: import org.netbeans.modules.gsf.api.OffsetRange;
048: import org.netbeans.modules.gsf.api.annotations.CheckForNull;
049: import org.netbeans.modules.gsf.api.annotations.NonNull;
050:
051: /**
052: * Interface that a plugin can implement to assist with bracket completion during
053: * editing.
054: *
055: * @todo Rename Pair Completion? Or perhaps PairMatcher?
056: *
057: * @author Tor Norbye
058: */
059: public interface BracketCompletion {
060: /**
061: * (Based on BracketCompletion class in NetBeans' java editor support)
062: *
063: * A hook method called after a character was inserted into the
064: * document. The function checks for special characters for
065: * completion ()[]'"{} and other conditions and optionally performs
066: * changes to the doc and or caret (complets braces, moves caret,
067: * etc.)
068: *
069: * Return true if the character was already inserted (and the IDE
070: * should not further insert anything)
071: *
072: * XXX Fix javadoc.
073: */
074: boolean beforeCharInserted(Document doc, int caretOffset,
075: JTextComponent target, char ch) throws BadLocationException;
076:
077: /** @todo Rip out the boolean return value? What does it mean? */
078: boolean afterCharInserted(Document doc, int caretOffset,
079: JTextComponent target, char ch) throws BadLocationException;
080:
081: /**
082: * (Based on BracketCompletion class in NetBeans' java editor support)
083: *
084: * Hook called after a character *ch* was backspace-deleted from
085: * *doc*. The function possibly removes bracket or quote pair if
086: * appropriate.
087: * @todo Document why both caretOffset and caret is passed in!
088: * Return the new offset, or -1
089: */
090:
091: /** @todo Split into before and after? */
092: public boolean charBackspaced(Document doc, int caretOffset,
093: JTextComponent target, char ch) throws BadLocationException;
094:
095: /**
096: * A line break is being called. Return -1 to do nothing.
097: * If you want to modify the document first, you can do that, and then
098: * return the new offset to assign the caret to AFTER the newline has been
099: * inserted.
100: *
101: * @todo rip out return value
102: * @todo Document why both caretOffset and caret is passed in!
103: */
104: int beforeBreak(Document doc, int caretOffset, JTextComponent caret)
105: throws BadLocationException;
106:
107: /**
108: * Compute a range matching the caret position. If no eligible range
109: * is found, return {@link OffsetRange.NONE}.
110: */
111: @NonNull
112: OffsetRange findMatching(Document doc, int caretOffset);
113:
114: /**
115: * Compute set of selection ranges for the given parse tree (around the given offset),
116: * in leaf-to-root order.
117: */
118: @NonNull
119: List<OffsetRange> findLogicalRanges(CompilationInfo info,
120: int caretOffset);
121:
122: /**
123: * Compute the previous word position, if any. Can be used to implement
124: * camel case motion etc.
125: *
126: * @param doc The document to move in
127: * @param caretOffset The caret position corresponding to the current word
128: * @param reverse If true, move forwards, otherwise move backwards (e.g. "previous" word)
129: * @return The next word boundary offset in the given direction, or -1 if this
130: * implementation doesn't want to compute word boundaries (the default will be used)
131: */
132: @CheckForNull
133: int getNextWordOffset(Document doc, int caretOffset, boolean reverse);
134: }
|