intellij-sdk-code-samples/topics/ui/controls/button.topic

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<!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="button" title="Button">
    <show-structure/>
    <link-summary>UI guidelines on using buttons.</link-summary>

    <tldr>
        <p>
            <control>Implementation</control>:
            <a href="https://docs.oracle.com/javase/tutorial/uiswing/components/button.html">JButton</a>
        </p>
    </tldr>
    <img src="button_example.png" alt="Cancel and Save buttons" width="706"/>
    <chapter title="When to use" id="when-to-use">
        <p>Use a button to invoke an immediate action:</p>
        <img src="button_when_to_use.png" alt="When to use a button" width="706"/>
    </chapter>
        <chapter title="When not to use" id="when-not-to-use">
        <table style="none" border="false" column-width="fixed">
            <tr>
                <td><img src="button_link_instead.png" alt="Using links instead of buttons" width="378"/></td>
                <td><p>Use a link instead if:</p>
                    <list>
                    <li><p>The action takes the user to another page of the same dialog or an external source like
                        documentation.</p>
                        <note>Exception: the <control>Next</control> and <control>Previous</control> buttons in wizard navigation.</note>
                    </li>
                    <li>
                        The command is a secondary action that isn't related to the primary purpose of the window,
                        and the space is constrained.
                    </li>
                    </list>
                </td>
            </tr>
            <tr>
                <td><img src="button_toolbar.png" alt="Using toolbar buttons instead of buttons" width="378"/></td>
                <td><p>Use a <a href="toolbar.md">toolbar button</a> instead if there are several buttons related to a table or list.</p>
                </td>
            </tr>
            <tr>
                <td><img src="button_split_button.png" alt="Using split buttons instead of buttons" width="378"/></td>
                <td><p>Use a <a href="split_button.md">split button</a> instead if:</p>
                    <list>
                        <li>There are more than two related actions, but the space is limited and/or packed.</li>
                        <li>The action isn't common and is dangerous, for example, can destroy user data and cannot be easily
                            undone.
                        </li>
                    </list>
                </td>
            </tr>
            <tr>
                <td>
                    <img src="button_built_in_button.png" alt="Using built-in buttons instead of buttons" width="378"/>
                </td>
                <td><p>Use a <a href="built_in_button.md">built-in button</a> instead if it's related to an input field, combo box,
                    search field.</p>
                </td>
            </tr>
</table>
</chapter>

    <chapter title="How to use" id="how-to-use">
        <chapter title="Label" id="label">
            <p>Use an action name as a button label.</p>
            <chapter title="Use title capitalization" id="use-title-capitalization">
        <p>Use <a href="capitalization.md">title capitalization</a> for button labels.</p>
            </chapter>
            <chapter title="Use imperative verbs" id="use-imperative-verbs">
            <p>Write the label as an imperative verb, for example, Save, Print, Cancel. Use title capitalization.</p>
            <note><p>Exceptions: standard buttons like <control>OK</control>, <control>Back</control>/<control>Forward</control>,
                <control>Previous</control>/<control>Next</control>, <control>Yes</control>/<control>No</control>, <control>Agree</control>,
                <control>Options</control>, <control>Settings</control>, <control>Details</control>.
            </p></note>
            </chapter>
            <chapter title="Be specific" id="be-specific">
            <p>The button should answer the question in the title, so the user can skip the description. Prefer specific
                labels over
                generic ones.</p>
                <note>
                    Exception: the <control>Cancel</control> button if it's clear what action is being canceled.
                    For example, use
                    <control>Cancel</control> instead of <control>Don’t Create</control>.
                </note>
            <table style="none" border="false" column-width="fixed">
                <tr>
                    <td><format color="369650" style="bold">Correct</format>
                        <img src="button_default_save.png" alt="A correct button with a clear 'Save' label" width="378"/></td>
                    <td><format color="E55765" style="bold">Incorrect</format>
                        <img src="button_default_OK.png" alt="An incorrect button with a generic 'OK' label" width="378"/></td>
                </tr>
            </table>
                <p>Do not
                    use the word
                    <control>Now</control> in labels because buttons always trigger an immediate action:
                </p>
                <table style="none" border="false" column-width="fixed">
                    <tr>
                        <td>
                            <format color="369650" style="bold">Correct</format>
                            <img src="button_check_for_updates.png" alt="A button with 'Check for Updates' label" width="378"/>
                        </td>
                        <td><format color="E55765" style="bold">Incorrect</format>
                            <img src="button_check_now.png" alt="A button with 'Check Now' label" width="378"/></td>
                    </tr>
                </table>
            </chapter>
            <chapter title="Be short and clear" id="short_and_clear">
            <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" border="false" column-width="fixed">
                    <tr>
                        <td><format color="369650" style="bold">Correct</format>
                            <img src="button_active_edit_action.png"
                                 alt="A button with the 'Edit Action Icon...' label"
                                 width="378"/></td>
                        <td><format color="DarkOrange" style="bold">Acceptable</format>
                            <img src="button_edit.png" alt="A button with 'Edit' label" width="378"/></td>
                    </tr>
                </table>
            </chapter>
            <chapter title="Ellipsis" id="ellipsis">
                <list>
                    <li>Add an ellipsis if additional actions such as adding more info or confirming the action are required.
                    </li>
                    <li>Don't add an ellipsis if another window is opened, but no more input from the user is required. For example,
                        <control>About</control>, <control>Details</control>.</li>
                </list>
            <img src="button_ellipsis.png" alt="Buttons with ellipsis" width="706"/>
            </chapter>
        </chapter>
<!--        <chapter title="Icons" id="icons">
            <p>Don't add an icon to the button. The main purpose of an icon is to quickly find a
                familiar action in a packed toolbar or menu. Usually, no more than three buttons
                are placed nearby, their labels can be scanned quickly, and icons aren't required.
            </p>
        </chapter>-->

    <chapter title="Button states" id="button-states">
        <chapter title="Default" id="default">

            <img src="button_default.png" alt="Default button on macOS and Windows" width="706"/>
            <list>
                <li>The default button confirms the main purpose of a dialog. It is triggered by pressing
                    <shortcut>Enter</shortcut>
                    or
                    <shortcut>Ctrl+Enter</shortcut>
                    on Windows/Linux and
                    <shortcut>Enter</shortcut>
                    or
                    <shortcut>Cmd+Enter</shortcut>
                    on macOS.
                    <note>Exception: if the focus is on an element that uses the
                        <shortcut>Enter</shortcut>
                        key, for example, a text area, the default button is triggered only by
                        <shortcut>Ctrl+Enter</shortcut>
                        on Windows/Linux and
                        <shortcut>Cmd+Enter</shortcut>
                        on macOS.</note>
                </li>
                <li>The default button should always be present in a dialog. Only one button in a dialog can be the default
                one.
                </li>
                <li>If an action that a default button performs is dangerous, which means it can lead to data loss, there
                    should always be an easy way to undo it.
                    Otherwise, use a secondary button for a dangerous action and a default button for a safe action:
                <img src="button_merge_dialog.png"
                     alt="A dialog with secondary and primary buttons"
                     width="706"/>
            </li>
            </list>
        </chapter>
        <chapter title="Focused" id="focused">
            <img src="button_focused.png" alt="'Cancel' button in a focused state" width="706"/>
            <p>All buttons can get focus, even on macOS if the
                <control>Full Keyboard Access</control>
                option is disabled in Preferences &gt; Keyboard &gt;
                Shortcuts.
                A focused button behavior varies on macOS/Linux and Windows.
            </p>

           <tabs>
            <tab title="macOS">
                <list>
                    <li>
                        <p>A focused button is invoked by pressing
                            <shortcut>Space</shortcut>. Focused and default buttons are
                            <b>independent</b>,
                            so when
                            the focus moves from one button to another, the default button does not change.
                        </p>
                    </li>
                    <li>
                        <p>
                            Make the second most popular button in the dialog focused. It’s recommended to have one
                            default and one focused button so that most of the actions can be triggered using
                            the keyboard.
                        </p>
                    </li>
                    <li>
                        <p>It’s recommended to have one default and one focused button, so that most of the actions can be
                            triggered using
                            the keyboard.</p>
                    </li>
                </list>
            </tab>
            <tab title="Windows, Linux">
            <list>
                <li>The focused button is triggered by pressing
                    <shortcut>Enter</shortcut>
                    or
                    <shortcut>Space</shortcut>. If a non-default
                    button gets focus, the default button is invoked using
                    <shortcut>Ctrl+Enter</shortcut>.
                    <p>On pressing the
                        <shortcut>Tab</shortcut>
                        key, the
                        <control>New Window</control>
                        button gets the focus and is triggered with
                        <shortcut>Enter</shortcut>
                        or
                        <shortcut>Space</shortcut>
                        .
                        The original
                        <control>This Window</control>
                        button is triggered with
                        <shortcut>Ctrl+Enter</shortcut>.</p>
                    <p>
                    If the focus moves to the control that’s not a button, the original default button is triggered by
                    <shortcut>Enter</shortcut>.</p>
                </li>
            </list>
               </tab>
           </tabs>
            <format color="369650" style="bold">Correct</format>
            <img src="button_open_project_dialog.png"
                 width="706"
                 alt="A dialog with buttons: 'New Window' (focused), 'Cancel', and 'This Window' (default)."
                 style="block"/>
            <format color="E55765" style="bold">Incorrect</format>
            <img
                    src="button_open_project_dialog_incorrect.png"
                    alt="A dialog with buttons: 'New Window', 'Cancel', and 'This Window' (default and focused)."
                    width="706"/>
        </chapter>


        <chapter title="Disabled" id="disabled">
            <img src="button_disabled.png"
                 alt="Disabled button"
                 width="706"/>
            <p>Disable a button if:</p>
            <list>
                <li>The control to which the button is related is disabled.</li>
                <li>Not all required fields in the dialog are filled.
                </li>
            </list>
            <p>Other <a anchor="standard-buttons">standard buttons</a> are described below. They can be regular or default buttons.</p>
        </chapter>


        <chapter title="Hover" id="hover">

            <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>
            <p>If the action is clear, show the shortcut only. If the action can be clarified, show the action name and the shortcut:
            </p>
            <img src="button_hovered.png" alt="Hovered buttons" width="706"/>
        </chapter>
    </chapter>
    <chapter title="Standard buttons" id="standard-buttons">
        <chapter title="Apply" id="apply">
            <table style="none" border="false" column-width="fixed">
                <tr>
                    <td>
                        <img src="button_apply.png" alt="Hovered buttons" width="378"/>

                    </td>
                    <td>
                        <p>Use the <control>Apply</control> button in dialogs with many settings that affect how data is displayed. The
                            <control>Apply</control> button
                            allows you to save and preview the effect of the selected options and continue changing the
                            settings, for example, change the editor color scheme in settings.</p>
                        <p>The <control>Apply</control> should be <a anchor="disabled">disabled</a> if no changes have been made in the dialog.
                        </p>
                    </td>
                </tr>
            </table>
        </chapter>
        <chapter title="Cancel" id="cancel">
            <table style="none" border="false" column-width="fixed">
                <tr>
                    <td>
                        <img src="button_cancel.png" alt="Hovered buttons" width="378"/>

                    </td>
                        <td>
                            <p>The<control>Cancel</control> button reverts the app to the state before the dialog was
                                invoked and works as an equivalent to the <shortcut>Esc</shortcut> key.</p>
                            <p>If a confirmation button is present in a dialog, for example,
                            <control>OK</control> or
                            <control>Save</control>, it’s recommended to have the <control>Cancel</control> button.</p>
                            <p>If it is not clear what will happen on clicking the <control>Cancel</control> button,
                            make the label more <a anchor="be-specific">specific</a>, for example, <control>Continue Editing</control>.</p>
                    </td>
                </tr>
            </table>

        </chapter>

        <chapter title="Close">
            <table style="none" border="false" column-width="fixed">
                <tr>
                    <td width="378">
                        <img src="button_close.png" alt="Hovered buttons" width="378"/>

                    </td>
                    <td width="378">
                        <p>Use the
                            <control>Close</control>
                            label only if nothing can be changed in the dialog and there is no confirmation button, for example, in
                            the
                            <ui-path>Help | My Productivity</ui-path>
                            dialog.
                            In all other cases, use the
                            <control>Cancel</control>
                            button.
                        </p>
                    </td>
                </tr>
            </table>
        </chapter>
        <chapter title="Help" id="help">
            <table style="none" border="false" column-width="fixed">
                <tr>
                    <td width="378">
                        <img src="button_help.png" alt="Hovered buttons" width="378"/>

                    </td>
                    <td width="378">
                        <p>The help button appears in the bottom-left corner of a dialog and
                            opens a documentation website. Add this button if the dialog's functionality is described
                            in documentation.</p>
                        </td>
                </tr>
            </table>
        </chapter>
    </chapter>
    </chapter>
</topic>