built-in-button

topics/ui/controls/built_in_button.md

@@ -6,31 +6,19 @@
 
 A built-in button is an icon placed inside an input control.
 
-![](input_browse.png){width=250}
+![Built-in-button](built_in_button.png){width=706}
 
-## How to use
-
-Place the built-in button inside the input control. Do **not** place the built-in button on the right of a control:
-
-![](outside.png){width=250}
-
-To place a button inside a text field, use [`ExtendableTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/fields/ExtendableTextField.java) and
-its `addExtension()` method.
-
-The shortcut for a built-in button is <shortcut>Shift+Enter</shortcut>.
-
-## Types
+## When to use
 
 ### Browse
-
-A browse button opens a dialog with the disk, a tree view or a table of values.
-Use a control with the browse icon for a file/folder path selected from the disk.
-
-![](input_browse.png){width=378}
+The **Browse** button opens a dialog with the disk, a tree view, or a table of values.
+Use the **Browse** icon for a file/folder path selected from the disk:
+<img src="built_in_button_browse.png" alt="Browse" width="706"/>
 
 [//]: # (An input field with browse button: [`TextFieldWithBrowseButton`]&#40;%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/TextFieldWithBrowseButton.java&#41;)
 
-A combo box with browse button:
+<chapter collapsible="true" title="Code example">
+<p>A combo box with the <control>Browse</control> button:</p>
 <tabs group="languages">
 <tab title="Kotlin" group-key="kotlin">
 
@@ -79,44 +67,77 @@ extComboBox.setEditor(new BasicComboBoxEditor() {
 
 </tab>
 </tabs>
+</chapter>
 
-Do **not** place the button on the right of the control.
-
-![](browse_buttons.png){width=250}
 
-### Expand field
+### Expand a field
 
-If the input text can be long and place is constrained, use a built-in button to expand the control
+If the input text can be long and the place is constrained,
+use the **Expand** button to expand the control
 ([`ExpandableTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/fields/ExpandableTextField.java)):
 
-![](expandable_1.png){width=332}
+![Collapsed built-in button](built_in_button_collapsed.png){width=706}
 
-![](expandable_2.png){width=582}
+When the field is expanded, show the **Collapse** button:
+![Expanded built-in button](built_in_button_expanded.png){width=706}
 
-Do **not** use the Show Viewer button instead.
+### List values
 
-![](input_expand.png){width=357}
+Use the **List** icon to select a value from the list of classes, methods, or environment variables:
 
-### List values
+![List of values](built_in_button_list.png){width=706}
 
-Use a control with the table icon to select from the list of classes, methods or environment variables:
+### Add value
 
-![](input_table.png){width=250}
+The **Plus** button works the same way as the **[Browse](#browse)** button.
+The only difference is that the selected value is added instead of overwriting the existing one.
 
-Use a combo box instead of the Variables button. This icon works as a combo box.
+![Add a value to the field](built_in_button_add.png){width=706}
 
-![](variables_combobox.png){width=514}
+## How to use
 
-### Add value
+Place the built-in button inside the input field. Do not place the built-in button next to the field control:
+<table style="none" border="false">
+<tr>
+<td><format color="369650" style="bold">Correct</format></td>
+<td><format color="E55765" style="bold">Incorrect</format></td>
+</tr>
+<tr>
+<td><img src="built_in_button_browse_correct.png" alt="Browse button" width="378"/></td>
+<td><img src="built_in_button_browse_incorrect.png" alt="Incorrect browse button" width="378"/></td>
+</tr>
+</table>
 
-The Plus button works the same way as the Browse button.
-The only difference is that the selected value is added, instead of overwriting the existing one.
-Place the plus icon inside the control.
-![](plus.png){width=250}
+To place a button inside a text field, use [`ExtendableTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/fields/ExtendableTextField.java) and
+its `addExtension()` method.
 
-### Copy, Info
+The shortcut for a built-in button is <shortcut>Shift+Enter</shortcut>.
 
-| ![](copy_button.png){width="57"} | Do not use the Copy button, the content can be selected and copied using the Cmd/Ctrl+C shortcut or the context menu. |
-|----------------------------------|-----------------------------------------------------------------------------------------------------------------------|
-| ![](info_button.png){width="57"} | Do not use the info button to open an external link. Use <a href="context_help.md">context help</a> instead.          |
-{style=none}
+## When not to use
+
+### Cut, Copy, Paste
+Do not use the **Copy**, **Paste** or **Cut** button. Instead, make sure these actions are available on pressing <shortcut>Cmd/Ctrl+X</shortuct>, <shortcut>Cmd/Ctrl+C</shortuct>, and <shortcut>Cmd/Ctrl+V</shortuct> shortcuts or  from the context menu.
+<table style="none" border="false">
+<tr>
+<td><format color="369650" style="bold">Correct</format></td>
+<td><format color="E55765" style="bold">Incorrect</format></td>
+</tr>
+<tr>
+<td><img src="built_in_button_copy_correct.png" alt="Browse button" width="378"/></td>
+<td><img src="built_in_button_copy_incorrect.png" alt="Incorrect browse button" width="378"/></td>
+</tr>
+</table>
+
+### Help, Info
+Do not use the **Help** or **Info** buttons to open an external link or a hint. Use the [context help](context_help.md) instead.
+
+<table style="none" border="false">
+<tr>
+<td><format color="369650" style="bold">Correct</format></td>
+<td><format color="E55765" style="bold">Incorrect</format></td>
+</tr>
+<tr>
+<td><img src="built_in_button_help_correct.png" alt="Context help " width="378"/></td>
+<td><img src="built_in_button_help_incorrect.png" alt="Incorrect browse button" width="378"/></td>
+</tr>
+</table>

topics/ui/controls/button.topic

@@ -19,7 +19,7 @@
         <img src="when_to_use_button.png" alt="When to use a button" width="706"/>
     </chapter>
         <chapter title="When not to use" id="when-not-to-use">
-        <table style="none">
+        <table style="none" border="false">
             <tr>
                 <td width="50%"><img src="link_instead_of_button.png" alt="Using links instead of buttons" width="378"/></td>
                 <td><p>Use a link instead if:</p>
@@ -78,7 +78,7 @@
             <p>The button should answer the question in the title, so the user can skip the description. Prefer specific
                 labels over
                 generic ones:</p>
-            <table style="none">
+            <table style="none" border="false">
                 <tr>
                     <td width="50%">
                         <p>
@@ -105,7 +105,7 @@
                     use the word
                     <control>Now</control> in labels because buttons always trigger an immediate action:
                 </p>
-                <table style="none">
+                <table style="none" border="false">
                     <tr>
                         <td width="50%">
                             <p>
@@ -130,7 +130,7 @@
             <p>The label should be short, not more than five words. If it’s not obvious what element the button is related
                 to, add more
                 words to make it clear. Prefer clear labels to short ones:</p>
-                <table style="none">
+                <table style="none" border="false">
                     <tr>
                         <td width="50%">
                             <p>
@@ -313,7 +313,7 @@
             <p>On hovering over a button, show a tooltip with the shortcut and the action name if it can be clarified.
                 For more details,
                 see <a href="context_help.md">Context help</a>.</p>
-            <table style="none" column-width="fixed">
+            <table style="none" column-width="fixed" border="false">
                 <tr>
                     <td width="378">
                         <img src="hovered_button.png" alt="Hovered buttons" width="378"/>
@@ -332,7 +332,7 @@
     </chapter>
     <chapter title="Standard buttons" id="standard-buttons">
         <chapter title="Apply" id="apply">
-            <table style="none" column-width="fixed">
+            <table style="none" column-width="fixed" border="false">
                 <tr>
                     <td width="378">
                         <img src="apply.png" alt="Hovered buttons" width="378"/>
@@ -350,7 +350,7 @@
             </table>
         </chapter>
         <chapter title="Cancel" id="cancel">
-            <table style="none" column-width="fixed">
+            <table style="none" border="false" column-width="fixed">
                 <tr>
                     <td width="378">
                         <img src="cancel.png" alt="Hovered buttons" width="378"/>
@@ -386,7 +386,7 @@
         </chapter>
 
         <chapter title="Close">
-            <table style="none" column-width="fixed">
+            <table style="none" column-width="fixed" border="false">
                 <tr>
                     <td width="378">
                         <img src="close.png" alt="Hovered buttons" width="378"/>
@@ -413,7 +413,7 @@
             </table>
         </chapter>
         <chapter title="Help" id="help">
-            <table style="none" column-width="fixed">
+            <table style="none" border="false" column-width="fixed">
                 <tr>
                     <td width="378">
                         <img src="help.png" alt="Hovered buttons" width="378"/>

topics/ui/controls/input_field.md

@@ -131,8 +131,8 @@ If users are more likely to re-enter the entire value, select the whole text whe
 
 ### Input field types
 
-If the input text can be long and place is constrained, use an expandable input field [`ExpandableTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/fields/ExpandableTextField.java).
-For more details, see [built-in buttons](built_in_button.md#expand-field).
+If the input text can be long and the place is constrained, use an expandable input field [`ExpandableTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/fields/ExpandableTextField.java).
+For more details, see [built-in buttons](built_in_button.md#expand-a-field).
 
 ![](expandable_1.png){width=332}