diff --git a/source/components/navigation/actionbutton.rst b/source/components/navigation/actionbutton.rst index c092c73..aaae4a8 100644 --- a/source/components/navigation/actionbutton.rst +++ b/source/components/navigation/actionbutton.rst @@ -1,102 +1,102 @@ 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 -^^^^^^^^ +~~~~~~~~ .. 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/menubar.rst b/source/components/navigation/menubar.rst index c9607a2..eccb4a3 100644 --- a/source/components/navigation/menubar.rst +++ b/source/components/navigation/menubar.rst @@ -1,125 +1,125 @@ Menu bar ======== Purpose ------- A *menu bar* appears at the top of an application's main window. It provides access to all commands and most of the settings available in an application. Users refer frequently to the menu bar, especially when they are seeking a function for which they know of no other interface. Ensuring that menus are well organized, are worded clearly, and behave correctly is crucial to the user’s ability to explore and access the functionality of the application. Examples -------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - A menu bar is mandatory for applications that have a :doc:`very complex command structure `, such as those used for content creation or editing, file manipulation, or other productivity work. - Menu bars are optional for simple apps that are able to expose all functionality using visible buttons and toolbars. If any functionality is not visible by default, err on the side of providing a menu bar. - Do not display a menu bar in secondary or internal windows, like the settings dialog or file dialog. Very small main windows are likewise usually poor candidates for menu bars. - Do not include a menu bar in a convergent application's mobile user interface. Behavior ~~~~~~~~ - Do not have more than nine menu categories within a menu bar. Too many categories are overwhelming and makes the menu bar difficult to use. - At the minimum, all windows should have File, Edit, Settings, and Help menus. If they apply, the window can also have View, Insert, Format, Tools and, Window menus. - Do not put more than 12 items within a single level of a menu. Add separators between logical groups within a menu. Organize the menu items into groups of seven or fewer strongly related items. - Assign shortcut keys to the most frequently used menu items. Use `KStandardAction `_ and `KStandardShortcut `_ items for common functions, which will result in menu items automatically receiving consistent names, icons, and shortcut keys. Any tool or function that is accessible using a keyboard shortcut must have an item in the menu bar so that users can discover it. - Do not hide the menu bar by default. If this is configurable, users should easily be able to make the menu bar viewable again. - Use submenus cautiously. Submenus add complexity to the interface and are physically more difficult to use, so you should take care not to overuse them. Appearance ~~~~~~~~~~ - Place the most frequently used items at the top of the menu. - Provide icons for all menu items. Do not re-use the same icon for multiple items. - For your menu items' text, follow the :doc:`general label guidelines `. - Do not change menu items' labels dynamically. - Choose single word names for menu categories. Using multiple words makes the separation between categories confusing. - Disable menu items that don't apply to the current context instead of removing them from view. **Exception:** It is acceptable to hide menu items completely if they are permanently unavailable on the user's system due to missing hardware capabilities. - Assign :doc:`shortcut keys ` to the most frequently used menu items (Ctrl+). For well-known shortcut keys, use standard assignments. Use function keys for commands that have a small-scale effect (F2 = Rename) and ctrl key for large-scale effect (Ctrl+S = Save). - For menu items that toggle some state on or off, always use the positive form. For example, use the text 'Show hidden files' instead of 'Hide hidden files', and do not change the text when hidden files are shown. Code ---- Kirigami -^^^^^^^^ +~~~~~~~~ .. code-block:: qml ... import QtQuick.Controls 2.2 as Controls import org.kde.kirigami 2.4 as Kirigami ... Kirigami.ApplicationWindow { ... menuBar: MenuBar { Menu { title: i18n("&File") Action { text: i18n("&New...") } Action { text: i18n("&Import") } Action { text: i18n("&Export") } } Menu { title: i18n("&Edit") Action { text: i18n("&Merge contacts") } Action { text: i18n("&Search dupplicate contacts") } Action { text: i18n("&Export") } } Menu { title: i18n("&Settings") Action { text: i18n("&Settings") } Action { text: i18n("&Configure shortcuts") } } Menu { title: i18n("&Help") Action { text: i18n("&Report Bug...") } Action { text: i18n("&Donate") } Action { text: i18n("&About Addressbook") } Action { text: i18n("&About KDE") } } } ... } diff --git a/source/components/navigation/toolbar.rst b/source/components/navigation/toolbar.rst index 8afc59c..da60ec2 100644 --- a/source/components/navigation/toolbar.rst +++ b/source/components/navigation/toolbar.rst @@ -1,160 +1,160 @@ 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 ~~~~~~~~ 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.