...
 
Commits (21)
......@@ -121,7 +121,7 @@ Color and Contrast
- The software is not dependent on any particular
:doc:`high contrast themes </style/color/high>` or settings.
See :doc:`the HIG's page about color </style/color/index>` and
See :doc:`the HIG's page about color </style/color/index>` and
:doc:`colors in Kirigami <kirigami:style/color>` for more information.
Testing
......
......@@ -57,5 +57,5 @@ if the number is very large.
Notification emblem with a large number
For symbolic icon emblems, see the :doc:`Breeze icon guidelines </style/icon>`.
For symbolic icon emblems, see :doc:`/style/icons/emblem`.
......@@ -53,8 +53,8 @@ Guidelines
any other side effect.
- Don't 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.
- Consider to show a :doc:`notification </platform/notification>` if
information does not concern the current workflow.
Is this the right control? / Behavior
-------------------------------------
......
......@@ -58,17 +58,21 @@ It is recomended that you use the standard card layout for consistency, but card
a lot of different layouts.
.. figure:: /img/Card6.qml.png
:alt: Default card layout with a header image, text content, and optional actions.
:alt: Default card layout with a header image, text content, and optional
actions.
Default card layout with a header image, text content, and optional actions.
Default card layout with a header image, text content, and optional
actions.
The only common requirement is the container around it. While cards can have a lot of
The only common requirement is the container around it. While cards can have a
lot of
different layouts, each should focus only on one bit of information or content.
Here are some general recommendations for card layouts:
- Use images, icons or video elements to create visually immersive cards.
Feel free to use different text sizes, cards are not a control for plain text.
Feel free to use different text sizes, cards are not a control for plain
text.
- Use a well known aspect ratio for a header image
......@@ -86,6 +90,7 @@ Here are some general recommendations for card layouts:
Padding for text and buttons.
Code
----
......@@ -96,3 +101,6 @@ Kirigami
- :kirigamiapi:`Kirigami: CardsGridView <CardsGridView>`
- :kirigamiapi:`Kirigami: CardsLayout <CardsLayout>`
- :kirigamiapi:`Kirigami: CardsListView <CardsListView>`
.. literalinclude:: /../../examples/kirigami/Card.qml
:language: qml
......@@ -40,7 +40,8 @@ Is this the right control?
- Use a combo box for single selection of one out of many items of
lists that can be extended by the user. Prefer a simple :doc:`drop-down list <dropdown>` in case of read-only interaction.
- Consider to replace the combo box by a :doc:`list view <list>` with a connected :doc:`edit control <editcontrol>`.
- Consider to replace the combo box by a :doc:`list view <list>` with a
connected :doc:`line edit control <lineedit>`.
Behavior
~~~~~~~~
......
Grid
====
.. image:: /img/Grid1.png
:alt: Grid
Like a table, a grid is a structure to distribute items into rows and columns.
Unlike a table, a grid doesn't have a fixed structure; rather, the rows and
columns are determent by the available space.
.. figure:: /img/Wallpaper-dark.png
:alt: Choose a new Plasma Design
:scale: 40%
Choose a new wallpaper
Guidelines
----------
Is this the right control?
~~~~~~~~~~~~~~~~~~~~~~~~~~
Like :doc:`lists <list>`, Grids are used to display a sorted or unsorted set of
items. All items should be of the same kind.
Behavior
~~~~~~~~
On mouseover, items are darkened or highlighted
(depending on the active color scheme) to
emphasize their overlay buttons.
Grids adjust the number of columns dynamically to distribute the items according
to the available horizontal space without making the grid horizontally
scrollable. Grids can be vertically scrollable though.
.. raw:: html
<video autoplay controls
src="https://cdn.kde.org/hig/video/20180620-1/CardLayout2.webm" loop="true"
playsinline="true" width="536" onended="this.play()" class="border"></video>
- Don't have blank grid items; use meta-options, e.g. (None) instead.
- Place options that represent general options (e.g. All, None) at the
beginning of the grid.
- Sort grid items in a logical order. Make sure sorting fits translation.
.. attention::
|devicon| For :doc:`accessibility </accessibility/index>` make sure to test
keyboard navigation with the grid.
On-Demand Actions
^^^^^^^^^^^^^^^^^
Overlay Buttons
^^^^^^^^^^^^^^^
Grid items can use the :doc:`on-demand pattern </patterns/command/ondemand>`
for inline actions.
Overlay buttons only appear on mouseover. Overlay buttons should
only affect the item they are on. They should never affect other items.
Picker
^^^^^^
Grids can be used for the :doc:`picker pattern </patterns/content/picker>`.
Place a button below the grid to add items to the grid. To remove items from
the grid, either add a 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
grid.
Ordering
^^^^^^^^
If the the order of the items can be changed by the user, permit re-ordering via
drag-and-drop.
Appearance
~~~~~~~~~~
- All items must be the same size.
- All rows, except the last one, have the same number of items
- Overlay buttons are placed at the bottom right corner of items.
- Grids have a PaperWhite background on desktop, and no background on
mobile.
- All items must be the same size. Item can change their size, either through
user input or as a response to changes of the available space for the grid.
- All rows, except the last one, must have the same number of items.
- Use :doc:`sentence style capitalization </style/writing/capitalization>`
for grid view items.
Cards
^^^^^
See :doc:`cards <card>` for more information on how to use cards in a grid view.
KCM
^^^
Use the :doc:`KCMGrid </platform/kcmgrid>` for grids in KCMs.
Code
----
......@@ -36,4 +89,3 @@ Kirigami
~~~~~~~~
- `QML: GridView <https://doc.qt.io/qt-5/qml-qtquick-gridview.html>`_
- :kirigamiapi:`Kirigami: CardsGridView <CardsGridView>`
......@@ -43,6 +43,10 @@ Behavior
- Sort list items in a logical order. Make sure sorting fits
translation.
.. attention::
|devicon| For :doc:`accessibility </accessibility/index>`, make sure to test
keyboard navigation with the list.
On-Demand Actions
^^^^^^^^^^^^^^^^^
......
......@@ -6,7 +6,7 @@ Purpose
A group box is a labeled rectangular area that surrounds a set of
related controls. A frame is an unlabeled rectangular area that
can be used to mark relationships.
can be used to mark relationships.
Group box and frame are a way to show visual relationships; it provides
no additional functionality.
......
......@@ -72,8 +72,8 @@ 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 </patterns/content/settings>` in the last position if the
application has settings which are not commonly changed
- Should contain an entry :doc:`Settings </platform/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
......
......@@ -69,7 +69,7 @@ Appearance
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 <shortcuts>` to the most frequently used menu items
- Assign 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).
......
......@@ -98,7 +98,7 @@ Appearance
- Provide a label with an access key for each tab. Use nouns with
:doc:`title capitalization </style/writing/capitalization>` to
describe the content.
- Don't expand tabs to use empty space of the widget (see `expanding`_
- Don't expand tabs to use empty space of the widget (see the ``expanding``
property of the Qt tab bar, unfortunately true by default).
- Avoid long tab names. Use a compelling, easy to understand label.
Phrases not sentences.
......
......@@ -91,7 +91,8 @@ Appearance
- 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 </style/icon>`.
depiction is crucial. Follow the advices for :doc:`icon design
</style/icons/index>`.
- Don't simulate Microsoft's ribbon controls.
Code
......
......@@ -18,8 +18,6 @@
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
from sphinx.util.console import bold
import requests
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
......@@ -91,8 +89,7 @@ html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
from globalconf import html_theme_options
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
......@@ -204,17 +201,8 @@ rst_epilog += """
"""
doxylink = {
'kirigamiapi' : ('Kirigami2.tags', 'https://api.kde.org/frameworks/kirigami/html/'), # https://api.kde.org/frameworks/kirigami/html/Kirigami2.tags
'kwidgetsaddonsapi' : ('KWidgetsAddons.tags', 'https://api.kde.org/frameworks/kwidgetsaddons/html/'), # https://api.kde.org/frameworks/kwidgetsaddons/html/KWidgetsAddons.tags
'plasmaapi' : ('Plasma.tags', 'https://api.kde.org/frameworks/plasma-framework/html/') # https://api.kde.org/frameworks/plasma-framework/html/Plasma.tags
}
for doc in doxylink.values():
print(bold("Downloading file {} to {}".format(doc[1] + "/" + doc[0], doc[0])))
tagFile = open("../" + doc[0], "w")
tagFile.write(requests.get(doc[1] + "/" + doc[0]).text)
tagFile.close()
from globalconf import get_doxylink
doxylink = get_doxylink()
rst_prolog = """
......@@ -228,7 +216,7 @@ rst_prolog = """
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
'kirigami': ('https://kirigami.kde.org/', None),
'kirigami': ('https://kirigami.kde.org', None),
'pm': ('https://docs.plasma-mobile.org', None)
}
......
......@@ -18,9 +18,10 @@ KDE Human Interface Guidelines
patterns/content/index
patterns/navigation/index
accessibility/index
plattform/index
platform/index
resources/about
resources/contribute
resources/media
resources/glossary
......
......@@ -87,7 +87,7 @@ can have issues with text.
Base Units in Plasma and Kirigami
---------------------------------
There a two types of DPI independent base units in Kirigami:
There are two types of DPI independent base units in Kirigami:
- ``Units.gridUnit`` is the height needed to display one line of text.
Use this for defining height and width of an element.
......
......@@ -49,7 +49,5 @@ Bottom Drawer and Dialog Sheet
:alt: Bottom drawer
:scale: 40 %
For a full modal dialog, use a
:doc:`dialog sheet </components/navigation/dialogsheet>`.
For a quick choice, use a
:doc:`bottom drawer </components/navigation/bottomdrawer>`.
For a full modal dialog, use a dialog sheet. For a quick choice, use a bottom
drawer.
......@@ -41,9 +41,10 @@ On mobile, a toolbar is diplayed as a group of
- If there are controls that need to be accessed often within the
application's primary tasks but the content needs as much space to be
available as possible, you can add up to three primary action buttons
- The primary action buttons are at the bottom of the user interface and
there cannot be more then three buttons.
- If more than three actions are required, put the remaining ones in the
available as possible, you can add up to three primary action buttons.
- The primary action buttons are at the bottom of the user interface and there
cannot be more then three buttons.
- If more than three actions are required,
put the remaining ones in the
:doc:`global drawer </components/navigation/globaldrawer>`
or :doc:`context drawer </components/navigation/contextdrawer>`.
Form
====
A form layout is used to help align and structure a layout containing many
control and input fields.
A form layout is used to help align and structure a layout that contains many
controls and input fields.
When to Use
-----------
- Use a Form layout when there are many related controls and input fields.
- Form layouts are ideal for :doc:`settings dialogs </patterns/content/settings>`.
- Form layouts are often used for :doc:`settings </platform/settings>`.
How to Use
----------
- On |desktopicon| Desktop it is recommended to place the labels to the left
- Use Qt's QFormLayout or Kirigami.FormLayout wherever possible.
- Do not synthesize your own FormLayout-style layout using a grid.
.. attention::
|devicon| If for some reason you must create your own FormLayout style layout
without using one of the aforementioned controls, there are several very
important things to take into account for
:doc:`accessibility </accessibility/index>` reasons""
- Form labels need to be connected with input fields.
- Headlines for groupings need to be connected.
- Make sure to test keyboard navigation with the form.
- Ctrl + Tab should switch between logical groups of controls.
- Make sure to set the focus to focused controls; don't just highlight them.
Alignment
^^^^^^^^^
|desktopicon| Desktop
"""""""""""""""""""""
- On Desktop it is recommended to place the labels to the left
of the connected widgets. Labels that are to the left of their connected
widgets should be right-aligned and end with a colon (in case of
right-to-left languages, mirror the alignment). This makes the whole group
of form widgets appear to be center-aligned. In Qt 5, using a QFormLayout handles all of this for you automatically.
of form widgets appear to be center-aligned. In Qt 5, using a QFormLayout
handles all of this for you automatically.
- Align the form in the top center of the window or view in which it is
located, but below the title.
- See the pages on
:doc:`radio buttons </components/editing/radiobutton>` and
:doc:`checkboxes </components/editing/checkbox>` for detailed information
......@@ -27,7 +55,7 @@ How to Use
.. container::
.. figure:: /img/Form_Align_KDE3.qml.png
.. figure:: /img/Form_Align_KDE3.png
:scale: 80%
:figclass: dont
......@@ -36,7 +64,7 @@ How to Use
.. container::
.. figure:: /img/Form_Align_KDE5.qml.png
.. figure:: /img/Form_Align_KDE5.png
:scale: 80%
:figclass: do
......@@ -47,7 +75,7 @@ How to Use
.. container::
.. figure:: /img/Form_Align_OSX.qml.png
.. figure:: /img/Form_Align_OSX.png
:scale: 80%
:figclass: dont
......@@ -56,7 +84,7 @@ How to Use
.. container::
.. figure:: /img/Form_Align_KDE5.qml.png
.. figure:: /img/Form_Align_KDE5.png
:scale: 80%
:figclass: do
......@@ -74,7 +102,7 @@ How to Use
.. container::
.. figure:: /img/Form_Align_NO.qml.png
.. figure:: /img/Form_Align_NO.png
:scale: 80%
:figclass: dont
......@@ -83,29 +111,78 @@ How to Use
.. container::
.. figure:: /img/Form_Align_YES.qml.png
.. figure:: /img/Form_Align_YES.png
:scale: 80%
:figclass: do
:noblefir:`Do.` |br|
Align controls to the left.
- Keep track of label sizes; avoid big differences in text length that could
result in too much whitespace for multiple aligned controls. Keep
translation in mind too; existing length differences will be exaggerated
for wordy languages such as German and Brazilian Portuguese.
- Keep track of label sizes; avoid large differences in text length that could
result in too much whitespace. Keep translation in mind too; existing length
differences will be exaggerated for wordy languages such as German and
Brazilian Portuguese.
.. figure:: /img/Form_Align_Long.qml.png
.. figure:: /img/Form_Align_Long.png
:scale: 80%
:figclass: dont
:iconred:`Don't.` |br|
Don't use very long captions.
- For |mobileicon| mobile, or if only narrow space is available, it is
recommended to place the labels above the connected widgets.
|mobileicon| Mobile and narrow space
""""""""""""""""""""""""""""""""""""
- For mobile, or if only a very small amount of horizontal space is available,
it is recommended to place the labels above the connected widgets.
- When using labels on top, labels and widgets should be left-aligned.
.. image:: /img/Form_Align_YES_Mobile.qml.png
.. image:: /img/Form_Align_YES_Mobile.png
:scale: 80%
Titles
""""""
.. figure:: /img/Settings-Notification-dark.png
:alt: Notifications settings in a form layout
:scale: 40%
Notifications settings
Spacing and Grouping
^^^^^^^^^^^^^^^^^^^^
Use :doc:`spacing </layout/metrics>` to group and separate controls in your
forms.
.. figure:: /img/Form3.png
Spacing used to create three groups of controls
Alternatively, you can use separators for a stronger separation.
.. figure:: /img/Form4.png
Using a separator to group controls
To create even stronger separation, you can add subtiles for groups of
controls. Subtitles are left aligned with the longest label of their group.
.. figure:: /img/Form5.png
Alignment of subtitles
Code
----
Kirigami
^^^^^^^^
- :kirigamiapi:`Kirigami: FormLayout <FormLayout>`
.. literalinclude:: /../../examples/kirigami/FormLayout.qml
:language: qml
......@@ -11,7 +11,6 @@ Content Patterns
iconandtext
help
picker
settings
viewingediting
- :doc:`duallist`
......@@ -19,5 +18,4 @@ Content Patterns
- :doc:`iconandtext`
- :doc:`help`
- :doc:`picker`
- :doc:`settings`
- :doc:`viewingediting`
......@@ -38,20 +38,20 @@ How to Use
Using an overlay to pick aditional items.
- Use a :doc:`grid </components/editing/grid>` or a
:doc:`list </components/editing/list>` to display the selected elemets.
- Open list of additional items to choose in a overlay sheet or a dialog
:doc:`list </components/editing/list>` to display the selected elements.
- Open a list of additional items to choose in an 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
- Use either an on-demand control or display a 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.
- Don't have blank list items; use meta-options, (e.g. "None") instead.
- Don't 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
- If the lists or grids appear 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 </style/writing/capitalization>`
......
Settings
========
A settings page provides the ability to customize how an application or
Plasma widget should behave. It is intended for settings that are persistent but not changed very frequently. Following KDE's "Simple by
default, powerful when needed" :doc:`design mantra <../../index>`,
settings are split into common and advanced groups. Advanced settings are
not important to most users but essential for some, and therefore cannot be
removed. Those settings are hidden by default to reduce the mental overhead
of using the settings page, but with easy access.
When to Use
-----------
- Use the settings page to display settings that are persistent but not
accessed or changed very frequently. The toolbar or the main menu (and optionally context menus) are more appropriate places for settings that
are frequently accessed and changed, such as icon view style or sort order.
- Don't use settings pages to change the properties of a selected item.
Instead, use a properties dialog or a contextual editing panel.
- Don't use the settings page for potentially dangerous developer settings
like the name of an SQL table. Instead, use configuration files or separate
dialogs.
How to Use
----------
- **Simple by default**: Define smart and polite defaults so that your target
:doc:`personas </introduction/personas>` don't have to alter them at all.
- **Powerful when needed**: Provide enough settings for the perfect
customization according individual needs and preferences. But even
though customizability is very important for KDE software, try to
keep your settings page as small and simple as possible. Remember:
every option requires more code and more testing, and makes the settings
page slower to use.
- Respect the privacy of the users: Always use opt-in, never an opt-out
model for features that transmit potentially private data (e.g. usage
statistics). See KDE's
`Telemetry Policy <https://community.kde.org/Policies/Telemetry_Policy>`_
for details.
Implementation
--------------
- For a desktop app, put your settings page inside a dialog window and don't
allow it to have a vertical or horizontal scrollbar because all of the
content will not fit. Instead, separate your controls into more groups and
make use of :doc:`tabbed views </components/navigation/tab>`. This does not apply to scrollbars within inline tables and grid views, which are
acceptable.
- On mobile, use a full-screen view for your settings page. Vertical scrolling
is acceptable.
- Lay out your settings page according to the
:doc:`alignment </layout/alignment>` guidelines. The overall layout
should appear to be centered, with with section labels on the left side,
and controls on the right. Tables and grid views are the exception, and
should span the window width.
- Organize your settings into logical groups, with more important groups
appearing higher up on the page. Separate the groups with whitespace or
put them into different tabs of a
:doc:`tabbed view </components/navigation/tab>` (if appropriate).
Try to avoid the use of group boxes to distinguish sections.
(#1 in the example)
- Separate common and advanced settings into different groups. If necessary,
hide the advanced settings behind a collapsible group box. Make the
standard settings comprehensible and easy to use. (#5)
- Consider adding access to third-party add-ons via Get Hot New Stuff!,
if available for this group. Use the label "Get New [term used for
add-on content]s" (#4)
- When a change is applied, the application should adopt it immediately
without the need to restart it.
- Don't change the settings page depending on the context. It
should always start with the same landing page regardless of the
application context.
- Don't use a wizard to change settings. Only use a wizard if a group of
settings are all interrelated and must be edited all at once, e.g.
setting up an email account.
- If some of the program's settings are only applicable in certain contexts,
don't hide the inapplicable ones. Instead, disable them and hint to the
user why they're disabled.
**Exception:** it is acceptable to hide settings for non-existent hardware.
For example, it's okay to hide the touchpad configuration when no touchpad
is present.
Mockup
~~~~~~
.. image:: /img/HIG-Settings.png
:alt: HIG-Settings.png
#. Access groups via sidebar.
#. The preview has to be on the top of the content area.
#. Offer a good number of pre-defined profiles/schmes to let the user
choose one out of different factory settings. Anchor the profiles so
that users can have more space for the area below using the
horizontal splitter. Cut long captions with ellipsis and show the
full name in a tooltip.
(Remark 1: The mockup has very large splitters. The implementation
should be visually less obtrusive.)
(Remark 2: The profile selection replaces the former "reset (to
default)" function.)
#. Allow users to add more profiles via Get Hot New Stuff (GHNS).
Organize the setting in a way that GHNS access is per group and not
global.
#. Provide access to the most relevant settings at the Standard section.
Make sure that these settings are easy to understand.
#. Indicate that Advanced settings are available but keep this section
collapsed by default. Use a descriptive label so that it reflects the
functionality.
#. Allow users to export the current settings to a file that can be
easily imported on any other machine.
#. Allow to Apply the current settings to the application without
closing the dialog.
#. Provide access to functions for user-defined profiles per context
menu and standard shortcuts.
#. Scroll the whole area of options but neither the preview not the
profiles, if necessary.
......@@ -26,12 +26,12 @@ When to Use
Column-based navigation is ideal for navigating through a hierarchically
organized information space, where users often go back and forth between
different levels of the hierarchy
different levels of the hierarchy.
For example:
- Accounts ->Folders -> (Sub-Folders) -> Mails -> Invidual mail
- Accounts ->Folders -> (Sub-Folders) -> Mails -> Individual mail
- Folders -> RSS Feeds -> Feed items -> Individual item
- File system hirachy
- File system hierarchy
Kirigami implements this pattern in the form of a PageRow, which allows
users to scroll horizontally through pages and allows the application to
......@@ -57,7 +57,7 @@ General
a useful breadcrumb trail.
- When on the lowest level, showing the content of an individual list
item, use a swipe beyond the top/bottom of the content to jump to the
previous/next item in the list
previous/next item in the list.
- For the command structure, see the :doc:`command patterns </patterns/command/index>`.
......
......@@ -16,12 +16,15 @@ Pattern for a flat content structure.
- 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 </patterns/navigation/wizard>` pattern guidelines for
more details on using that pattern.
- See the `draft for wizard pattern guidelines
<https://community.kde.org/KDE_Visual_Design_Group/HIG/Layout/Wizard>`_ 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
-------------------
......
Platform
=========
========
.. toctree::
:titlesonly:
:hidden:
getnew
kcmgrid
notification
settings
tray
This is an overview of how to integrate your application into the
:doc:`Plasma Workspace </introduction/architecture>`.
* :doc:`getnew`
* :doc:`kcmgrid`
* :doc:`notification`
* :doc:`settings`
* :doc:`tray`
KCMGrid
=======
Code
----
Use of KCMGrid in Plasma's System Settings:
.. literalinclude:: /../../examples/kirigami/KCMGrid.qml
:language: qml
......@@ -101,5 +101,5 @@ Code
SLOT(slotOpenChat()) );
notification->sendEvent();
Use :knotificationsapi:`<KNotification>` to send notifications to the
Use :knotificationsapi:`KNotification` to send notifications to the
:doc:`Plasma Workspaces </introduction/architecture>`.
Settings
========
Settings provide the ability to customize the appearance and behavior of an
application, a Plasma widget, or the Plasma Workspace. Dedicated settings views
are intended for settings that are persistent but not changed very frequently.
A settings page for the Plasma Desktop is referred to as a KCM (KDE Config
Module). KCMs can either appear in Plasma's System Settings app, or as
standalone configuration dialogs.
Example
-------
.. figure:: /img/Settings-dark.png
:alt: Buttons on the bottom of the settings
:scale: 60%
Guidelines
----------
When to Use
~~~~~~~~~~~
- Use a settings page to display settings that are persistent but infrequently
accessed or changed. Settings that are frequently accessed and changed (e.g.
an icon view style or list's sort order) should be located close to the
views or tools that they affect, such as in the window's toolbar.
- Don't use a settings page to change the properties of a selected item.
Instead, use a properties dialog or a contextual editing panel.
- Don't use a settings page for potentially dangerous developer settings
like the name of an SQL table. Instead, use configuration files or separate
dialogs.
How to Use
~~~~~~~~~~
- **Simple by default**: Define smart and polite defaults so that your target
:doc:`personas </introduction/personas>` don't have to alter them at all.
- **Powerful when needed**: Provide enough settings for the perfect
customization according to individual needs and preferences. But even
though customizability is very important for KDE software, try to keep your
settings page as small and simple as possible. Remember: every option
requires more code and more testing, and makes the settings page slower to
use.
- Respect the privacy of the users: Always use opt-in, never an opt-out model
for features that transmit potentially private data (e.g. usage statistics).
See KDE's
`Telemetry Policy <https://community.kde.org/Policies/Telemetry_Policy>`_
for details.
- Following KDE's "Simple by default, powerful when needed"
:doc:`design mantra </index>`, settings can be split into common and advanced
groups. Advanced settings are not important to most users but essential for
some. There therefore cannot be removed, but they can be de-emphasized in
visual weight.
Behavior
~~~~~~~~
- When a change is applied, the application should adopt it immediately
without the need to restart it.
- Don't change the settings page depending on the context. It
should always start with the same landing page regardless of the
application context.
- Don't use a wizard to change settings. Only use a wizard if a group of
settings are all interrelated and must be edited all at once, e.g.
setting up an email account.
- If some of the program's settings are only applicable in certain contexts,
don't hide the inapplicable ones. Instead, disable them and hint to the
user why they're disabled.
**Exception:** it is acceptable to hide settings for non-existent hardware.
For example, it's okay to hide the touchpad configuration when no touchpad
is present, or hide multi-screen controls when only one screen is connected.
- Consider adding access to third-party add-ons via
:doc:`Get New Stuff! <getnew>`.
- Ctrl + Tab should switch between logical groups of controls.
.. attention::
|devicon| For :doc:`accessiblity </accessibility/index>` make sure to test
keyboard navigation with the settings. Make sure to set the focus to focused
controls and don't just highlight it.
Appearance
~~~~~~~~~~
- Place the main title at the top left corner of the window or view your form
is placed in.
- For a desktop app, put your settings page inside a dialog window.
- Place Help, Defaults, Reset, OK, Apply, and Cancel buttons on the bottom of
the dialog window.
- If there is a :doc:`Get New Stuff! <getnew>` button, place it above the
bottom row of buttons.
.. figure:: /img/SettingsButtons.png
:alt: Buttons on the bottom of the settings
:scale: 60%
:figclass: border
The *Help*, *Defaults*, *Reset* buttons on the left side.
- Avoid vertical and especially horizontal scrollbars. The dialog should be
large enough to fit its contents without scrolling being necessary. As more
controls are added, err on the side of adding additional pages or
:doc:`tabbed views </components/navigation/tab>`. rather than making the
dialog window larger. This does not apply to scrollbars within inline tables,
lists and grid views.
- On mobile, use a full-screen view for your settings page.
**There are several well established layouts for settings that are used
throughout KDE software:**
Forms
"""""
.. figure:: /img/Settings-Notification-dark.png
:alt: Notifications settings in a form layout
:scale: 40%
Notifications settings in a form layout
Use a :doc:`form </patterns/content/form>` if your settings have many controls
and input fields.
- Lay out your settings page according to the
:doc:`alignment </layout/alignment>` guidelines.
- Organize your settings into logical groups, with more important groups
appearing higher up on the page. Separate the groups with whitespace or
put them into different tabs of a
:doc:`tabbed view </components/navigation/tab>` (if appropriate).
- Separate common and advanced settings into different groups. If necessary,
hide the advanced settings behind a collapsible group box or on another
page or tab. Make the common settings comprehensible and easy to use.
Grid
""""
.. figure:: /img/Wallpaper-dark.png
:alt: Choose a new Plasma Design
:scale: 40%
Choose a new wallpaper
Use a :doc:`grid </components/editing/grid>` for a selection of a single item
when all items are visually distinctive. To implement a grid in a KCM, use the
:doc:`KCMGrid <kcmgrid>`.
Lists
"""""
.. figure:: /img/LanguagePicker.png
:alt: Language settings
:scale: 60%
Language settings
Use a :doc:`picker </patterns/content/picker>` for selection and configuration
of list based settings where the items are not visually distinctive.
.. Mockup
.. ~~~~~~
..
.. .. image:: /img/HIG-Settings.png
.. :alt: HIG-Settings.png
..
..
.. #. Access groups via sidebar.
.. #. The preview has to be on the top of the content area.
.. #. Offer a good number of pre-defined profiles/schmes to let the user
.. choose one out of different factory settings. Anchor the profiles so
.. that users can have more space for the area below using the
.. horizontal splitter. Cut long captions with ellipsis and show the
.. full name in a tooltip.
.. (Remark 1: The mockup has very large splitters. The implementation
.. should be visually less obtrusive.)
.. (Remark 2: The profile selection replaces the former "reset (to
.. default)" function.)
.. #. Allow users to add more profiles via Get Hot New Stuff (GHNS).
.. Organize the setting in a way that GHNS access is per group and not
.. global.
.. #. Provide access to the most relevant settings at the Standard section.
.. Make sure that these settings are easy to understand.
.. #. Indicate that Advanced settings are available but keep this section
.. collapsed by default. Use a descriptive label so that it reflects the
.. functionality.
.. #. Allow users to export the current settings to a file that can be
.. easily imported on any other machine.
.. #. Allow to Apply the current settings to the application without
.. closing the dialog.
.. #. Provide access to functions for user-defined profiles per context
.. menu and standard shortcuts.
.. #. Scroll the whole area of options but neither the preview not the
.. profiles, if necessary.
......@@ -39,5 +39,5 @@ Behavior
Appearance
~~~~~~~~~~
Use a :doc:`monochrome, Shade Black, icon </style/icon>` and use color only to
communicate state.
Use a :doc:`monochrome, shade black icon </style/icons/index>` and use color
only to communicate state.
......@@ -34,7 +34,6 @@ Rectangle {
id: addrbook
index: 3
Component.onCompleted: {
addrbook.pageStack.push(addrbook.detailPage)
qmlControler.start();
}
}
......
import QtQuick 2.6
import QtQuick.Controls 2.0 as Controls
import QtQuick.Layouts 1.2
import org.kde.kirigami 2.4 as Kirigami
import "../../lib" as HIG
import "../../lib/annotate.js" as A
Rectangle {
id: root
width: 600
height: 300
Kirigami.CardsLayout {
x: Kirigami.Units.gridUnit * 2
y: x
width: 500
//height: Layout.preferredHeight
id: layout
Kirigami.Card {
headerOrientation: Qt.Horizontal
actions: [
Kirigami.Action {
text: "Action1"
icon.name: "add-placemark"
},
Kirigami.Action {
text: "Action2"
icon.name: "address-book-new-symbolic"
}
]
banner {
fillMode: Image.Pad
imageSource: "../../../img/coastal-fog/coastal-fog-400x300.png"
title: "Title"
}
contentItem: Controls.Label {
wrapMode: Text.WordWrap
text: "A card can optionally have horizontal orientation.\n In this case will be wider than tall, so is fit to be used also in a ColumnLayout.\nIf you need to put it in a CardsLayout, it will have by default a columnSpan of 2 (which can be overridden)."
}
}
}
HIG.Raster {
z: 1
}
// HACK coordinates are only final after a small delay
Timer {
interval: 1000
repeat: false
running: true
onTriggered: {
var a = new A.An(root);
a.find("privateactiontoolbutton").draw({
"outline": {},
}).first().draw({
"ruler": {},
});
a.find("bannerimage").draw({
"outline": {
"aspectratio": true
}
});
qmlControler.start();
}
}
}
import QtQuick 2.6
import QtQuick.Controls 2.0 as Controls
import QtQuick.Layouts 1.2
import org.kde.kirigami 2.4 as Kirigami
import "../../lib" as HIG
import "../../lib/annotate.js" as A
Rectangle {
id: root
width: 400
height: 420
Kirigami.CardsLayout {
x: Kirigami.Units.gridUnit * 2
y: x
width: 320
//height: Layout.preferredHeight
id: layout
Kirigami.Card {
actions: [
Kirigami.Action {
text: "Action1"
icon.name: "add-placemark"
},
Kirigami.Action {
text: "Action2"
icon.name: "address-book-new-symbolic"
}
]
banner {
imageSource: "../../../img/coastal-fog/coastal-fog-160x90.png"
title: "This is a title"
}
contentItem: Controls.Label {
wrapMode: Text.WordWrap
text: "This is an instance of the Card type: it can optionally have an image, a title and an icon assigned to its banner group property, one or all of the properties together. A Card can also have Actions that will appear in the footer."
}
}
}
/*HIG.Grid {
z: 1
}*/
// HACK coordinates are only final after a small delay
Timer {
interval: 1000
repeat: false
running: true
onTriggered: {
var a = new A.An(root);
a.find("privateactiontoolbutton").draw({
"outline": {},
});
a.find("bannerimage").draw({
"outline": {
// "aspectratio": true
}
});
a.find("card").draw({
"padding": {}
});
qmlControler.start();
}
}
}
import QtQuick 2.6
import QtQuick.Controls 2.0 as Controls
import QtQuick.Layouts 1.2
import org.kde.kirigami 2.4 as Kirigami
import "../../lib" as HIG
import "../../lib/annotate.js" as A
Rectangle {
id: root
width: 600
height: 300
Kirigami.CardsLayout {
x: Kirigami.Units.gridUnit * 2
y: x
width: 500
id: layout
Kirigami.Card {
width: 320
height: 180
headerOrientation: Qt.Horizontal
actions: [
Kirigami.Action {
text: "Action1"
icon.name: "add-placemark"
},
Kirigami.Action {
text: "Action2"
icon.name: "address-book-new-symbolic"
}
]
banner {
imageSource: "../../../img/wallpaper/BytheWater.jpg"
title: "Title"
}
contentItem: Controls.Label {
wrapMode: Text.WordWrap
text: "A card can optionally have horizontal orientation.\n In this case will be wider than tall, so is fit to be used also in a ColumnLayout.\nIf you need to put it in a CardsLayout, it will have by default a columnSpan of 2 (which can be overridden)."
}
}
}
HIG.Raster {
z: 1
}
// HACK coordinates are only final after a small delay
Timer {
interval: 1000
repeat: false
running: true
onTriggered: {
var a = new A.An(root);
a.find("privateactiontoolbutton").draw({
"outline": {},
}).first().draw({
"brace": {
"to": a.find("privateactiontoolbutton").last(),
"center": false
},
});
a.find("bannerimage").draw({
"outline": {label: false}
});
qmlControler.start();
}
}
}
import QtQuick 2.6
import QtQuick.Controls 2.0 as Controls
import QtQuick.Layouts 1.2
import org.kde.kirigami 2.4 as Kirigami
import "../../lib" as HIG
import "../../lib/annotate.js" as A
Rectangle {
id: root
width: 600
height: 420
Kirigami.CardsLayout {
x: Kirigami.Units.gridUnit * 2
y: x
width: 500
id: layout
Kirigami.Card {
banner.imageSource: "../banner.jpg"
header: Rectangle {
color: Qt.rgba(0,0,0,0.3)
implicitWidth: headerLayout.implicitWidth
implicitHeight: headerLayout.implicitHeight - avatarIcon.height/2
ColumnLayout {
id: headerLayout
anchors {
left: parent.left
right: parent.right
}
Controls.Label {
Layout.fillWidth: true
padding: Kirigami.Units.largeSpacing
color: "white"
wrapMode: Text.WordWrap
text: "It's possible to have custom contents overlapping the image, for cases where a more personalised design is needed."
}
Rectangle {
id: avatarIcon
color: "steelblue"
radius: width
Layout.alignment: Qt.AlignHCenter
Layout.preferredWidth: Kirigami.Units.iconSizes.huge
Layout.preferredHeight: Kirigami.Units.iconSizes.huge
}
}
}
contentItem: Controls.Label {
wrapMode: Text.WordWrap
topPadding: avatarIcon.height/2
text: "It's possible to customize the look and feel for Cards too, if the no padding behavior for headers is needed. This is usually discouraged in order to have greater consistency, but in some cases the design requires a more fancy layout, as shown in this example of a Card. If a custom header is used, the title and icon in the banner property shouldn't be used. If a custom footer is used (which is discouraged), actions shouldn't be used."
}
footer: RowLayout {
Controls.Label {
Layout.fillWidth: true
text: "Custom footer"
}
Controls.Button {
text: "Ok"
}
}
}
}
HIG.Raster {
z: 1
}
// HACK coordinates are only final after a small delay
Timer {
interval: 1000
repeat: false
running: true
onTriggered: {
var a = new A.An(root);
//a.tree();
a.find("card").draw({
"padding": {},
"messure": [{
"to": a.find('qquickrectangle{"color": "#4682b4"}'),
"type": "top"
}, {
"to": a.find('qquickrectangle{"color": "#4682b4"}'),
"type": "left"
}, {
"to": a.find('qquickrectangle{"color": "#4682b4"}'),
"type": "right"
}]
});
a.find('qquickrectangle{"color": "#4682b4"}').draw({
"outline": {},
});
a.find("qquickrowlayout").last().draw({
"outline": {}
});
qmlControler.start();
}
}
}
import QtQuick 2.6
import QtQuick.Controls 2.0 as Controls
import QtQuick.Layouts 1.2
import org.kde.kirigami 2.4 as Kirigami
import "../../lib" as HIG
import "../../lib/annotate.js" as A
Rectangle {
id: root
width: 900
height: 400
Kirigami.CardsLayout {
x: Kirigami.Units.gridUnit * 2
y: x
width: 800
columns: 3
id: layout
Kirigami.Card {
actions: [
Kirigami.Action {
text: "Action1"
icon.name: "add-placemark"
},
Kirigami.Action {
text: "Action2"
icon.name: "address-book-new-symbolic"
}
]
banner {
imageSource: "../../../img/coastal-fog/coastal-fog-160x90.png"
}
contentItem: Controls.Label {
wrapMode: Text.WordWrap
text: "This is an instance of the Card type."
}
}
Kirigami.Card {
actions: [
Kirigami.Action {
text: "Action1"
icon.name: "add-placemark"
},
Kirigami.Action {
text: "Action2"
icon.name: "address-book-new-symbolic"
}
]
banner {
imageSource: "../../../img/coastal-fog/coastal-fog-40x30.png"
}
contentItem: Controls.Label {
wrapMode: Text.WordWrap
text: "This is an instance of the Card type."
}
}
Kirigami.Card {
actions: [
Kirigami.Action {
text: "Action1"
icon.name: "add-placemark"
},
Kirigami.Action {
text: "Action2"
icon.name: "address-book-new-symbolic"
}
]
banner {
imageSource: "../../../img/coastal-fog/coastal-fog.png"
}
contentItem: Controls.Label {
wrapMode: Text.WordWrap
text: "This is an instance of the Card type."
}
}
}