diff --git a/HIG/.kateconfig b/.kateconfig similarity index 100% rename from HIG/.kateconfig rename to .kateconfig diff --git a/HIG/source/components/assistance/inline.rst b/HIG/source/components/assistance/inline.rst index a6f9baa..aa49c1e 100644 --- a/HIG/source/components/assistance/inline.rst +++ b/HIG/source/components/assistance/inline.rst @@ -1,185 +1,163 @@ Inline message ============== .. container:: intend |desktopicon| |mobileicon| Purpose ------- A *inline message* is a small panel that informs users of a non-critical problem or special condition. It is embedded in the content and should not overlap content or controls. The panel has four visual style options which can be used for neutral messages, success conditions, warnings, and errors. It can also be given buttons. .. figure:: /img/Message5.png :alt: Different levels of inline messages. :scale: 80% The four different levels of inline messages. Examples -------- .. figure:: /img/Message-example.png :alt: An inline message is used for feeback after an upload has been completed. Guidelines ---------- - Use inline messages in cases of non-critical problems that user can solve. - Use *negative feedback* (aka error) as a secondary indicator of failure, e.g. if a transaction was not completed successfully - Show the information on a warning level in case of relevant information that do not concern the current workflow, e.g. No Internet connection available. - Use *positive feedback* to notify about user-initiated processes, e.g. to indicate completion of background tasks - Use *opportunistic interaction* (aka notification) to acknowledge the user about options that he or she might be interested in, e.g. "Remember password?" - Display the information immediately. - When users dismiss the inline message, do not display any other UI or start any other side effect. - Do not add controls to the inline message other than action buttons for opportunistic interaction. - Consider to show a :doc:`notification` if information does not concern the current workflow. Is this the right control? / Behavior ------------------------------------- Negative feedback ~~~~~~~~~~~~~~~~~ The inline message should be used as a secondary indicator of failure: the first indicator is for instance that the action the user expected to happen did not happen. Example: User fills a form, clicks "Submit". - Expected feedback: form closes - First indicator of failure: form stays there - Second indicator of failure: a inline message appears on top of the form, explaining the error condition When used to provide negative feedback, an inline message should be placed close to its context. In the case of a form, it should appear on top of the form entries. An inline message should get inserted in the existing layout. Space should not be reserved for it, otherwise it becomes "dead space", ignored by the user. An inline message should also not appear as an overlay to prevent blocking access to elements the user needs to interact with to fix the failure. When used for negative feedback, do not offer a close button. The message panel only closes when the problem it informs about (e.g. the error) is fixed. Positive feedback ~~~~~~~~~~~~~~~~~ An inline message can be used for positive feedback but it shouldn't be overused. It is often enough to provide feedback by simply showing the results of an action. Examples of acceptable uses: - Confirm success of "critical" transactions - Indicate completion of background tasks Example of wrong uses: - Indicate successful saving of a file - Indicate a file has been successfully removed Opportunistic interaction ~~~~~~~~~~~~~~~~~~~~~~~~~ Opportunistic interaction is the situation where the application suggests to the user an action he could be interested in perform, either based on an action the user just triggered or an event which the application noticed. Example use cases: - A browser can propose remembering a recently entered password - A music collection can propose ripping a CD which just got inserted - A chat application may notify the user a "special friend" just connected Appearance ---------- A basic inline messages consists of an icon and text. It can contain an optional close button and :doc:`buttons <../navigation/pushbutton>`. .. figure:: /img/Message1.png :alt: Inline message with a custom icon and a close button. :scale: 80% Inline message with a custom icon and a close button. .. figure:: /img/Message2.png :alt: Inline message with two buttons. :scale: 80% Inline message with two buttons. If there is not enough space to display all the buttons, an overflow menu is shown instead. .. figure:: /img/Message3.png :alt: Inline message with overflow menu. :scale: 80% Inline message with overflow menu. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: InlineMessage ` -.. code-block:: qml - - ... - import QtQuick.Controls 2.2 as Controls - import org.kde.kirigami 2.4 as Kirigami - ... - - Kirigami.InlineMessage { - visible: true - text: i18n("&Remember password?") - type: Kirigami.MessageType.Positive - showCloseButton: true - ... - - actions: [ - Kirigami.Action { - text: i18n("&Remember") - icon.name: "dialog-ok-apply" - }, - Kirigami.Action { - text: i18n("&Do not remember") - icon.name: "dialog-cancel" - } - ] - } + .. literalinclude:: /../../examples/kirigami/InlineMessage.qml + :language: qml + Qt Widgets ~~~~~~~~~~ - :kwidgetsaddonsapi:`QtWidgets: KMessageWidget ` diff --git a/HIG/source/components/editing/list.rst b/HIG/source/components/editing/list.rst index 19fa62e..5679260 100644 --- a/HIG/source/components/editing/list.rst +++ b/HIG/source/components/editing/list.rst @@ -1,356 +1,305 @@ List View ========= Purpose ------- A *list view* offers orientation, organization, and allows navigation without the need for more controls. Additionally, a list view may be used for single selection (users select one item from a list of mutually exclusive values) or multiple selections (selections in combination with the Shift key or Control key). However, because there is no common visual clue whether a list box’ mode is single or multiple and since other controls are more efficient for single selection, a list box should be used for single selection only. .. image:: /img/ListView.png :alt: ListView.png Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Prefer a list view to show items that belong together and in case there is enough space. - Use the list view for selection when it is easy for users to know which items are selected at any given time, for one or more of these reasons: - There are no more than twice the number of options then are visible at a time - The options are well-known and familiar (for example months of a year or days of a week) - Usually the selected options are close to each other in the list Behavior ~~~~~~~~ - Do not have blank list items; use meta-options, e.g. (None) instead. - Place options that represent general options (e.g. All, None) at the beginning of the list. - Sort list items in a logical order. Make sure sorting fits translation. On demand actions ^^^^^^^^^^^^^^^^^ List items can uses an :doc:`on-demand pattern ` as an alternative to always-visible controls. If the user often performs tasks on single items of a list, you can add on-demand controls to the list item for these. .. image:: /img/Slide_to_reveal.jpg :alt: Slide to reveal actions :scale: 30 % |desktopicon| Desktop """"""""""""""""""""" If only one action is available, most the time it's better to not use the on-demand pattern and instead show the action right away. .. raw:: html On-demand controls are shown when hovering over the item with the cursor. A handle is shown to support devices with touch screens. Swiping the handle right to left reveals the actions. As soon as the user taps anywhere else or the pointer is no longer hovering over the item, the handle is slid back. |mobileicon| Mobile """"""""""""""""""" .. raw:: html On-demand controls are revealed by sliding a handle from right to left to reveal them. As soon as the user taps anywhere else, the handle is slid back. Selection ^^^^^^^^^ List items can contain a checkbox to enable the selection of multiple items at the same time. Clicking on the checkbox should not trigger an action, but only change the selection. Place buttons below the list to perform actions on the selected items. If the selection is the only action a user can execute on the items, there is no need for a checkbox. Change the background item color to toggle selection state. .. figure:: /img/PickerOverlay.png :alt: Picker in Language KCM :scale: 60% Multiple selected items in a picker overlay. - Do *not* provide extended multiple selections with Shift+Click or Ctrl+Click to select groups of contiguous or non-adjacent values, respectively. Instead, use the :doc:`dual-list pattern ` or the :doc:`picker pattern ` if multiple items have to be selected, because it allows users to easily see which items are selected at any point, without having to scroll through the available options, and it can be used with only the mouse. Picker ^^^^^^ Lists can be used for the :doc:`picker pattern `. Place a button below the list to add items to the list. To remove items from the list, either add an remove action on the item, or give the user the possibility to select items and add a global remove button at the bottom of the list. Ordering ^^^^^^^^ Allow drag and drop of items, if the the order of the items can be changed by the user. |desktopicon| Desktop """"""""""""""""""""" If you use a :doc:`dual-list pattern ` and want to be able to re-order the items in the selected list you can add aditional up and down buttons. .. figure:: /img/DualListOrdering.png :scale: 50 % :alt: Dual-list pattern with up and down buttons Dual-list pattern with up and down buttons Appearance ~~~~~~~~~~ - Alternate row color (use theme settings). Use different keys (e.g. page up/down) when more lists should be accessible. - Show at least four list view items at any time without the need for scrolling. - Make windows and the list within a dialog or utility window resizeable so that users can choose how many list items are visible at a time without scrolling. Make these windows remember last used dimensions. - If selections affect the appearance or control states, place these controls next to the list view. - Disable controls in a dialog if not in use rather than hide, or remove them from the list (i.e. they are dependent controls), - Label the list view with a descriptive caption to the top left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - End each label with a colon. ":" - Use :doc:`sentence style capitalization ` for list view items. |desktopicon| Desktop ^^^^^^^^^^^^^^^^^^^^^ .. figure:: /img/Listview6.png :alt: Several different lists :scale: 40 % :figclass: border List items with and without icons List items can have a lot of different styles and sizes, but should always be coherent in a list. .. container:: flex .. container:: .. figure:: /img/Listview3.png :alt: Default padding of an item :scale: 40 % :figclass: border Default padding of a SwipeListItem on desktop Items have a padding of :doc:`Units.smallSpacing ` on the top and bottom and a padding of :doc:`2 * Units.smallSpacing ` on the left. .. container:: .. figure:: /img/Listview4.png :alt: Label is vertically centered :scale: 40 % :figclass: border Label is vertically centered Labels are vertically centered within the list item. If the list item includes an icon, add a :doc:`2 * Units.smallSpacing ` margin between the icon and the label. |mobileicon| Mobile ^^^^^^^^^^^^^^^^^^^ .. container:: flex .. container:: .. figure:: /img/Listview1.png :alt: Default padding of an item :scale: 50 % :figclass: border Default padding of a SwipeListItem on mobile Items have a padding of :doc:`Units.largeSpacing ` on the top and bottom and a padding of :doc:`2 * Units.largeSpacing ` on the left. .. container:: .. figure:: /img/Listview2.png :alt: Label is vertically centered :scale: 50 % :figclass: border Label is vertically centered Labels are vertically centered within the list item. If the list item includes an icon, add a :doc:`2 * Units.largeSpacing ` margin between the icon and the label. Selection ^^^^^^^^^ Checkboxes should be placed to the left of the item. .. figure:: /img/Listview5.png :alt: List items with checkboxes :scale: 40 % :figclass: border List items with checkboxes for multi selection. Add a :doc:`2 * Units.largeSpacing ` margin between the checkbox and the icon or the label. If you change the background color to toggle selection state, use Kirigami.Theme.highlightColor to indicate an active item. Picker ^^^^^^ Place the button to add items to the bottom right of list. .. figure:: /img/ListPicker.png :alt: Picker :scale: 40 % :figclass: border Add button at the bottom right of a list For deselection you can either add a remove button for seleted icons next to the add button or use an icon on the list item. .. figure:: /img/ListPickerRemoveItem.png :alt: Remove from a picker :scale: 40 % :figclass: border Using an on-demand pattern to display a "Remove" icon. Ordering ^^^^^^^^ Code ---- Kirigami ~~~~~~~~ - `QML: ListView `_ - :kirigamiapi:`Kirigami: CardsListView ` - :kirigamiapi:`Kirigami: AbstractListItem ` - :kirigamiapi:`Kirigami: BasicListItem ` - :kirigamiapi:`Kirigami: SwipeListItem ` -.. code-block:: qml - - ... - ListView { - ... - - delegate: Kirigami.SwipeListItem { - id: lineItem - - contentItem: Row { - spacing: lineItem.leftPadding - - Item { - width: Kirigami.Units.iconSizes.medium - height: width - - Image { - id: avatar - width: parent.width - height: width - source: "..." - visible: false - } - OpacityMask { - anchors.fill: avatar - source: avatar - maskSource: Rectangle { - height: avatar.width - width: height - radius: height / 2 - } - } - } - Label { - anchors.verticalCenter: parent.verticalCenter - text: "..." - } - } - actions: [ - Kirigami.Action { - text: i18n("&Make call") - iconName: "call-start" - }, - Kirigami.Action { - text: i18n("&Write mail") - iconName: "mail-message" - } - ] - } - - ... - } - ... +.. literalinclude:: /../../examples/kirigami/AddressbookListView.qml + :language: qml Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ListItem ` diff --git a/HIG/source/components/navigation/actionbutton.rst b/HIG/source/components/navigation/actionbutton.rst index 4d42d7b..b19c0d0 100644 --- a/HIG/source/components/navigation/actionbutton.rst +++ b/HIG/source/components/navigation/actionbutton.rst @@ -1,105 +1,79 @@ 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") - } - } - } - ... - } +.. literalinclude:: /../../examples/kirigami/ActionButton.qml + :language: qml diff --git a/HIG/source/components/navigation/contextdrawer.rst b/HIG/source/components/navigation/contextdrawer.rst index 5c26244..3052b7c 100644 --- a/HIG/source/components/navigation/contextdrawer.rst +++ b/HIG/source/components/navigation/contextdrawer.rst @@ -1,127 +1,78 @@ Context drawer ============== .. container:: intend |desktopicon| |mobileicon| .. container:: available plasma qwidgets |nbsp| .. figure:: /img/Contextdrawer1.png :figclass: border :scale: 50 % :alt: Examples of a context drawer on mobile Examples of a context drawer on mobile Purpose ------- The Context Drawer is used to access controls that depend on the current context. This can be, for example, controls that affect a selected element in a list or that navigate through an opened document. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ Use a Context Drawer if your application has any functions which are only relevant in specific contexts, and which are not central enough to the application's main purpose to put them in the main user interface or in a toolbar. For actions which are always available, use the :doc:`Global Drawer `. Behavior ~~~~~~~~ - The Context Drawer is opened by swiping in from the left or right edge of the screen (depending on a system-wide setting) and closed by swiping in the other direction or tapping outside of it. - At the top of the drawer, state which object the controls affect (e.g. "Selected email") - By default, the Context Drawer simply contains a vertical list of action buttons which affect the currently selected/opened element - Center the list vertically instead of top-aligning, to allow an easier reach with the thumb - If needed, other controls related to the current context can be put in the Context Drawer - Try to keep the content of the context drawer in one page. If there two distinct "modes" of contextual actions (for example navigating through a PDF either by table of contents or thumbnails), consider using two :doc:`Tabs ` to separate them, but never use more than two tabs. .. figure:: /img/Contextdrawer2.png :figclass: border :scale: 50 % :alt: Examples of a context drawer on desktop Examples of a context drawer on desktop 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 { - ... - contextualActions: [ - Kirigami.Action { - iconName: "favorite" - text: i18n("&Select as favorite") - }, - Kirigami.Action { - iconName: "document-share" - text: i18n("&Share") - }, - Kirigami.Action { - iconName: "document-edit" - text: i18n("&Edit") - }, - Kirigami.Action { - iconName: "edit-image-face-add" - text: i18n("&Choose photo") - }, - Kirigami.Action { - iconName: "im-kick-user" - text: i18n("&Block number") - }, - Kirigami.Action { - iconName: "delete" - text: i18n("&Delete contact") - }, - Kirigami.Action { - iconName: "edit-clear-history" - text: i18n("&Delete history") - } - ] - ... - } - } - ... - contextDrawer: Kirigami.ContextDrawer { - } - ... - } +.. literalinclude:: /../../examples/kirigami/AddressbookContextDrawer.qml + :language: qml diff --git a/HIG/source/components/navigation/globaldrawer.rst b/HIG/source/components/navigation/globaldrawer.rst index 801a698..bff65c2 100644 --- a/HIG/source/components/navigation/globaldrawer.rst +++ b/HIG/source/components/navigation/globaldrawer.rst @@ -1,150 +1,110 @@ Global drawer ============= Purpose ------- The Global Drawer is a standard element in KDE mobile applications. It contains an application's main menu, and any functions which are not part of the application's main usecases but are not specific to the current context either. .. container:: intend |desktopicon| |mobileicon| .. container:: available plasma qwidgets |nbsp| .. figure:: /img/Globaldrawer1.png :alt: Global drawer on mobile :figclass: border :scale: 40 % Global drawer on mobile Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: /img/Globaldrawer3.png :figclass: border :alt: Global drawer on desktop :scale: 40 % Global drawer on desktop Use a Global Drawer whenever your application has any functions which are not central enough to the application's main purpose to put them in the main user interface, and which are not dependent on the current context. For context-specific actions (e.g. those affecting a selected item), use the :doc:`Context Drawer ` Behavior ~~~~~~~~ .. figure:: /img/Globaldrawer2.png :alt: Global drawer on desktop :scale: 40 % :figclass: border Hamburger button on the toolbar on desktop. The Global Drawer is either opened by clicking on the hamburger button on the toolbar or by swiping from the left edge of the screen. It can be closed by swiping in the other direction, clicking the close button or tapping outside of it. A Global Drawer may contain the following controls: - :doc:`Tabs ` - A main menu - :doc:`Push Buttons ` to execute non-contextual actions - :doc:`Checkboxes <../editing/checkbox>` or :doc:`Radio Buttons <../editing/radiobutton>` to change settings which are commonly changed The main menu - Must not have more than three levels - Should if possible not contain more elements than fit on the screen - Should contain an entry :doc:`Settings ` in the last position if the application has settings which are not commonly changed - Selecting an entry in the menu either executes an action or goes down one level, replacing the menu with the items in the selected submenu - In lower menu levels, below the entries there is a button to go up one level. Do not use the Menu Drawer for navigation purposes. |desktopicon| Collapsible """"""""""""""""""""""""" On the desktop, if the elements in the Global Drawer need to be accessed more often and enough space is available, the Global Drawer can default to showing a collapsed state, where the labels disappear but all actions continue to be available via icons-only ToolButtons. Pressing the hamburger menu button expands the Global Drawer to its full width and shows the actions' text labels. Pressing the close button or anywhere outside of it collapses it to its collapsed icons-only state. .. raw:: html Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: GlobalDrawer ` -.. code-block:: qml - - ... - import QtQuick.Controls 2.2 as Controls - import org.kde.kirigami 2.4 as Kirigami - ... - - Kirigami.ApplicationWindow { - ... - globalDrawer: Kirigami.GlobalDrawer { - title: "..." - titleIcon: "..." - - topContent: [ - ... - ] - - actions: [ - Kirigami.Action { - iconName: "list-import-user" - text: i18n("&Import") - }, - Kirigami.Action { - iconName: "list-export-user" - text: i18n("&Export") - }, - Kirigami.Action { - iconName: "user-group-delete" - text: i18n("&Merge contacts") - }, - Kirigami.Action { - iconName: "user-group-new" - text: i18n("&Search dupplicate contacts") - }, - Kirigami.Action { - iconName: "configure" - text: i18n("&Settings") - } - ] - } - ... - } + .. literalinclude:: /../../examples/kirigami/AddressbookGlobalDrawer.qml + :language: qml diff --git a/HIG/source/components/navigation/menubar.rst b/HIG/source/components/navigation/menubar.rst index 09e4e94..38b3d8f 100644 --- a/HIG/source/components/navigation/menubar.rst +++ b/HIG/source/components/navigation/menubar.rst @@ -1,128 +1,93 @@ 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 ~~~~~~~~ - :kirigamiapi:`Kirigami: ApplicationWindow ` - `QML: MenuBar `_ -.. 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") } - } - } - ... - } + .. literalinclude:: /../../examples/kirigami/AddressbookMenubar.qml + :language: qml diff --git a/HIG/source/components/navigation/toolbar.rst b/HIG/source/components/navigation/toolbar.rst index c6028d9..f7fc072 100644 --- a/HIG/source/components/navigation/toolbar.rst +++ b/HIG/source/components/navigation/toolbar.rst @@ -1,170 +1,125 @@ 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") - } - } - } - ... - } + .. literalinclude:: /../../examples/kirigami/ApplicationToolbar.qml + :language: qml 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") - } - ] - ... - } - ... + .. literalinclude:: /../../examples/kirigami/ComponentToolbar.qml + :language: qml Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ToolBar ` diff --git a/Kirigami/source/style/color.rst b/Kirigami/source/style/color.rst index 44d2715..3949198 100644 --- a/Kirigami/source/style/color.rst +++ b/Kirigami/source/style/color.rst @@ -1,189 +1,189 @@ Color ===== .. toctree:: :maxdepth: 2 :caption: Contents: Kirigami has a color palette that follow the system colors, to better integrate on the platform it's running in, for instance Plasma Desktop, Plasma Mobile, GNOME or Android. All the default controls available as QML comoponents provided by Kirigami and all the components available in the QtQuickControls2 QML plugin will already follow this palette by default, so usually no custom coloring should be needed at all for those controls. Primitive components such as ``Rectangle`` should always be colored with the color palette provided by Kirigami via the ``Theme`` attached property. Hardcoded colors in QML, such as ``#32b2fa`` or ``red`` should usually be avoided; if it's really necessary to have elements with custom colors, it should be an area where only custom colors are used (usually in the *content* area of the app, and never in the *crome* such as toolbars or dialogs), for instance an hardcoded "black" foreground can't be used over a ``Kirigami.Theme.backgroundColor`` background, because if the platform uses a dark color scheme the result will bea poor contrasting black over almost black. Theme ----- For more information about the Kirigami Thmeme class, see the :kirigamiapi:`API docs `. ``Kirigami.Theme`` is an attached property, therefore is available to use in any QML item, it contains as properties all the colors available in the palette, and what palette to use, as the ``colorSet`` property. Example: -.. literalinclude:: /../../examples/kirigami/useTheme.qml +.. literalinclude:: /../../examples/kirigami/UseTheme.qml :language: qml [TODO]: screenshot of a qml file with an annotated UI showing all the available color Color Set ^^^^^^^^^ Depending where a control is, it should use a different color set: for instance, (with the Breeze light color theme) in itemviews, the normal background is almost white, while in other regions, such as toolbars or dialogs, the normal background color is gray. If you set a color set for an item, all of child items (as well as granchildren and so on) will inherit it automatically (unless the property ``inherit`` has explicitly been set to ``false``, which should always be done when the developer wants to force a specific color set) so it's easy to change colors for an entire hierarchy if items without touching any of the items themselves. ``Kirigami.Theme`` supports 5 different color sets: * View: Color set for item views, usually the lightest of all (in light color themes) * Window: **Default** Color set for windows and "chrome" areas * Button: Color set used by buttons * Selection: Color set used by selectged areas * Tooltip: Color set used by tooltips * Complementary: Color set meant to be complementary to Window: usually is dark even in light themes. may be used for "emphasis" in small areas of the application Example: .. code-block:: qml import QtQuick 2.11 import QtQuick.Controls 2.2 as Controls import org.kde kirigami 2.9 as Kirigami // The comments assume the system uses the Breeze Light color theme ... Rectangle { // A gray color will be used, as the default color set is Window color: Kirigami.Theme.backgroundColor Controls.Label { // The text will be near-black, as is defined in the Window // color set text: i18n("hello") } Rectangle { ... // Use the set for ItemViews Kirigami.Theme.colorSet: Kirigami.Theme.View // Don't inherit from the parent Kirigami.Theme.inherit: false // This will be a near-white color color: Kirigami.Theme.backgroundColor Rectangle { ... // This will be a near-white color too, as the colorSet // is inherited from the parent and will be View color: Kirigami.Theme.backgroundColor Controls.Label { // The text will be near-black, as is defined in the View // color set text: i18n("hello") } } Rectangle { ... // Use the Complementary set Kirigami.Theme.colorSet: Kirigami.Theme.Complementary // Don't inherit from the parent Kirigami.Theme.inherit: false // This will be near-black as in the Complementary color set // the background color is dark. color: Kirigami.Theme.backgroundColor Controls.Label { // The text will be near-white, as is defined in the // Complementary color set text: i18n("hello") } } } } Some components such as Labels will automatically inherit by default the color set, some other components have a fixed color set, for instance Buttons are fixed to the ``Button`` color set. If is desired for the button to inherit the parent color set, the inherit property should be explicitly set to true: .. code-block:: qml import QtQuick 2.11 import QtQuick.Controls 2.2 as Controls import org.kde kirigami 2.9 as Kirigami ... Controls.Button { Kirigami.Theme.inherit: true text: i18n("ok") } [TODO]: screenshot of a comparison between a button that inherits and one that doesn't Using Custom Colors ^^^^^^^^^^^^^^^^^^^ Altough is discouraged to use hardcoded colors, Kirigami offers a more maintainable way to assign a custom hardcoded palette to an item and all its children, that will allow to define such custom colors in one place and one only: .. code-block:: qml import QtQuick 2.11 import QtQuick.Controls 2.2 as Controls import org.kde kirigami 2.9 as Kirigami Rectangle { Kirigami.Theme.inherit: false // NOTE: regardless of the color set used, it's recommended to replace // all available colors in Theme, to avoid badly contrasting colors Kirigami.Theme.colorSet: Kirigami.Theme.Window Kirigami.Theme.backgroundColor: "#b9d795" Kirigami.Theme.textColor: "#465c2b" Kirigami.Theme.highlightColor: "#89e51c" ... // Redefine all the others // This will be "#b9d795" color: Kirigami.Theme.backgroundColor Rectangle { // This will be "#465c2b" color: Kirigami.Theme.textColor } } [TODO] Screenshot diff --git a/examples/kirigami/ActionButton.qml b/examples/kirigami/ActionButton.qml new file mode 100644 index 0000000..b2ec08e --- /dev/null +++ b/examples/kirigami/ActionButton.qml @@ -0,0 +1,25 @@ +... +import org.kde kirigami 2.9 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/examples/kirigami/AddressbookContextDrawer.qml b/examples/kirigami/AddressbookContextDrawer.qml new file mode 100644 index 0000000..f372b46 --- /dev/null +++ b/examples/kirigami/AddressbookContextDrawer.qml @@ -0,0 +1,48 @@ +... +import org.kde kirigami 2.9 as Kirigami +... + +Kirigami.ApplicationWindow { + ... + pageStack.initialPage: Kirigami.ScrollablePage { + ... + actions { + ... + contextualActions: [ + Kirigami.Action { + iconName: "favorite" + text: i18n("&Select as favorite") + }, + Kirigami.Action { + iconName: "document-share" + text: i18n("&Share") + }, + Kirigami.Action { + iconName: "document-edit" + text: i18n("&Edit") + }, + Kirigami.Action { + iconName: "edit-image-face-add" + text: i18n("&Choose photo") + }, + Kirigami.Action { + iconName: "im-kick-user" + text: i18n("&Block number") + }, + Kirigami.Action { + iconName: "delete" + text: i18n("&Delete contact") + }, + Kirigami.Action { + iconName: "edit-clear-history" + text: i18n("&Delete history") + } + ] + ... + } + } + ... + contextDrawer: Kirigami.ContextDrawer { + } + ... +} diff --git a/examples/kirigami/AddressbookGlobalDrawer.qml b/examples/kirigami/AddressbookGlobalDrawer.qml new file mode 100644 index 0000000..b40ce1a --- /dev/null +++ b/examples/kirigami/AddressbookGlobalDrawer.qml @@ -0,0 +1,39 @@ +... +import org.kde kirigami 2.9 as Kirigami +... + +Kirigami.ApplicationWindow { + ... + globalDrawer: Kirigami.GlobalDrawer { + title: "..." + titleIcon: "..." + + topContent: [ + ... + ] + + actions: [ + Kirigami.Action { + iconName: "list-import-user" + text: i18n("&Import") + }, + Kirigami.Action { + iconName: "list-export-user" + text: i18n("&Export") + }, + Kirigami.Action { + iconName: "user-group-delete" + text: i18n("&Merge contacts") + }, + Kirigami.Action { + iconName: "user-group-new" + text: i18n("&Search dupplicate contacts") + }, + Kirigami.Action { + iconName: "configure" + text: i18n("&Settings") + } + ] + } + ... +} diff --git a/examples/kirigami/AddressbookListView.qml b/examples/kirigami/AddressbookListView.qml new file mode 100644 index 0000000..e236054 --- /dev/null +++ b/examples/kirigami/AddressbookListView.qml @@ -0,0 +1,51 @@ +... +ListView { + ... + + delegate: Kirigami.SwipeListItem { + id: lineItem + + contentItem: Row { + spacing: lineItem.leftPadding + + Item { + width: Kirigami.Units.iconSizes.medium + height: width + + Image { + id: avatar + width: parent.width + height: width + source: "..." + visible: false + } + OpacityMask { + anchors.fill: avatar + source: avatar + maskSource: Rectangle { + height: avatar.width + width: height + radius: height / 2 + } + } + } + Label { + anchors.verticalCenter: parent.verticalCenter + text: "..." + } + } + actions: [ + Kirigami.Action { + text: i18n("&Make call") + iconName: "call-start" + }, + Kirigami.Action { + text: i18n("&Write mail") + iconName: "mail-message" + } + ] + } + + ... +} +... diff --git a/examples/kirigami/AddressbookMenubar.qml b/examples/kirigami/AddressbookMenubar.qml new file mode 100644 index 0000000..9ac61a7 --- /dev/null +++ b/examples/kirigami/AddressbookMenubar.qml @@ -0,0 +1,34 @@ +... +import org.kde.kirigami 2.9 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/examples/kirigami/ApplicationToolbar.qml b/examples/kirigami/ApplicationToolbar.qml new file mode 100644 index 0000000..c5eb9c6 --- /dev/null +++ b/examples/kirigami/ApplicationToolbar.qml @@ -0,0 +1,25 @@ +... +import org.kde.kirigami 2.9 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/examples/kirigami/ComponentToolbar.qml b/examples/kirigami/ComponentToolbar.qml new file mode 100644 index 0000000..c363c03 --- /dev/null +++ b/examples/kirigami/ComponentToolbar.qml @@ -0,0 +1,19 @@ +... +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/examples/kirigami/InlineMessage.qml b/examples/kirigami/InlineMessage.qml new file mode 100644 index 0000000..1a22406 --- /dev/null +++ b/examples/kirigami/InlineMessage.qml @@ -0,0 +1,22 @@ +... +import org.kde kirigami 2.9 as Kirigami +... + +Kirigami.InlineMessage { + visible: true + text: i18n("&Remember password?") + type: Kirigami.MessageType.Positive + showCloseButton: true + ... + + actions: [ + Kirigami.Action { + text: i18n("&Remember") + icon.name: "dialog-ok-apply" + }, + Kirigami.Action { + text: i18n("&Do not remember") + icon.name: "dialog-cancel" + } + ] +} diff --git a/examples/kirigami/useTheme.qml b/examples/kirigami/UseTheme.qml similarity index 100% rename from examples/kirigami/useTheme.qml rename to examples/kirigami/UseTheme.qml