lvcs-impl
[idea/community.git] / lang-api / src / com / intellij / lang / folding / FoldingBuilderEx.java
1 /*
2  * Copyright 2000-2009 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
17 package com.intellij.lang.folding;
18
19 import com.intellij.lang.ASTNode;
20 import com.intellij.openapi.editor.Document;
21 import com.intellij.psi.PsiElement;
22 import org.jetbrains.annotations.NotNull;
23 import org.jetbrains.annotations.Nullable;
24
25 /**
26  * Allows a custom language plugin to define rules for folding code in the language handled
27  * by the plugin.
28  *
29  * @author max
30  * @see com.intellij.lang.folding.LanguageFolding#forLanguage(com.intellij.lang.Language)
31  */
32
33 public abstract class FoldingBuilderEx implements FoldingBuilder {
34   /**
35    * Builds the folding regions for the specified node in the AST tree and its children.
36    *
37    * @param root     the element for which folding is requested.
38    * @param document the document for which folding is built. Can be used to retrieve line
39    *                 numbers for folding regions.
40    * @param quick    whether the result should be providen as soon as possible. Is true, when
41    *                 an editor is opened and we need to auto-fold something immediately, like Java imports.
42    *                 If true, one should perform no reference resolving and avoid complex checks if possible.
43    * @return the array of folding descriptors.
44    */
45   @NotNull
46   public abstract FoldingDescriptor[] buildFoldRegions(@NotNull PsiElement root, @NotNull Document document, boolean quick);
47
48   @NotNull
49   public FoldingDescriptor[] buildFoldRegions(@NotNull ASTNode node, @NotNull Document document) {
50     return buildFoldRegions(node.getPsi(), document, false);
51   }
52
53   /**
54    * Returns the text which is displayed in the editor for the folding region related to the
55    * specified node when the folding region is collapsed.
56    *
57    * @param node the node for which the placeholder text is requested.
58    * @return the placeholder text.
59    */
60   @Nullable
61   public abstract String getPlaceholderText(@NotNull ASTNode node);
62
63   /**
64    * Returns the default collapsed state for the folding region related to the specified node.
65    *
66    * @param node the node for which the collapsed state is requested.
67    * @return true if the region is collapsed by default, false otherwise.
68    */
69   public abstract boolean isCollapsedByDefault(@NotNull ASTNode node);
70 }