e27fedbdf9ff70c3eb3fd987bf046a4bf653fb99
[idea/community.git] / platform / editor-ui-api / src / com / intellij / openapi / editor / LineWrapPositionStrategy.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 com.intellij.openapi.project.Project;
19 import org.jetbrains.annotations.NotNull;
20 import org.jetbrains.annotations.Nullable;
21
22 /**
23  * Defines contract for the strategy that calculates the best place to apply wrap to particular line (sequence of characters).
24  * <p/>
25  * One possible use case for such functionality is a situation when user opens document with lines that are wider that editor's
26  * visible area. We can represent such long strings in multiple visual line then and need to know the best place to insert
27  * such virtual wrap.
28  *
29  * @author Denis Zhdanov
30  * @since Aug 25, 2010 11:14:29 AM
31  */
32 public interface LineWrapPositionStrategy {
33
34   /**
35    * Allows to calculate the most appropriate position to wrap target line.
36    *
37    * @param document                          target document which text is being processed
38    * @param project                           target project
39    * @param startOffset                       start offset to use with the given text holder (exclusive)
40    * @param endOffset                         end offset to use with the given text holder (exclusive)
41    * @param maxPreferredOffset                this method is expected to do its best to return offset that belongs to
42    *                                          <code>(startOffset; maxPreferredOffset]</code> interval. However, it's allowed
43    *                                          to return value from <code>(maxPreferredOffset; endOffset)</code> interval
44    *                                          unless <code>'allowToBeyondMaxPreferredOffset'</code> if <code>'false'</code>
45    * @param allowToBeyondMaxPreferredOffset   indicates if it's allowed to return value from
46    *                                          <code>(maxPreferredOffset; endOffset]</code> interval in case of inability to
47    *                                          find appropriate offset from <code>(startOffset; maxPreferredOffset]</code> interval
48    * @param virtual                           identifies if current request is for virtual wrap (soft wrap) position
49    * @return                                  offset from <code>(startOffset; endOffset)</code> interval where
50    *                                          target line should be wrapped OR <code>-1</code> if no wrapping should be performed
51    */
52   int calculateWrapPosition(
53     @NotNull Document document, @Nullable Project project, int startOffset, int endOffset, int maxPreferredOffset,
54     boolean allowToBeyondMaxPreferredOffset, boolean virtual
55   );
56 }