diff options
6 files changed, 92 insertions, 80 deletions
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/link/ILinkedModeListener.java b/org.eclipse.text/src/org/eclipse/jface/text/link/ILinkedModeListener.java index d4b5e3429d8..1dca0ae0297 100644 --- a/org.eclipse.text/src/org/eclipse/jface/text/link/ILinkedModeListener.java +++ b/org.eclipse.text/src/org/eclipse/jface/text/link/ILinkedModeListener.java @@ -10,43 +10,64 @@ *******************************************************************************/ package org.eclipse.jface.text.link; - /** - * Protocol used by <code>LinkedModeModel</code>s to communicate state changes, such - * as leaving the environment, suspending it due to a child environment coming up, and resuming - * after a child environment has left. + * Protocol used by {@link LinkedModeModel}s to communicate state changes, such + * as leaving linked mode, suspending it due to a child mode coming up, and + * resuming after a child mode has left. + * <p> + * This interface may implemented by clients. + * </p> * * @since 3.0 */ public interface ILinkedModeListener { + /** Flag to <code>leave</code> specifying no special action. */ int NONE= 0; - /** Flag to <code>leave</code> specifying that all nested environments should exit. */ + /** + * Flag to <code>leave</code> specifying that all nested modes should + * exit. + */ int EXIT_ALL= 1 << 0; - /** Flag to <code>leave</code> specifying that the caret should be moved to the exit position. */ + /** + * Flag to <code>leave</code> specifying that the caret should be moved to + * the exit position. + */ int UPDATE_CARET= 1 << 1; - /** Flag to <code>leave</code> specifying that a UI of a parent environment should select the current position. */ + /** + * Flag to <code>leave</code> specifying that a UI of a parent mode should + * select the current position. + */ int SELECT= 1 << 2; - /** Flag to <code>leave</code> specifying that document content outside of a linked position was modified. */ + /** + * Flag to <code>leave</code> specifying that document content outside of + * a linked position was modified. + */ int EXTERNAL_MODIFICATION= 1 << 3; + /** - * The leave event occurs when a linked environment exits. + * The leave event occurs when linked is left. * - * @param environment the leaving environment + * @param model the model being left * @param flags the reason and commands for leaving linked mode */ - void left(LinkedModeModel environment, int flags); + void left(LinkedModeModel model, int flags); + /** - * The suspend event occurs when a nested linked environment is installed on this environment. + * The suspend event occurs when a nested linked mode is installed within + * <code>model</code>. * - * @param environment the environment being suspended due to a nested environment being installed + * @param model the model being suspended due to a nested model being + * installed */ - void suspend(LinkedModeModel environment); + void suspend(LinkedModeModel model); + /** - * The resume event occurs when a nested linked environment exits. + * The resume event occurs when a nested linked mode exits. * - * @param environment the environment being resumed due to a nested environment exiting + * @param model the linked mode model being resumed due to a nested mode + * exiting * @param flags the commands to execute when resuming after suspend */ - void resume(LinkedModeModel environment, int flags); -} + void resume(LinkedModeModel model, int flags); +}
\ No newline at end of file diff --git a/org.eclipse.text/src/org/eclipse/jface/text/link/InclusivePositionUpdater.java b/org.eclipse.text/src/org/eclipse/jface/text/link/InclusivePositionUpdater.java index 1f8f49fa446..3df6b45197d 100644 --- a/org.eclipse.text/src/org/eclipse/jface/text/link/InclusivePositionUpdater.java +++ b/org.eclipse.text/src/org/eclipse/jface/text/link/InclusivePositionUpdater.java @@ -16,10 +16,12 @@ import org.eclipse.jface.text.IPositionUpdater; import org.eclipse.jface.text.Position; /** - * Position updater that takes any change in [position.offset, position.offset + position.length] as - * belonging to the position.<p> + * Position updater that takes any change in + * <code>[position.offset, position.offset + position.length]</code> as + * belonging to the position. + * <p> * Internal class. Do not use. Public for testing purposes only. - * + * </p> * * @since 3.0 */ diff --git a/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedModeModel.java b/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedModeModel.java index 4027246d5b2..3a0bd6e6401 100644 --- a/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedModeModel.java +++ b/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedModeModel.java @@ -46,7 +46,7 @@ import org.eclipse.jface.text.IDocumentExtension.IReplace; * </p> * <p> * If the document is changed outside any linked position, the model is - * teared down and all positions are deleted. The same happens upon calling + * torn down and all positions are deleted. The same happens upon calling * {@link #exit(int)}. * </p> * <h4>Nesting</h4> @@ -56,13 +56,16 @@ import org.eclipse.jface.text.IDocumentExtension.IReplace; * single position in a parent model that has previously been installed on * the same document(s). * </p> + * <p> + * Clients may instantiate instances of this class. + * </p> * * @since 3.0 */ public class LinkedModeModel { /** - * Checks whether there is already a linked mode model installed on <code>document</code>. + * Checks whether there is already a model installed on <code>document</code>. * * @param document the <code>IDocument</code> of interest * @return <code>true</code> if there is an existing model, <code>false</code> @@ -251,7 +254,7 @@ public class LinkedModeModel { private final IPositionUpdater fUpdater= new InclusivePositionUpdater(getCategory()); /** The document listener on the documents affected by this model. */ private final IDocumentListener fDocumentListener= new DocumentListener(); - /** The parent model for a hierachical set up, or <code>null</code>. */ + /** The parent model for a hierarchical set up, or <code>null</code>. */ private LinkedModeModel fParentEnvironment; /** * The position in <code>fParentEnvironment</code> that includes all @@ -304,7 +307,7 @@ public class LinkedModeModel { /** * Causes this model to exit. Called either if a document change - * outside this enviroment is detected, or by the UI. + * outside this model is detected, or by the UI. * * <p> * This method part of the private protocol between @@ -380,11 +383,9 @@ public class LinkedModeModel { * If the positions in <code>group</code> conflict with any other group in * this model, a <code>BadLocationException</code> is thrown. Also, * if this model is nested inside another one, all positions in all - * groups of the child model have to lie in a single position in the - * parent model, otherwise a <code>BadLocationException</code> is - * thrown. + * groups of the child model have to reside within a single position in the + * parent model, otherwise a <code>BadLocationException</code> is thrown. * </p> - * * <p> * If <code>group</code> already exists, nothing happens. * </p> @@ -409,7 +410,6 @@ public class LinkedModeModel { fGroups.add(group); } - /** * Installs this model, which includes registering as document * listener on all involved documents and storing global information about @@ -588,7 +588,7 @@ public class LinkedModeModel { * Returns whether this model is nested. * * <p> - * This method part of the private protocol between + * This method is part of the private protocol between * <code>LinkedUIControl</code> and <code>LinkedModeModel</code>. * </p> * @@ -604,7 +604,7 @@ public class LinkedModeModel { * order they were added. * * <p> - * This method part of the private protocol between + * This method is part of the private protocol between * <code>LinkedUIControl</code> and <code>LinkedModeModel</code>. * </p> * @@ -757,5 +757,4 @@ public class LinkedModeModel { } return null; } - } diff --git a/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedPosition.java b/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedPosition.java index 4566c325ca3..807294d2c51 100644 --- a/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedPosition.java +++ b/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedPosition.java @@ -19,7 +19,9 @@ import org.eclipse.jface.text.Position; /** * A <code>Position</code> on a document that knows which document it is * registered with and has a sequence number for tab stops. - * + * <p> + * Clients may extend this class. + * </p> * @since 3.0 */ public class LinkedPosition extends Position { @@ -44,7 +46,7 @@ public class LinkedPosition extends Position { } /** - * Creates a new instance. Equivalent to calling + * Creates a new instance. Equivalent to calling * <code>LinkedPosition(document, offset, length, LinkedPositionGroup.NO_STOP)</code> * * @param document the document @@ -77,7 +79,8 @@ public class LinkedPosition extends Position { * Returns whether this position overlaps with <code>position</code>. * * @param position the position to check. - * @return <code>true</code> if this position overlaps with <code>position</code>, <code>false</code> otherwise + * @return <code>true</code> if this position overlaps with + * <code>position</code>,<code>false</code> otherwise */ public boolean overlapsWith(LinkedPosition position) { return position.getDocument() == fDocument && overlapsWith(position.getOffset(), position.getLength()); @@ -87,7 +90,8 @@ public class LinkedPosition extends Position { * Returns whether this position includes <code>event</code>. * * @param event the event to check. - * @return <code>true</code> if this position includes <code>event</code>, <code>false</code> otherwise + * @return <code>true</code> if this position includes <code>event</code>, + * <code>false</code> otherwise */ public boolean includes(DocumentEvent event) { return includes(event.getDocument(), event.getOffset(), event.getLength()); @@ -97,19 +101,21 @@ public class LinkedPosition extends Position { * Returns whether this position includes <code>position</code>. * * @param position the position to check. - * @return <code>true</code> if this position includes <code>position</code>, <code>false</code> otherwise + * @return <code>true</code> if this position includes + * <code>position</code>,<code>false</code> otherwise */ public boolean includes(LinkedPosition position) { return includes(position.getDocument(), position.getOffset(), position.getLength()); } /** - * Overrides {@link Position#includes(int)} so every offset is considered included that lies in - * between the first and last offset of this position, and offsets that are right at the end - * of the position. + * Overrides {@link Position#includes(int)}so every offset is considered + * included that lies in between the first and last offset of this position, + * and offsets that are right at the end of the position. * * @param pOffset the offset to check - * @return <code>true</code> if <code>pOffset</code> is in [offset, offset + length] + * @return <code>true</code> if <code>pOffset</code> is in + * <code>[offset, offset + length]</code> */ public boolean includes(int pOffset) { return this.offset <= pOffset && pOffset <= this.offset + this.length; @@ -168,5 +174,4 @@ public class LinkedPosition extends Position { public int hashCode() { return fDocument.hashCode() | super.hashCode() | fSequenceNumber; } - } diff --git a/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedPositionGroup.java b/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedPositionGroup.java index a1219c61277..e628b4fa3ef 100644 --- a/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedPositionGroup.java +++ b/org.eclipse.text/src/org/eclipse/jface/text/link/LinkedPositionGroup.java @@ -36,9 +36,12 @@ import org.eclipse.jface.text.Position; * Normally, new positions are given a tab stop weight which can be used by * clients, e.g. the UI. If no weight is given, a position will not be visited. * If no weights are used at all, the first position in a document is taken as - * the only stop as to comply with the behaviour of the old linked position + * the only stop as to comply with the behavior of the old linked position * infrastructure. * </p> + * <p> + * Clients may instantiate this class. + * </p> * * @since 3.0 */ @@ -315,7 +318,8 @@ public class LinkedPositionGroup { /** * Returns whether this group contains any positions. * - * @return <code>true</code> if this group is empty, <code>false</code> if it is not + * @return <code>true</code> if this group is empty, <code>false</code> + * if it is not */ public boolean isEmtpy() { return fPositions.size() == 0; diff --git a/org.eclipse.text/src/org/eclipse/jface/text/link/package.html b/org.eclipse.text/src/org/eclipse/jface/text/link/package.html index aeab0f0e75e..bc58040011e 100644 --- a/org.eclipse.text/src/org/eclipse/jface/text/link/package.html +++ b/org.eclipse.text/src/org/eclipse/jface/text/link/package.html @@ -1,13 +1,9 @@ <!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> -<html> -<head> - <meta content="text/html; charset=iso-8859-1" - http-equiv="Content-Type"> +<html><head> + <meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type"> <meta content="IBM" name="Author"> - <meta content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]" - name="GENERATOR"> - <title>Linked Position Infrastructure</title> -</head> + <meta content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]" name="GENERATOR"><title>Linked Position Infrastructure</title></head> + <body> Application programming interfaces for interaction with the Eclipse Java User Interface text support. @@ -22,27 +18,18 @@ of one linked position will be reflected in the others. <h4>Classes</h4> <ul> <li><code>LinkedPositionGroup</code>: a set of linked positions. Add -positions to a group using the <code>addPosition</code> and <code>createPosition</code> -methods, which -also allow to specify an iteration order. See <span - style="font-family: monospace;">ProposalPosition</span><code><span - style="font-family: helvetica,arial,sans-serif;"> </span></code><span - style="font-family: helvetica,arial,sans-serif;">for a position type -that lets one attach </span><span style="font-family: monospace;">ICompletionProposals</span><span - style="font-family: monospace;"></span><span - style="font-family: helvetica,arial,sans-serif;"> </span><span - style="font-family: helvetica,arial,sans-serif;">to</span> +positions to a group using the <code>addPosition</code> method. See <span style="font-family: monospace;">LinkedPosition</span><code><span style="font-family: helvetica,arial,sans-serif;"> and</span></code> <span style="font-family: monospace;">ProposalPosition</span><code><span style="font-family: helvetica,arial,sans-serif;"> </span></code><span style="font-family: helvetica,arial,sans-serif;">for a position type +that lets one attach </span><span style="font-family: monospace;">ICompletionProposals</span><span style="font-family: monospace;"></span><span style="font-family: helvetica,arial,sans-serif;"> </span><span style="font-family: helvetica,arial,sans-serif;">to</span> be shown when the position is hit.</li> - <li><code>LinkedEnvironment</code>: umbrellas several <code>PositionGroup</code>s, + <li><code>LinkedModeModel</code>: umbrellas several <code>LinkedPositionGroup</code>s, e.g. in a template that has several groups of linked positions. Handles -the forwarding of updates received via an IDocumentListener. Add <code>PositionGroup</code>s +the forwarding of updates received via an IDocumentListener. Add <code>LinkedPositionGroup</code>s to -an environment using the <code>addGroup</code> method. Existence of a <span - style="font-family: monospace;">LinkedEnvironment </span>can be +an model using the <code>addGroup</code> method. Existence of a <span style="font-family: monospace;">LinkedModeModel </span>can be tested by one of the static methods.<br> </li> - <li><code>LinkedUIControl</code>: The UI for linked mode (for one -environment, to be precise). Monitors key etc. activity, monitors exit + <li><code>LinkedModeUI</code>: The UI for linked mode (for one +model, to be precise). Monitors key etc. activity, monitors exit conditions, creates a painter etc. <br> Properties: <ul> @@ -54,9 +41,9 @@ mode (e.g. using Enter, or Tab from the last position when not cycling). Set <code>isTabStop</code> to <code>true</code> if tabbing should stop over when cycling.</li> <li><span style="font-weight: bold;">position listener</span>: -you can register a position listener which will get notified whenever -the focus position changes. An example is <span - style="font-family: monospace;">org.eclipse.ui.texteditor.link.EditorHistoryUpdater</span> +extending classes may register a position listener which will get +notified whenever +the focus position changes. An example is <span style="font-family: monospace;">org.eclipse.ui.texteditor.link.EditorLinkedModeUI.EditorHistoryUpdater</span> which will store the edit location in the editor navigation history.<br> </li> </ul> @@ -64,11 +51,5 @@ which will store the edit location in the editor navigation history.<br> . </ul> <h4>Example</h4> -<pre> IDocument doc1, doc2;<br> ITextViewer viewer1, viewer2;<br> <br> /* create groups - this step is independent of the linked mode */<br> PositionGroup group1= new PositionGroup();<br> group1.addPosition(doc1, 3,4);<br> group1.addPosition(doc1, 7,8);<br> <br> PositionGroup group2= newPositionGroup();<br> group2.addPosition(doc1, 15, 25);<br> group2.addPosition(doc2, 0, 10);<br> <br> /* set up linked mode */<br> LinkedEnvironment env= new LinkedEnvironment();<br> env.addGroup(group1);<br> env.addGroup(group2);<br> env.forceInstall();<br> <br> /* create UI */<br> LinkedUIControl ui= new LinkedUIControl(env, new ITextViewer[] { viewer1, viewer2 });<br> ui.enter();<br></pre> -<h4>Todo</h4> -<ul> - <li>handle lazy computation of per-group proposals using a <code>IContentAssistProcessor</code> -(see PositionGroup, ProposalPosition) .</li> -</ul> -</body> -</html> +<pre> IDocument doc1, doc2;<br> ITextViewer viewer1, viewer2;<br> <br> /* create groups - this step is independent of the linked mode */<br> LinkedPositionGroup group1= new LinkedPositionGroup();<br> group1.addPosition(new LinkedPosition(doc1, 3, 4));<br> group1.addPosition(new LinkedPosition(doc1, 7, 8));<br> <br> LinkedPositionGroup group2= new LinkedPositionGroup();<br> group2.addPosition(new LinkedPosition(doc1, 15, 25));<br> group2.addPosition(new LinkedPosition(doc2, 0, 10));<br> <br> /* set up linked mode */<br> LinkedModeModel model= new LinkedModeModel();<br> model.addGroup(group1);<br> model.addGroup(group2);<br> model.forceInstall();<br> <br> /* create UI */<br> LinkedModeUI ui= new LinkedModeUI(model, new ITextViewer[] { viewer1, viewer2 });<br> ui.enter();<span style="font-family: sans-serif;"><br><br></span></pre> +</body></html>
\ No newline at end of file |