# HG changeset patch # Parent bdd42a5d0757ed359fc35b7f4afbdd4db57e15c8 diff --git a/editor.bracesmatching/apichanges.xml b/editor.bracesmatching/apichanges.xml --- a/editor.bracesmatching/apichanges.xml +++ b/editor.bracesmatching/apichanges.xml @@ -107,6 +107,22 @@ + + + Semantic context can be provided for a brace + + + + + + The brace tooltip may need to display additional text, if for example if-condition spans multiple lines, + or for an else-branch, where the important information (if-condition text) is located elsewhere. BraceMatcher + can implement the optional mixin BraceMatcher.ContextLocator and provide boundaries for this additional text. + + + + + Document locking changed diff --git a/editor.bracesmatching/nbproject/project.properties b/editor.bracesmatching/nbproject/project.properties --- a/editor.bracesmatching/nbproject/project.properties +++ b/editor.bracesmatching/nbproject/project.properties @@ -3,7 +3,7 @@ javadoc.arch=${basedir}/arch.xml javadoc.apichanges=${basedir}/apichanges.xml -spec.version.base=1.29.0 +spec.version.base=1.30.0 test.config.stableBTD.includes=**/*Test.class test.config.stableBTD.excludes=\ **/MasterMatcherTest.class diff --git a/editor.bracesmatching/src/org/netbeans/spi/editor/bracesmatching/BraceContext.java b/editor.bracesmatching/src/org/netbeans/spi/editor/bracesmatching/BraceContext.java new file mode 100644 --- /dev/null +++ b/editor.bracesmatching/src/org/netbeans/spi/editor/bracesmatching/BraceContext.java @@ -0,0 +1,141 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2013 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2013 Sun Microsystems, Inc. + */ +package org.netbeans.spi.editor.bracesmatching; + +import javax.swing.text.Position; + +/** + * Provides context information for a single brace. The brace may be preceded or followed + * by a semantically connected text, such as `if' statement or `while' statement in a do-while + * loop in Java. Such text may be displayed as a context for the brace highlight. The marked text + * should include the brace sign itself. + *

+ * It may be necessary to provide a completely unrelated context, such is in the example + * of if-else statement. The 'else' does not provide enough information itself as it is + * just a negation of earlier condition. Such related piece of text can be reported as 'related' + * BraceContext instance. Note that related instances may be chained - see the example below. + *

+ * The infrastructure uses the provided information to present the context to the user. If + * a 'related' positions are present the infrastructure will attempt to present the source + * on the 'context' and 'related' positions in the source text order (e.g. displays portion of the document); + * contents between 'context' and 'related' positions may be suppressed. + *

+ * An example of context and related areas for Java (PHP) if-elseif-else, with the origin t + * 

+ *  //  vvvvvvvvvvvvvvvvv -- related
+ *      if (condition1) {
+ *  //  vvvvvvvvvvvvvvvvvvvvvvvvvvv -- related
+ *      } else if (elsecondition) {
+ *      ...
+ *      } else {
+ *  //    ^^^^^^ -- context
+ *      ...
+ *      }
+ * //   ^ -- origin/caret location
+ *
+ * @author sdedic + */ +public final class BraceContext { + /** + * @return Starting position of the context text content + */ + public Position getOpenContextStart() { + return start; + } + + /** + * @return Ending position of the context text content + */ + public Position getCloseContextEnd() { + return end; + } + + /** + * @return the related range, or {@code null} for none. + */ + public BraceContext getRelated() { + return related; + } + + /** + * Creates a new BraceContext related to this one. + * + * @param start start of the contextual text + * @param end end of the text + * @return the new instance of BraceContext + */ + public BraceContext createRelated(Position start, Position end) { + return new BraceContext(start, end, this); + } + + /** + * Creates a new context area for the brace. + * @param start start of the text + * @param end end of the text + * @return a new instance of BraceContext + */ + public static BraceContext create(Position start, Position end) { + return new BraceContext(start, end, null); + } + + /** + * Start of the related text + */ + private final Position start; + + /** + * End of the related text + */ + private final Position end; + + /** + * The related area(s) + */ + private final BraceContext related; + + private BraceContext(Position openContextStart, Position closeContextEnd, + BraceContext related) { + this.start = openContextStart; + this.end = closeContextEnd; + this.related = related; + } +} diff --git a/editor.bracesmatching/src/org/netbeans/spi/editor/bracesmatching/BracesMatcher.java b/editor.bracesmatching/src/org/netbeans/spi/editor/bracesmatching/BracesMatcher.java --- a/editor.bracesmatching/src/org/netbeans/spi/editor/bracesmatching/BracesMatcher.java +++ b/editor.bracesmatching/src/org/netbeans/spi/editor/bracesmatching/BracesMatcher.java @@ -44,6 +44,7 @@ package org.netbeans.spi.editor.bracesmatching; import javax.swing.text.BadLocationException; +import javax.swing.text.Position; /** * The common interface for all matchers. Implementations of this interface @@ -168,4 +169,24 @@ * @throws javax.swing.text.BadLocationException If a document operation fails. */ public int [] findMatches() throws InterruptedException, BadLocationException; + + /** + * Mixin interface, which provides context ranges for brace matches. + * The interface is expected to be implemented on the {@link BracesMatcher} instances + * produced by {@link BracesMatcherFactory}. If implemented, the infrastructure may + * call the method to obtain additional context for display along with brace highlight. + * See the {@link BraceContext} for more information. + */ + public interface ContextLocator { + /** + * Obtains context for the given text position. At this moment, only start offset + * of the origin will be passed in, but the implementation should be prepared to + * handle (or ignore) each of the starting offsets reported by {@link #findOrigin()} or + * {@link #findMatches()}. + * + * @param originOrMatchPosition position of 'origin' or 'match' brace + * @return context information or {@code null} if the context cannot be provided. + */ + public BraceContext findContext(int originOrMatchPosition); + } }