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: * A <code>IDocumentInformationMapping</code> represents a mapping between the coordinates of two
014: * <code>IDocument</code> objects: the original and the image. The document information mapping
015: * can translate document information such as line numbers or character ranges given for the original into
016: * the corresponding information of the image and vice versa.
017: *
018: * In order to provided backward compatibility for clients of <code>IDocumentInformationMapping</code>, extension
019: * interfaces are used to provide a means of evolution. The following extension interfaces
020: * exist:
021: * <ul>
022: * <li> {@link org.eclipse.jface.text.IDocumentInformationMappingExtension} since version 3.0 extending the
023: * degree of detail of the mapping information.</li>
024: * <li> {@link org.eclipse.jface.text.IDocumentInformationMappingExtension2} since version 3.1, adding lenient
025: * image region computation.</li>
026: * </ul>
027: *
028: * @since 2.1
029: */
030: public interface IDocumentInformationMapping {
031:
032: /**
033: * Returns the minimal region of the original document that completely comprises all of the image document
034: * or <code>null</code> if there is no such region.
035: *
036: * @return the minimal region of the original document comprising the image document or <code>null</code>
037: */
038: IRegion getCoverage();
039:
040: /**
041: * Returns the offset in the original document that corresponds to the given offset in the image document
042: * or <code>-1</code> if there is no such offset
043: *
044: * @param imageOffset the offset in the image document
045: * @return the corresponding offset in the original document or <code>-1</code>
046: * @throws BadLocationException if <code>imageOffset</code> is not a valid offset in the image document
047: */
048: int toOriginOffset(int imageOffset) throws BadLocationException;
049:
050: /**
051: * Returns the minimal region of the original document that completely comprises the given region of the
052: * image document or <code>null</code> if there is no such region.
053: *
054: * @param imageRegion the region of the image document
055: * @return the minimal region of the original document comprising the given region of the image document or <code>null</code>
056: * @throws BadLocationException if <code>imageRegion</code> is not a valid region of the image document
057: */
058: IRegion toOriginRegion(IRegion imageRegion)
059: throws BadLocationException;
060:
061: /**
062: * Returns the range of lines of the original document that corresponds to the given line of the image document or
063: * <code>null</code> if there are no such lines.
064: *
065: * @param imageLine the line of the image document
066: * @return the corresponding lines of the original document or <code>null</code>
067: * @throws BadLocationException if <code>imageLine</code> is not a valid line number in the image document
068: */
069: IRegion toOriginLines(int imageLine) throws BadLocationException;
070:
071: /**
072: * Returns the line of the original document that corresponds to the given line of the image document or
073: * <code>-1</code> if there is no such line.
074: *
075: * @param imageLine the line of the image document
076: * @return the corresponding line of the original document or <code>-1</code>
077: * @throws BadLocationException if <code>imageLine</code> is not a valid line number in the image document
078: */
079: int toOriginLine(int imageLine) throws BadLocationException;
080:
081: /**
082: * Returns the offset in the image document that corresponds to the given offset in the original document
083: * or <code>-1</code> if there is no such offset
084: *
085: * @param originOffset the offset in the original document
086: * @return the corresponding offset in the image document or <code>-1</code>
087: * @throws BadLocationException if <code>originOffset</code> is not a valid offset in the original document
088: */
089: int toImageOffset(int originOffset) throws BadLocationException;
090:
091: /**
092: * Returns the minimal region of the image document that completely comprises the given region of the
093: * original document or <code>null</code> if there is no such region.
094: *
095: * @param originRegion the region of the original document
096: * @return the minimal region of the image document comprising the given region of the original document or <code>null</code>
097: * @throws BadLocationException if <code>originRegion</code> is not a valid region of the original document
098: */
099: IRegion toImageRegion(IRegion originRegion)
100: throws BadLocationException;
101:
102: /**
103: * Returns the line of the image document that corresponds to the given line of the original document or
104: * <code>-1</code> if there is no such line.
105: *
106: * @param originLine the line of the original document
107: * @return the corresponding line of the image document or <code>-1</code>
108: * @throws BadLocationException if <code>originLine</code> is not a valid line number in the original document
109: */
110: int toImageLine(int originLine) throws BadLocationException;
111:
112: /**
113: * Returns the line of the image document whose corresponding line in the original document
114: * is closest to the given line in the original document.
115: *
116: * @param originLine the line in the original document
117: * @return the line in the image document that corresponds best to the given line in the original document
118: * @throws BadLocationException if <code>originLine</code>is not a valid line in the original document
119: */
120: int toClosestImageLine(int originLine) throws BadLocationException;
121: }
|