replaced <code></code> with more concise {@code}
[idea/community.git] / platform / editor-ui-api / src / com / intellij / openapi / editor / SoftWrapModel.java
1 /*
2  * Copyright 2000-2013 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.intellij.openapi.editor;
17
18 import org.jetbrains.annotations.NotNull;
19 import org.jetbrains.annotations.Nullable;
20
21 import java.util.List;
22
23 /**
24  * Defines contract for the services that bring {@code 'soft wrapping'} to the editor.
25  * <p/>
26  * {@code 'Soft wrap'} here means representation of the line that exceeds right component viewport margin as if it is wrapped.
27  * No changes are introduced to the actual document/file system during that, i.e. it's a pure {@code 'view'} facility.
28  * <p/>
29  * <b>Example:</b>
30  * <p/>
31  * <b>Raw text (as stored at file system)</b>
32  * <p/>
33  * <pre>
34  *     public class Test {                                         | &lt;- right margin
35  *                                                                 |
36  *         public void baz() {                                     |
37  *             foo("test1", "test2", "test3", "test4", "test5", "test6");
38  *         }                                                       |
39  *                                                                 |
40  *         public void foo(Object ... args) {                      |
41  *         }                                                       |
42  *     }                                                           |
43  *      </pre>
44  * <p/>
45  * <b>The same text with soft wraps as shown to end-user at editor</b>
46  * <p/>
47  * <pre>
48  *     public class Test {                                         | &lt;- right margin
49  *                                                                 |
50  *         public void baz() {                                     |
51  *             foo("test1", "test2", "test3", "test4", "test5",    |
52  *                 "test6");                                       |
53  *         }                                                       |
54  *                                                                 |
55  *         public void foo(Object ... args) {                      |
56  *         }                                                       |
57  *     }                                                           |
58  *      </pre>
59  * <p/>
60  * Another important soft wrap feature is that as soon as the user starts typing on a line which representation is affected by
61  * soft wrap (e.g. starts adding new call argument after {@code "test6"} at example above), that soft wraps becomes
62  * {@code 'hard wrap'}, i.e. virtual changes introduced by it are flushed to the underlying document.
63  * <p/>
64  * <b>Note:</b> soft wrap is assumed to provide as user-friendly indentation for those wrapped line as possible
65  * (note that {@code "test6"} at example below is aligned to the parameters start).
66  * <p/>
67  * Implementations of this interface are not obliged to be thread-safe.
68  *
69  * @author Denis Zhdanov
70  * @since Jun 8, 2010 3:15:18 PM
71  */
72 public interface SoftWrapModel {
73
74   /**
75    * Allows to answer if {@code 'soft wrap'} feature is enabled.
76    *
77    * @return    {@code true} if {@code 'soft wraps'} are enabled; {@code false} otherwise
78    */
79   boolean isSoftWrappingEnabled();
80
81   /**
82    * Asks current model for the soft wrap registered for the given document offset if any.
83    *
84    * @param offset      target document offset
85    * @return            soft wrap registered for the given offset within the current model if any; {@code null} otherwise
86    */
87   @Nullable
88   SoftWrap getSoftWrap(int offset);
89
90   /**
91    * Allows to ask current model about all soft wraps registered for the given document offsets range.
92    *
93    * @param start   start document offset range to use (inclusive)
94    * @param end     end document offset range to use (inclusive)
95    * @return        all soft wraps registered for the target document offsets range
96    */
97   @NotNull
98   List<? extends SoftWrap> getSoftWrapsForRange(int start, int end);
99
100   /**
101    * Allows to ask current model about all soft wraps registered for the given document line.
102    *
103    * @param documentLine    target document line
104    * @return                all soft wraps registered for the given document line
105    */
106   @NotNull
107   List<? extends SoftWrap> getSoftWrapsForLine(int documentLine);
108
109   /**
110    * Allows to answer if given soft wrap is shown.
111    * <p/>
112    * The soft wrap may be not shown if it's located, for example, inside collapsed folding region.
113    *
114    * @param softWrap    soft wrap to check
115    * @return            {@code true} if given soft wrap is visible; {@code false} otherwise
116    */
117   boolean isVisible(SoftWrap softWrap);
118
119   /**
120    * Notifies current model that target document is about to be changed at current caret location.
121    * <p/>
122    * Primary purpose of this method is to perform {@code 'soft wrap' -> 'hard wrap'} conversion if the user types in virtual
123    * soft wraps-introduced space.
124    */
125   void beforeDocumentChangeAtCaret();
126
127   /**
128    * Allows to answer if given visual position points to soft wrap-introduced virtual space.
129    *
130    * @param position    target visual position to check
131    * @return            {@code true} if given visual position points to soft wrap-introduced virtual space;
132    *                    {@code false} otherwise
133    */
134   boolean isInsideSoftWrap(@NotNull VisualPosition position);
135
136   /**
137    * Allows to answer if given visual position points to soft wrap-introduced virtual space or points just before soft wrap.
138    *
139    * @param visual    target visual position to check
140    * @return          {@code true} if given visual position points to soft wrap-introduced virtual space;
141    *                  {@code false} otherwise
142    */
143   boolean isInsideOrBeforeSoftWrap(@NotNull VisualPosition visual);
144
145   /**
146    * Callback method to ask soft wrap model to release all resources.
147    */
148   void release();
149 }