diff --git a/source/components/navigation/toolbar.rst b/source/components/navigation/toolbar.rst index 3130845..e986540 100644 --- a/source/components/navigation/toolbar.rst +++ b/source/components/navigation/toolbar.rst @@ -1,165 +1,165 @@ 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 `. + :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") } ] ... } ... diff --git a/source/layout/metrics.rst b/source/layout/metrics.rst index 047695f..97745d9 100644 --- a/source/layout/metrics.rst +++ b/source/layout/metrics.rst @@ -1,132 +1,133 @@ Metrics and placement ===================== Purpose ------- All controls have a default *height and width* to establish a harmonic overall picture. Nevertheless, size is used to direct users' attention. For instance, a list that captures most of screen’s space points to its central role in the current work flow. And, size can be used to indicate possible interactions. Smaller edits are probably constrained, for instance. Similar to size, the *space* between controls generates a visual impression and supports layout. Space between controls indicates their relatedness. Objects with smaller distances are mentally associated according to the Gestalt theory. *Whitespace* is an important element of design which enables the objects in it to exist at all. The balance between content and whitespace is key to *grouping*. Please read :doc:`units` for more information which and how different units such as px, dpi independent pixels, smallSpacing and largeSpacing are used. Guidelines ---------- Size ~~~~ - If the control appears in a dialog or utility window, consider making the window and the control within it resizeable so that the user can choose how many items are visible at a time without scrolling. Each time the user opens this dialog, set its dimensions to those that the user last resized it to. - Size controls with a minimum of - - Icon:16x16px - - Buttons: 72 x 32px - - Line edits, Drop-downs, Combo boxes ≥80 x 32 px - - Text edits: ≥80 x ≥36 px (text should not exceed 80 characters per + + - Icon:16x16px + - Buttons: 72 x 32px + - Line edits, Drop-downs, Combo boxes ≥80 x 32 px + - Text edits: ≥80 x ≥36 px (text should not exceed 80 characters per line) - Checkbox, Radio button including label: ≥80 x 24 px - Group boxes: ≥120 x ≥96 px - Tree view: ≥120 x ≥96 px - List view: ≥80 px (per column) x ≥96 - KDE seeks to support XGA (1024x768px) or WXGA (1280x768px) at least. - - Keep in mind that not everyone is provided with a high resolution - display. - - Avoid to have a large number of controls visible at once, which in - turn requires a huge minimal size. - - Keep in mind that the available screen area typically also will be - shrunk by panels and the window titlebar. Also, user's font might - be bigger than yours (e.g. for accessibility reason). - - You therefore should ideally preserve ~10% to catch those - variables and try to not exceed 920x690px. + - Keep in mind that not everyone is provided with a high resolution + display. + - Avoid to have a large number of controls visible at once, which in + turn requires a huge minimal size. + - Keep in mind that the available screen area typically also will be + shrunk by panels and the window titlebar. Also, user's font might + be bigger than yours (e.g. for accessibility reason). + - You therefore should ideally preserve ~10% to catch those + variables and try to not exceed 920x690px. Space ~~~~~ Qt widgets ^^^^^^^^^^ If you are using Qt widgets you should use one of `Qt's Layout Classes `_, which will take care of laying out and spacing of your controls. QML ^^^ For consistency you should try to use Kirigami and Plasma's smallSpacing and largeSpacing for margins and paddings whenever possible. See :doc:`units` for more details. Use multiples of smallSpacing or largeSpacing, where more spacing is required. .. figure:: /img/Margin.qml.png :alt: Use of base units Use of base units Recommended minimum paddings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - A smallSpacing padding is the minimum recommended padding inside elements (buttons, drop boxes, text fields, etc.) - An 2 * smallSpacing padding is the minimum recommended padding inside grouping frames (group boxes, tabs, etc.) - Use default spacing of - related items within groups: 2 * smallSpacing - label and item: smallSpacing - related controls with same type (checkboxes / radio buttons): smallSpacing - related controls with different type (checkbox / button): smallSpacing - unrelated controls: ≥ 3 * smallSpacing .. figure:: /img/SpacingPadding.qml.png :alt: Sample spacing Sample spacing - In some cases it may be useful to visually separate groups of related options within one group to facilitate scanning of the dialog. In that case, put a vertical, fixed-size spacer of 18px height between the options. .. figure:: /img/SpacingSeperate.qml.png :alt: Separating groups of related options with a vertical spacer. Separating groups of related options with a vertical spacer. .. hint:: |designicon| It often helps to use a soft grid of 18px (gridUnit), when creating mockups. But only use this as a visual hint, since plasma components and icon size are not multiples of the gridUnit, you won't be able to align everything to the grid. Resize ~~~~~~ - Provide resizing for all primary and mode-less windows. - If form resizing is not provided disable border icons and adjust form style. - Define a minimum size for resizable forms. - Make the content area scrollable if size is too small for all controls; do not scale controls. .. figure:: /img/Resize.qml.png :alt: Give hints how to resize Give hints how to resize diff --git a/source/patterns/navigation/master.rst b/source/patterns/navigation/master.rst index 1012c11..093e740 100644 --- a/source/patterns/navigation/master.rst +++ b/source/patterns/navigation/master.rst @@ -1,34 +1,33 @@ Master-Detail ============= .. container:: intend |desktopicon| |mobileicon| Pattern for a flat content structure. .. image:: /img/NP-flat-3a.png :alt: Master-Detail |desktopicon| Desktop --------------------- - These patterns are useful when multiple pieces of content are intended to be shown at once, alongside a larger, more complete presentation of the selected item. -- See the :doc:`wizard ` pattern guidelines for - more details on using that - pattern. +- See the :doc:`wizard ` pattern guidelines for + more details on using that pattern. - Examples include a contact list that shows the full details of the selected contact, a slideshow with a "film-strip" to select photographs, or setup for newly installed software. |mobileicon| Mobile ------------------- - The list - detail view pattern is useful when the user usually focuses on a single item in the list. - Tapping an item in the list shows its details in a new view - Use swipe left to go back to the list. - Use a swipe beyond the top/bottom of the content to jump to the previous/next item in the list. diff --git a/source/style/writing/placeholder.rst b/source/style/writing/placeholder.rst index 65ff51b..3a3bcbc 100644 --- a/source/style/writing/placeholder.rst +++ b/source/style/writing/placeholder.rst @@ -1,39 +1,39 @@ Placeholder =========== Purpose ------- A placeholder can be shown on an input element that expects text input. It can either contain an example of the expected format, or a hint about the action that will be triggered when the user types in the input element. Guidelines ---------- Example ~~~~~~~ - A placeholder with an example is not a replacement for a label, but should give the user only an additional hint about what kind of data is expected. .. image:: /img/Placeholder-1.png :alt: Placeholders showing an example of what to enter in fields Actions ~~~~~~~ - A placeholder with an action replaces the label. - Use an ellipsis (...) after the text. - Show visiual feedback as soon as the user types, e.g. trigger the action or show a menu with autocompletion suggestions. - Keep the text as short as possible. - Since the placeholder won't be visible anymore as soon as the user types, you should only use it on standalone input elements, not in groups of input elements such as forms. - Use :doc:`sentence style capitalization `. .. figure:: /img/Krunner-1.png :alt: Krunner showing a placeholder instead of a label with an action. - .. Krunner showing a placeholder instead of a label with an action. + Krunner showing a placeholder instead of a label with an action.