As discussed in the Settings Guide, plugins can add Settings to IntelliJ Platform-based IDEs. The IDE displays the Settings in response to a user choosing . Custom Settings are displayed and function just like those native to the IDE.
Overview of Custom Settings Implementation
Using the SDK code sample
settings, this tutorial illustrates the steps to create custom Application-level Settings. Many IntelliJ Platform Settings implementations use fewer classes, but the
settings code sample factors the functionality into three classes for clarity:
AppSettingsConfigurableis analogous to a Controller in the MVC model - it interacts with the other two Settings classes and the IntelliJ Platform,
AppSettingsStateis like a Model because it stores the Settings persistently,
AppSettingsComponentis similar to a View because it displays and captures edits to the values of the Settings.
The AppSettingsState Class
AppSettingsState class persistently stores the custom Settings. It is based on the IntelliJ Platform Persistence Model.
Given a Light Service is not used, the persistent data class must be declared as a Service EP in the plugin.xml file. If these were Project Settings, the
com.intellij.projectService EP would be used. However, because these are Application Settings, the
com.intellij.applicationService EP is used with the fully qualified name (FQN) of the implementation class:
Creating the AppSettingState Implementation
As discussed in Implementing the PersistentStateComponent Interface,
AppSettingsState uses the pattern of implementing
@State annotation, located just above the class declaration, defines the data storage location. For
AppSettingsState, the data
name parameter is the FQN of the class. Using FQN is the best practice to follow, and is required if custom data gets stored in the standard project or workspace files.
storages parameter utilizes the
@Storage annotation to define a custom file name for the
AppSettingsState data. In this case, the file is located in the
options directory of the configuration directory for the IDE.
Persistent Data Fields
AppSettingState implementation has two public fields: a
String and a
boolean. Conceptually, these fields hold the name of a user, and whether that person is an IntelliJ IDEA user, respectively. See Implementing the State Class for more information about how
PersistentStateComponent serializes public fields.
The fields are so limited and straightforward for this class that encapsulation is not used for simplicity. All that's needed for functionality is to override the two methods called by the IntelliJ Platform when a new component state is loaded (
PersistentStateComponent.loadState()), and when a state is saved (
PersistentStateComponent for more information about these methods.
One static convenience method has been added -
AppSettingState.getInstance() - which allows
AppSettingsConfigurable to easily acquire a reference to
The AppSettingsComponent Class
The role of the
AppSettingsComponent is to provide a
JPanel for the custom Settings to the IDE Settings Dialog. The
JPanel, and is responsible for its lifetime. The
AppSettingsComponent is instantiated by
Creating the AppSettingsComponent Implementation
The constructor builds the
JPanel using the convenient
FormBuilder, and saves a reference to the
JPanel. The rest of the class are simple accessors and mutators to encapsulate the UI components used on the
The AppSettingsConfigurable Class
The methods of
AppSettingsConfigurable are called by the IntelliJ Platform, and
AppSettingsConfigurable in turn interacts with
Declaring the AppSettingsConfigurable
Creating the AppSettingsConfigurable Implementation
AppSettingsConfigurable class implements
Configurable interface. The class has one field to hold a reference to the
All the methods in this class are overrides of the methods in the
Configurable interface. Readers are encouraged to review the Javadoc comments for the
Configurable methods. Also review notes about IntelliJ Platform Interactions with
Testing the Custom Settings Plugin
After performing the steps described above, compile and run the plugin in a Development Instance to see the custom Settings available in the Settings Dialog. Open the IDE Settings by selecting. The settings are preloaded with the default values:
Now edit the settings values to "John Doe" and click the checkbox. Click on the OK button to close the Settings dialog and save the changes. Exit the Development Instance.
Open the file SdkSettingsPlugin.xml to see the Settings persistently stored. In this demonstration the file resides in code_samples/settings/build/idea-sandbox/config/options/, but see IDE Development Instances for the general Development Instance case, or Default IDE directories if you are testing the
settings plugin directly in an IDE.