mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-28 01:07:49 +08:00
253 lines
23 KiB
HTML
253 lines
23 KiB
HTML
|
||
|
||
|
||
<!doctype html>
|
||
<html lang="en-US">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<title>Plugin Components / IntelliJ Platform SDK DevGuide</title>
|
||
<link rel="stylesheet" href="/intellij/sdk/docs/app/css/styles.min.css">
|
||
|
||
<!-- non-retina iPad pre iOS 7 -->
|
||
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-72x72.png" sizes="72x72">
|
||
|
||
<!-- retina iPhone pre iOS 7 -->
|
||
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-114x114.png" sizes="114x114">
|
||
|
||
<!-- retina iPad pre iOS 7 -->
|
||
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-144x144.png" sizes="144x144">
|
||
<link rel="apple-touch-icon-precomposed" sizes="144x144" href="/intellij/sdk/docs/apple-touch-icon-precomposed.png">
|
||
|
||
<!-- normal favicon -->
|
||
<link rel="shortcut icon" type="image/x-icon" href="/intellij/sdk/docs/favicon.ico">
|
||
<link rel="icon" type="image/png" href="/intellij/sdk/docs/favicon.png">
|
||
<link rel="stylesheet" href="/intellij/sdk/docs/styles/styles.css"></head>
|
||
<body data-id="basics/plugin_structure/plugin_components">
|
||
<div class="wrapper">
|
||
<section class="panel _nav">
|
||
<header class="panel__header">
|
||
<div class="container">
|
||
<form class="search-box">
|
||
<label for="search-box__input" class="search-box__label">
|
||
<input type="text" class="search-box__input" id="search-box__input" placeholder="Search IntelliJ Platform SDK DevGuide">
|
||
</label>
|
||
<div class="search-box__clear" title="Clear"></div>
|
||
</form>
|
||
</div>
|
||
</header>
|
||
<nav class="panel__content">
|
||
<div class="container _nav">
|
||
<menu class="nav-tree"></menu>
|
||
</div>
|
||
<div class="container _footer panel__footer">
|
||
<p><a href="https://youtrack.jetbrains.com/issues/IJSDK">Send feedback</a></p>
|
||
<p>© 2000–2016 <a href="//www.jetbrains.com">JetBrains</a> s.r.o.<br>
|
||
All rights reserved.</p>
|
||
</div>
|
||
</nav>
|
||
</section>
|
||
|
||
<main class="panel _main" role="main">
|
||
<header class="panel__header">
|
||
<div class="container">
|
||
<h3>IntelliJ Platform SDK DevGuide</h3>
|
||
|
||
<div class="shortcuts-switcher"><label for="switch-shortcuts">Keymap:</label><select id="switch-shortcuts" class="select _shortcuts" height="1">
|
||
<option data-group="primary" value="default" selected>Default</option>
|
||
<option data-group="primary" value="default_for_gnome">GNOME</option>
|
||
<option data-group="primary" value="default_for_kde">KDE</option>
|
||
<option data-group="primary" value="default_for_xwin">XWindow</option>
|
||
<option data-group="primary" value="emacs">Emacs</option>
|
||
<option data-group="primary" value="jbuilder">JBuilder</option>
|
||
<option data-group="primary" value="visual_studio">Visual Studio</option>
|
||
<option data-group="primary" value="netbeans_6.5">NetBeans 6.5</option>
|
||
<option data-group="primary" value="eclipse">Eclipse</option>
|
||
<option data-group="secondary" value="mac_os_x_10.5_">OS X 10.5+</option>
|
||
<option data-group="secondary" value="mac_os_x">OS X</option>
|
||
<option data-group="secondary" value="eclipse_mac_os_x">OS X Eclipse</option></select>
|
||
</div>
|
||
|
||
<div class="panel-trigger"></div>
|
||
</div>
|
||
</header>
|
||
<section class="panel__content">
|
||
<div class="container">
|
||
<article class="article" data-shortcut-switcher="false">
|
||
|
||
<h1>Plugin Components</h1>
|
||
<p>Components are the fundamental concept of plugin integration. There are three kinds of components:</p>
|
||
|
||
<ul>
|
||
<li><strong>Application level components</strong> are created and initialized when your IDE starts up. They can be acquired from the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/application/Application.java" data-bypass="yes" target="_blank"><span>Application</span></a> instance by using the <code class="code highlight language-text">getComponent(Class)</code> method.</li>
|
||
<li><strong>Project level components</strong> are created for each <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java" data-bypass="yes" target="_blank"><span><code class="code highlight language-text">Project</code></span></a> instance in the IDE. (Please note that components may be created even for unopened projects.) They can be acquired from the <code class="code highlight language-text">Project</code> instance by using the <code class="code highlight language-text">getComponent(Class)</code> method.</li>
|
||
<li><strong>Module level components</strong> are created for each <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java" data-bypass="yes" target="_blank"><span><code class="code highlight language-text">Module</code></span></a> inside every project loaded in the IDE.
|
||
Module level components can be acquired from a <code class="code highlight language-text">Module</code> instance with the <code class="code highlight language-text">getComponent(Class)</code> method.</li>
|
||
</ul>
|
||
|
||
<p>Every component should have interface and implementation classes specified in the configuration file. The interface class will be used for retrieving the component from other components, and the implementation class will be used for component instantiation.</p>
|
||
|
||
<p>Note that two components of the same level (<a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/application/Application.java" data-bypass="yes" target="_blank"><span>Application</span></a>, <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java" data-bypass="yes" target="_blank"><span>Project</span></a> or <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java" data-bypass="yes" target="_blank"><span>Module</span></a>) cannot have the same interface class. The same class may be specified for both interface and Implementation.</p>
|
||
|
||
<p>Each component has a unique name which is used for its externalization and other internal needs. The name of a component is returned by its <code class="code highlight language-text">getComponentName()</code> method.</p>
|
||
|
||
<a name="components-naming-notation" class="elem-anchor"></a>
|
||
<h2>Components naming notation<a href="#components-naming-notation" class="anchor-link"><span></span></a></h2>
|
||
|
||
<p>It is recommended to name components in the form <code class="code highlight language-text"><plugin_name>.<component_name></code>.</p>
|
||
|
||
<a name="application-level-components" class="elem-anchor"></a>
|
||
<h2>Application level components<a href="#application-level-components" class="anchor-link"><span></span></a></h2>
|
||
|
||
<p>Optionally, an application level component’s implementation class may implement the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java" data-bypass="yes" target="_blank"><span>ApplicationComponent</span></a> interface.</p>
|
||
|
||
<p>An application component that has no dependencies should have a constructor with no parameters which will be used for its instantiation. If an application component depends on other application components, it can specify these components as constructor parameters. The <em>IntelliJ Platform</em> will ensure that the components are instantiated in the correct order to satisfy the dependencies.</p>
|
||
|
||
<p>Note that application level components must be registered in the <code class="code highlight language-text"><application-components></code> section of the plugin.xml file (see <a href="plugin_configuration_file.html"><span>Plugin Configuration File</span></a>).</p>
|
||
|
||
<a name="quick-creation-of-application-components" class="elem-anchor"></a>
|
||
<h3>Quick creation of application components<a href="#quick-creation-of-application-components" class="anchor-link"><span></span></a></h3>
|
||
|
||
<p>The <em>IntelliJ Platform</em> suggests a simplified way to create application components, with all the required infrastructure.</p>
|
||
|
||
<p>The IntelliJ Platform interface will help you declare the application component’s implementation class, and will automatically make appropriate changes to the <code class="code highlight language-text"><application-components></code> section of the <code class="code highlight language-text">plugin.xml</code> file.</p>
|
||
|
||
<p><strong>To create and register an application component:</strong></p>
|
||
|
||
<ol>
|
||
<li>In your project, open the context menu of the destination package and click <em>New</em> (or press <kbd>Alt</kbd>+<kbd>Insert</kbd>).</li>
|
||
<li>In the <em>New</em> menu, click <em>Application Component</em>.</li>
|
||
<li>In the <em>New Application Component</em> dialog box that opens, enter the application component name, and then click <em>OK</em>.</li>
|
||
</ol>
|
||
|
||
<p>The <em>IntelliJ Platform</em> will generate a new Java class that implements the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java" data-bypass="yes" target="_blank"><span>ApplicationComponent</span></a> interface. First register the newly created component in the <code class="code highlight language-text">plugin.xml</code> file, then add a node to the module tree view; and open the created application component class file in the editor.</p>
|
||
|
||
<a name="project-level-components" class="elem-anchor"></a>
|
||
<h2>Project level components<a href="#project-level-components" class="anchor-link"><span></span></a></h2>
|
||
|
||
<p>A project level component’s implementation class may implement the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java" data-bypass="yes" target="_blank"><span>ProjectComponent</span></a> interface.</p>
|
||
|
||
<p>The constructor of a project level component can have a parameter of the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java" data-bypass="yes" target="_blank"><span>Project</span></a> type, if it needs the project instance. It can also specify other application-level or project-level components as parameters, if it depends on those components.</p>
|
||
|
||
<p>Note that project level components must be registered in the <code class="code highlight language-text"><project-components></code> section of the <code class="code highlight language-text">plugin.xml</code> file (see <a href="plugin_configuration_file.html"><span>Plugin Configuration File</span></a>).</p>
|
||
|
||
<a name="quick-creation-of-project-components" class="elem-anchor"></a>
|
||
<h3>Quick creation of project components<a href="#quick-creation-of-project-components" class="anchor-link"><span></span></a></h3>
|
||
|
||
<p><!--TODO Link to demo source code -->
|
||
The <em>IntelliJ Platform</em> suggests a simplified way to create project components, with all the required infrastructure.</p>
|
||
|
||
<p>The IDEA interface will help you declare the project component’s implementation class, and will automatically make appropriate changes to the <code class="code highlight language-text"><project-components></code> section of the <code class="code highlight language-text">plugin.xml</code> file.</p>
|
||
|
||
<p><strong>To create and register a project component</strong></p>
|
||
|
||
<ol>
|
||
<li>In your project, open the context menu of the destination package and click <em>New</em> (or press <kbd>Alt</kbd>+<kbd>Insert</kbd>).</li>
|
||
<li>In the <em>New</em> menu, click <em>Project Component</em>.</li>
|
||
<li>In the <em>New Project Component</em> dialog box that opens, enter the project component name, and then click <em>OK</em>.</li>
|
||
</ol>
|
||
|
||
<p>The <em>IntelliJ Platform</em> will generate a new Java class that implements the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java" data-bypass="yes" target="_blank"><span>ProjectComponent</span></a> interface; register the newly created component in the <code class="code highlight language-text">plugin.xml</code> file; add a node to the module tree view; and open the created application component class file in the editor.</p>
|
||
|
||
<a name="module-level-components" class="elem-anchor"></a>
|
||
<h2>Module level components<a href="#module-level-components" class="anchor-link"><span></span></a></h2>
|
||
|
||
<p>Optionally, a module level component’s implementation class may implement the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java" data-bypass="yes" target="_blank"><span>ModuleComponent</span></a> interface.</p>
|
||
|
||
<p>The constructor of a module level component can have a parameter of the Module type, if it needs the module instance. It can also specify other application level, project level or module level components as parameters, if it depends on those components.</p>
|
||
|
||
<p>Note that module level components must be registered in the <code class="code highlight language-text"><module-components></code> section of the <code class="code highlight language-text">plugin.xml</code> file (see <a href="plugin_configuration_file.html"><span>Plugin Configuration File</span></a>).</p>
|
||
|
||
<a name="quick-creation-of-module-components" class="elem-anchor"></a>
|
||
<h3>Quick creation of module components<a href="#quick-creation-of-module-components" class="anchor-link"><span></span></a></h3>
|
||
|
||
<p>The <em>IntelliJ Platform</em> suggests a simplified way to create module components, with all the required infrastructure.</p>
|
||
|
||
<p>The IDEA interface will help you declare the module component’s implementation class, and will automatically make appropriate changes to the <code class="code highlight language-text"><module-components></code> section of the <code class="code highlight language-text">plugin.xml</code> file.</p>
|
||
|
||
<p><em>To create and register a module component</em></p>
|
||
|
||
<ol>
|
||
<li>In your project, open the context menu of the destination package and click <em>New</em> (or press <kbd>Alt</kbd>+<kbd>Insert</kbd>).</li>
|
||
<li>In the <em>New</em> menu, click <em>Module Component</em>.</li>
|
||
<li>In the <em>New Module Component</em> dialog box that opens, enter the module component name, and then click <em>OK</em>.</li>
|
||
</ol>
|
||
|
||
<p>The <em>IntelliJ Platform</em> will generate a new Java class that implements the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java" data-bypass="yes" target="_blank"><span>ModuleComponent</span></a> interface; register the newly created component in the <code class="code highlight language-text">plugin.xml</code> file; add a node to the module tree view; and open the created application component class file in the editor.</p>
|
||
|
||
<a name="persisting-the-state-of-components" class="elem-anchor"></a>
|
||
<h2>Persisting the state of components<a href="#persisting-the-state-of-components" class="anchor-link"><span></span></a></h2>
|
||
|
||
<p>The state of every component will be automatically saved and loaded if the component’s class implements the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java" data-bypass="yes" target="_blank"><span>JDOMExternalizable</span></a> (deprecated) or <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java" data-bypass="yes" target="_blank"><span>PersistentStateComponent</span></a> interface.</p>
|
||
|
||
<p>When the component’s class implements the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java" data-bypass="yes" target="_blank"><span>PersistentStateComponent</span></a> interface, the component state is saved in an XML file that you can specify using the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/components/State.java" data-bypass="yes" target="_blank"><span>@State</span></a> and <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/components/Storage.java" data-bypass="yes" target="_blank"><span>@Storage</span></a> annotations in your Java code.</p>
|
||
|
||
<p>When the component’s class implements the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java" data-bypass="yes" target="_blank"><span>JDOMExternalizable</span></a> interface, the components save their state in the following files:</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<p>Project level components save their state to the project (<code class="code highlight language-text">.ipr</code>) file.</p>
|
||
|
||
<p>However, if the workspace option in the <code class="code highlight language-text">plugin.xml</code> file is set to <code class="code highlight language-text">true</code>, the component saves its configuration to the workspace (<code class="code highlight language-text">.iws</code>) file instead.</p>
|
||
</li>
|
||
<li>
|
||
<p>Module level components save their state to the module (<code class="code highlight language-text">.iml</code>) file.</p>
|
||
</li>
|
||
</ul>
|
||
|
||
<p>For more information and samples, refer to <a href="/intellij/sdk/docs/basics/persisting_state_of_components.html"><span>Persisting State of Components</span></a>.</p>
|
||
|
||
<a name="defaults" class="elem-anchor"></a>
|
||
<h2>Defaults<a href="#defaults" class="anchor-link"><span></span></a></h2>
|
||
|
||
<p>The defaults (a component’s predefined settings) should be placed in the <code class="code highlight language-text"><component_name>.xml</code> file. Place this file in the plugin’s classpath in the folder corresponding to the default package. The <code class="code highlight language-text">readExternal()</code> method will be called on the <code class="code highlight language-text"><component></code> root tag.</p>
|
||
|
||
<p>If a component has defaults, the <code class="code highlight language-text">readExternal()</code> method is called twice:</p>
|
||
|
||
<ul>
|
||
<li>The first time for defaults</li>
|
||
<li>The second time for saved configuration</li>
|
||
</ul>
|
||
|
||
<a name="plugin-components-lifecycle" class="elem-anchor"></a>
|
||
<h2>Plugin components lifecycle<a href="#plugin-components-lifecycle" class="anchor-link"><span></span></a></h2>
|
||
|
||
<p>The components are loaded in the following order:</p>
|
||
|
||
<ul>
|
||
<li>Creation - constructor is invoked.</li>
|
||
<li>Initialization - the <code class="code highlight language-text">initComponent</code> method is invoked (if the component implements the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java" data-bypass="yes" target="_blank"><span>ApplicationComponent</span></a> interface).</li>
|
||
<li>Configuration - the <code class="code highlight language-text">readExternal</code> method is invoked (if the component implements <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java" data-bypass="yes" target="_blank"><span>JDOMExternalizable</span></a> interface), or the <code class="code highlight language-text">loadState</code> method is invoked (if the component implements <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java" data-bypass="yes" target="_blank"><span>PersistentStateComponent</span></a> and has non-default persisted state).</li>
|
||
<li>For module components, the <code class="code highlight language-text">moduleAdded</code> method of the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java" data-bypass="yes" target="_blank"><span>ModuleComponent</span></a> interface is invoked to notify that a module has been added to the project.</li>
|
||
<li>For project components, the <code class="code highlight language-text">projectOpened</code> method of the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java" data-bypass="yes" target="_blank"><span>ProjectComponent</span></a> interface is invoked to notify that a project has been loaded.</li>
|
||
</ul>
|
||
|
||
<p>The components are unloaded in the following order:</p>
|
||
|
||
<ul>
|
||
<li>Saving configuration - the <code class="code highlight language-text">writeExternal</code> method is invoked (if the component implements the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java" data-bypass="yes" target="_blank"><span>JDOMExternalizable</span></a> interface), or the <code class="code highlight language-text">getState</code> method is invoked (if the component implements PersistentStateComponent).</li>
|
||
<li>Disposal - the <code class="code highlight language-text">disposeComponent</code> method is invoked.</li>
|
||
</ul>
|
||
|
||
<p>Note that you should not request any other components using the <code class="code highlight language-text">getComponent()</code> method in the constructor of your component, otherwise you’ll get an assertion. If you need access to other components when initializing your component, you can specify them as constructor parameters or access them in the <code class="code highlight language-text">initComponent</code> method.</p>
|
||
|
||
|
||
<div class="last-modified">
|
||
Last modified: 30 November 2015
|
||
</div>
|
||
</article>
|
||
|
||
<section class="disqus">
|
||
<div id="disqus_thread"></div>
|
||
</section>
|
||
</div>
|
||
</section>
|
||
</main>
|
||
</div>
|
||
|
||
|
||
<script data-main="/intellij/sdk/docs/app/js/main.build" data-baseurl="/intellij/sdk/docs/" src="/intellij/sdk/docs/app/js/vendor/requirejs/require.js"></script>
|
||
|
||
</body>
|
||
</html>
|
||
|