toolbar.rst 5.19 KB
Newer Older
1 2
Toolbar
=======
3

4
.. figure:: /img/Toolbar1.png
5 6 7
   :figclass: border
   :alt:  Primary Action Buttons on Desktop
   
8 9
   Toolbar with the most important actions :doc:`toolbar <toolbar>` and an 
   overflow menu
10
   
11 12 13
Purpose
-------

14 15 16
A *toolbar* is a graphical presentation of commands optimized for fast
access. A toolbar can be either be defined for a whole application or as
part of another component.
17

18 19 20
As an application toolbar it contains buttons that correspond to items
in the application's menu, providing direct access to application's most
frequently used functions.
21
A good menu bar is a comprehensive catalog of all the available
22
top-level commands, whereas a good toolbar gives quick, convenient
23 24
access to frequently used commands.

25 26 27 28 29 30
As part of another component, like a card or an inline mesage, it is used
to allow quick access to the most important commands for a single, focused
content item.

Guidelines for application
--------------------------
31 32 33 34

Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~

35 36 37
-  For standard applications, show a toolbar by default.
-  Provide a toolbar in addition to the menu bar, but do not replace
   the menu bar. 
38 39 40 41

Behavior
~~~~~~~~

42
-  A toolbar should contain only a few, frequently used operations. If
43 44
   the number of operations is above 5 they have to be grouped with
   separators. Not more than 3 of those sections should be implemented.
45 46 47
-  Do not abuse the toolbar to expose application's features. Only the
   most frequently functions should be add to the toolbar.
-  Execute operations immediately; do not require additional input.
Fabian Riethmayer's avatar
Fabian Riethmayer committed
48
-  Try to avoid using :doc:`split buttons <pushbutton>` 
49
   or :doc:`toggle buttons <../editing/togglebutton>` in order to
50 51 52
   keep the interaction with all buttons in the toolbar consistent.
-  Do not hide toolbars by default. If configurable, users should
   easily be able to make the toolbar viewable again.
53
-  Disable buttons that do not apply to the current context.
54
-  Consider to provide customization for toolbars in respect to
55
   position and content.
56
-  Providing a label for each action is a good practice but define a meaningful icon too because the label could be hidden in mobile mode or if there isn't enough space when the window is resized.
57

58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
   
Guidelines for components
-------------------------

Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~

-  Use a toolbar only if an item has few actions or few frequently used
   actions.
-  Embed a toolbar only in another control that is clearly visually seperated
   like a card or an inline message.
   

Behavior
~~~~~~~~

-  A toolbar should contain only a few, frequently used operations. 
   The number of operations should not exceed 3.
-  Do not group with separators. 
-  Execute operations immediately; do not require additional input.
-  Do not hide toolbars or make them configurable.
-  Toolbars can be responsive. If there is not enough space to display all 
   the buttons, an overflow menu is shown instead.

.. raw:: html

   <video src="https://cdn.kde.org/hig/video/20180620-1/CardLayout1.webm" loop="true" playsinline="true" width="536" controls="true" onended="this.play()" class="border"></video>
   

87
Appearance
88
----------
89

90
-  Do not change the button style from the default, which is 
91
   :doc:`text beside icons </patterns/content/iconandtext>`.
92
-  Use and design toolbar icons with special care. Users remember
93 94 95 96 97
   location of an object but rely as well on icon properties.
-  A distinct association between the underlying function and its visual
   depiction is crucial. Follow the advices for :doc:`icon design </style/icon>`.
-  Do not simulate Microsoft's ribbon controls. KDE stays plain and
   simple.Microsoft's ribbon controls. KDE stays plain and simple.
98 99 100 101

Code
----

102 103
Kirigami
~~~~~~~~
104 105 106 107 108

 - :kirigamiapi:`Kirigami: Action <Action>`
 - :kirigamiapi:`Kirigami: ScrollablePage <ScrollablePage>`
 - :kirigamiapi:`Kirigami: ActionToolBar <ActionToolBar>`
 
109
 
110
Application toolbar
111
"""""""""""""""""""
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165

.. code-block:: qml

    ...
    import QtQuick.Controls 2.2 as Controls
    import org.kde.kirigami 2.4 as Kirigami
    ...
    
    Kirigami.ApplicationWindow {
        ...
        pageStack.initialPage: Kirigami.ScrollablePage {
            ...
            actions {
                left: Kirigami.Action {
                    iconName: "mail-message"
                    text: i18n("&Write mail")
                }
                main: Kirigami.Action {
                    iconName: "call-start"
                    text: i18n("&Make call")
                }
                right: Kirigami.Action {
                    iconName: "kmouth-phrase-new"
                    text: i18n("&Write SMS")
                }
            }
        }
        ...
    }

Component toolbar
^^^^^^^^^^^^^^^^^

.. code-block:: qml

    ...
    import QtQuick.Controls 2.2 as Controls
    import org.kde.kirigami 2.4 as Kirigami
    ...
        Kirigami.ActionToolBar {
            ...
            actions: [
                Kirigami.Action {
                    iconName: "favorite"
                    text: i18n("&Select as favorite")
                },
                Kirigami.Action {
                    iconName: "document-share"
                    text: i18n("&Share")
                }
            ]
            ...
        }
    ...