From a1a01e322f18ebd176c6c1c7805a5d0cbcda84da Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Tue, 8 Aug 2023 16:26:58 +0200 Subject: [PATCH] settings_guide.md: Improve Table of Attributes readability --- topics/reference_guide/settings_guide.md | 26 ++++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/topics/reference_guide/settings_guide.md b/topics/reference_guide/settings_guide.md index c4d04fde3..143913abe 100644 --- a/topics/reference_guide/settings_guide.md +++ b/topics/reference_guide/settings_guide.md @@ -80,24 +80,24 @@ This section provides some additional clarification of those comments. The attributes supported by `com.intellij.applicationConfigurable` EP and `com.intellij.projectConfigurable` EP are in the table below: -| Attribute |

Implementation

Basis

| Required |

Attribute

Value

| -|---------------------|----------------------------------------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `instance` | `Configurable` | Y [(1)](#attribute-notes) | FQN of implementation. See [](#the-configurable-interface) for more information. | -| `provider` | `ConfigurableProvider` | Y [(1)](#attribute-notes) | FQN of implementation. See [](#the-configurableprovider-class) for more information. | -| `nonDefaultProject` | `Configurable` | Y |

Applicable _only_ to the `com.intellij.projectConfigurable` (project Settings) EP.

`true` = show Settings for all projects _except_ the [default project](https://www.jetbrains.com/help/idea/configure-project-settings.html#new-default-settings).

`false` = show Settings for all projects.

| -| `displayName` |

`Configurable`

`ConfigurableProvider`

| Y [(2)](#attribute-notes) |

The non-localized Settings name visible to users, which is needed for the Settings dialog left-side menu.

For a _localized_ visible name omit `displayName` and use the `key` and `bundle` attributes.

| -| `key` and `bundle` |

`Configurable`

`ConfigurableProvider`

| Y [(2)](#attribute-notes) |

The [localization](localization_guide.md) key and bundle for the Settings name visible to users.

For non-localized visible names omit `key` and `bundle` and use `displayName`.

| -| `id` |

`Configurable`

`ConfigurableProvider`

| Y |

The unique, FQN identifier for this implementation.

The FQN should be based on the plugin `id` to ensure uniqueness.

| -| `parentId` |

`Configurable`

`ConfigurableProvider`

| Y |

This attribute is used to create a hierarchy of Settings. This component is declared one of the specified `parentId` component's children. Typically used for placing a Settings panel within the Settings Dialog menu. Acceptable values for `parentId` are given in [](#values-for-parent-id-attribute).

`groupId` is deprecated. [(3)](#attribute-notes)

| -| `groupWeight` |

`Configurable`

`ConfigurableProvider`

| N |

Specifies the weight (stacking order) of this component within the group of a parent configurable component. The default weight is 0, meaning lowest in the order.

If one child in a group or a parent component has non-zero weight, all children will be sorted descending by their weight. If the weights are equal, the components will be sorted ascending by their display name.

| -| `dynamic` | `Configurable.Composite` | N |

This component's children are dynamically calculated by calling the `getConfigurables()` method.

Not recommended because it requires loading additional classes while building a Settings tree. If possible, use XML attributes instead.

| -| `childrenEPName` | `Configurable` | N | Specifies the FQN name of the Extension Point that will be used to calculate the children of this component. | +| Attribute | Required |

Attribute

Value

|

Implementation

Basis

| +|---------------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------| +| `instance` | **yes** [(1)](#attribute-notes) | FQN of implementation. See [](#the-configurable-interface) for more information. | `Configurable` | +| `provider` | **yes** [(1)](#attribute-notes) | FQN of implementation. See [](#the-configurableprovider-class) for more information. | `ConfigurableProvider` | +| `nonDefaultProject` | **yes** |

Applicable _only_ to the `com.intellij.projectConfigurable` (project Settings) EP.

`true` = show Settings for all projects _except_ the [default project](https://www.jetbrains.com/help/idea/configure-project-settings.html#new-default-settings).

`false` = show Settings for all projects.

| `Configurable` | +| `displayName` | **yes** [(2)](#attribute-notes) |

The non-localized Settings name visible to users, which is needed for the Settings dialog left-side menu.

For a _localized_ visible name omit `displayName` and use the `key` and `bundle` attributes.

|

`Configurable`

`ConfigurableProvider`

| +| `key` and `bundle` | **yes** [(2)](#attribute-notes) |

The [localization](localization_guide.md) key and bundle for the Settings name visible to users.

For non-localized visible names omit `key` and `bundle` and use `displayName`.

|

`Configurable`

`ConfigurableProvider`

| +| `id` | **yes** |

The unique, FQN identifier for this implementation.

The FQN should be based on the plugin `id` to ensure uniqueness.

|

`Configurable`

`ConfigurableProvider`

| +| `parentId` | **yes** |

This attribute is used to create a hierarchy of Settings. This component is declared one of the specified `parentId` component's children. Typically used for placing a Settings panel within the Settings Dialog menu. Acceptable values for `parentId` are given in [](#values-for-parent-id-attribute).

`groupId` is deprecated. [(3)](#attribute-notes)

|

`Configurable`

`ConfigurableProvider`

| +| `groupWeight` | no |

Specifies the weight (stacking order) of this component within the group of a parent configurable component. The default weight is 0, meaning lowest in the order.

If one child in a group or a parent component has non-zero weight, all children will be sorted descending by their weight. If the weights are equal, the components will be sorted ascending by their display name.

|

`Configurable`

`ConfigurableProvider`

| +| `dynamic` | no |

This component's children are dynamically calculated by calling the `getConfigurables()` method.

Not recommended because it requires loading additional classes while building a Settings tree. If possible, use XML attributes instead.

| `Configurable.Composite` | +| `childrenEPName` | no | Specifies the FQN name of the Extension Point that will be used to calculate the children of this component. | `Configurable` | ##### Attribute Notes (1) Either `instance` or `provider` must be specified depending on the implementation. -(2) One of these attribute sets must be specified depending on whether the displayed Settings name is localized. +(2) Either `displayName` or `key` and `bundle` must be specified depending on whether the displayed Settings name is localized. (3) If both `groupId` and `parentId` are specified, a warning is logged. Also, see _default_ entry in [](#values-for-parent-id-attribute).