UX-2323 Update existing UI Guidelines: the Checkbox guideline update, Eldar Isiangulov

2025-07-28 01:07:49 +08:00 · 2024-11-12 17:06:58 +01:00 · 2024-11-12 17:06:58 +01:00 · 7592d8a014
commit 7592d8a014
parent ac7412651a
38 changed files with 198 additions and 196 deletions
--- a/ijs.tree
+++ b/ijs.tree
@ -462,7 +462,7 @@
        <toc-element topic="built_in_button.md"/>
        <toc-element topic="split_button.md"/>
      </toc-element>
-      <toc-element topic="checkbox.md"/>
+      <toc-element topic="checkbox.topic"/>
      <toc-element topic="combo_box.md"/>
      <toc-element topic="context_help.md">
        <toc-element topic="inline_help_text.md"/>
--- a/images/ui/checkbox/checkbox.png
+++ b/images/ui/checkbox/checkbox.png
--- a/images/ui/checkbox/checkbox_dark.png
+++ b/images/ui/checkbox/checkbox_dark.png
--- a/images/ui/checkbox/checkbox_download_status.png
+++ b/images/ui/checkbox/checkbox_download_status.png
--- a/images/ui/checkbox/checkbox_download_status_dark.png
+++ b/images/ui/checkbox/checkbox_download_status_dark.png
--- a/images/ui/checkbox/checkbox_three_state.png
+++ b/images/ui/checkbox/checkbox_three_state.png
--- a/images/ui/checkbox/checkbox_three_state_dark.png
+++ b/images/ui/checkbox/checkbox_three_state_dark.png
--- a/images/ui/checkbox/checkbox_when_not_to_use_1.png
+++ b/images/ui/checkbox/checkbox_when_not_to_use_1.png
--- a/images/ui/checkbox/checkbox_when_not_to_use_1_dark.png
+++ b/images/ui/checkbox/checkbox_when_not_to_use_1_dark.png
--- a/images/ui/checkbox/checkbox_when_not_to_use_2-1.png
+++ b/images/ui/checkbox/checkbox_when_not_to_use_2-1.png
--- a/images/ui/checkbox/checkbox_when_not_to_use_2.png
+++ b/images/ui/checkbox/checkbox_when_not_to_use_2.png
--- a/images/ui/checkbox/checkbox_when_not_to_use_2_dark.png
+++ b/images/ui/checkbox/checkbox_when_not_to_use_2_dark.png
--- a/images/ui/checkbox/checkbox_when_not_to_use_3-1.png
+++ b/images/ui/checkbox/checkbox_when_not_to_use_3-1.png
--- a/images/ui/checkbox/checkbox_when_not_to_use_3.png
+++ b/images/ui/checkbox/checkbox_when_not_to_use_3.png
--- a/images/ui/checkbox/checkbox_when_not_to_use_3_dark.png
+++ b/images/ui/checkbox/checkbox_when_not_to_use_3_dark.png
--- a/images/ui/checkbox/checkbox_when_to_use.png
+++ b/images/ui/checkbox/checkbox_when_to_use.png
--- a/images/ui/checkbox/checkbox_when_to_use_1.png
+++ b/images/ui/checkbox/checkbox_when_to_use_1.png
--- a/images/ui/checkbox/checkbox_when_to_use_1_dark.png
+++ b/images/ui/checkbox/checkbox_when_to_use_1_dark.png
--- a/images/ui/checkbox/checkbox_when_to_use_2.png
+++ b/images/ui/checkbox/checkbox_when_to_use_2.png
--- a/images/ui/checkbox/checkbox_when_to_use_2_dark.png
+++ b/images/ui/checkbox/checkbox_when_to_use_2_dark.png
--- a/images/ui/checkbox/checkbox_when_to_use_3.png
+++ b/images/ui/checkbox/checkbox_when_to_use_3.png
--- a/images/ui/checkbox/checkbox_when_to_use_3_dark.png
+++ b/images/ui/checkbox/checkbox_when_to_use_3_dark.png
--- a/images/ui/checkbox/checkbox_when_to_use_dark.png
+++ b/images/ui/checkbox/checkbox_when_to_use_dark.png
--- a/images/ui/checkbox/checkbox_writing_1_correct.png
+++ b/images/ui/checkbox/checkbox_writing_1_correct.png
--- a/images/ui/checkbox/checkbox_writing_1_correct_dark.png
+++ b/images/ui/checkbox/checkbox_writing_1_correct_dark.png
--- a/images/ui/checkbox/checkbox_writing_1_incorrect.png
+++ b/images/ui/checkbox/checkbox_writing_1_incorrect.png
--- a/images/ui/checkbox/checkbox_writing_1_incorrect_dark.png
+++ b/images/ui/checkbox/checkbox_writing_1_incorrect_dark.png
--- a/images/ui/checkbox/checkbox_writing_2_correct-1.png
+++ b/images/ui/checkbox/checkbox_writing_2_correct-1.png
--- a/images/ui/checkbox/checkbox_writing_2_correct.png
+++ b/images/ui/checkbox/checkbox_writing_2_correct.png
--- a/images/ui/checkbox/checkbox_writing_2_correct_dark.png
+++ b/images/ui/checkbox/checkbox_writing_2_correct_dark.png
--- a/images/ui/checkbox/checkbox_writing_2_incorrect-1.png
+++ b/images/ui/checkbox/checkbox_writing_2_incorrect-1.png
--- a/images/ui/checkbox/checkbox_writing_2_incorrect.png
+++ b/images/ui/checkbox/checkbox_writing_2_incorrect.png
--- a/images/ui/checkbox/checkbox_writing_2_incorrect_dark.png
+++ b/images/ui/checkbox/checkbox_writing_2_incorrect_dark.png
--- a/topics/ui/Components.topic
+++ b/topics/ui/Components.topic
@ -22,7 +22,7 @@
            <td>An icon placed inside an input control.</td>
        </tr>
        <tr>
-            <td><a href="checkbox.md"></a></td>
+            <td><a href="checkbox.topic"></a></td>
            <td>Use checkboxes for yes/no choices or for selecting several items in a group.
            </td>
        </tr>
--- a/topics/ui/controls/checkbox.md
+++ b/topics/ui/controls/checkbox.md
@ -1,192 +0,0 @@
 <!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 # Checkbox
 <link-summary>UI guidelines on using checkboxes.</link-summary>
 <tldr>
 **Implementation:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html), [`JBCheckBox`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBCheckBox.java)
 </tldr>
 ![](checkbox_example.png){width=166}
 ## When to use
 Use checkboxes for yes/no choices or for selecting several items in a group.
 Do **not** use checkboxes if:
 * Only one option in a group can be selected. Use a [radio button group](radio_button.md) instead.
 * The behavior in the "off" state is unclear from the checkbox label. Use two radio buttons instead and label them accordingly.
  ![](when_to_use.png){width=365}
 * With the checkbox, it is unclear how the setting works if it’s unchecked. With radio buttons, both states are labeled clearly.*
 ## How to use
 ### Label
 A label accompanies each checkbox and is placed next to it.
 ![](checkbox_label.png){width=161}
 If a label is long, split it into two lines. Use HTML formatting for that.
 ![](label_twoline.png){width=331}
 <tabs group="languages">
 <tab title="Kotlin UI DSL" group-key="kotlin">
 ```kotlin
 checkBox(
    """<html>Insert selected suggestion by  pressing space, dot,<br/>
    or other context-dependent keys</html>""")
 ```
 </tab>
 <tab title="Java" group-key="java">
 ```java
 new JCheckBox(
    "<html>Insert selected suggestion by  pressing space, dot,<br/>" +
    "or other context-dependent keys</html>");
 ```
 </tab>
 </tabs>
 Avoid labels that take more than two lines. See recommendations on writing concise labels below.
 If a checkbox appears in a table, place the label into the column header and do not repeat it on every row.
 ![](checkbox_table.png){width=347}
 **Implementation**: Checkboxes are rendered in tables with [`BooleanTableCellRenderer`](%gh-ic%/platform/core-ui/src/ui/BooleanTableCellRenderer.java)
 and edited with `DefaultCellEditor(JCheckBox)` implementation.
 For any column that should be rendered as a checkbox, set both a renderer and editor for consistency.
 The type of data in the correspondent column of the `Table` model should either be `Boolean` or `String` containing `true` or `false`.
 ```java
 TableColumn column = table.getColumnModel().getColumn(COLUMN_INDEX);
 column.setCellEditor(JBTable.createBooleanEditor());
 column.setCellRenderer(new BooleanTableCellRender());
 ```
 ### Writing guidelines
 Use sentence-style capitalization.
 Do not use ending punctuation.
 Use the imperative form of verbs.
 ![](label_short.png){width=350}
 Do not use negation in labels as it complicates understanding.
 **Exception**: "Do not show again" checkbox.
 ![](label_answeryes.png){width=224}
 Make labels short and intelligible — see [Writing short and clear](writing_short.md).
 ### Three-state checkbox
 In a group of options, use the parent checkbox to show the status of its children.
 ![](indeterminate_checkbox.png){width=542}
 *The parent checkbox in checked, indeterminate and unchecked states*
 **Implementation**: The three-state checkbox is represented by the [`ThreeStateCheckBox`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/ThreeStateCheckBox.java)
 class which represents its state with the `ThreeStateCheckBox.State` enum containing `SELECTED, NOT_SELECTED, DONT_CARE` states.
 When the user clicks an indeterminate checkbox for the first time, the whole group becomes checked. The second click unchecks the whole group.
 An indeterminate checkbox can also show the download status. An example with a remote repository:
 ![](indeterminate_status.png){width=358}
 *Repositories "tools-base" and "contrib" are being loaded. When loading is finished, the indeterminate checkbox will be replaced with the checked checkbox if there are commits, or an unchecked checkbox if there are no commits.*
 **Implementation**: In a table, the three-state checkbox is represented by [`ThreeStateCheckBoxRenderer`](%gh-ic%/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/table/ThreeStateCheckBoxRenderer.java)
 that provides both `TableCellRenderer` and `TableEditor`.
 It accepts `Boolean` type in the column being supplied by the `TableModel` and becomes `DONT_CARE` when the value in the cell is null.
 Otherwise, it becomes `SELECTED` for `Boolean.TRUE`, and `NOT_SELECTED` for `Boolean.FALSE`.
 ## Placement
 If a checkbox depends on another control, e.g., an input field, follow the rules for [dependent controls](layout.md#dependent-controls). Otherwise, follow the rules for [independent controls](layout.md#independent-controls).
 <!--
 ### Colors
 <p> The color keys can be used only in a UI theme plugin. </p>
 <table>
 <col width="50%">
      <tr>
         <td> Unchecked background </td>
         <td> Checkbox.Background.Default <br/>
              Checkbox.Background.Default.Dark </td>
     </tr>
     <tr>
         <td> Checked background </td>
         <td> Checkbox.Background.Selected <br/>
              Checkbox.Background.Selected.Dark
         </td>
     </tr>
     <tr>
         <td> Disabled background </td>
         <td> Checkbox.Background.Disabled <br/>
              Checkbox.Background.Disabled.Dark
         </td>
     </tr>
     <tr>
         <td> Unchecked border </td>
         <td> Checkbox.Border.Default <br/>
              Checkbox.Border.Default.Dark
         </td>
     </tr>
     <tr>
         <td> Checked border </td>
         <td> Checkbox.Border.Selected <br/>
              Checkbox.Border.Selected.Dark
         </td>
     </tr>
     <tr>
         <td> Disabled border </td>
         <td> Checkbox.Border.Disabled <br/>
              Checkbox.Border.Disabled.Dark
         </td>
     </tr>
     <tr>
          <td> Focused inner 1px border for unchecked state </td>
          <td> Checkbox.Focus.Thin.Default <br/>
               Checkbox.Focus.Thin.Default.Dark
          </td>
      </tr>
      <tr>
          <td> Focused inner 1px border for checked state </td>
          <td> Checkbox.Focus.Thin.Selected <br/>
               Checkbox.Focus.Thin.Selected.Dark
          </td>
      </tr>
      <tr>
          <td> Focused outer 2px border </td>
          <td> Checkbox.Focus.Wide <br/>
               Checkbox.Focus.Wide.Dark
          </td>
      </tr>
      <tr>
          <td> Checkmark fill </td>
          <td> Checkbox.Foreground.Selected <br/>
               Checkbox.Foreground.Selected.Dark
          </td>
      </tr>
      <tr>
          <td> Disabled checkmark fill </td>
          <td> Checkbox.Foreground.Disabled <br/>
               Checkbox.Foreground.Disabled.Dark
          </td>
      </tr>
 </table>
 -->
--- a/topics/ui/controls/checkbox.topic
+++ b/topics/ui/controls/checkbox.topic
@ -0,0 +1,194 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE topic SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
 <topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
       id="checkbox" title="Checkbox">
    <!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
    <title>
        Checkbox
    </title>
    <link-summary>UI guidelines on using checkboxes.</link-summary>
    <tldr>
        <p>
            <control>Implementation:</control>
            <a href="https://docs.oracle.com/javase/tutorial/uiswing/components/button.html"><code>JCheckBox</code></a>,
            <a href="%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBCheckBox.java"><code>JBCheckBox</code></a>
        </p>
    </tldr>
    <img src="checkbox.png" alt="A preview of checkboxes in different states" width="706"/>
    <chapter title="When to use" id="when-to-use">
        <p>Use checkboxes for yes/no choices or for selecting several items in a group:</p>
        <img src="checkbox_when_to_use.png" alt="An example of a checkbox group with two selected options" width="706"/>
    </chapter>
    <chapter title="When not to use" id="when-not-to-use">
        <p>Use <a href="radio_button.md">radio button</a> instead if:</p>
        <table style="none" border="false">
            <tr>
                <td width="50%">
                    <img src="checkbox_when_not_to_use_1.png" alt="A radio button group with only one selected option possible" width="378"/>
                </td>
                <td>Only one option in a group can be selected</td>
            </tr>
            <tr>
                <td width="50%">
                    <img src="checkbox_when_not_to_use_2.png" alt="Two radio buttons with clear labels" width="378"/>
                </td>
                <td>The behavior in the "off" state is unclear from the checkbox label. Use two radio buttons instead
                    and label them accordingly
                </td>
            </tr>
            <tr>
                <td width="50%">
                    <img src="checkbox_when_not_to_use_3.png" alt="A radio button group displaying the correct way for showing different states of a setting" width="378"/>
                </td>
                <td>With the checkbox, it is unclear how the setting works if it’s unchecked. With radio buttons, both
                    states are labeled clearly
                </td>
            </tr>
        </table>
    </chapter>
    <chapter title="How to use" id="how-to-use">
        <chapter title="Label" id="label">
            <table style="none" border="false">
                <tr>
                    <td width="50%"><img src="checkbox_when_to_use_1.png"
                                         alt="A checkbox showing the correct way to use a label" width="378"/></td>
                    <td>A label accompanies each checkbox and is placed next to it.</td>
                </tr>
                <tr>
                    <td width="50%"><img src="checkbox_when_to_use_2.png"
                                         alt="A checkbox with a long label split into two lines" width="378"/></td>
                    <td>If a label is long, split it into two lines. Use HTML formatting for that.</td>
                </tr>
            </table>
            <tabs group="languages">
                <tab title="Kotlin UI DSL" group-key="kotlin">
                    <code-block lang="kotlin">
                        checkBox(
                        &quot;&quot;&quot;&lt;html&gt;Insert selected suggestion by pressing space, dot,&lt;br/&gt;
                        or other context-dependent keys&lt;/html&gt;&quot;&quot;&quot;)
                    </code-block>
                </tab>
                <tab title="Java" group-key="java">
                    <code-block lang="java">
                        new JCheckBox(
                        &quot;&lt;html&gt;Insert selected suggestion by pressing space, dot,&lt;br/&gt;&quot; +
                        &quot;or other context-dependent keys&lt;/html&gt;&quot;);
                    </code-block>
                </tab>
            </tabs>
            <p>Avoid labels that take more than two lines. See recommendations on writing concise labels below.</p>
            <p>If a checkbox appears in a table, place the label into the column header and do not repeat it on every
                row.</p>
            <img src="checkbox_when_to_use_3.png"
                 alt="A table with checkboxes where the label is placed into the column header" width="706"/>
            <p>
                <control>Implementation</control>
                : Checkboxes are rendered in tables with <a
                    href="%gh-ic%/platform/core-ui/src/ui/BooleanTableCellRenderer.java"><code>BooleanTableCellRenderer</code></a>
                and edited with <code>DefaultCellEditor(JCheckBox)</code> implementation.
                For any column that should be rendered as a checkbox, set both a renderer and editor for consistency.
                The type of data in the correspondent column of the <code>Table</code> model should either be <code>Boolean</code>
                or <code>String</code> containing <code>true</code> or <code>false</code>.
            </p>
            <code-block lang="java">
                TableColumn column = table.getColumnModel().getColumn(COLUMN_INDEX);
                column.setCellEditor(JBTable.createBooleanEditor());
                column.setCellRenderer(new BooleanTableCellRender());
            </code-block>
        </chapter>
        <chapter title="Writing guidelines" id="writing-guidelines">
            <p>Use sentence-style capitalization.</p>
            <p>Do not use ending punctuation.</p>
            <p>Use the imperative form of verbs</p>
            <table style="none" border="false">
                <tr>
                    <td width="50%">
                        <p>
                            <format color="369650" style="bold">Correct</format>
                        </p>
                    </td>
                    <td width="50%">
                        <p>
                            <format color="E55765" style="bold">Incorrect</format>
                        </p>
                    </td>
                </tr>
                <tr>
                    <td><img src="checkbox_writing_1_correct.png"
                             alt="A correct checkbox with the imperative form of the verb" width="378"/></td>
                    <td><img src="checkbox_writing_1_incorrect.png"
                             alt="An incorrect checkbox with the declarative form of verb" width="378"/></td>
                </tr>
            </table>
            <p>Do not use negation in labels as it complicates understanding.</p>
            <note>Exception: &quot;Do not show again&quot; checkbox.</note>
            <table style="none" border="false">
                <tr>
                    <td>
                        <p>
                            <format color="369650" style="bold">Correct</format>
                        </p>
                    </td>
                    <td>
                        <p>
                            <format color="E55765" style="bold">Incorrect</format>
                        </p>
                    </td>
                </tr>
                <tr>
                    <td><img src="checkbox_writing_2_correct.png" alt="A correct checkbox without negation"
                             width="378"/></td>
                    <td><img src="checkbox_writing_2_incorrect.png" alt="An incorrect checkbox with negation"
                             width="378"/></td>
                </tr>
            </table>
            <p>Make labels short and intelligible — see <a href="writing_short.md">Writing short and clear</a>.</p>
        </chapter>
        <chapter title="Three-state checkbox" id="three-state-checkbox">
            <p>In a group of options, use the parent checkbox to show the status of its children.</p>
            <img src="checkbox_three_state.png"
                 alt="Different states for a parent checkbox: checked, indeterminate, and unchecked" width="706"/>
            <p>
                <emphasis>The parent checkbox in checked, indeterminate and unchecked states</emphasis>
                <control>Implementation</control>
                : The three-state checkbox is represented by the <a
                    href="%gh-ic%/platform/util/ui/src/com/intellij/util/ui/ThreeStateCheckBox.java"><code>ThreeStateCheckBox</code></a>
                class which represents its state with the <code>ThreeStateCheckBox.State</code> enum containing <code>SELECTED,
                NOT_SELECTED, DONT_CARE</code> states.
            </p>
            <p>When the user clicks an indeterminate checkbox for the first time, the whole group becomes checked. The
                second click unchecks the whole group.</p>
            <p>An indeterminate checkbox can also show the download status. An example with a remote repository:</p>
            <img src="checkbox_download_status.png" alt="Indeterminate checkboxes showing download status" width="706"/>
            <p>
                <emphasis>Repositories &quot;tools-base&quot; and &quot;contrib&quot; are being loaded. When loading is
                    finished, the indeterminate checkbox will be replaced with the checked checkbox if there are
                    commits, or an unchecked checkbox if there are no commits.
                </emphasis>
            </p>
            <p>
                <control>Implementation</control>
                : In a table, the three-state checkbox is represented by <a
                    href="%gh-ic%/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/table/ThreeStateCheckBoxRenderer.java"><code>ThreeStateCheckBoxRenderer</code></a>
                that provides both <code>TableCellRenderer</code> and <code>TableEditor</code>.
                It accepts <code>Boolean</code> type in the column being supplied by the <code>TableModel</code> and
                becomes <code>DONT_CARE</code> when the value in the cell is null.
                Otherwise, it becomes <code>SELECTED</code> for <code>Boolean.TRUE</code>, and <code>NOT_SELECTED</code>
                for <code>Boolean.FALSE</code>.
            </p>
        </chapter>
    </chapter>
    <chapter title="Placement" id="placement">
        <p>If a checkbox depends on another control, e.g., an input field, follow the rules for <a href="layout.md"
                                                                                                   anchor="dependent-controls">dependent
            controls</a>. Otherwise, follow the rules for <a href="layout.md" anchor="independent-controls">independent
            controls</a>.</p>
    </chapter>
 </topic>
--- a/topics/ui/controls/radio_button.md
+++ b/topics/ui/controls/radio_button.md
@ -18,7 +18,7 @@ Use a radio button group to choose one option from 2 to 4 mutually exclusive opt
 Do **not** use radio buttons if:
-* Several options in a group can be selected. Use a group of [checkboxes](checkbox.md) instead.
+* Several options in a group can be selected. Use a group of [checkboxes](checkbox.topic) instead.
 * There are only 2 opposite yes/no options. Use a checkbox instead.
 ![](tworadio_checkbox.png){width=427}
--- a/topics/ui/controls/toggle_button.md
+++ b/topics/ui/controls/toggle_button.md
@ -55,7 +55,7 @@ If the setting is in a tree or menu, use the toggle button label to specify wher
 ![](label_menu_se.png){width=676 style=block}
 *The same setting in search results; separate the first menu level with a vertical bar, and separate others with a colon*
-Refer to [checkbox](checkbox.md) for writing checkbox labels and menu labels.
+Refer to [checkbox](checkbox.topic) for writing checkbox labels and menu labels.
 [//]: # (TODO: and [menu]&#40;menu_list.md&#41;)