diff --git a/source/components/navigation/actionbutton.rst b/source/components/navigation/actionbutton.rst index 6d71982..4d42d7b 100644 --- a/source/components/navigation/actionbutton.rst +++ b/source/components/navigation/actionbutton.rst @@ -1,108 +1,105 @@ Primary Action Button ===================== .. figure:: /img/Actionbutton1.png :figclass: border :alt: Primary Action Button Primary action, create a new address book entry. When to use ----------- Use a Primary Action Button whenever there is a primary action for a certain page of your application or for the whole application, which is executed frequently. Typical primary actions are "Create New", "Edit,", "Save" or "Send". Aditionally you can opt to define two secondary primary actions that are placed left and right to the main primary button. .. figure:: /img/Actionbutton2.png :figclass: border :alt: Primary Action Button with two secondary buttons Call, message and write an email as primary actions. If there is no primary action, you may opt to use the Primary Action Button as a shortcut to navigate back to the application's main page instead of omitting it completely. Do that if - navigating back to the main page is a frequent action in your application - or you use Primary Action buttons on some pages and would like to keep the layout consistent across pages - or drawers are frequently used - and the space occupied by the button is not urgently needed for the content If the primary action is clearly associated with a specific element on the user interface, place controls within the content instead. How to use ---------- - Provide a clear icon for the Primary Action Button since it has no text label - If the Primary Action Button changes its action within a page (for example switching to "save" when editing, change its icon as well - If you use the Primary Action Button as a shortcut for going to the main page, use the "go-home" icon from the actions category for it. Desktop-specific ~~~~~~~~~~~~~~~~ If your application is using :doc:`column-based navigation ` - If there is a global Primary Action, associate it with the first column - If there is a Primary action for the context of a specific column, associated with the respective page .. figure:: /img/Actionbutton3.png :figclass: border :alt: Primary Action Buttons on Desktop Primary Action Buttons are placed in a :doc:`toolbar ` Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` .. 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") } } } ... } - - - diff --git a/source/components/navigation/toolbar.rst b/source/components/navigation/toolbar.rst index e986540..c6028d9 100644 --- a/source/components/navigation/toolbar.rst +++ b/source/components/navigation/toolbar.rst @@ -1,165 +1,170 @@ Toolbar ======= .. figure:: /img/Toolbar1.png :figclass: border :alt: Primary Action Buttons on Desktop Toolbar with the most important actions :doc:`toolbar ` and an overflow menu Purpose ------- 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. 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. A good menu bar is a comprehensive catalog of all the available top-level commands, whereas a good toolbar gives quick, convenient access to frequently used commands. 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 -------------------------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - For standard applications, show a toolbar by default. - Provide a toolbar in addition to the menu bar, but do not replace the menu bar. Behavior ~~~~~~~~ - A toolbar should contain only a few, frequently used operations. If the number of operations is above 5 they have to be grouped with separators. Not more than 3 of those sections should be implemented. - 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. - Try to avoid using :doc:`split buttons ` or :doc:`toggle buttons <../editing/togglebutton>` in order to 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. - Disable buttons that do not apply to the current context. - Consider to provide customization for toolbars in respect to position and content. - 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. 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 Appearance ---------- - Do not change the button style from the default, which is :doc:`text beside icons `. - Use and design toolbar icons with special care. Users remember 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 `. - Do not simulate Microsoft's ribbon controls. KDE stays plain and simple.Microsoft's ribbon controls. KDE stays plain and simple. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` - :kirigamiapi:`Kirigami: ActionToolBar ` Application toolbar """"""""""""""""""" .. 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") } ] ... } ... + +Plasma components +~~~~~~~~~~~~~~~~~ + + - :plasmaapi:`Plasma ToolBar `