From 14997068cb03dd91ecc4825c6049b49a3ff41f90 Mon Sep 17 00:00:00 2001 From: Sergey Malenkov Date: Wed, 8 Apr 2015 17:38:02 +0300 Subject: [PATCH] IDEA-132304 Update com.intellij.openapi.options.ConfigurableEP java doc --- .../openapi/options/Configurable.java | 8 +- .../openapi/options/ConfigurableEP.java | 106 +++++++++++++++++- 2 files changed, 106 insertions(+), 8 deletions(-) diff --git a/platform/platform-api/src/com/intellij/openapi/options/Configurable.java b/platform/platform-api/src/com/intellij/openapi/options/Configurable.java index dc57e298e7ce..5f7c5c9b99e1 100644 --- a/platform/platform-api/src/com/intellij/openapi/options/Configurable.java +++ b/platform/platform-api/src/com/intellij/openapi/options/Configurable.java @@ -59,12 +59,12 @@ import org.jetbrains.annotations.Nullable; *
This attribute specifies the setting name visible to users. * If the display name is not set, a configurable component will be instantiated to retrieve its name dynamically. * This causes a loading of plugin classes and increases the delay before showing the settings dialog. - * It is highly recommended specifiyng the display name in XML to improve UI responsiveness.
+ * It is highly recommended specifying the display name in XML to improve UI responsiveness. *
{@code key} and {@code bundle}
*
These attributes specify the display name too, if the specified key is declared in the specified resource bundle.
*
{@code id}
*
This attribute specifies the {@link SearchableConfigurable#getId() unique identifier} - * for the configurable component. It is also recommended specifiyng the identifier in XML.
+ * for the configurable component. It is also recommended specifying the identifier in XML. *
{@code parentId}
*
This attribute is used to create a hierarchy of settings. * If it is set, the configurable component will be a child of the specified parent component.
@@ -76,7 +76,7 @@ import org.jetbrains.annotations.Nullable; *
ROOT {@code groupId="root"}
*
This is the invisible root group that contains all other groups. * Usually, you should not place your settings here.
- *
Appearance & Behavior {@code groupId="appearance"}
+ *
Appearance & Behavior {@code groupId="appearance"}
*
This group contains settings to personalize IDE appearance and behavior: * change themes and font size, tune the keymap, and configure plugins and system settings, * such as password policies, HTTP proxy, updates and more.
@@ -92,7 +92,7 @@ import org.jetbrains.annotations.Nullable; *
Build Tools {@code groupId="build.tools"}
*
This is subgroup of the group above. Here you can configure your project integration * with the different build tools, such as Maven, Gradle, or Gant.
- *
Languages & Frameworks {@code groupId="language"}
+ *
Languages & Frameworks {@code groupId="language"}
*
This group is intended to configure the settings related to specific frameworks and technologies used in your project.
*
Tools {@code groupId="tools"}
*
This group contains settings to configure integration with third-party applications, diff --git a/platform/platform-api/src/com/intellij/openapi/options/ConfigurableEP.java b/platform/platform-api/src/com/intellij/openapi/options/ConfigurableEP.java index 6bcba2f80027..d075d0858553 100644 --- a/platform/platform-api/src/com/intellij/openapi/options/ConfigurableEP.java +++ b/platform/platform-api/src/com/intellij/openapi/options/ConfigurableEP.java @@ -33,6 +33,8 @@ import org.picocontainer.PicoContainer; import java.util.ResourceBundle; /** + * Declares a named component that enables to configure settings. + * * @author nik * @see Configurable */ @@ -40,12 +42,27 @@ import java.util.ResourceBundle; public class ConfigurableEP extends AbstractExtensionPointBean { private static final Logger LOG = Logger.getInstance("#com.intellij.openapi.options.ConfigurableEP"); + /** + * This attribute specifies the setting name visible to users. + * It has precedence over the pair of attributes {@link #key}-{@link #bundle}. + * If the display name is not set, a configurable component will be instantiated to retrieve its name dynamically. + * This causes a loading of plugin classes and increases the delay before showing the settings dialog. + * It is highly recommended specifying the display name in XML to improve UI responsiveness. + */ @Attribute("displayName") public String displayName; + /** + * This attribute specifies the resource key in the specified {@link #bundle}. + * This is another way to specify the {@link #displayName display name}. + */ @Attribute("key") public String key; + /** + * This attribute specifies the resource bundle that contains the specified {@link #key}. + * This is another way to specify the {@link #displayName display name}. + */ @Attribute("bundle") public String bundle; @@ -70,18 +87,27 @@ public class ConfigurableEP extends AbstractExten public ConfigurableEP[] children; /** - * Extension point of ConfigurableEP type to calculate children + * This attribute specifies a name of the extension point of {@code ConfigurableEP} type that will be used to calculate children. + * + * @see #dynamic */ @Attribute("childrenEPName") public String childrenEPName; /** - * Indicates that configurable has dynamically calculated children. - * {@link com.intellij.openapi.options.Configurable.Composite#getConfigurables()} will be called for such configurables. + * This attribute states that a custom configurable component implements the {@link Configurable.Composite} interface + * and its children are dynamically calculated by calling the {@link Configurable.Composite#getConfigurables()} method. + * It is needed to improve performance, because we do not want to load any additional classes during the building a setting tree. */ @Attribute("dynamic") public boolean dynamic; + /** + * This attribute is used to create a hierarchy of settings. + * If it is set, the configurable component will be a child of the specified parent component. + * + * @see #groupId + */ @Attribute("parentId") public String parentId; @@ -94,16 +120,66 @@ public class ConfigurableEP extends AbstractExten return children; } + /** + * This attribute specifies the {@link SearchableConfigurable#getId() unique identifier} of the configurable component. + * It is also recommended specifying the identifier in XML to improve UI responsiveness. + */ @Attribute("id") public String id; + /** + * This attribute specifies a top-level group, which the configurable component belongs to. + * If this attribute is not set, the configurable component will be added to the Other Settings group. + * The following groups are supported: + *
+ *
ROOT {@code groupId="root"}
+ *
This is the invisible root group that contains all other groups. + * Usually, you should not place your settings here.
+ *
Appearance & Behavior {@code groupId="appearance"}
+ *
This group contains settings to personalize IDE appearance and behavior: + * change themes and font size, tune the keymap, and configure plugins and system settings, + * such as password policies, HTTP proxy, updates and more.
+ *
Editor {@code groupId="editor"}
+ *
This group contains settings to personalize source code appearance by changing fonts, + * highlighting styles, indents, etc. Here you can customize the editor from line numbers, + * caret placement and tabs to source code inspections, setting up templates and file encodings.
+ *
Default Project / Project Settings {@code groupId="project"}
+ *
This group is intended to store some project-related settings, but now it is rarely used.
+ *
Build, Execution, Deployment {@code groupId="build"}
+ *
This group contains settings to configure you project integration with the different build tools, + * modify the default compiler settings, manage server access configurations, customize the debugger behavior, etc.
+ *
Build Tools {@code groupId="build.tools"}
+ *
This is subgroup of the group above. Here you can configure your project integration + * with the different build tools, such as Maven, Gradle, or Gant.
+ *
Languages & Frameworks {@code groupId="language"}
+ *
This group is intended to configure the settings related to specific frameworks and technologies used in your project.
+ *
Tools {@code groupId="tools"}
+ *
This group contains settings to configure integration with third-party applications, + * specify the SSH Terminal connection settings, manage server certificates and tasks, configure diagrams layout, etc.
+ *
Other Settings {@code groupId="other"}
+ *
This group contains settings that are related to non-bundled custom plugins and are not assigned to any other category.
+ *
+ * This attribute should not be used together with the {@link #parentId} attribute, which has precedence. + * Currently, it is possible to specify a group identifier in the {@link #parentId} attribute. + */ @Attribute("groupId") public String groupId; + /** + * This attribute specifies the weight of a configurable component within a group or a parent configurable component. + * The default weight is {@code 0}. If one child in a group or a parent configurable component has non-zero weight, + * all children will be sorted descending by their weight. And if the weights are equal, + * the components will be sorted ascending by their display name. + */ @Attribute("groupWeight") public int groupWeight; - /** Marks project level configurables that do not apply to the default project. */ + /** + * This attribute is applicable to the {@code projectConfigurable} extension only. + * If it is set to {@code true}, the corresponding project settings will be shown for a real project only, + * not for the {@link com.intellij.openapi.project.ProjectManager#getDefaultProject() template project}, + * which provides default settings for all the new projects. + */ @Attribute("nonDefaultProject") public boolean nonDefaultProject; @@ -114,10 +190,32 @@ public class ConfigurableEP extends AbstractExten /** * @deprecated use '{@link #instanceClass instance}' or '{@link #providerClass provider}' attribute instead */ + @Deprecated @Attribute("implementation") public String implementationClass; + + /** + * This attribute specifies a qualified name of a custom implementation of this interface. + * The constructor will be determined automatically from the tag name: + *
{@code } + *
{@code     } + *
{@code } + * + * @see #providerClass provider + */ @Attribute("instance") public String instanceClass; + + /** + * This attribute can be used instead of the {@link #instanceClass instance} attribute. + * It specifies a qualified name of a custom implementation of the {@link ConfigurableProvider} interface, + * which provides another way to create a configurable component: + *
{@code } + *
{@code     } + *
{@code } + * + * @see #instanceClass instance + */ @Attribute("provider") public String providerClass;