hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-30 18:27:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'IJSDK-698'

Browse Source 
# Conflicts:
#	reference_guide/api_notable/api_notable_list_2020.md
This commit is contained in:
JohnHake 2020-03-17 18:51:49 -07:00
commit c55e6a72cc
14 changed files with 263 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
_SUMMARY.md
View File

@ -142,13 +142,14 @@
## Part V - Features
* Navigation
* Go To Symbol
* Editing
* [Editing](basics/editing.md)
* Code Completion
* Templates
* [Templates](basics/templates.md)
* [Live Templates](tutorials/live_templates.md)
* [1. Adding Live Template Support](tutorials/live_templates/template_support.md)
* [Adding Live Templates to a Plugin](tutorials/live_templates/template_support.md)
* [Creating New Functions for Live Templates](tutorials/live_templates/new_macros.md)
* Surround Templates
* File Templates
* Surround Templates
* QuickDoc
* [Intentions](tutorials/code_intentions.md)
* Analysing

9
basics/editing.md Normal file
View File

@ -0,0 +1,9 @@
---
title: Editing
---
<!-- Copyright 2000-2020 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. -->
* Code Completion
* [Templates](/basics/templates.md)
* QuickDoc
* [Intentions](/tutorials/code_intentions.md)

10
basics/templates.md Normal file
View File

@ -0,0 +1,10 @@
---
title: Templates
---
<!-- Copyright 2000-2020 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. -->
* [Live Templates](/tutorials/live_templates.md)
* [Adding Live Templates to a Plugin](/tutorials/live_templates/template_support.md)
* [Creating New Functions for Live Templates](/tutorials/live_templates/new_macros.md)
* Surround Templates
* File Templates

14
code_samples/live_templates/build.gradle
View File

@ -1,24 +1,24 @@
// Copyright 2000-2020 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.
plugins {
id 'java'
id 'org.jetbrains.intellij' version '0.4.16'
id 'java'
id 'org.jetbrains.intellij' version '0.4.16'
}
group 'org.intellij.sdk'
version '2.0.0'
version '2.1.0'
sourceCompatibility = 1.8
repositories {
mavenCentral()
mavenCentral()
}
// See https://github.com/JetBrains/gradle-intellij-plugin/
intellij {
version '2019.3.3'
updateSinceUntilBuild = false
version '201-EAP-SNAPSHOT'
sameSinceUntilBuild = true
}
patchPluginXml {
version = project.version
version = project.version
}

19
code_samples/live_templates/src/main/java/org/intellij/sdk/liveTemplates/MarkdownTemplateProvider.java
View File

@ -1,19 +0,0 @@
// Copyright 2000-2020 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.
package org.intellij.sdk.liveTemplates;
import com.intellij.codeInsight.template.impl.DefaultLiveTemplatesProvider;
import org.jetbrains.annotations.Nullable;
public class MarkdownTemplateProvider implements DefaultLiveTemplatesProvider {
@Override
public String[] getDefaultLiveTemplateFiles() {
return new String[]{"liveTemplates/Markdown"};
}
@Nullable
@Override
public String[] getHiddenLiveTemplateFiles() {
return null;
}
}

42
code_samples/live_templates/src/main/java/org/intellij/sdk/liveTemplates/TitleCaseMacro.java Normal file
View File

@ -0,0 +1,42 @@
// Copyright 2000-2020 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.
package org.intellij.sdk.liveTemplates;
import com.intellij.codeInsight.template.*;
import com.intellij.codeInsight.template.macro.MacroBase;
import com.intellij.openapi.util.text.StringUtil;
import org.jetbrains.annotations.NotNull;
public class TitleCaseMacro extends MacroBase {
public TitleCaseMacro() {
super("titleCase", "titleCase(String)");
}
/**
* Strictly to uphold contract for constructors in base class.
*/
private TitleCaseMacro(String name, String description) {
super(name, description);
}
@Override
protected Result calculateResult(@NotNull Expression[] params, ExpressionContext context, boolean quick) {
// Retrieve the text from the macro or selection, if any is available.
String text = getTextResult(params, context, true);
if (text != null) {
if (text.length() > 0) {
// Capitalize the start of every word
text = StringUtil.toTitleCase(text);
}
return new TextResult(text);
}
return null;
}
@Override
public boolean isAcceptableInContext(TemplateContextType context) {
// Might want to be less restrictive in future
return (context instanceof MarkdownContext);
}
}

11
code_samples/live_templates/src/main/resources/META-INF/plugin.xml
View File

@ -2,17 +2,12 @@
<idea-plugin>
<!-- Unique id for this plugin. Must stay constant for the life of the plugin. -->
<id>org.intellij.sdk.liveTemplates</id>
<!-- Text to display as name on Preferences/Settings | Plugin page -->
<name>SDK: Live Templates Sample Project</name>
<!-- The version of this plugin -->
<version>2.0.0</version>
<!-- Compatible with the following versions of IntelliJ Platform - needed for plugin logo -->
<idea-version since-build="191"/>
<!-- Product and plugin compatibility requirements -->
<depends>com.intellij.modules.lang</depends>
@ -25,6 +20,7 @@
<change-notes>
<![CDATA[
<ul>
<li><b>2.1.0</b> Use com.intellij.defaultLiveTemplates, add custom macro.</li>
<li><b>2.0.0</b> Convert to Gradle-based plugin, change plugin ID</li>
<li><b>1.0.0</b> Release 2018.3 and earlier.</li>
</ul>
@ -35,8 +31,9 @@
<vendor url="https://plugins.jetbrains.com">IntelliJ Platform SDK</vendor>
<extensions defaultExtensionNs="com.intellij">
<defaultLiveTemplatesProvider implementation="org.intellij.sdk.liveTemplates.MarkdownTemplateProvider"/>
<defaultLiveTemplates file="/liveTemplates/Markdown.xml"/>
<liveTemplateContext implementation="org.intellij.sdk.liveTemplates.MarkdownContext"/>
<liveTemplateMacro implementation="org.intellij.sdk.liveTemplates.TitleCaseMacro"/>
</extensions>
</idea-plugin>

14
code_samples/live_templates/src/main/resources/liveTemplates/Markdown.xml
View File

@ -1,7 +1,7 @@
<templateSet group="Markdown">
<template name="["
<template name="{"
value="[$TEXT$]($LINK$)$END$"
description="SDK: New link reference."
description="SDK: New link reference"
toReformat="false"
toShortenFQNames="false">
<variable name="TEXT" expression="" defaultValue="" alwaysStopAt="true"/>
@ -10,4 +10,14 @@
<option name="MARKDOWN" value="true"/>
</context>
</template>
<template name="mc"
value="$TITLE$"
description="SDK: Convert to title case"
toReformat="true"
toShortenFQNames="false">
<variable name="TITLE" expression="titleCase(SELECTION)" defaultValue="the quick brown fox" alwaysStopAt="true" />
<context>
<option name="MARKDOWN" value="true" />
</context>
</template>
</templateSet>

3
reference_guide/api_notable/api_notable_list_2020.md
View File

@ -29,6 +29,9 @@ Configurable status bar widgets
JCEF Support (_Experimental Feature_)
: Allows [embedding](/reference_guide/jcef.md) Chromium-based browser in the IDE.
[DefaultLiveTemplatesProvider](upsource:///platform/lang-impl/src/com/intellij/codeInsight/template/impl/DefaultLiveTemplatesProvider.java) is deprecated.
: Use extension point `com.intellij.defaultLiveTemplates` instead.
## Notable Changes in IntelliJ IDEA
EOL for JetBrains TFS Plugin

15
tutorials/live_templates.md
View File

@ -3,14 +3,21 @@ title: Live Templates
---
<!-- Copyright 2000-2020 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. -->
*Live templates* are customizable rules that allow developers to abbreviate repetitive patterns of text in the editor. When a user types the designated abbreviation followed by a configurable *expansion key* (usually `Tab`), the IDE will transform the preceding input sequence to its full-length output, and update the cursor position. For example, consider a `for` loop. Typically, the end user would need to type `for(int i = 0; i < 10; i++) {<Enter><Tab><Enter><Enter>}<Up>`. This pattern may be shortened to `fori<Tab>` and the remaining contents will be expanded, leaving the following structure:
*Live Templates* are customizable rules that allow developers to abbreviate repetitive patterns of text in the editor.
When a user types the designated abbreviation followed by a configurable *expansion key* (usually `Tab`), the IDE transforms the preceding input sequence to its full-length output, and update the cursor position.
For example, consider a `for` loop. Typically, the end user would need to type `for(int i = 0; i < 10; i++) {<Enter><Tab><Enter><Enter>}<Up>`.
This pattern may be shortened to `fori<Tab>` and the remaining contents will be expanded, leaving the following structure:
```
for(int i = [|]; i < []; i++) {
[]
}
```
As the user completes each section of the `for` loop and presses `Tab`, the cursor will advance to the next position in the editor. For more information about creating your own Custom Live Templates, you may refer to the [corresponding documentation](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html). In this tutorial, we will illustrate how to add default Custom Live Templates to an IntelliJ Platform plugin, and assign valid contexts where these templates can take on added functionality based on the surrounding code and file type. We will discuss how to export existing live templates, and bundle them within a plugin to give users added typing efficiency when using a custom language.
* [1. Create a new Live Template](live_templates/template_support.md)
As the user completes each section of the `for` loop and presses `Tab`, the cursor advances to the next position in the editor.
For more information about creating Custom Live Templates, refer to the [corresponding documentation](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html).
These sections describe how to add Live Templates, and their associated building blocks, to plugins.
* [Adding Live Templates to a Plugin](live_templates/template_support.md)
* [Creating New Functions for Live Templates](live_templates/new_macros.md)
* Surround Templates

BIN
tutorials/live_templates/img/applied_titleCase.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 114 KiB

BIN
tutorials/live_templates/img/invoke_titleCase.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 164 KiB

70
tutorials/live_templates/new_macros.md Normal file
View File

@ -0,0 +1,70 @@
---
title: Creating New Functions for Live Templates
---
<!-- Copyright 2000-2020 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. -->
The [Predefined Functions](https://www.jetbrains.com/help/idea/template-variables.html?s=quick#predefined_functions) are the building blocks for creating [Parameterized Templates and Surround Templates](https://www.jetbrains.com/help/idea/using-live-templates.html?s=quick#live_templates_types).
However, sometimes the Predefined Functions are not enough.
This tutorial illustrates how to add custom functions to an IntelliJ Platform plugin and make them available for use by Live Templates.
As an example, a function is created to convert a selection to Title Case.
Refer to the SDK code sample [`live_templates`](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/live_templates).
* bullet
{:toc}
## Implementing a New Function
Under the hood, the predefined functions for Live Templates are called _macros_.
A new custom function for Live Templates is implemented in `TitleCaseMacro`, which extends [`MacroBase`](upsource:///platform/lang-impl/src/com/intellij/codeInsight/template/macro/MacroBase.java).
Three `TitleCaseMacro` methods are of particular interest:
* The `TitleCaseMacro()` constructor passes the name and description of the macro to the parent constructor.
* The `isAcceptableInContext()` method tests whether the macro is available in the current context.
The test relies on the [`MarkdownContext`](template_support.md#implement-templatecontexttype) object previously defined in the `live_templates` plugin.
* The `calculateResult()` method gets invoked when the titleCase function is used in a Live Template.
The text to be capitalized is retrieved from the Live Template and converted to Title Case.
```java
{% include /code_samples/live_templates/src/main/java/org/intellij/sdk/liveTemplates/TitleCaseMacro.java%}
```
## Adding a Live Template
Using the procedures previously discussed for [Template Creation](template_support.md#template-creation) and [Export the Live Template](template_support.md#export-the-live-template), add a Live Template to the [Markdown.xml](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/live_templates/src/main/resources/liveTemplates) file for the plugin.
The XML representation of an example Live Template using the new `titleCase` function is listed below.
There is only one variable, `TITLE`.
The expression for `TITLE` evaluates to the `titleCase` function provided by the plugin.
The argument to the `titleCase` function is `SELECTION`, which tells the IntelliJ Platform to operate on the current selection.
```xml
<template name="mc"
value="$TITLE$"
description="SDK: Convert to title case"
toReformat="true"
toShortenFQNames="false">
<variable name="TITLE" expression="titleCase(SELECTION)" defaultValue="the quick brown fox" alwaysStopAt="true" />
<context>
<option name="MARKDOWN" value="true" />
</context>
</template>
```
## Register Extension Point
Using the `com.intellij.liveTemplateMacro` extension point, register the implementation with the IntelliJ Platform.
```xml
<extensions defaultExtensionNs="com.intellij">
<liveTemplateMacro implementation="org.intellij.sdk.liveTemplates.TitleCaseMacro"/>
</extensions>
```
## Check Plugin
Now verify the plugin is working correctly.
* Run the plugin in a Development Instance.
* Create a new file `testing.md` and enter several words in lower case.
* Highlight the text and enter <kbd>⌥⌘J</kbd> to open the Select Template popup.
Confirm that the _SDK: Convert to title case_ is available in the popup, and select it.
![Convert to title case](img/invoke_titleCase.png){:width="700px"}
Test that the Live Template works by entering <kbd>m</kbd> or <kbd>return</kbd>.
The text will change to have each word capitalized:
![Converted to title case](img/applied_titleCase.png){:width="700px"}

121
tutorials/live_templates/template_support.md
View File

@ -1,65 +1,122 @@
---
title: 1. Adding Live Template Support
title: Adding Live Templates to a Plugin
---
<!-- Copyright 2000-2020 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. -->
This tutorial illustrates how to add default Custom Live Templates to an IntelliJ Platform plugin, and assign valid contexts for these templates based on the surrounding code and file type.
In addition, the tutorial discusses how to export existing Live Templates, and bundle them within a plugin.
Any Live Template that can be created and exported can be added to a plugin by following the Template Creation, Export, and Extension Point Registration processes.
This tutorial uses the SDK code sample [`live_templates`](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/live_templates).
* bullet
{:toc}
## Template Creation
Initially, you will need to [create a new Live Template](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html#d1476224e158) from scratch. Add a new Template Group, "Markdown" and create a new Live Template under this group. Then give the template an abbreviation (ex. "[") and a description (ex. "New markdown link"). Paste the following snippet into the *Template text*:
```
Get started by [creating a new Live Template](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html) within the IntelliJ Platform-based IDE:
* Add a new Template Group, "Markdown" and create a new Live Template under this group.
* Assign the template the abbreviation "**{**".
* Assign the description "**SDK: New link reference**".
* Paste the following snippet into the *Template text* field:
```text
[$TEXT$]($LINK$)$END$
```
The variables `$TEXT$` and `$LINK$` may be further configured in the *Edit variables* dialogue, to reorder their precedence and bind to functions that will invoke auto-completion at the appropriate time, among many other [useful functions](https://www.jetbrains.com/idea/help/creating-and-editing-template-variables.html). Developers should become familiar with the provided functions before implementing any special functionality in a plugin, in case the desired feature is available as a [predefined function](https://www.jetbrains.com/idea/help/creating-and-editing-template-variables.html#predefined_functions).
The variables `$TEXT$` and `$LINK$` may be further configured in the *Edit variables* dialogue to reorder their precedence and bind to functions that invoke auto-completion at the appropriate time.
In the *Edit variables* dialog, set the `Expression` for the `LINK` to `complete()` using the combobox.
Finally, give your new Live Template an applicable context (ie. "Everywhere" or "Other").
There are many other [predefined functions](https://www.jetbrains.com/idea/help/creating-and-editing-template-variables.html) that developers should become familiar with before implementing any unique functionality in a plugin.
> **Tip** Consider iteratively testing the Live Template using the current editor and a markdown file to minimize debugging later.
## Export the Live Template
Once confident the Live Template produces the expected result (consider testing it inside the current editor to minimize debugging later), export the Live Template (**File \| Export Settings \| ☑ Live Templates**). Unpack the resulting archive, and inside a directory `./templates/` there will be a file called `Markdown.xml` with the following contents:
Once the Live Template produces the expected result, [export the Live Template](https://www.jetbrains.com/help/idea/sharing-live-templates.html).
The export produces a file called `Markdown.xml` with the following contents:
```xml
<templateSet group="Markdown">
<template name="[" value="[$TEXT$]($LINK$)$END$" description="New link reference." toReformat="false" toShortenFQNames="false">
<template name="{"
value="[$TEXT$]($LINK$)$END$"
description="SDK: New link reference"
toReformat="false"
toShortenFQNames="false">
<variable name="TEXT" expression="" defaultValue="" alwaysStopAt="true" />
<variable name="LINK" expression="complete()" defaultValue="" alwaysStopAt="true" />
<context>
<option name="OTHER" value="true" />
</context>
</template>
</templateSet>
```
Copy this file into your plugin's resources, (eg. `resources/liveTemplates/Markdown.xml`.
## Implement DefaultLiveTemplatesProvider
The [`DefaultLiveTemplatesProvider`](upsource:///platform/lang-impl/src/com/intellij/codeInsight/template/impl/DefaultLiveTemplatesProvider.java) tells us where to find the Live Template settings file. Make sure to include the full path to the file, relative to the resources directory, excluding the file name.
```java
{% include /code_samples/live_templates/src/main/java/org/intellij/sdk/liveTemplates/MarkdownTemplateProvider.java %}
```
Copy this file into the [plugin's resources folder](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/live_templates/src/main/resources/liveTemplates).
## Implement TemplateContextType
A [`TemplateContextType`](upsource:///platform/lang-api/src/com/intellij/codeInsight/template/TemplateContextType.java) tells us where the live template is applicable.
A [`TemplateContextType`](upsource:///platform/lang-api/src/com/intellij/codeInsight/template/TemplateContextType.java) tells the IntelliJ Platform where the Live Template is applicable: Markdown files.
Every context must have a unique `TemplateContextType` defined for it, and many context types are defined by the Platform.
The `MarkdownContext` class defines it for Markdown files.
Ultimately, a file's extension determines the applicable Markdown context.
```java
{% include /code_samples/live_templates/src/main/java/org/intellij/sdk/liveTemplates/MarkdownContext.java%}
```
Once you define the `TemplateContextType`, be sure to add the assigned context type to the previously created Live Template settings file. Under `<template>...</template>` add the following context:
> **Note** Once the `MarkdownContext` is defined, be sure to add the new context type to the previously created Live Template settings file.
Within the `<template>...</template>` elements in the `Markdown.xml` [Live Template definition file](#export-the-live-template), add the following context elements:
```xml
<context>
<option name="MARKDOWN" value=true />
</context>
<variable.../>
<context>
<option name="MARKDOWN" value="true"/>
</context>
</template>
```
It is not always necessary to define your own `TemplateContextType`, as there are many existing template contexts already defined in the IntelliJ Platform. Consider reusing one of the [many existing template contexts](upsource:///platform/lang-api/src/com/intellij/codeInsight/template/TemplateContextType.java) if you are augmenting language support to an existing area.
It is not always necessary to define your own `TemplateContextType`, as there are many existing template contexts already defined in the IntelliJ Platform.
Consider reusing one of the many existing template context types that inherit from `TemplateContextType` if you are augmenting language support to an existing area.
## Register Extension Points
## Completing the Live Template Implementation
Depending on the version of the IntelliJ Platform, different steps are used to complete the implementation of the feature.
### Versions 2020.1 and Later
For 2020.1 and later, follow this section to register the extension points and then proceed to the [Check Plugin](#check-plugin) section.
#### Register Extension Points
Using the `com.intellij.defaultLiveTemplates` and `com.intellij.liveTemplateContext` extension points, register the implementations with the IntelliJ Platform.
The `file` attribute in the `defaultLiveTemplates` element specifies `path/filename` under the `src/main/resources` folder.
```xml
<extensions defaultExtensionNs="com.intellij">
<defaultLiveTemplates file="/liveTemplates/Markdown.xml"/>
<liveTemplateContext implementation="org.intellij.sdk.liveTemplates.MarkdownContext"/>
</extensions>
```
Now go to the [Check Plugin](#check-plugin) section to test the template.
### Versions 2019.3 and Earlier
For older versions of the IntelliJ Platform follow this section to complete the implementation and register the extension points.
Then proceed to the [Check Plugin](#check-plugin) section.
#### Implement DefaultLiveTemplatesProvider
The `MarkdownTemplateProvider` tells the Platform where to find the Live Template settings file.
Make sure to include the full path to the file, relative to the `src/main/resources` directory, excluding the file extension.
```java
package org.intellij.sdk.liveTemplates;
import com.intellij.codeInsight.template.impl.DefaultLiveTemplatesProvider;
import org.jetbrains.annotations.Nullable;
public class MarkdownTemplateProvider implements DefaultLiveTemplatesProvider {
@Override
public String[] getDefaultLiveTemplateFiles() {
return new String[]{"liveTemplates/Markdown"};
}
@Nullable
@Override
public String[] getHiddenLiveTemplateFiles() {
return null;
}
}
```
#### Register Extension Points
Using the `com.intellij.defaultLiveTemplatesProvider` and `com.intellij.liveTemplateContext` extension points, register the implementations with the IntelliJ Platform.
```xml
<extensions defaultExtensionNs="com.intellij">
@ -69,4 +126,6 @@ Using the `com.intellij.defaultLiveTemplatesProvider` and `com.intellij.liveTemp
```
## Check Plugin
Now check that the plugin is working correctly. Run the plugin and verify there is a new entry under *File \| Settings \| Live Templates \| Markdown \| \[*. Finally, create a new file `Test.md` and confirm that the Live Template works.
Now verify the plugin is working correctly.
Run the plugin in a Development Instance and verify there is a new entry under **Settings/Preferenes \| Live Templates \| Markdown \| \{ (SDK: New link reference)**.
Finally, create a new file `Test.md` and confirm that the Live Template works by entering a <kbd>{</kbd> character and then pressing <kbd>Tab</kbd>.