lvcs-impl
[idea/community.git] / lang-api / src / com / intellij / ide / favoritesTreeView / FavoriteNodeProvider.java
1 /*
2  * Copyright 2000-2007 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.ide.favoritesTreeView;
18
19 import com.intellij.ide.projectView.ViewSettings;
20 import com.intellij.ide.util.treeView.AbstractTreeNode;
21 import com.intellij.openapi.actionSystem.DataContext;
22 import com.intellij.openapi.extensions.ExtensionPointName;
23 import com.intellij.openapi.project.Project;
24 import com.intellij.openapi.vfs.VirtualFile;
25 import com.intellij.psi.PsiElement;
26 import org.jetbrains.annotations.NonNls;
27 import org.jetbrains.annotations.NotNull;
28 import org.jetbrains.annotations.Nullable;
29
30 import java.util.Collection;
31
32 /**
33  * Returns the nodes which should be added to the Favorites for the given data context.
34  * Implementations of this class must be registered as extensions for
35  * <code>com.intellij.favoriteNodeProvider</code> extension point.
36  *
37  * @author yole
38  */
39 public abstract class FavoriteNodeProvider {
40   public static final ExtensionPointName<FavoriteNodeProvider> EP_NAME = new ExtensionPointName<FavoriteNodeProvider>("com.intellij.favoriteNodeProvider");
41
42   @Nullable
43   public abstract Collection<AbstractTreeNode> getFavoriteNodes(DataContext context, final ViewSettings viewSettings);
44
45   @Nullable
46   public AbstractTreeNode createNode(final Project project, final Object element, final ViewSettings viewSettings) {
47     return null;
48   }
49
50   /**
51    * Checks if the specified project view node element (the value of {@link AbstractTreeNode}) contains
52    * the specified virtual file as one of its children.
53    *
54    * @param element the value element of a project view node.
55    * @param vFile   the file to check.
56    * @return true if the file is contained, false if not or if <code>element</code> is not an element supported by this provider.
57    */
58   public abstract boolean elementContainsFile(final Object element, final VirtualFile vFile);
59
60   /**
61    * Returns the weight of the specified project view node element to use when sorting the favorites list.
62    *
63    * @param element the element for which the weight is requested.
64    * @param isSortByType
65    * @return the weight, or -1 if <code>element</code> is not an element supported by this provider.
66    */
67   public abstract int getElementWeight(final Object element, final boolean isSortByType);
68
69   /**
70    * Returns the location text (grey text in parentheses) to display in the Favorites view for the specified element.
71    *
72    * @param element the element for which the location is requested.
73    * @return the location text, or -1 if <code>element</code> is not an element supported by this provider.
74    */
75   @Nullable
76   public abstract String getElementLocation(final Object element);
77
78   /**
79    * Checks if the specified element is invalid and needs to be removed from the tree.
80    *
81    * @param element the element to check.
82    * @return true if the element is invalid, false if the element is valid or not supported by this provider.
83    */
84   public abstract boolean isInvalidElement(final Object element);
85
86   /**
87    * Returns the identifier used to persist favorites for this provider.
88    *
89    * @return the string identifier.
90    */
91   @NotNull @NonNls
92   public abstract String getFavoriteTypeId();
93
94   /**
95    * Returns the persistable URL for the specified element.
96    *
97    * @param element
98    * @return the URL, or null if the element is not supported by this provider.
99    */
100   @Nullable @NonNls
101   public abstract String getElementUrl(final Object element);
102
103   /**
104    * Returns the name of the module containing the specified element.
105    *
106    * @param element
107    * @return the name of the module, or null if the element is not supported by this provider or the module name is unknown.
108    */
109   @Nullable
110   public abstract String getElementModuleName(final Object element);
111
112   /**
113    * Returns the path of node objects to be added to the favorites tree for the specified persisted URL and module name.
114    *
115    * @param project the project to which the favorite is related.
116    * @param url the loaded URL (initially returned from {@link #getElementUrl }).
117    * @param moduleName the name of the module containing the element (initially returned from {@link #getElementModuleName})
118    * @return the path of objects to be added to the tree, or null if it was not possible to locate an object with the
119    * specified URL.
120    */
121   @Nullable
122   public abstract Object[] createPathFromUrl(final Project project, final String url, final String moduleName);
123
124   @Nullable
125   public PsiElement getPsiElement(final Object element) {
126     if (element instanceof PsiElement) {
127       return (PsiElement)element;
128     }
129     return null;
130   }
131 }