KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > text > IDocumentInformationMapping


1 /*******************************************************************************
2  * Copyright (c) 2000, 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jface.text;
12
13
14 /**
15  * A <code>IDocumentInformationMapping</code> represents a mapping between the coordinates of two
16  * <code>IDocument</code> objects: the original and the image. The document information mapping
17  * can translate document information such as line numbers or character ranges given for the original into
18  * the corresponding information of the image and vice versa.
19  *
20  * In order to provided backward compatibility for clients of <code>IDocumentInformationMapping</code>, extension
21  * interfaces are used to provide a means of evolution. The following extension interfaces
22  * exist:
23  * <ul>
24  * <li> {@link org.eclipse.jface.text.IDocumentInformationMappingExtension} since version 3.0 extending the
25  * degree of detail of the mapping information.</li>
26  * <li> {@link org.eclipse.jface.text.IDocumentInformationMappingExtension2} since version 3.1, adding lenient
27  * image region computation.</li>
28  * </ul>
29  *
30  * @since 2.1
31  */
32 public interface IDocumentInformationMapping {
33
34     /**
35      * Returns the minimal region of the original document that completely comprises all of the image document
36      * or <code>null</code> if there is no such region.
37      *
38      * @return the minimal region of the original document comprising the image document or <code>null</code>
39      */
40     IRegion getCoverage();
41
42     /**
43      * Returns the offset in the original document that corresponds to the given offset in the image document
44      * or <code>-1</code> if there is no such offset
45      *
46      * @param imageOffset the offset in the image document
47      * @return the corresponding offset in the original document or <code>-1</code>
48      * @throws BadLocationException if <code>imageOffset</code> is not a valid offset in the image document
49      */
50     int toOriginOffset(int imageOffset) throws BadLocationException;
51
52     /**
53      * Returns the minimal region of the original document that completely comprises the given region of the
54      * image document or <code>null</code> if there is no such region.
55      *
56      * @param imageRegion the region of the image document
57      * @return the minimal region of the original document comprising the given region of the image document or <code>null</code>
58      * @throws BadLocationException if <code>imageRegion</code> is not a valid region of the image document
59      */
60     IRegion toOriginRegion(IRegion imageRegion) throws BadLocationException;
61
62     /**
63      * Returns the range of lines of the original document that corresponds to the given line of the image document or
64      * <code>null</code> if there are no such lines.
65      *
66      * @param imageLine the line of the image document
67      * @return the corresponding lines of the original document or <code>null</code>
68      * @throws BadLocationException if <code>imageLine</code> is not a valid line number in the image document
69      */
70     IRegion toOriginLines(int imageLine) throws BadLocationException;
71
72     /**
73      * Returns the line of the original document that corresponds to the given line of the image document or
74      * <code>-1</code> if there is no such line.
75      *
76      * @param imageLine the line of the image document
77      * @return the corresponding line of the original document or <code>-1</code>
78      * @throws BadLocationException if <code>imageLine</code> is not a valid line number in the image document
79      */
80     int toOriginLine(int imageLine) throws BadLocationException;
81
82
83
84     /**
85      * Returns the offset in the image document that corresponds to the given offset in the original document
86      * or <code>-1</code> if there is no such offset
87      *
88      * @param originOffset the offset in the original document
89      * @return the corresponding offset in the image document or <code>-1</code>
90      * @throws BadLocationException if <code>originOffset</code> is not a valid offset in the original document
91      */
92     int toImageOffset(int originOffset) throws BadLocationException;
93
94     /**
95      * Returns the minimal region of the image document that completely comprises the given region of the
96      * original document or <code>null</code> if there is no such region.
97      *
98      * @param originRegion the region of the original document
99      * @return the minimal region of the image document comprising the given region of the original document or <code>null</code>
100      * @throws BadLocationException if <code>originRegion</code> is not a valid region of the original document
101      */
102     IRegion toImageRegion(IRegion originRegion) throws BadLocationException;
103
104     /**
105      * Returns the line of the image document that corresponds to the given line of the original document or
106      * <code>-1</code> if there is no such line.
107      *
108      * @param originLine the line of the original document
109      * @return the corresponding line of the image document or <code>-1</code>
110      * @throws BadLocationException if <code>originLine</code> is not a valid line number in the original document
111      */
112     int toImageLine(int originLine) throws BadLocationException;
113
114     /**
115      * Returns the line of the image document whose corresponding line in the original document
116      * is closest to the given line in the original document.
117      *
118      * @param originLine the line in the original document
119      * @return the line in the image document that corresponds best to the given line in the original document
120      * @throws BadLocationException if <code>originLine</code>is not a valid line in the original document
121      */
122     int toClosestImageLine(int originLine) throws BadLocationException;
123 }
124
Popular Tags