# 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 @@
     <!-- ACTUAL CHANGES BEGIN HERE: -->
 
     <changes>
+        
+        <change id="brace.context">
+            <summary>Semantic context can be provided for a brace</summary>
+            <version major="1" minor="30"/>
+            <date day="6" month="5" year="2013"/>
+            <author login="sdedic"/>
+            <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible"/>
+            <description>
+                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.
+            </description>
+            <class package="org.netbeans.spi.editor.bracesmatching" name="BracesMatcher"/>
+            <class package="org.netbeans.spi.editor.bracesmatching" name="BraceContext"/>
+            <issue number="217730"/>
+        </change>
 
         <change id="document.locking.changed">
             <summary>Document locking changed</summary>
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/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);
+    }
 }