mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-27 16:57:49 +08:00
114 lines
6.2 KiB
Markdown
114 lines
6.2 KiB
Markdown
# Custom Settings Groups
|
|
|
|
<!-- Copyright 2000-2023 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
|
|
|
|
<link-summary>Defining groups of related settings.</link-summary>
|
|
|
|
As described in [](settings_guide.md#extension-points-for-settings), custom Settings can be declared as children of existing parent groups such as <ui-path>Tools</ui-path>.
|
|
These parent groups are the existing categories of Settings in the IntelliJ Platform-based IDE.
|
|
|
|
However, suppose the custom Settings are rich enough to require multiple levels?
|
|
For example, a custom Setting implementation has multiple sub-Settings implementations.
|
|
Extension Point declarations can create this kind of multilayer Settings hierarchy.
|
|
|
|
<include from="settings_guide.md" element-id="settings_ui_inspector"/>
|
|
|
|
## Extension Points for Parent-Child Settings Relationships
|
|
|
|
There are multiple ways of creating parent-child relationships in groups of Settings: in implementations, or Extension Point declarations.
|
|
However, there are performance penalties for creating these relationships in implementations because the objects must be instantiated to determine the relationships.
|
|
This section describes the syntax for declaring more complex parent-child relationships in `com.intellij.projectConfigurable` or `com.intellij.applicationConfigurable` EPs.
|
|
|
|
> An application configurable can be a parent of a project configurable.
|
|
>
|
|
{style="note"}
|
|
|
|
There are two ways of declaring parent-child relationships using the `com.intellij.projectConfigurable` EP or `com.intellij.applicationConfigurable` EP.
|
|
The first is to use separate EP declarations that are tied together by the value of one attribute.
|
|
The second method is to use nested declarations.
|
|
|
|
### Parent-Child Settings Using Separate EPs
|
|
|
|
One way of declaring a parent-child relationship is by using two separate declarations.
|
|
This form can be used regardless of whether the parent Settings declaration is in the same plugin.
|
|
If the `id` attribute of the parent is known, a plugin can add Settings as a child of that parent.
|
|
|
|
For example, below are two declarations for project Settings.
|
|
The first gets added to the `tools` group, and the second gets added to the `id` of the parent.
|
|
The `id` of the second, child `<projectConfigurable>` adds a suffix (`servers`) to the `id` of the parent.
|
|
|
|
```xml
|
|
<extensions defaultExtensionNs="com.intellij">
|
|
<projectConfigurable
|
|
parentId="tools"
|
|
id="com.intellij.sdk.tasks"
|
|
displayName="Tasks"
|
|
nonDefaultProject="true"
|
|
instance="com.intellij.sdk.TaskConfigurable"/>
|
|
|
|
<projectConfigurable
|
|
parentId="com.intellij.sdk.tasks"
|
|
id="com.intellij.sdk.tasks.servers"
|
|
displayName="Servers"
|
|
nonDefaultProject="true"
|
|
instance="com.intellij.sdk.TaskRepositoriesConfigurable"/>
|
|
</extensions>
|
|
```
|
|
|
|
See the [Attributes for Parent-Child Settings EPs](#attributes-for-parent-child-settings-eps) section for details about the suffix `id`.
|
|
|
|
### Parent-Child Settings Using Nested EPs
|
|
|
|
A shorthand for the separate declaration approach is using the `configurable` property.
|
|
This approach nests the child's Settings declaration within the `com.intellij.projectConfigurable` or `com.intellij.applicationConfigurable` EP.
|
|
|
|
When using `configurable` there isn't a `parentId` for the child because the nesting implies it.
|
|
As with using separate EP declarations, formatting restrictions are placed on the child's `id` attribute - the suffix (`servers`) gets added.
|
|
See the [](#attributes-for-parent-child-settings-eps) section.
|
|
|
|
The example below demonstrates a nested `configurable` declaration:
|
|
|
|
```xml
|
|
<extensions defaultExtensionNs="com.intellij">
|
|
<projectConfigurable
|
|
parentId="tools"
|
|
id="com.intellij.sdk.tasks"
|
|
displayName="Tasks"
|
|
nonDefaultProject="true"
|
|
instance="com.intellij.sdk.TaskConfigurable"/>
|
|
<configurable
|
|
id="com.intellij.sdk.tasks.servers"
|
|
displayName="Servers"
|
|
nonDefaultProject="true"
|
|
instance="com.intellij.sdk.TaskRepositoriesConfigurable"/>
|
|
</projectConfigurable>
|
|
</extensions>
|
|
```
|
|
|
|
Within the parent `<projectConfigurable>` EP declaration above, more `<configurable>` declarations could be added as sibling Settings.
|
|
|
|
### Attributes for Parent-Child Settings EPs
|
|
|
|
There is only one unique attribute when declaring a child Settings EP.
|
|
The other attributes are the same as discussed in [](settings_guide.md#settings-declaration-attributes).
|
|
|
|
For the child of a parent, the `id` attribute becomes compound:
|
|
|
|
| Attribute | Required | Value |
|
|
|:----------|:--------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| `id` | Y | <p>Compound FQN of implementation based on `com.intellij.openapi.options.Configurable` in the form: `XX.YY` where:</p><ul><li>`XX` - the parent Settings component FQN-based ID</li><li>`YY` - unique to the child among other siblings</li></ul> |
|
|
|
|
> All children share the parent's `id` as the basis of their own `id`.
|
|
> All children have an `id` suffix that is unique among their siblings.
|
|
|
|
## Implementations for Parent-Child Settings
|
|
|
|
Implementations can be based on [`Configurable`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/options/Configurable.java), [`ConfigurableProvider`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/options/ConfigurableProvider.java) or one of their subtypes.
|
|
For more information about creating Settings implementations, see [](settings_guide.md#implementations-for-settings-extension-points).
|
|
|
|
### Configurable Marker Interfaces
|
|
|
|
The `Configurable.Composite` interface indicates a configurable component has child components.
|
|
The preferred approach is to specify child components in the [EP declaration](#extension-points-for-parent-child-settings-relationships).
|
|
Using the `Composite` interface incurs the penalty of loading child classes while building the tree of Settings Swing components.
|