[i18n] idea-ui
[idea/community.git] / platform / platform-api / src / com / intellij / openapi / options / Configurable.java
1 // Copyright 2000-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
2 package com.intellij.openapi.options;
3
4 import com.intellij.ide.ui.UINumericRange;
5 import com.intellij.openapi.extensions.BaseExtensionPointName;
6 import com.intellij.openapi.extensions.ExtensionPointName;
7 import com.intellij.openapi.extensions.ProjectExtensionPointName;
8 import com.intellij.openapi.ui.ComboBox;
9 import com.intellij.openapi.util.Comparing;
10 import com.intellij.openapi.util.NlsContexts;
11 import com.intellij.openapi.util.text.StringUtil;
12 import org.jetbrains.annotations.Contract;
13 import org.jetbrains.annotations.NonNls;
14 import org.jetbrains.annotations.NotNull;
15 import org.jetbrains.annotations.Nullable;
16
17 import javax.swing.*;
18 import java.awt.*;
19 import java.util.Collection;
20
21 /**
22  * This interface represents a named configurable component that provides a Swing form
23  * to configure some settings via the Settings dialog.
24  * <p/>
25  * To register a custom implementation of this interface use the following extension points:
26  * {@code com.intellij.applicationConfigurable} for settings, which are global for IDE,
27  * and {@code com.intellij.projectConfigurable} for project settings, which are applied
28  * to the current project only.  They differ only in the constructor implementation.
29  * Classes for IDE settings must have a default constructor with no arguments,
30  * while classes for project settings must declare a constructor with a single argument
31  * of the {@link com.intellij.openapi.project.Project Project} type.
32  * <p/>
33  * The following attributes are available for both extension points mentioned above:
34  * <dl>
35  *   <dt>{@link ConfigurableEP#instanceClass instance}</dt>
36  *   <dd>This attribute specifies a qualified name of a custom implementation of this interface.
37  *   The constructor will be determined automatically from the tag name:
38  *   <br>{@code <extensions defaultExtensionNs="com.intellij">}
39  *   <br>{@code &nbsp;&nbsp;&nbsp;&nbsp;<projectConfigurable instance="fully.qualified.class.name"/>}
40  *   <br>{@code </extensions>}</dd>
41  *   <dt>{@link ConfigurableEP#providerClass provider}</dt>
42  *   <dd>This attribute can be used instead of the {@code instance} attribute.
43  *   It specifies a qualified name of a custom implementation of the {@link ConfigurableProvider} interface,
44  *   which provides another way to create a configurable component:
45  *   <br>{@code <extensions defaultExtensionNs="com.intellij">}
46  *   <br>{@code &nbsp;&nbsp;&nbsp;&nbsp;<projectConfigurable provider="fully.qualified.class.name"/>}
47  *   <br>{@code </extensions>}</dd>
48  *   <dt><strike>{@link ConfigurableEP#implementationClass implementation}</strike></dt>
49  *   <dd>This attribute is deprecated and replaced with two attributes above.
50  *   In fact, it works as the {@code instance} attribute.</dd>
51  *   <dt>{@link ConfigurableEP#nonDefaultProject nonDefaultProject}</dt>
52  *   <dd>This attribute is applicable to the {@code projectConfigurable} extension only.
53  *   If it is set to {@code true}, the corresponding project settings will be shown for a real project only,
54  *   not for the {@link com.intellij.openapi.project.ProjectManager#getDefaultProject() template project},
55  *   which provides default settings for all the new projects.</dd>
56  *   <dt>{@link ConfigurableEP#displayName displayName}</dt>
57  *   <dd>This attribute specifies the setting name visible to users.
58  *   If the display name is not set, a configurable component will be instantiated to retrieve its name dynamically.
59  *   This causes a loading of plugin classes and increases the delay before showing the settings dialog.
60  *   It is highly recommended specifying the display name in XML to improve UI responsiveness.</dd>
61  *   <dt>{@link ConfigurableEP#key key} and {@link ConfigurableEP#bundle bundle}</dt>
62  *   <dd>These attributes specify the display name too, if the specified key is declared in the specified resource bundle.</dd>
63  *   <dt>{@link ConfigurableEP#id id}</dt>
64  *   <dd>This attribute specifies the {@link SearchableConfigurable#getId() unique identifier}
65  *   for the configurable component.  It is also recommended specifying the identifier in XML.</dd>
66  *   <dt>{@link ConfigurableEP#parentId parentId}</dt>
67  *   <dd>This attribute is used to create a hierarchy of settings.
68  *   If it is set, the configurable component will be a child of the specified parent component.</dd>
69  *   <dt>{@link ConfigurableEP#groupId groupId}</dt>
70  *   <dd>This attribute specifies a top-level group, which the configurable component belongs to.
71  *   If this attribute is not set, the configurable component will be added to the Other Settings group.
72  *   The following groups are supported:
73  *   <dl>
74  *     <dt>ROOT {@code groupId="root"}</dt>
75  *     <dd>This is the invisible root group that contains all other groups.
76  *     Usually, you should not place your settings here.</dd>
77  *     <dt>Appearance & Behavior {@code groupId="appearance"}</dt>
78  *     <dd>This group contains settings to personalize IDE appearance and behavior:
79  *     change themes and font size, tune the keymap, and configure plugins and system settings,
80  *     such as password policies, HTTP proxy, updates and more.</dd>
81  *     <dt>Editor {@code groupId="editor"}</dt>
82  *     <dd>This group contains settings to personalize source code appearance by changing fonts,
83  *     highlighting styles, indents, etc.  Here you can customize the editor from line numbers,
84  *     caret placement and tabs to source code inspections, setting up templates and file encodings.</dd>
85  *     <dt>Default Project / Project Settings {@code groupId="project"}</dt>
86  *     <dd>This group is intended to store some project-related settings, but now it is rarely used.</dd>
87  *     <dt>Build, Execution, Deployment {@code groupId="build"}</dt>
88  *     <dd>This group contains settings to configure you project integration with the different build tools,
89  *     modify the default compiler settings, manage server access configurations, customize the debugger behavior, etc.</dd>
90  *     <dt>Build Tools {@code groupId="build.tools"}</dt>
91  *     <dd>This is subgroup of the group above. Here you can configure your project integration
92  *     with the different build tools, such as Maven, Gradle, or Gant.</dd>
93  *     <dt>Languages & Frameworks {@code groupId="language"}</dt>
94  *     <dd>This group is intended to configure the settings related to specific frameworks and technologies used in your project.</dd>
95  *     <dt>Tools {@code groupId="tools"}</dt>
96  *     <dd>This group contains settings to configure integration with third-party applications,
97  *     specify the SSH Terminal connection settings, manage server certificates and tasks, configure diagrams layout, etc.</dd>
98  *     <dt>Other Settings {@code groupId="other"}</dt>
99  *     <dd>This group contains settings that are related to non-bundled custom plugins and are not assigned to any other category.</dd>
100  *   </dl>
101  *   The {@code parentId} and the {@code groupId} attributes should not be used together and the {@code parentId} has precedence.
102  *   Currently, it is possible to specify a group identifier in the {@code parentId} attribute.</dd>
103  *   <dt>{@link ConfigurableEP#groupWeight groupWeight}</dt>
104  *   <dd>This attribute specifies the weight of a configurable component within a group or a parent configurable component.
105  *   The default weight is {@code 0}. If one child in a group or a parent configurable component has non-zero weight,
106  *   all children will be sorted descending by their weight. And if the weights are equal,
107  *   the components will be sorted ascending by their display name.</dd>
108  *   <dt>{@link ConfigurableEP#dynamic dynamic}</dt>
109  *   <dd>This attribute states that a custom configurable component implements the {@link Composite} interface
110  *   and its children are dynamically calculated by calling the {@code getConfigurables} method.
111  *   It is needed to improve performance, because we do not want to load any additional classes during the building a setting tree.</dd>
112  *   <dt>{@link ConfigurableEP#childrenEPName childrenEPName}</dt>
113  *   <dd>This attribute specifies a name of the extension point that will be used to calculate children.</dd>
114  *   <dt>{@link ConfigurableEP#children configurable}</dt>
115  *   <dd>This is not an attribute, this is an inner tag. It specifies children directly in the main tag body. For example,
116  *   <br>{@code <projectConfigurable id="tasks" nonDefaultProject="true" instance="com.intellij.tasks.config.TaskConfigurable">}
117  *   <br>{@code &nbsp;&nbsp;&nbsp;&nbsp;<configurable id="tasks.servers" instance="com.intellij.tasks.config.TaskRepositoriesConfigurable"/>}
118  *   <br>{@code </projectConfigurable>}
119  *   <br>is similar to the following declarations
120  *   <br>{@code <projectConfigurable id="tasks" nonDefaultProject="true" instance="com.intellij.tasks.config.TaskConfigurable"/>}
121  *   <br>{@code <projectConfigurable parentId="tasks" id="tasks.servers" nonDefaultProject="true" instance="com.intellij.tasks.config.TaskRepositoriesConfigurable"/>}</dd>
122  * </dl>
123  *
124  * @see ConfigurableEP
125  * @see SearchableConfigurable
126  * @see ShowSettingsUtil
127  */
128 public interface Configurable extends UnnamedConfigurable {
129   ExtensionPointName<ConfigurableEP<Configurable>> APPLICATION_CONFIGURABLE = new ExtensionPointName<>("com.intellij.applicationConfigurable");
130   ProjectExtensionPointName<ConfigurableEP<Configurable>> PROJECT_CONFIGURABLE = new ProjectExtensionPointName<>("com.intellij.projectConfigurable");
131
132   /**
133    * Returns the visible name of the configurable component.
134    * Note, that this method must return the display name
135    * that is equal to the display name declared in XML
136    * to avoid unexpected errors.
137    *
138    * @return the visible name of the configurable component
139    */
140   @NlsContexts.ConfigurableName
141   @Contract(pure = true)
142   String getDisplayName();
143
144   /**
145    * Returns the topic in the help file which is shown when help for the configurable is requested.
146    *
147    * @return the help topic, or {@code null} if no help is available
148    */
149   @Nullable
150   @NonNls
151   @Contract(pure = true)
152   default String getHelpTopic() {
153     return null;
154   }
155
156   /**
157    * This interface represents a configurable component that has child components.
158    * It is not recommended to use this approach to specify children of a configurable component,
159    * because it causes loading additional classes during the building a setting tree.
160    * Use XML attributes instead if possible.
161    */
162   @FunctionalInterface
163   interface Composite {
164     Configurable @NotNull [] getConfigurables();
165   }
166
167   /**
168    * This marker interface notifies the Settings dialog to not add scroll bars to the Swing form.
169    * Required when the Swing form contains its own scrollable components.
170    */
171   interface NoScroll {
172     // see ConfigurableCardPanel#create(Configurable)
173   }
174
175   /**
176    * This marker interface notifies the Settings dialog to not add an empty border to the Swing form.
177    * Required when the Swing form is a tabbed pane.
178    */
179   interface NoMargin {
180     // see ConfigurableCardPanel#create(Configurable)
181   }
182
183   /**
184    * Allows to dynamically define if current configurable settings apply to current project or to the IDE and update "For current project"
185    * indicator accordingly.
186    */
187   interface VariableProjectAppLevel {
188     /**
189      * @return True if current settings apply to the current project (enable "For current project" indicator), false for application-level
190      *         (IDE) settings.
191      */
192     boolean isProjectLevel();
193   }
194
195   /**
196    * The interface is used for configurable that depends on some dynamic extension points.
197    * If a configurable implements the interface by default the configurable will re-created after adding / removing extensions for the EP.
198    *
199    * Examples: postfix template configurable. If we have added a plugin with new postfix templates we have to re-create the configurable
200    * (but only if the content of the configurable was loaded)
201    *
202    * @apiNote if the configurable is not marked as dynamic=true it must not initialize EP-depend resources in the constructor. 
203    * This interface also can be used with {@link ConfigurableProvider}.
204    * 
205    */
206   interface WithEpDependencies {
207     /**
208      * @return EPName-s that affect the configurable or configurable provider
209      */
210     @NotNull
211     Collection<BaseExtensionPointName<?>> getDependencies();
212   }
213
214   default boolean isModified(@NotNull JTextField textField, @NotNull String value) {
215     return !StringUtil.equals(textField.getText().trim(), value);
216   }
217
218   default boolean isModified(@NotNull JTextField textField, int value, @NotNull UINumericRange range) {
219     try {
220       int currentValue = Integer.parseInt(textField.getText().trim());
221       return range.fit(currentValue) == currentValue && currentValue != value;
222     }
223     catch (NumberFormatException e) {
224       return false;
225     }
226   }
227
228   default boolean isModified(@NotNull JToggleButton toggleButton, boolean value) {
229     return toggleButton.isSelected() != value;
230   }
231
232   default <T> boolean isModified(@NotNull ComboBox<T> comboBox, T value) {
233     return !Comparing.equal(comboBox.getSelectedItem(), value);
234   }
235
236   /**
237    * @return component which should be focused when the dialog appears
238    *         on the screen.
239    */
240   default JComponent getPreferredFocusedComponent() {
241     return null;
242   }
243
244   interface TopComponentController {
245     TopComponentController EMPTY = new TopComponentController() {
246       @Override
247       public void setLeftComponent(@Nullable Component component) {}
248
249       @Override
250       public void showProgress(boolean start) {}
251     };
252
253     void setLeftComponent(@Nullable Component component);
254
255     void showProgress(boolean start);
256   }
257
258   interface TopComponentProvider {
259     default boolean isAvailable() {
260       return true;
261     }
262
263     @NotNull
264     Component getCenterComponent(@NotNull TopComponentController controller);
265   }
266 }