001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.text;
011:
012: /**
013: * Extension interface for {@link org.eclipse.jface.text.ITextViewer}. Defines
014: * a conceptual replacement of the original visible region concept. This interface
015: * replaces {@link org.eclipse.jface.text.ITextViewerExtension3}.
016: * <p>
017: * Introduces the explicit concept of model and widget coordinates. For example,
018: * a selection returned by the text viewer's control is a widget selection. A
019: * widget selection always maps to a certain range of the viewer's document.
020: * This range is considered the model selection.
021: * <p>
022: * All model ranges that have a corresponding widget ranges are considered
023: * "exposed model ranges". The viewer can be requested to expose a given model
024: * range. Thus, a visible region is a particular degeneration of exposed model
025: * ranges.
026: * <p>
027: * This interface allows implementers to follow a sophisticated presentation
028: * model in which the visible presentation is a complex projection of the
029: * viewer's input document.
030: *
031: * @since 3.0
032: */
033: public interface ITextViewerExtension5 extends ITextViewerExtension3 {
034:
035: /**
036: * Returns the minimal region of the viewer's input document that completely
037: * comprises everything that is visible in the viewer's widget or
038: * <code>null</code> if there is no such region.
039: *
040: * @return the minimal region of the viewer's document comprising the
041: * contents of the viewer's widget or <code>null</code>
042: */
043: IRegion getModelCoverage();
044:
045: /**
046: * Returns the widget line that corresponds to the given line of the
047: * viewer's input document or <code>-1</code> if there is no such line.
048: *
049: * @param modelLine the line of the viewer's document
050: * @return the corresponding widget line or <code>-1</code>
051: */
052: int modelLine2WidgetLine(int modelLine);
053:
054: /**
055: * Returns the widget offset that corresponds to the given offset in the
056: * viewer's input document or <code>-1</code> if there is no such offset
057: *
058: * @param modelOffset the offset in the viewer's document
059: * @return the corresponding widget offset or <code>-1</code>
060: */
061: int modelOffset2WidgetOffset(int modelOffset);
062:
063: /**
064: * Returns the minimal region of the viewer's widget that completely
065: * comprises the given region of the viewer's input document or
066: * <code>null</code> if there is no such region.
067: *
068: * @param modelRange the region of the viewer's document
069: * @return the minimal region of the widget comprising
070: * <code>modelRange</code> or <code>null</code>
071: */
072: IRegion modelRange2WidgetRange(IRegion modelRange);
073:
074: /**
075: * Returns the offset of the viewer's input document that corresponds to the
076: * given widget offset or <code>-1</code> if there is no such offset
077: *
078: * @param widgetOffset the widget offset
079: * @return the corresponding offset in the viewer's document or
080: * <code>-1</code>
081: */
082: int widgetOffset2ModelOffset(int widgetOffset);
083:
084: /**
085: * Returns the minimal region of the viewer's input document that completely
086: * comprises the given widget region or <code>null</code> if there is no
087: * such region.
088: *
089: * @param widgetRange the widget region
090: * @return the minimal region of the viewer's document comprising
091: * <code>widgetlRange</code> or <code>null</code>
092: */
093: IRegion widgetRange2ModelRange(IRegion widgetRange);
094:
095: /**
096: * Returns the line of the viewer's input document that corresponds to the
097: * given widget line or <code>-1</code> if there is no such line.
098: *
099: * @param widgetLine the widget line
100: * @return the corresponding line of the viewer's document or
101: * <code>-1</code>
102: */
103: int widgetLine2ModelLine(int widgetLine);
104:
105: /**
106: * Returns the widget line of the given widget offset.
107: *
108: * @param widgetOffset the widget offset
109: * @return the widget line of the widget offset
110: */
111: int widgetLineOfWidgetOffset(int widgetOffset);
112:
113: /**
114: * Returns the maximal subranges of the given model range thus that there is
115: * no offset inside a subrange for which there is no image offset.
116: *
117: * @param modelRange the model range
118: * @return the list of subranges
119: */
120: IRegion[] getCoveredModelRanges(IRegion modelRange);
121:
122: /**
123: * Exposes the given model range. Returns whether this call caused a change
124: * of the set of exposed model ranges.
125: *
126: * @param modelRange the model range to be exposed
127: * @return <code>true</code> if the set of exposed model ranges changed,
128: * <code>false</code> otherwise
129: */
130: boolean exposeModelRange(IRegion modelRange);
131: }
|