platform/editor-ui-api/src/com/intellij/openapi/editor/LineWrapPositionStrategy.java

/*
 * Copyright 2000-2013 JetBrains s.r.o.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.intellij.openapi.editor;

import com.intellij.openapi.project.Project;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

/**
 * Defines contract for the strategy that calculates the best place to apply wrap to particular line (sequence of characters).
 * <p/>
 * One possible use case for such functionality is a situation when user opens document with lines that are wider that editor's
 * visible area. We can represent such long strings in multiple visual line then and need to know the best place to insert
 * such virtual wrap.
 *
 * @author Denis Zhdanov
 * @since Aug 25, 2010 11:14:29 AM
 */
public interface LineWrapPositionStrategy {

  /**
   * Allows to calculate the most appropriate position to wrap target line.
   *
   * @param document                          target document which text is being processed
   * @param project                           target project
   * @param startOffset                       start offset to use with the given text holder (exclusive)
   * @param endOffset                         end offset to use with the given text holder (exclusive)
   * @param maxPreferredOffset                this method is expected to do its best to return offset that belongs to
   *                                          <code>(startOffset; maxPreferredOffset]</code> interval. However, it's allowed
   *                                          to return value from <code>(maxPreferredOffset; endOffset)</code> interval
   *                                          unless <code>'allowToBeyondMaxPreferredOffset'</code> if <code>'false'</code>
   * @param allowToBeyondMaxPreferredOffset   indicates if it's allowed to return value from
   *                                          <code>(maxPreferredOffset; endOffset]</code> interval in case of inability to
   *                                          find appropriate offset from <code>(startOffset; maxPreferredOffset]</code> interval
   * @param virtual                           identifies if current request is for virtual wrap (soft wrap) position
   * @return                                  offset from <code>(startOffset; endOffset)</code> interval where
   *                                          target line should be wrapped OR <code>-1</code> if no wrapping should be performed
   */
  int calculateWrapPosition(
    @NotNull Document document, @Nullable Project project, int startOffset, int endOffset, int maxPreferredOffset,
    boolean allowToBeyondMaxPreferredOffset, boolean virtual
  );
}