Author: IBM

Application programming interfaces for interaction with the Eclipse text editor's linked position support.

## Linked Position Infrastructure

### package `org.eclipse.jface.text.link`

The Linked Position Infrastructure lets one set up a mode in an editor in which regions in a document (or several documents) are linked, i.e. editions of one linked position will be reflected in the others.

#### Classes

- `LinkedPositionGroup`: a set of linked positions. Add positions to a group using the `addPosition` method. See `LinkedPosition` and `ProposalPosition` for a position type that lets one attach `ICompletionProposal`s to be shown when the position is hit.
- `LinkedModeModel`: umbrellas several `LinkedPositionGroup`s, e.g. in a template that has several groups of linked positions. Handles the forwarding of updates received via an `IDocumentListener`. Add `LinkedPositionGroup`s to an model using the `addGroup` method. Existence of a `LinkedModeModel` can be tested by one of the static methods.
- `LinkedModeUI`: The UI for linked mode (for one model, to be precise). Monitors key etc. activity, monitors exit conditions, creates a painter etc.
  Properties:
  - cycling mode (whether to jump to the first position after the last): either of `CYCLE_ALWAYS`, `CYCLE_NEVER` and `CYCLE_WHEN_NO_PARENT` (default).
  - exit position: where to jump upon leaving the linked mode (e.g. using Enter, or Tab from the last position when not cycling). Set `isTabStop` to `true` if tabbing should stop over when cycling.
  - position listener: extending classes may register a position listener which will get notified whenever the focus position changes. An example is `org.eclipse.ui.texteditor.link.EditorLinkedModeUI.EditorHistoryUpdater` which will store the edit location in the editor navigation history.

#### Example

    	IDocument doc1, doc2;
    	ITextViewer viewer1, viewer2;

    	/* create groups - this step is independent of the linked mode */
    	LinkedPositionGroup group1= new LinkedPositionGroup();
    	group1.addPosition(new LinkedPosition(doc1, 3, 4));
    	group1.addPosition(new LinkedPosition(doc1, 7, 8));

    	LinkedPositionGroup group2= new LinkedPositionGroup();
    	group2.addPosition(new LinkedPosition(doc1, 15, 25));
    	group2.addPosition(new LinkedPosition(doc2, 0, 10));

    	/* set up linked mode */
    	LinkedModeModel model= new LinkedModeModel();
    	model.addGroup(group1);
    	model.addGroup(group2);
    	model.forceInstall();

    	/* create UI */
    	LinkedModeUI ui= new LinkedModeUI(model, new ITextViewer[] { viewer1, viewer2 });
    	ui.enter();