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]} interval. However, it's allowed
  43    *                                          to return value from {@code (maxPreferredOffset; endOffset)} interval
  44    *                                          unless {@code 'allowToBeyondMaxPreferredOffset'} if {@code 'false'}
  45    * @param allowToBeyondMaxPreferredOffset   indicates if it's allowed to return value from
  46    *                                          {@code (maxPreferredOffset; endOffset]} interval in case of inability to
  47    *                                          find appropriate offset from {@code (startOffset; maxPreferredOffset]} interval
  48    * @param virtual                           identifies if current request is for virtual wrap (soft wrap) position
  49    * @return                                  offset from {@code (startOffset; endOffset)} interval where
  50    *                                          target line should be wrapped OR {@code -1} 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 }