Merge branch 'link-eldar'

topics/ui/Principles.md

@@ -8,3 +8,4 @@
 - [](platform_theme_colors.md)
 - [](typography.md)
 - [](validation_errors.md)
+- [](Window-sizes.md)

topics/ui/controls/link.md

@@ -10,127 +10,297 @@
 
 </tldr>
 
-![](01_link_example.png){width=120}
+![A preview of link types: default, drop-down, and external.](link.png){width=706}
 
 ## When to use
 
-Use a regular link for navigation between pages of the same window.
+### Navigation inside a window
 
-![](02_deployment_server.png){width=494}
+Use a regular link for navigation between pages of the same window. In the example bellow <control>Manage scopes…</control> opens another page in Settings for editing the values.
 
-*This option is in the Settings dialog. "Configure servers" opens another page of the same dialog.*
+<table style="none" border="false">
+  <tr>
+    <td>
+        <format color="369650" style="bold">Correct</format>
+        <img src="link_when_to_1_correct.png" width="378" alt="A vertical list of three options: 'Non-Project Files', 'Problems', and 'Production', followed by a 'Manage scopes…' link below."/>
+    </td>
+    <td>
+        <format color="E55765" style="bold">Incorrect</format>
+        <img src="link_when_to_1_incorrect.png" width="378" alt="A vertical list of three options: 'Non-Project Files', 'Problems', and 'Production', followed 'Manage scopes' button below."/>
+    </td>
+  </tr>
+</table>
 
-![](03_manage_scopes.png){width=411}
+### Web resources
-
-*Do not use a button to navigate to another page of the same window.*
 
 Use an external link for navigation to web resources. See below for the [external link icon](#external-link-icon).
 
-![](04_external_link.png){width=248}
+![Text 'Learn more about what is logged' with 'what is logged' as an external link with an arrow icon.](link_when_to_2.png){width=706}
+
+### Secondary actions in packed UI areas
 
 Use a regular or [drop-down link](#drop-down-link) for secondary actions in packed or small UI areas.
 
-![](05_action_regular_link.png){width=367}
 
-*The "Reset" action is a link for two reasons: (1) The action appears only when the default value in the field is changed and reverting to a default is considered a rare scenario. (2) A lightweight link fits better than a button in this busy layout.*
+![Build and run section with 'Modify options' drop-down link. Contains a Java SDK selector, a command line arguments selector, and a program arguments input.](link_when_to_4.png){width=706}
 
-![](06_action_dropdown.png){width=550}
+### Secondary actions in a tree or table
 
-*The "Modify options" drop-down link fits into the top right corner of a busy layout.*
+#### Some items can be changed
 
-Do <control>not</control> use links for primary actions or when a UI is not constrained.
+Use a link as a secondary action for some items of a tree or table.
-Use a [button](button.topic) or a [drop down list](drop_down.md) instead.
+
+![A tree with a checkbox and four dependent controls, and links 'Set…' in the first and the fourth control](link_when_to_5.png){width=706}
+
+#### All items can be changed
+
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+        <img src="link_when_to_6_1.png" width="378" alt="Table with a toolbar with icon buttons"/>
+    </td>
+    <td>
+        <p>Add an <a href="icon_button.md">icon button</a> to a toolbar.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="378">
+        <img src="link_when_to_6_2.png" width="378" alt="Table with a toolbar with icon buttons"/>
+    </td>
+    <td>
+        <p>For a list of choices, add a separate table column of drop-down cells (see <a href="table.md" anchor="editing-values">Table</a>).</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="378">
+        <img src="link_when_to_6_3.png" width="378" alt="Links in the Push Commits window 'origin : master'"/>
+    </td>
+    <td>
+        <p>If a link in every tree or table line has meaningful formatting, leave it.</p>
+        <p>For example, links in the <control>Push Commits</control> window help understand the relation between them: <control>[remote repository] : [branch]</control>; moving these links elsewhere would break this meaning.</p>
+    </td>
+  </tr>
+</table>
+
+<table style="none" border="false">
+  <tr>
+    <td>
+        <format color="369650" style="bold">Correct</format>
+        <img src="link_when_to_6_correct.png" width="378" alt="Table with a toolbar with icon-buttons"/>
+    </td>
+    <td>
+        <format color="E55765" style="bold">Incorrect</format>
+        <img src="link_when_to_6_incorrect.png" width="378" alt="Table with a link 'Edit…' in every row"/>
+    </td>
+  </tr>
+</table>
+
+## When not to use
+
+### Primary actions
+
+Use a [button](button.topic) or a [drop down list](drop_down.md) for primary actions. These controls can be selected from the keyboard and are bigger and easier to click.
+
+<table style="none" border="false">
+  <tr>
+    <td>
+        <format color="369650" style="bold">Correct</format>
+        <img src="link_when_not_to_1_correct.png" width="378" alt="The Commit Message input with primary and secondary actions as buttons."/>
+    </td>
+    <td>
+        <format color="E55765" style="bold">Incorrect</format>
+        <img src="link_when_not_to_1_incorrect.png" width="378" alt="The Commit Message input with primary and secondary actions as links."/>
+    </td>
+  </tr>
+</table>
+
+### Simple UI
+
+Use a [button](button.topic) or a [drop down list](drop_down.md) when a UI is not constrained.
 These controls can be selected from the keyboard and are bigger and easier to click.
 
-![](07_android_sdk.png){width=451}
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="369650" style="bold">Correct</format>
+      <img src="link_when_not_to_2_correct.png" width="706" alt="A stack of controls with a button 'Edit' following one of the controls."/>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="link_when_not_to_2_incorrect.png" width="706" alt="A stack of controls with a link 'Edit' following one of the controls."/>
+    </td>
+  </tr>
+</table>
 
 ## How to use
 
 ### Writing guidelines
 
-Use sentence capitalization.
+#### Use sentence capitalization
 
-Add an ellipsis to a button-link if it opens another UI area where input is possible. See examples for the [Button](button.topic).
+Follow the [sentence capilaziation](capitalization.md#sentence) guideline.
 
-Do not use words like "navigate" or "click here". A link already implies navigation or clicking.
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="369650" style="bold">Correct</format>
+      <img src="link_how_to_1_correct.png" width="378" alt="A 'Modify options' drod-down with the sentence style capitalization."/>
+    </td>
+    <td>
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="link_how_to_1_incorrect.png" width="378" alt="A 'Modify Options' drod-down with the title style capitalization."/>
+    </td>
+  </tr>
+</table>
 
-![](08_writing_1.png){width=398}
+#### Ellipsis
 
-When possible, replace "Learn more" and other generic phrases with more informative ones.
+Add an ellipsis to a link if it opens another UI area where input is possible. See examples for the [Button](button.topic).
 
-![](08_writing_2.png){width=316}
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="369650" style="bold">Correct</format>
+      <img src="link_how_to_2_correct.png" width="378" alt="A vertical list of three options: 'Non-Project Files', 'Problems', and 'Production', followed by a 'Manage scopes…' link below. The link has an ellipsis in the end."/>
+    </td>
+    <td>
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="link_how_to_2_incorrect.png" width="378" alt="Vertical list of three options: 'Non-Project Files', 'Problems', and 'Production', followed by a 'Manage scopes' link below. The link doesn't have an ellipsis in the end."/>
+    </td>
+  </tr>
+</table>
+
+#### Wording
+
+Do not use words like <code>navigate</code> or <code>click here</code>. A link already implies navigation or clicking.
+
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="369650" style="bold">Correct</format>
+      <img src="link_how_to_3_correct.png" width="378" alt="Link 'Proxy settings…'."/>
+    </td>
+    <td>
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="link_how_to_3_incorrect.png" width="378" alt="Link 'Navigate to general proxy settings'."/>
+    </td>
+  </tr>
+</table>
+
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="369650" style="bold">Correct</format>
+      <img src="link_how_to_4_correct.png" width="378" alt="Link 'Download drivers…'."/>
+    </td>
+    <td>
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="link_how_to_4_incorrect.png" width="378" alt="Text reading 'Click here to download drivers' where 'here' is a link."/>
+    </td>
+  </tr>
+</table>
+
+#### Make it informative
+
+When possible, replace <code>Learn more</code> and other generic phrases with more informative ones.
+
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="369650" style="bold">Correct</format>
+      <img src="link_how_to_5_correct.png" width="378" alt="Link 'How to use Closure Linter'."/>
+    </td>
+    <td>
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="link_how_to_5_incorrect.png" width="378" alt="Link 'Learn more'."/>
+    </td>
+  </tr>
+</table>
 
 ### Link as a part of text
 
-A link can be a part of a checkbox or radio button label or of any stand-alone text, like the text in an [empty state](empty_state.md) or in [context help](context_help.md).
+A link can be a part of a checkbox or radio button label or of any stand-alone text, like the text in an [empty state](empty_state.md) or in [context help](context_help.md):
 
-![](09_part_of_text_1.png){width=403}
+![Checkbox 'Use console font instead of the default font' where 'deafult font' is a link.](link_how_to_6.png){width=706}
 
-Make a link the minimum phrase that is enough to understand what will happen without reading the whole text.
+Make a link the minimum phrase that is enough to understand what will happen without reading the whole text:
 
-![](09_part_of_text_2.png){width=489}
+<table style="none" border="false">
-
+  <tr>
-### Link in a tree or table
+    <td>
-
+      <format color="369650" style="bold">Correct</format>
-Use a link as a secondary action for some items of a tree or table.
+      <img src="link_how_to_7_correct.png" width="378" alt="Text reading 'Learn more about what is logged' where 'what is logged' is a link."/>
-
+    </td>
-![](10_tree.png){width=387}
+    <td>
-
+      <format color="E55765" style="bold">Incorrect</format>
-If an action is needed for all items of a tree or table:
+      <img src="link_how_to_7_incorrect.png" width="378" alt="Link 'Learn more about what is logged'."/>
-
+    </td>
-* Add an [icon button](icon_button.md) to a toolbar.
+  </tr>
-* For a list of choices, add a separate table column of drop-down cells (see [Table](table.md#editing-values)).
+</table>
-* If a link in every tree or table line has meaningful formatting, leave it:
-  ![](11_table.png){width=342}
-  *Links in the "Push Commits" window have the format that helps understand the relation between them: "[remote repository] : [branch]". Moving these links elsewhere would break this meaning.*
 
 ### External link icon
 
-Always add the arrow icon for an external link. The icon shows that the user will switch to a browser and lose the current context.
+Add the arrow icon for an external link. The icon shows that the user will switch to a browser and lose the current context.
 
-![](04_external_link.png){width=248}
+![Text 'Learn more about what is logged' where 'what is logged' is an external link with the external link icon.](link_how_to_8.png){width=706}
-<tabs group="languages">
-<tab title="Kotlin" group-key="kotlin">
 
-```kotlin
+<chapter title="Implementation" collapsible="true">
-val externalLink = ActionLink("External link") {
-  BrowserUtil.browse("https://www.jetbrains.com")
-}.apply {
-  setExternalLinkIcon()
-}
-```
 
-</tab>
+  <tabs group="languages">
-<tab title="Java" group-key="java">
+    <tab title="Kotlin" group-key="kotlin">
 
-```java
+  ```kotlin
-ActionLink externalLink = new ActionLink(
+  val externalLink = ActionLink("External link") {
-    "External link",
+    BrowserUtil.browse("https://www.jetbrains.com")
-    event -> BrowserUtil.browse("https://www.jetbrains.com")
+  }.apply {
-);
+    setExternalLinkIcon()
-externalLink.setExternalLinkIcon();
+  }
-```
+  ```
+  </tab>
+  <tab title="Java" group-key="java">
 
-</tab>
+  ```java
-</tabs>
+  ActionLink externalLink = new ActionLink(
+      "External link",
+      event -> BrowserUtil.browse("https://www.jetbrains.com")
+  );
+  externalLink.setExternalLinkIcon();
+  ```
+  </tab>
+  </tabs>
 
-An exception is a help topic link in [empty states](empty_state.md).
+</chapter>
-The help icon already hints that this is an external help resource, so the arrow icon is unnecessary.
 
-![](12_external_link_no_icon.png){width=164}
+### Help icon
+
+Use the help icon in links in [empty states](empty_state.md) to indicate that this is an external help resource. The arrow icon in this case is unnecessary.
+
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="369650" style="bold">Correct</format>
+      <img src="link_how_to_9_correct.png" width="378" alt="Empty state in the Database tool window with an explanation text and a help source link 'Defining a database' with the help icon."/>
+    </td>
+    <td>
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="link_how_to_9_incorrect.png" width="378" alt="Empty state in the Database tool window with an explanation text and an external link 'Defining a database' with the external link icon."/>
+    </td>
+  </tr>
+</table>
 
 ### Drop-down link
 
-Drop-down links show a context menu or a popup.
+Drop-down links show a context menu or a popup. To implement, use [`DropDownLink`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/DropDownLink.kt).
-Use [`DropDownLink`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/DropDownLink.kt) to implement a drop-down link.
 
-![](13_drop_down_links.png){width=445}
+![Control 'Changes from 2 commits' where '2 commits' is a drop-down link opening a list of all commits](link_dropdown.png){width=706}
 
 ## Placement
 
-Lay out button-links as buttons and dropdown-links as combo boxes. See [Layout](layout.md).
+* For default links follow [layout of buttons and links](layout.md#buttons-and-links).
+* For drop-down links follow [layout of labeled controls](layout.md#labeled-input-controls).
 
 ## Built-in behavior
 
 A focused link is activated from the keyboard with <shortcut>Space</shortcut>.
-

topics/ui/text/inspections.md

@@ -66,7 +66,7 @@ Provide details, such as:
 
 * A link to the language or framework docs explaining the correct usage of the syntax or feature, if applicable.
 
-![](link.png){width=520}
+![](inpsections_link.png){width=520}
 
 * Two code samples: the code with a problem and the code that bypasses this problem. By comparing the good code and the bad code, users can work out what causes the problem and how to avoid it.
   For example, for <ui-path>Java | Probable bugs | 'equals()' called on array</ui-path> adding such an example helps to understand the inspection quicker: