diff --git a/HIG/source/components/editing/dropdown.rst b/HIG/source/components/editing/dropdown.rst index 3e90fd3..9d5836a 100644 --- a/HIG/source/components/editing/dropdown.rst +++ b/HIG/source/components/editing/dropdown.rst @@ -1,100 +1,100 @@ Drop-Down ========= .. figure:: /img/Dropdown1.png :alt: Dropdown :figclass: border Control which allows the user to choose one value from a list. Purpose ------- A *drop-down list* is a GUI control which allows the user to choose one value from a list. When a drop-down list is inactive, it displays a single value. When activated, it displays (drops down) a list of values, from which the user may select one. When the user selects a new value, the control reverts to its inactive state, displaying the selected value. A drop-down list works similar to a list box but hides the complete list until the user initiate the drop down. The disadvantage of drop-down lists compared to related controls like radio buttons or lists is that the options are not visible without further interaction. The list provides auto-complete feature for the whole string, independently of the "editable" property. Given the items of "bike", "boat", and "car": - If one types "b", the list selects "bike". - If one (rapidly) types "bo", it selects "boat". - If one types "c", it selects "car". One can repeatedly type a letter to cycle through items of the (read-only) drop-down list starting with this letter. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a drop-down list for single selection of one out of many items. If users should be able to add items use a :doc:`combo box `. - For only a few options, consider to use a set of :doc:`radio buttons `. - For a single selection out of a large number of items (n>20), use a :doc:`list view `. - Prefer controls that show the options without further user interaction, except for the following cases: - the list of options may change over time, - the contents are obvious from the label and the one selected item, for example *Month* and *January* - the control is part of a related sequence of controls. For example, to set a reminder to ring 5 hours or minutes before or after an event. Behavior ~~~~~~~~ - Show a maximum of eight items at once (maxVisibleItems=8). - When possible apply changes immediately but don't initiate an action (like print, send, delete) when the user selects an item from a drop-down list. - Don't add controls to the drop-down (e.g. checkboxes for each item). - 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. - Make sure the items are easily accessible via keyboard by moving distinctive letters to the beginning of each option. For example, in a list of countries on continents, write "Germany (Europe)" instead of "Europe/Germany". - Don't have blank list items; use meta-options, e.g. (None) instead Appearance ~~~~~~~~~~ - If activating a choice affects the appearance or the enabled state of other controls, place them next to the drop down. - If certain controls in a configuration dialog are only relevant if a certain item is selected (i.e. they are dependent controls), disable them instead of hiding. - Label the drop down with a descriptive caption to the 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 items. Code ---- Kirigami ~~~~~~~~ - `QML: ComboBox `_ Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ComboBox ` diff --git a/HIG/source/components/navigation/commandlink.rst b/HIG/source/components/navigation/commandlink.rst index c2dea98..23b7b18 100644 --- a/HIG/source/components/navigation/commandlink.rst +++ b/HIG/source/components/navigation/commandlink.rst @@ -1,45 +1,45 @@ Command Link ============ Purpose ------- A *command link* is an area containing icon and text that is used to initiate an action. It is primarily designed to streamline Wizard-like interfaces and to select from a set of mutually exclusive, related choices. Complementary to command buttons, command links are used for navigation to other places. Links behave similar to buttons but have always a clean, lightweight appearance without stimulative nature. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use command links for a set of mutually exclusive responses like navigation from hub to spoke pages. - Don't present single command links. - Consider to use a :doc:`push button ` for single commands or if the action does not contain navigation. Behavior ~~~~~~~~ - Provide feedback when result is not aware to user or not available instantaneous. Display a busy pointer or present a progress bar to users. - Don't mix command links and command buttons at one place. Appearance ~~~~~~~~~~ - Command links are flat. - Use standard theme color for links. - Always apply an icon to command links. - Icons should have a size of 48x48 pixels. - Choose a concise, self-explanatory label that clearly communicates and differentiates what the command link does. - Don't use ellipsis. diff --git a/HIG/source/components/navigation/dialog.rst b/HIG/source/components/navigation/dialog.rst index ba5e283..15758ad 100644 --- a/HIG/source/components/navigation/dialog.rst +++ b/HIG/source/components/navigation/dialog.rst @@ -1,84 +1,84 @@ Dialog ====== .. image:: /img/Dialog1.png :alt: Dialog :scale: 50% Purpose ------- A dialog is a secondary window that allows users to perform a command, asks users a question, or provides users with information or progress feedback. Dialogs can be modal and require users to complete and close before continuing with the owner window, or modeless, i.e. users can switch between dialogs and parent window. Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a dialog to structure the work flow. For instance, the functions Open, Save, Advanced Search need user input or confirmation. In particular, dialogs are expected by users for configuration. - Don't use dialogs if the flow must not be interrupted. In this case prefer inline controls. - Consider to use alternative ways for communication with users like - :doc:`tooltip <../assistance/tooltip>` or a + :doc:`tooltip <../assistance/tooltip>` or an :doc:`inline message <../assistance/inline>`. - Always use standard dialogs, if available. Behavior ~~~~~~~~ - Don't use dialog boxes that require the use of a scroll bar. - Don't include a menu bar or status bar in dialogs. - Don't display more than one dialog at a time. Dialogs should never create more dialogs. - Always keep dialogs on top of their parent. - Set input focus on confirmation button by default. But set focus on disruptive button (Cancel, Don't apply or the like) if the dialog comprises of critical confirmation. - Avoid to nest dialogs, especially in case of modal dialogs. - Avoid dialogs that contain only one or two options. If possible, use direct selection or inline-editing instead. - Don't use dialogs to display low-importance or informative messages that lack options on how to proceed. Consider using a :doc:`tooltip <../assistance/tooltip>` or a :doc:`inline message <../assistance/inline>` instead. - Use modal dialogs only if allowing interaction with other parts of the application while the window is opened could cause data loss or some other serious problem. - Provide a clear way of leaving the modal dialog, such as a Cancel button. - When the dialog is used to inform about an unexpected condition that needs interaction, follow the guidelines for :doc:`message dialogs <../assistance/message>`. Appearance ~~~~~~~~~~ - Use tabbed dialogs when you have a limited number of tabs (max. 6). If you cannot see all the tabs without scrolling or splitting them into multiple rows, you are probably using too many and should use a paged dialog instead. - Always use paged dialogs for configuration dialogs - assuming that there is more than one section of options to be configured. For other dialogs, use paged dialogs if there are too many tabs to put them into a tabbed dialog. - Dialogs should not be bigger than two thirds of the screen size and should always be resizable. Take care about high resolution displays (i.e. QXGA and more). - Save and restore user adjustments of dialog size. - Make sure at least one-third of the dialog's area is whitespace. Don't overload the dialog. the panel. - Consider the common reading direction from left to right and top to bottom. - Dialogs are grouped in meaningful sections, for instance by :doc:`group boxes <../formating/groupbox>`. The actions are grouped along their context of use, not along technical relations. - Provide a title to each section. - Follow the guidelines for :doc:`alignment `. diff --git a/HIG/source/introduction/architecture.rst b/HIG/source/introduction/architecture.rst index ba90718..455c402 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 + :alt: Discover, a convergent application built with Kirigami - Discover, a convergent application build using Kirigami + Discover, a convergent application built 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 :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 is 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 diff --git a/HIG/source/resources/contribute.rst b/HIG/source/resources/contribute.rst index 03abd5b..176bc05 100644 --- a/HIG/source/resources/contribute.rst +++ b/HIG/source/resources/contribute.rst @@ -1,223 +1,222 @@ Contribute ========== The HIG is written in `reStructuredText `_, a lightweight markup language. For example the chapter heading together with the first paragraph looks like this in reStructuredText .. code-block:: rst Contribute ========== The HIG is written in `reStructuredText `_, a light weight markup language. For example the chapter heading together with the first paragraph looks like this in reStructuredText The restructuredText of the full HIG is organized into several source files. You can view and modify these source files with any text editor. The source files are hosted in a `Git repo `_. `Sphinx `_ is used to generate HTML pages from these source files. Tasks and changes are organized via `https://invent.kde.org `_. .. note:: On every page of the HIG, there is a *View page source* link in the top right corner. For more information and help you can find us on `Matrix `_, `IRC `_ or -`Telegram `_ -. +`Telegram `_. -If you are new to KDE devlopment, make sure to read -`how to become a kde developer +If you are new to KDE development, make sure to read +`how to become a KDE developer `_ first. Getting Started --------------- #. Install some tools with your distro's package manager: ================================== ================================ Distribution Command ================================== ================================ Arch, Manjaro ``sudo pacman -S git make`` Debian, Ubuntu, KDE Neon ``sudo apt install git make`` openSUSE ``sudo zypper install git make`` Fedora ``sudo dnf install git make`` CentOS/RHEL ``sudo yum install git make`` ================================== ================================ #. Clone the HIG source code repository into an empty folder: .. code-block:: sh git clone https://invent.kde.org/websites/hig-kde-org.git cd hig-kde-org #. Install some tools with Python's package manager, Pip. Pip should already be Installed, but if for some reason it is not, here are instructions for getting it: https://pip.pypa.io/en/stable/installing/ You can use Pip to install the required python modules either globally: .. code-block:: sh sudo pip install -r HIG/requirements.txt ...or in your home directory: .. code-block:: sh pip install -r HIG/requirements.txt --user If you install it in you home directory, make sure you have the installed packages in your path by adding it to your .profile: .. code-block:: sh echo "PATH=~/.local/lib:\$PATH" >> ~/.profile source ~/.profile Now you are ready to contribute to the HIG! To preview changes on your local machine, do the following: #. Enter the HIG directory with ``cd HIG`` #. Run ``make html`` to create the HTML pages #. Open ``build/html/index.html`` in your browser (e.g. run ``firefox build/html/index.html``) Page Structure -------------- This defines the structure that should be used for writing pattern and component pages for the HIG. Pattern ^^^^^^^ :: Pattern name ============== Give a short into into the pattern. Examples -------- Showcase the pattern with videos or images. When to use ----------- Describe when to use this pattern and when not to use it. How to use ---------- Describe how to use this pattern. Pages about patterns should not include any details on implementation, about behavior or appearance, but rather link to the corresponding components needed to implement a pattern. Optional: you can add subsections for desktop and mobile. :: When to use ----------- Desktop ^^^^^^^ Mobile ^^^^^^ Component ^^^^^^^^^ :: Component name ============== Purpose ------- A very short description on why and how to use the component. This should primarily link to the corresponding pattern pages. Example ------- Showcase the component with a video or image. Guidelines ---------- - Is this the right control - ~~~~~~~~~~~~~~~~~~~~~~~~~ + Is this the right control? + ~~~~~~~~~~~~~~~~~~~~~~~~~~ Describe when to use a component and when not. Behavior ~~~~~~~~ Describe the behavior of the component. Appearance ~~~~~~~~~~ Describe the appearance of the component. Code ---- Kirigami ~~~~~~~~ Link to the API and example code how to use the component with QML and Kirigami. Qt Widgets ~~~~~~~~~~ Link to the API and example code how to use the component with Qt Widgets. Optional: you can add subsections for desktop and mobile. :: Behavior ~~~~~~~~ Desktop """"""" Mobile """""" Code Examples ------------- Adding examples to the HIG is very easy. #. Add a file with source code in the ``./examples/`` folder. #. Add the following markup at the point you want to insert the example: .. code-block:: rst .. literalinclude:: /../../examples/kirigami/InlineMessage.qml :language: qml Creating media -------------- See :doc:`media` on how to create media files for the HIG. diff --git a/HIG/source/resources/glossary.rst b/HIG/source/resources/glossary.rst index 1185e3d..46fd3fc 100644 --- a/HIG/source/resources/glossary.rst +++ b/HIG/source/resources/glossary.rst @@ -1,43 +1,43 @@ Glossary ======== - **Human Interface Guidelines**, **HIG** A set of recommendations for designing and developing user interfaces for mobile, desktop, convergent applications and workspace widgets. - **User Interface**, **UI** In the field of human–computer interaction, the User Interface is the space where interactions between humans and machines occur. The goal of this interaction is to allow effective operation and control of the machine from the human end, whilst the machine simultaneously feeds back information that aids the operators' decision-making process. *Source*: ``_ - **User Experience**, **UX** UX refers to a person's emotions and attitudes about using a particular product, system or service. It includes the practical, experiential, affective, meaningful and valuable aspects of human–computer interaction and product ownership. Additionally, it includes a person’s perceptions of system aspects such as utility, ease of use and efficiency. User experience may be considered subjective in nature to the degree that it is about individual perception and thought with respect to the system. User experience is dynamic as it is constantly modified over time due to changing usage circumstances and changes to individual systems as well as the wider usage context in which they can be found. In the end, user experience is about how the user interacts with and experiences the product. *Source:*: ``_ - **Get New Stuff**, **GNS** :doc:`/platform/getnew` -- **Aassistive technology**, **AT** +- **Assistive technology**, **AT** - Screen readers and other assistive technology is often refered as AT + Screen readers and other assistive technologies are often referred to as AT.