diff --git a/source/components/editing/list.rst b/source/components/editing/list.rst index 539f6f4..bb55d51 100644 --- a/source/components/editing/list.rst +++ b/source/components/editing/list.rst @@ -1,284 +1,301 @@ 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 -- 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 ` 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. (Once the - list view is being revised this guideline is subject of change.) - 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 alternative to always visible controls. If the user often performs tasks on single items of a list, add a handle on the side the list item (next to the context drawer's edge, defined by a system-wide configuration) which. .. 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, but show the action right away. .. image:: /img/desktop-listview.png :alt: Hover to reveal :scale: 60 % 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 not any longer hovering 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. -https://community.kde.org/KDE_Visual_Design_Group/HIG/SOU_Workspace/ -Rich_Selection_List +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 picker content 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 posibility to select items and -add a global remove button at the bottom of the list. - -https://community.kde.org/KDE_Visual_Design_Group/HIG/SOU_Workspace/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 posibility +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 """"""""""""""""""""" -Aditionally add up and down buttons next to the list, to +Aditionally you can add up and down buttons next to the list, to move the selected item in the list. 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/Listview3.png - :alt: Default padding of an item - :scale: 60 % - :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. - - .. figure:: /img/Listview4.png - :alt: Label is vertically centered - :scale: 60 % - :figclass: border - - Label is vertically centered +.. container:: flex -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. + .. 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 -""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^ - .. figure:: /img/Listview1.png - :alt: Default padding of an item - :scale: 60 % - :figclass: border - - Default padding of a swipelistitem on mobile +.. container:: flex -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/Listview1.png + :alt: Default padding of an item + :scale: 50 % + :figclass: border + + Default padding of a swipelistitem on mobile - .. figure:: /img/Listview2.png - :alt: Label is vertically centered - :scale: 60 % - :figclass: border + 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 + 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. + 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. On demand actions ^^^^^^^^^^^^^^^^^ Selection ^^^^^^^^^ TODO https://community.kde.org/KDE_Visual_Design_Group/HIG/SOU_Workspace/ Rich_Selection_List Picker ^^^^^^ TODO https://community.kde.org/KDE_Visual_Design_Group/HIG/SOU_Workspace/Picker Ordering ^^^^^^^^ TODO Code ---- Kirigami ~~~~~~~~ .. 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" } ] } ... } ... diff --git a/source/patterns/content/index.rst b/source/patterns/content/index.rst index 36c41c2..f544149 100644 --- a/source/patterns/content/index.rst +++ b/source/patterns/content/index.rst @@ -1,21 +1,23 @@ Content patterns ================ .. toctree:: :maxdepth: 1 :titlesonly: :hidden: duallist form iconandtext help + picker settings viewingediting - :doc:`duallist` - :doc:`form` - :doc:`iconandtext` - :doc:`help` +- :doc:`picker` - :doc:`settings` - :doc:`viewingediting` diff --git a/source/patterns/content/picker.rst b/source/patterns/content/picker.rst index 421e737..24dd136 100644 --- a/source/patterns/content/picker.rst +++ b/source/patterns/content/picker.rst @@ -1,50 +1,58 @@ Picker ====== Pickers are a pattern to select multiple items from a list of available choises. The main component only displays the selected items. More items can be added by choosing them from a list or grid in an dialog or overlay. In compairison to dual lists, they work well on desktop and mobile. Example ------- -.. figure:: /img/LanguagePicker.png.png +.. figure:: /img/LanguagePicker.png :alt: Picker in Language KCM + :scale: 60% Use of a picker to select aditional languages. When to use ----------- - Use a picker for multiple selection and in case of large lists. - Don't use it if both selected and unselected items need to be visible at once. Use a dual list instead. - Do not use a picker to show data primarily. - If selection state needs to change often, think about using a list with checkboxes or similar instead. How to use ---------- -- Use a grid or a list to display the selected elemets. +.. figure:: /img/PickerOverlay.png + :alt: Using an overlay + :scale: 60% + + Using an overlay to pick aditional items. + +- Use a :doc:`grid ` or a + :doc:`list ` to display the selected elemets. - Open list of additional items to choose in a overlay sheet or a dialog - Allow the user to select multiple items at once. - Use either an on demand control or display an button to allow the user to deselect items. - If the list of selected items can be reordered, place up/down buttons to the right of the list of current items. Only enable the up/down buttons when an item is selected and can be moved. - 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. Alphabetical sorting should be able to change when the text is translated. - If the lists or grids appears in a dialog, consider making the window and the lists or grids within it resizeable so that the user can choose how many list items are visible at a time without scrolling. - Use :doc:`sentence style capitalization ` for items.