ExtendWordSelectionHandler.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.codeInsight.editorActions;

import com.intellij.openapi.editor.Editor;
import com.intellij.openapi.extensions.ExtensionPointName;
import com.intellij.openapi.util.TextRange;
import com.intellij.psi.PsiElement;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.List;

/**
 * Add text-ranges that can be selected within a {@link PsiElement} using extend/shrink selection.
 *
 * The default behavior for extending/shrinking selections is to change the selected region based on parents/children in the
 * underlying PSI tree. This EP allows for adding intermediate steps when a selection is extended/shrunk.
 * A common use-case custom languages is a function-call {@code f(a,b)} where the function-call node has its two arguments
 * as children. With one of the arguments selected, extending the selection would directly grow the region to the whole function-call.
 * However, one might want to select all arguments as an intermediate step.
 * This can be achieved by implementing this EP, returning {@code true} from {@link #canSelect(PsiElement)} for the function-call node,
 * and providing the sub-region for all arguments in {@link #select(PsiElement, CharSequence, int, Editor)}.
 */
public interface ExtendWordSelectionHandler {
  ExtensionPointName<ExtendWordSelectionHandler> EP_NAME = ExtensionPointName.create("com.intellij.extendWordSelectionHandler");

  /**
   * Indicates if a {@link PsiElement} can provide addition text-ranges for extending/shrinking a selection.
   *
   * @param e Element to check
   * @return true if the {@link PsiElement} can provide addition text-ranges for selection and
   *          {@link #select(PsiElement, CharSequence, int, Editor)} should be called
   */
  boolean canSelect(@NotNull PsiElement e);

  /**
   * Computes a list of additional text-ranges for a {@link PsiElement} that are included when extending/shrinking a selection.
   *
   * @param e Element that returned true when {@link #canSelect} was called
   * @param editorText Text of the editor
   * @param cursorOffset Current offset of the cursor
   * @param editor Editor that contains the {@link PsiElement}
   * @return List of additional text-ranges that are used as a step when extending/shrinking a selection
   */
  @Nullable
  List<TextRange> select(@NotNull PsiElement e, @NotNull CharSequence editorText, int cursorOffset, @NotNull Editor editor);
}