Index: arch/arch-editor.xml =================================================================== RCS file: /cvs/editor/arch/arch-editor.xml,v --- arch/arch-editor.xml 13 Dec 2004 16:18:10 -0000 1.18 +++ arch/arch-editor.xml 14 Jan 2005 22:41:34 -0000 @@ -678,7 +678,12 @@ --> - No. + org.netbeans.modules.editor.hyperlink.LayerHyperlinkProviderManager + is registered using META-INF/services. +
+ It is an extension of org.netbeans.lib.editor.hyperlink.HyperlinkProviderManager + allowing to instantiate the org.netbeans.lib.editor.hyperlink.spi.HyperlinkProvider + instances from the xml layer of the System FS for particular mime-types. @@ -983,6 +988,17 @@

Please see layer.xml for further details.

+ +

+ The org.netbeans.lib.editor.hyperlink.spi.HyperlinkProvider + instances can be registered by editors for the particular mime-types + into Editors/|mime-type|/HyperlinkProviders. +
+ There can be multiple providers registered and their order + will be respected during querying by the hyperlinking infrastructure + (first provider which recognizes the given offset as a hyperlinking point + will be used). +

@@ -1079,8 +1095,24 @@ The editor functionality are mainly implementations of the Swing Text package APIs plus extension features such as Syntax Coloring, Code Completion, Word Matching, Abbreviations or Macros. -There are no official APIs yet but the Code Folding API -and other extensions APIs are being formed. + +

Hyperlink SPI

+ + Hyperlink SPI in org.netbeans.lib.editor.hyperlink.spi + allows the editors for a particular mime-type to respond to the situation + when a user hovers over the text with a Ctrl key pressed. + + +
+The Hyperlink SPI resolves whether the text under the mouse is hyperlink-able +and defines the span of the hyperlink and the action to be performed +when the user clicks on the hyperlink. +
+The SPI consists of a single HyperlinkProvider +class that contains a javadoc with instructions +about how to register the implementation in the xml layer for the given +mime-type (mentioned in the layer section here as well). + Index: libsrc/org/netbeans/lib/editor/hyperlink/spi/HyperlinkProvider.java =================================================================== RCS file: libsrc/org/netbeans/lib/editor/hyperlink/spi/HyperlinkProvider.java --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ libsrc/org/netbeans/lib/editor/hyperlink/spi/HyperlinkProvider.java 14 Jan 2005 22:41:34 -0000 @@ -0,0 +1,94 @@ +/* + * Sun Public License Notice + * + * The contents of this file are subject to the Sun Public License + * Version 1.0 (the "License"). You may not use this file except in + * compliance with the License. A copy of the License is available at + * http://www.sun.com/ + * + * The Original Code is NetBeans. The Initial Developer of the Original + * Code is Sun Microsystems, Inc. Portions Copyright 1997-2004 Sun + * Microsystems, Inc. All Rights Reserved. + */ + +package org.netbeans.lib.editor.hyperlink.spi; + +import javax.swing.text.Document; + +/** + * This interface should be implemented by anyone who whats to provide hyperlinking + * functionality in the source code. + *
+ * There should be one provider instance per mime-type. + * Its methods are called for all the opened editors of the given mime-type + * where the hyperlinking functionality gets requested. + * + *

+ * The providers need to be registered. + * For NetBeans IDE, the default approach is to use System FileSystem. + *
+ * The HyperlinkProvider(s) should be registered as ".instance" objects under + * Editors/<mime-type>/HyperlinkProviders directory. + *

+ * + *

+ * Please see {@link org.netbeans.lib.editor.hyperlink.HyperlinkProviderManager} + * for more details. + *

+ * + *

+ * Note: there is no assurance on the order of calling of the methods in this class. + * The callers may call the methods in any order and even do not call some of these methods + * at all. + *

+ * + * @author Jan Lahoda + * @since 1.0 + */ +public interface HyperlinkProvider { + + /** + * Should determine whether there should be a hyperlink on the given offset + * in the given document. May be called any number of times for given parameters. + *
+ * This method is called from event dispatch thread. + * It should run very fast as it is called very often. + * + * @param doc document on which to operate. + * @param offset >=0 offset to test (it generally should be offset < doc.getLength(), but + * the implementations should not depend on it) + * @return true if the provided offset should be in a hyperlink + * false otherwise + */ + boolean isHyperlinkPoint(Document doc, int offset); + + /** + * Should determine the span of hyperlink on given offset. Generally, if + * isHyperlinkPoint returns true for a given parameters, this class should + * return a valid span, but it is not strictly required. + *
+ * This method is called from event dispatch thread. + * This method should run very fast as it is called very often. + * + * @param doc document on which to operate. + * @param offset >=0 offset to test (it generally should be offset < doc.getLength(), but + * the implementations should not depend on it) + * @return a two member array which contains starting and ending offset of a hyperlink + * that should be on a given offset + */ + int[] getHyperlinkSpan(Document doc, int offset); + + /** + * The implementor should perform an action + * corresponding to clicking on the hyperlink on the given offset. The + * nature of the action is given by the nature of given hyperlink, but + * generally should open some resource or move cursor + * to certain place in the current document. + * + * @param doc document on which to operate. + * @param offset >=0 offset to test (it generally should be offset < doc.getLength(), but + * the implementations should not depend on it) + */ + void performClickAction(Document doc, int offset); + +}