diff --git a/HIG/source/_static/css/breeze.css b/HIG/source/_static/css/breeze.css index 0bff473..91367fe 100644 --- a/HIG/source/_static/css/breeze.css +++ b/HIG/source/_static/css/breeze.css @@ -1,271 +1,375 @@ @import url('https://fonts.googleapis.com/css?family=Noto+Sans'); /* color definitions */ .iconred { color: #da4453; } .plasmablue { color: #3daee9; } .noblefir { color: #27ae60; } body { font-family: "Noto Sans","Helvetica Neue", Arial, sans-serif; font-size: 14px; color: #232627; } h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { margin-top: 0; font-weight: 700; font-family: "Noto Sans", "Helvetica Neue", Arial, sans-serif; } p, ul > li, a { font-size: 14px; } a.reference, a:visited { color: #2980b9; } a.icon { color: #fcfcfc; } .flex { display: flex; flex-wrap: wrap; align-items: flex-start; } .flex > * { margin-right: 18px; max-width: 340px; } .flex > *:last-child { margin-right: 0; } .wy-nav-side { background-color: #eff0f1 !important; box-shadow: 0 1px 4px 0 rgba(0,0,0,.37); } .wy-side-nav-search { background-color: #27ae60 !important; } .wy-side-nav-search .icon-home:before { vertical-align: middle; font-size: 350%; display: "block"; } .wy-side-nav-search > div.version { color: rgba(255,255,255,0.7); } .wy-side-nav-search input[type="text"] { border-radius: 4px; border: 0 solid transparent; } .wy-nav-content-wrap { background-color: #fcfcfc; } .wy-menu-vertical a { color: #232627; } .wy-menu-vertical .current a { color: #232627; } .wy-menu-vertical a:hover { background-color: #93cee9; cursor: pointer; } .wy-menu-vertical li.toctree-l2 > a:hover { background: #93cee9; } .wy-menu-vertical li.toctree-l2.current > a { background-color: #fcfcfc; color: #232627; } .wy-menu-vertical li a.current:last-of-type { background: #3daee9; color: #fcfcfc; } .wy-menu-vertical li.current a { color: #232627; border-top: none; border-bottom: none; } .wy-menu-vertical li.toctree-l2.current li.toctree-l3.current > a { background: #3daee9; color: #fcfcfc; } .wy-menu-vertical li.toctree-l2 li.toctree-l3 > a:hover { background: #93cee9; } .admonition { box-shadow: 1px 1px 2px 2px rgba(0,0,0,.17); } .admonition.caution .admonition-title { background-color: #fdbc4b; } .admonition.hint .admonition-title { background-color: #27ae60; } .btn { background-color: #eff0f1 !important; box-shadow: 0.5px 0.5px 0.5px 0.5px rgba(35,38,39,.1); border-color: #bdc3c7; border-radius: 3px; padding: 8px; } .btn:hover { border-color: #93cee9; background-color: #eff0f1 !important; } .btn:active { box-shadow: 0.5px 0.5px 0.5px 0.5px rgba(35,38,39,.1); padding: 8px; } [itemprop='articleBody'] { position: relative; } .intend { position: absolute; top: 0; right: 0; color: #7f8c8d; } @media (max-width: 950px) { .intend { position: static; } } .intend p:before { content: "For " } .intend a + a:before { content: " and "; color: #7f8c8d; } .available { color: #da4453; } .border img { border: 1px solid #bdc3c7; } .available.qwidgets:before { content: 'Not available for qWidgets' } .available.plasma:before { content: 'Not available for Plasma' } .available.plasma.qwidgets:before { content: 'Not available for Plasma and qWidgets' } @font-face { font-family:"icons"; src:url("icons.eot?842739648e48d469142df14af06c1a3c"); src:url("icons.eot?#iefix") format("embedded-opentype"), url("icons.woff2?842739648e48d469142df14af06c1a3c") format("woff2"), url("icons.woff?842739648e48d469142df14af06c1a3c") format("woff"), url("icons.ttf?842739648e48d469142df14af06c1a3c") format("truetype"), url("icons.svg?842739648e48d469142df14af06c1a3c#icons") format("svg"); font-weight:normal; font-style:normal; } .fa-arrow-circle-left:before { font-family:"icons"; content:"\f101"; } .fa-arrow-circle-right:before { font-family:"icons"; content:"\f102"; } .icon-home:before { font-family:"icons"; content:"\f104"; } .wy-nav-top { background-color: #27ae60; } .wy-nav-top a:visited { color: #fcfcfc; } /* * Add more spacing and a 1px seperator between sections */ div[itemprop="articleBody"] .section:not(:first-of-type) { margin-top: 20px; padding-top: 20px; } div[itemprop="articleBody"] > .section > .section:not(:first-of-type) { border-top: 1px solid #bdc3c7; margin-top: 30px; padding-top: 30px; } /* Increase font sized to have more visual difference */ h1 { font-size: 300%; margin-bottom: 8px; font-weight: normal; } h2 { font-size: 240%; margin-bottom: 8px; font-weight: normal; } h3 { font-size: 180%; margin-bottom: 8px; font-weight: normal; } h4 { font-size: 140%; margin-bottom: 8px; font-weight: normal; } h5 { font-size: 120%; margin-bottom: 10px; font-weight: normal; } .rst-content img, video, audio { height: auto !important; max-width: 100%; } + +@media (prefers-color-scheme: dark) { + .wy-body-for-nav, .wy-nav-content-wrap { + background: left repeat-y #31363b; + color: #eff0f1; + } + + .wy-table-odd td, .wy-table-striped tr:nth-child(2n) td, .rst-content table.docutils:not(.field-list) tr:nth-child(2n) td { + background-color: #232629; + } + + .wy-table-odd td, .wy-table-striped tr:nth-child(2n-1) td, .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td { + background-color: #31363b; + } + + .wy-table thead, .rst-content table.docutils thead, .rst-content table.field-list thead { + color: #eff0f1; + } + + a:hover { + color: #3daee9; + } + + .wy-table td:first-child, .rst-content table.docutils td:first-child, .rst-content table.field-list td:first-child, .wy-table th:first-child, .rst-content table.docutils th:first-child, .rst-content table.field-list th:first-child { + border-left-width: 1px; + } + .btn.btn-neutral { + background-color: #31363b !important; + color: #eff0f1 !important; + } + + footer { + color: #bdc3c7; + } + + .wy-nav-side { + background-color: #232629 !important; + color: #eff0f1; + } + + .wy-menu-vertical .current a { + color: #eff0f1; + } + + .wy-menu-vertical li:hover > a, .wy-menu-vertical li.toctree-l2 > a:hover { + color: #232627; + } + + .wy-menu-vertical li.current { + background: #31363b !important; + } + + .wy-menu-vertical li.current a { + color: #eff0f1; + } + + .wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a { + background: #4d4d4d; + } + + .wy-menu-vertical li.current a, .wy-menu-vertical li.toctree-l2 a:hover span.toctree-expand { + color: #eff0f1; + } + .wy-menu-vertical li.on a span.toctree-expand, .wy-menu-vertical li.current > a span.toctree-expand { + color: #afb0b3; + } + + .wy-menu-vertical li.current a { + color: #eff0f1; + } + + .wy-menu-vertical li.toctree-l2.current > a, .wy-menu-vertical li.on a, .wy-menu-vertical li.current > a, .wy-menu-vertical li.on a:hover, .wy-menu-vertical li.current > a:hover { + background-color: rgb(20,20,20); + color: #eff0f1; + } + + .wy-alert.wy-alert-info, .rst-content .note, .rst-content .wy-alert-info.attention, .rst-content .wy-alert-info.caution, .rst-content .wy-alert-info.danger, .rst-content .wy-alert-info.error, .rst-content .wy-alert-info.hint, .rst-content .wy-alert-info.important, .rst-content .wy-alert-info.tip, .rst-content .wy-alert-info.warning, .rst-content .seealso, .rst-content .wy-alert-info.admonition-todo { + background: #31363b; + } + + .wy-alert.wy-alert-warning, .rst-content .wy-alert-warning.note, .rst-content .attention, .rst-content .caution, .rst-content .wy-alert-warning.danger, .rst-content .wy-alert-warning.error, .rst-content .wy-alert-warning.hint, .rst-content .wy-alert-warning.important, .rst-content .wy-alert-warning.tip, .rst-content .warning, .rst-content .wy-alert-warning.seealso, .rst-content .admonition-todo { + background: #f67400; + } + + .wy-alert.wy-alert-success, .rst-content .wy-alert-success.note, .rst-content .wy-alert-success.attention, .rst-content .wy-alert-success.caution, .rst-content .wy-alert-success.danger, .rst-content .wy-alert-success.error, .rst-content .hint, .rst-content .important, .rst-content .tip, .rst-content .wy-alert-success.warning, .rst-content .wy-alert-success.seealso, .rst-content .wy-alert-success.admonition-todo { + background: #27ae60; + + } + + .admonition.hint .admonition-title { + background: rgba(255, 255, 255, 0.5); + } + + img[alt="desktopicon"], img[alt="mobileicon"], img[alt="touchicon"] { + filter: contrast(0%); + } + + .rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal { + background: #232629; + border-width: 0px; + color: #da4453; + } +} + diff --git a/HIG/source/components/editing/list.rst b/HIG/source/components/editing/list.rst index 5679260..1cb878f 100644 --- a/HIG/source/components/editing/list.rst +++ b/HIG/source/components/editing/list.rst @@ -1,305 +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 +.. image:: /img/Slide_to_reveal.png :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 ` .. literalinclude:: /../../examples/kirigami/AddressbookListView.qml :language: qml Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ListItem ` diff --git a/HIG/source/img/Breeze-icon-design-creative-backgrounds.png b/HIG/source/img/Breeze-icon-design-creative-backgrounds.png index 3109d7c..1987135 100644 Binary files a/HIG/source/img/Breeze-icon-design-creative-backgrounds.png and b/HIG/source/img/Breeze-icon-design-creative-backgrounds.png differ diff --git a/HIG/source/img/Pixel.qml.png b/HIG/source/img/Pixel.qml.png index a975dd6..bf9d32a 100644 Binary files a/HIG/source/img/Pixel.qml.png and b/HIG/source/img/Pixel.qml.png differ diff --git a/HIG/source/img/Sample_color_icons.png b/HIG/source/img/Sample_color_icons.png index 2ce9b75..61654e5 100644 Binary files a/HIG/source/img/Sample_color_icons.png and b/HIG/source/img/Sample_color_icons.png differ diff --git a/HIG/source/img/Slide_to_reveal.jpg b/HIG/source/img/Slide_to_reveal.jpg deleted file mode 100644 index 6ba2be4..0000000 Binary files a/HIG/source/img/Slide_to_reveal.jpg and /dev/null differ diff --git a/HIG/source/img/Slide_to_reveal.png b/HIG/source/img/Slide_to_reveal.png new file mode 100644 index 0000000..0946bef Binary files /dev/null and b/HIG/source/img/Slide_to_reveal.png differ diff --git a/HIG/source/img/plasma-workspace.jpg b/HIG/source/img/plasma-workspace.jpg deleted file mode 100644 index ffbd97f..0000000 Binary files a/HIG/source/img/plasma-workspace.jpg and /dev/null differ diff --git a/HIG/source/img/plasma-workspace.png b/HIG/source/img/plasma-workspace.png new file mode 100644 index 0000000..a369bcc Binary files /dev/null and b/HIG/source/img/plasma-workspace.png differ diff --git a/HIG/source/introduction/architecture.rst b/HIG/source/introduction/architecture.rst index bcc8ab1..40dabdf 100644 --- a/HIG/source/introduction/architecture.rst +++ b/HIG/source/introduction/architecture.rst @@ -1,121 +1,121 @@ Architecture ============ There are three different UI toolkits you can use to development for `KDE Application `_ or the `Plasma Workspace `_ (Due to technical limitations, the toolkits have slight visual differences, but the recommended interaction patterns to be used are consistent regardless of the toolkit). KDE Applications ---------------- There are two UI toolkits that can be used to develop KDE Applications: * `Kirigami `_ * `Qt Widgets `_ Kirigami is KDE’s lightweight user interface framework for mobile and convergent applications. It allows Qt developers to easily create applications that run on most major mobile and desktop platforms without modification (though adapted user interfaces for different form-factors are supported and recommended for optimal user experience). It extends the touch-friendly Qt Quick Controls with larger application building blocks. Use Qt Widgets only if you plan to develop a desktop-only application with a complex UI, like KDevelop. .. figure:: /img/kirigami.jpg :scale: 25% :alt: Discover, a convergent application build with Kirigami Discover, a convergent application build using Kirigami .. hint:: |devicon| To test qml scenes use * ``QT_QUICK_CONTROLS_MOBILE=1`` and ``QT_QUICK_CONTROLS_STYLE=Plasma`` for mobile * ``QT_QUICK_CONTROLS_MOBILE=0`` and ``QT_QUICK_CONTROLS_STYLE=org.kde.desktop`` for desktop Plasma Workspace ---------------- Plasma is built on widgets, allowing you to move, mix, add, and remove just about everything to perfect your personal workflow. Use `plasma components v3 `_ to develop widgets for the :doc:`Plasma Mobile ` and Plasma Desktop workspace. -.. figure:: /img/plasma-workspace.jpg +.. figure:: /img/plasma-workspace.png :scale: 25% :alt: Plasma desktop and mobile workspace Plasma desktop and mobile workspace. Common Components ----------------- The KDE HIG defines a set of common components which are independent of any :doc:`device type `. .. figure:: /img/Desktop_UX.png :scale: 25% :alt: Example showing the common components on a Desktop device type - **Workspace**: The top-level container of the whole user interface. Often called "desktop", "home screen", or "shell", it shows the wallpaper and allows users to add widgets, app launchers, files or folders. - **Application Launcher**: Provides an overview of installed applications and allows the user to launch one of them. - **Application Shortcuts**: Provides quick access to frequently-used applications. - **Active Application Overview**: Provides an overview of the active applications that are directly used by the user. - **Workspace Tools**: Provides quick access to functionality integrated into the workspace that's both highly visible to the user and frequently changed, like enabling/disabling WiFi and Bluetooth, or whether or not to show notifications. - **Application-Workspace Interaction**: Displays information about each application's windows, and provides ways to move or close them and change how they run within the workspace. - **Application**: The top-level container of a single application. - **Application Tools**: Provides access to an application's commonly-used functionality in an always-accessible toolbar or menubar. These tools should not change depending on what the application is displaying. - **Application Content**: The actual content of an application. This depends on the application itself, but conformance to the KDE HIG should make it easier to allow :doc:`convergence ` for this component. This part of the application can also contain contextually-appropriate tools that operate directly on the active or selected content. .. figure:: /img/Mobile-UX.png :scale: 50% :alt: Example showing the common components on a Mobile device type Theme ----- There are three different kinds of themes influencing the the look-and-feel of KDE applications and the Plasma workspace. * Workspace * Application * Window decoration The default for all there of them is *Breeze*. .. note:: Only *Breeze*, *Breeze dark*, *Breeze Light*, *Breeze Highcontrast* are covered by the HIG, all other themes are not covered. .. figure:: /img/breeze.jpeg :scale: 50% :alt: Overview of breeze controls Overview of breeze controls