diff --git a/HIG/source/style/color/index.rst b/HIG/source/style/color/index.rst index 3637ee6..7d50236 100644 --- a/HIG/source/style/color/index.rst +++ b/HIG/source/style/color/index.rst @@ -1,115 +1,118 @@ Color ===== .. toctree:: :caption: Contents: :titlesonly: :hidden: default dark light high Purpose ------- Color is a distinguishing quality of human perception. Color can be used to communicate and draw attention efficiently. Color can assign significance to an object. However, color is a historical and cultural phenomenon and is subject to continuous aesthetical changes. It should also be noted that a large part of the population cannot perceive color in the same way that most people will. A consistent color set helps create a familiar visual language throughout the user interface. .. container:: flex .. container:: .. figure:: /img/Systemsettings.png :alt: System settings with Breeze color theme :scale: 30% System settings with Breeze color theme .. container:: .. figure:: /img/Systemsettings-dark.png :alt: System settings with Breeze Dark color theme :scale: 30% System settings with Breeze Dark color theme Guidelines ---------- - While the system color theme can be selected by the user, the :doc:`Breeze color palette ` is used for the reference visual design of KDE Applications and Workspaces, and make up the default system color theme. - Primary colors are used throughout the main interface of the applications and workspaces. **Plasma Blue** is used as the primary highlight color. - Secondary colors are used sparingly as accents throughout the visual design. - Whenever transparency is used (e.g. shadows) consider using the opacities listed. - Avoid using color as a primary method of communication. Color is best used as a secondary method to reinforce meaning visually. You should not only rely on color to convey meaning but also typography, layout, sizes, etc. - Ensure sufficient contrast between foreground and background colors. - Keep in mind accessibility for users with color vision deficiency (~5% population). Use one of the many available online color blindness simulators to ensure colors intended to be distinguishable remain distinguishable for color-blind users. Implementation -------------- Qt Widgets ~~~~~~~~~~ - When implementing colors in your application, select the appropriate theme color or system color from the palette provided by the Qt or KDE Platform/Frameworks library. You can use the `CheckColorRoles`_ theme to detect bugs regarding the use of system colors in your application. - `KColorScheme`_ provides methods to pick the colors from the system color scheme to avoid hardcoding colors where possible. Kirigami ~~~~~~~~ See :doc:`color in Kirigami ` for details on how to use colors and palettes. +.. literalinclude:: /../../examples/kirigami/UseTheme.qml + :language: qml + Plasma components ~~~~~~~~~~~~~~~~~ In Plasmoids use `PlasmaCore.Theme`_ to pick theme colors Color Mapping ------------- The Breeze color palettes maps to the KColorScheme color roles as shown as follow: - :doc:`Breeze ` - :doc:`Breeze Dark ` - :doc:`Breeze Light ` - :doc:`Breeze High Contrast ` .. _KColorScheme: http://api.kde.org/frameworks-api/frameworks5-apidocs/kconfigwidgets/html/classKColorScheme.html .. _PlasmaCore.Theme: https://api.kde.org/frameworks/plasma-framework/html/classPlasma_1_1QuickTheme. html diff --git a/Kirigami/source/conf.py b/Kirigami/source/conf.py index df3ab17..26a4f49 100644 --- a/Kirigami/source/conf.py +++ b/Kirigami/source/conf.py @@ -1,212 +1,214 @@ # -*- coding: utf-8 -*- # # Configuration file for the Sphinx documentation builder. # # This file does only contain a selection of the most common options. For a # full list see the documentation: # http://www.sphinx-doc.org/en/master/config # -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # 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('.')) sys.path.insert(0, os.path.abspath('../..')) # -- Project information ----------------------------------------------------- project = 'Kirigami' copyright = '2019, KDE. Licensed under Creative Commons License SA 4.0' author = 'Marco Martin' # The short X.Y version version = '' # The full version, including alpha/beta/rc tags release = '' # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. # # needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinxcontrib.doxylink' ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The master toctree document. master_doc = 'index' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = None +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # 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 = {} # 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, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. # # The default sidebars (for documents that don't match any pattern) are # defined by theme itself. Builtin themes are using these templates by # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', # 'searchbox.html']``. # # html_sidebars = {} # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = 'Kirigamidoc' # -- Options for LaTeX output ------------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # # 'preamble': '', # Latex figure (float) alignment # # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'Kirigami.tex', 'Kirigami Documentation', 'Marco Martin', 'manual'), ] # -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'kirigami', 'Kirigami Documentation', [author], 1) ] # -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'Kirigami', 'Kirigami Documentation', author, 'Kirigami', 'One line description of project.', 'Miscellaneous'), ] # Adding common substitions between Kirigami and HIG from epilog import rst_epilog rst_epilog += """ """ # -- Options for Epub output ------------------------------------------------- # Bibliographic Dublin Core info. epub_title = project # The unique identifier of the text. This can be a ISBN number # or the project homepage. # # epub_identifier = '' # A unique identification for the text. # # epub_uid = '' # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] # -- Extension configuration ------------------------------------------------- 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() # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { 'hig': ('https://hig.kde.org/', None), 'pm': ('https://docs.plasma-mobile.org', None) } # add css file def setup(app): app.add_stylesheet('css/breeze.css') diff --git a/Kirigami/source/gettingstarted/firstkirigamiproject/cmakedynamic.rst b/Kirigami/source/gettingstarted/firstkirigamiproject/cmakedynamic.rst index bfda131..9cdbfb0 100644 --- a/Kirigami/source/gettingstarted/firstkirigamiproject/cmakedynamic.rst +++ b/Kirigami/source/gettingstarted/firstkirigamiproject/cmakedynamic.rst @@ -1,4 +1,4 @@ CMake with dynamic linking -============ +========================== [TODO] diff --git a/Kirigami/source/gettingstarted/firstkirigamiproject/cmakestatic.rst b/Kirigami/source/gettingstarted/firstkirigamiproject/cmakestatic.rst index b413661..8bcb6e1 100644 --- a/Kirigami/source/gettingstarted/firstkirigamiproject/cmakestatic.rst +++ b/Kirigami/source/gettingstarted/firstkirigamiproject/cmakestatic.rst @@ -1,4 +1,4 @@ CMake with static linking -============ +========================= [TODO] diff --git a/Kirigami/source/gettingstarted/firstkirigamiproject/qmakestatic.rst b/Kirigami/source/gettingstarted/firstkirigamiproject/qmakestatic.rst index 04aba60..cd4b4a0 100644 --- a/Kirigami/source/gettingstarted/firstkirigamiproject/qmakestatic.rst +++ b/Kirigami/source/gettingstarted/firstkirigamiproject/qmakestatic.rst @@ -1,4 +1,4 @@ QMake with static linking -============ +========================= [TODO] diff --git a/Kirigami/source/introduction/devicetypes.rst b/Kirigami/source/introduction/devicetypes.rst index 44261ff..a72b988 100644 --- a/Kirigami/source/introduction/devicetypes.rst +++ b/Kirigami/source/introduction/devicetypes.rst @@ -1,21 +1,23 @@ Device Types ============ In today's world, there are many types of digital devices: desktop and laptop computers, smartphones, tablets, and so on. A harmonious and efficient user experience is only possible when the software's user interface is tailored to each device's physical characteristics and the way that a user will interact with it. -For information regarding the differences between a user interface and the user experience, see the :doc:`../resources/glossary`. +For information regarding the differences between a user interface and the user +experience, see the :doc:`responsive in the HIG `. Some devices are adaptable, e.g. a tablet with a keyboard plugged in, or a convertible laptop with only the touchscreen in use. These types of devices will require the user interface to adapt as necessary for each usage mode. If minimal changes are needed (for example, a laptop plugged into a large external screen) this can be achieved with a "responsive" design, as described -in :doc:`responsive`. For more extensive changes (for example, a tablet -plugged into a docking station with a mouse and keyboard attached), an entirely -different user interface paradigm may need to be presented. +in :doc:`responsive in the HIG `. For more +extensive changes (for example, a tablet plugged into a docking station with a +mouse and keyboard attached), an entirely different user interface paradigm may +need to be presented. [TODO] Notable differences in behavior of kirigami on different types diff --git a/Kirigami/source/style/color.rst b/Kirigami/source/style/color.rst index 3949198..0d72e21 100644 --- a/Kirigami/source/style/color.rst +++ b/Kirigami/source/style/color.rst @@ -1,189 +1,105 @@ 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 :language: qml -[TODO]: screenshot of a qml file with an annotated UI showing all the available -color +.. 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") - } - } - } - } +.. literalinclude:: /../../examples/kirigami/UseColorsets.qml + :language: qml 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 +.. literalinclude:: /../../examples/kirigami/InheritTheme.qml + :language: qml - ... - Controls.Button { - Kirigami.Theme.inherit: true - text: i18n("ok") - } +.. TODO:: -[TODO]: screenshot of a comparison between a button that inherits and one that -doesn't + 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 +.. literalinclude:: /../../examples/kirigami/CustomColors.qml + :language: qml - Rectangle { - // This will be "#465c2b" - color: Kirigami.Theme.textColor - } - } +.. TODO:: -[TODO] Screenshot + Screenshot diff --git a/examples/kirigami/CustomColors.qml b/examples/kirigami/CustomColors.qml new file mode 100644 index 0000000..9427dea --- /dev/null +++ b/examples/kirigami/CustomColors.qml @@ -0,0 +1,22 @@ +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 + } +} diff --git a/examples/kirigami/InheritTheme.qml b/examples/kirigami/InheritTheme.qml new file mode 100644 index 0000000..baf4fe3 --- /dev/null +++ b/examples/kirigami/InheritTheme.qml @@ -0,0 +1,9 @@ +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") +} diff --git a/examples/kirigami/UseColorsets.qml b/examples/kirigami/UseColorsets.qml new file mode 100644 index 0000000..eba51ff --- /dev/null +++ b/examples/kirigami/UseColorsets.qml @@ -0,0 +1,59 @@ +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") + } + } + } +}