diff --git a/.gitignore b/.gitignore index 039ee99..4233643 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ /env build *.qmlc *.jsc /__pycache__ *.tags +.vscode \ No newline at end of file diff --git a/HIG/source/accessibility/checklist.rst b/HIG/source/accessibility/checklist.rst index af86dc6..173ef6b 100644 --- a/HIG/source/accessibility/checklist.rst +++ b/HIG/source/accessibility/checklist.rst @@ -1,272 +1,272 @@ -Accessibility checklist +Accessibility Checklist ======================= Introduction ------------ This is a list of common things you should check for to have great :doc:`accessibility ` for your application or widgets. -Keyboard navigation +Keyboard Navigation ------------------- - Efficient keyboard access is provided for all application features. - All windows have a logical keyboard navigation order. - The correct tab order is used for controls whose enabled state is dependent on checkboxes, radio buttons or toggle buttons. - Keyboard access to application-specific functions does not override existing system accessibility features. - The application provides more than one method to perform keyboard tasks whenever possible. - There are alternative keyboard shortcuts wherever possible. - Frequently-accessed keyboard shortcuts should be physically easy to access and not require awkwardly bending the wrist or fingers. - The application does not require repetitive, simultaneous keypresses. - The application provides keyboard equivalents for all mouse functions. - The application provides keyboard equivalents for all mouse-based functions, including selecting, moving, and resizing items. - The application does not use any general navigation functions to trigger operations. - All keyboard-invoked menus, windows, and tooltips appear near the object they relate to. Testing ^^^^^^^ -The following keyboard operations should be tested. Do not use the mouse in any +The following keyboard operations should be tested. Don't use the mouse in any part of this test. - Using only keyboard commands, move the focus through all menu bars in the application. - Confirm that: - Context-sensitive menus display correctly. - Any functions listed on the toolbar can be triggered using the keyboard. - Every control in the client area of the application can be focused and activated. - Text and objects within the client area can be selected. - Any keyboard enhancements or shortcuts are working as designed. -Mouse interaction +Mouse Interaction ----------------- - No operations depend on input from the right or middle mouse buttons. - All mouse operations can be cancelled before they are complete. - Visual feedback is provided throughout drag and drop operations - The mouse pointer is never moved by the application, or its movement restricted to part of the screen by the application. -Graphical elements +Graphical Elements ------------------ - There are no hard-coded graphical attributes such as line, border or shadow thickness. - All multi-color graphical elements can be shown in monochrome only, where possible. - All interactive GUI elements are easily distinguishable from static GUI elements. - An option to hide non-essential graphics is provided. See :doc:`units ` for more information on how to use KDE's base units to avoid hardcoded size values. Testing ^^^^^^^ Test the application using a screen reader and confirm that: - Labels and text are being read correctly, including menus and toolbars. - Object information is read correctly. -Fonts and text +Fonts and Text -------------- - No font styles or sizes are hard-coded. - An option to turn off graphical backdrops behind text is provided. - All labels have names that make sense when taken out of context. - No label names are used more than once in the same window. - Label positioning is consistent throughout the application. - All static text labels that identify other controls end in a colon (:). - Static text labels that identify other controls immediately precede those controls in the tab order. - An alternative to WYSIWYG is provided. For example, the ability to specify different screen and printer fonts in a text editor. See :doc:`typography ` for more information on how to avoid hardcoded font sizes and :doc:`labels ` for more details about labels. Testing ^^^^^^^ - Change the font in the application and confirm that the settings are maintained. - Test the application by changing colors and confirm that all settings are maintained. - If magnification is available, test the font, color, and size using the magnification option. -Color and contrast +Color and Contrast ------------------ - Application colors are not hard-coded, but either use colors from current desktop theme or an application setting. - Color is only used as an enhancement, and not as the only means to convey information or actions. - The application supports all available :doc:`high contrast themes ` and settings. - The software is not dependent on any particular :doc:`high contrast themes ` or settings. See :doc:`the HIG's page about color ` and :doc:`colors in Kirigami ` for more information. Testing ^^^^^^^ - Print screenshots to a black and white printer and confirm that all information is visible. - Test applications using only black and white high-contrast settings and confirm that all information is conveyed correctly. - Test that the application provides at least three combinations of color schemes and that high-contrast schemes are available (e.g. white on black or yellow on blue). - Turn on high-contrast settings in the System Settings and confirm that the application respects these settings. - Test various themes to ensure that the software is working for all the available settings. Magnification ------------- - The application provides the ability to scale or magnify the work area. - The application's functionality is not affected by changing the magnification or scale settings. Audio ----- - Sound is not used as the only means of conveying any items of information. - The user can configure the frequency and volume of all sounds and warning beeps. Testing ^^^^^^^ There should be an option in the application to show audio alerts visually. Test that the audio is working correctly by enabling sound in the System Settings and then perform the following actions: - Perform an action that should generate an audio alert and confirm that the application is working as designed. - Verify that the application works correctly when increasing or decreasing the volume. - Confirm that warning messages and alerts can be heard correctly in a noisy work environment. Animation --------- - There are no flashing or blinking elements with a frequency greater than 2Hz or lower than 55Hz. - Any flashing or blinking is confined to small areas of the screen. - If animation is used, an option is available to turn it off before it is first shown. Testing ^^^^^^^ Verify that an option is available to stop animation and that it is working as designed. Turn the animation off. Confirm that all information is still conveyed correctly. -Keyboard focus +Keyboard Focus -------------- - When a window is opened, focus starts at the most commonly-used control. - Current input focus position is clearly displayed at all times. - Input focus is shown in exactly one window or view at all times. - Appropriate audio or visual feedback is provided when the user attempts to navigate past either end of a group of related objects. - The default audio or visual warning signal is played when the user presses an inappropriate key. - There is sufficient audio information for the visual focus that the user can figure out what to do next. -- Set the focus to the actual control, don't just highlight an area. +- Set the focus to the actual control. Don't just highlight an area. - When using assistive technologies, such as a screen reader or braille device, the current program indicates the position and content of the visual focus indicator. Testing ^^^^^^^ - Verify when moving among objects that the visual focus indicator is easy to identify. - Keyboard navigation through the software and menus should be clearly visible when the focus moves. - Confirm that the screen reader is tracking the visual focus indicator as you navigate using a keyboard. - Run a screen magnification program (if available) and verify that the magnifier can track the visual focus indicator as you navigate using the keyboard and mouse. Timing ------ - There are no hard-coded time-outs or time-based features in the application. - The display or hiding of important information is not triggered solely by movement of the mouse pointer. Testing ^^^^^^^ - Test all messages to confirm that the user is notified before a message times out and is given the option to indicate that more time is needed. - Make sure an option has been included to adjust the response time and confirm that it is working as designed. Documentation ------------- - All documentation is in an accessible format, with textual alternate descriptions provided for all figures and diagrams. - The documentation includes a section that covers all the application's accessibility features. Testing ^^^^^^^ Test ASCII text documentation with a screen reader to confirm that it is clear and precise and can be read by assistive technologies. Test HTML applications using a web browser and screen reader to confirm that the documentation is accessible to assistive technologies. Note: There are web accessibility guidelines available at ``_. Confirm the following information is included in the documentation: - State if the application does not support the standard keyboard access used by the OS. - Identify if there are unique keyboard commands. - Identify any unique accessibility features. - If an action is documented for the mouse, make sure there is an alternative for using the keyboard. .. note:: The content of this page is based on ``_ diff --git a/HIG/source/accessibility/index.rst b/HIG/source/accessibility/index.rst index 951f227..0e80f56 100644 --- a/HIG/source/accessibility/index.rst +++ b/HIG/source/accessibility/index.rst @@ -1,160 +1,160 @@ Accessibility ============= .. toctree:: :maxdepth: 1 :titlesonly: :hidden: checklist Introduction ------------ Accessibility is the design of products, devices, services, or environments for people with disabilities. The concept of accessible design and practice of accessible development ensures both "direct access" (i.e. unassisted) and "indirect access" meaning compatibility with a person's assistive technology. *Source*: ``_ But good accessibility benefits all users. A working keyboard navigation and well choosen colors and fonts setting not only help people with low vision, blindness, deafness, cognitive or motor impairments or situational disabilities, like a broken hand, but also improve the workflow and usability for all users. Fonts and Colors ---------------- -Many users have some deficiencies when it comes to seeing. This doesn't always -mean that they are blind. For some people it is enough when +Many users have some deficiencies when it comes to seeing. This does not always +mean that they are blind. For some people it's enough when :doc:`fonts ` are clear and the :doc:`color scheme ` can be adjusted. This is something every application should do in any case, so here is the list: - Follow the user interface guidelines! This will get you quite far. - Check that color scheme changes apply |br| Try switching to a :doc:`dark color scheme ` and see that your application is still usable - Test changing the :doc:`font size ` - Switch to different fonts and see that they apply - Increase the font size and make sure that the application layout still works Keyboard -------- When you have problems seeing, the mouse is quite hard to use. The keyboard is a -lot more reliable. Therefor it is important that applications can be used with +lot more reliable. Therefore it is important that applications can be used with the keyboard. For some users, using a mouse is difficult because of motor skill issues. Making applications keyboard accessible benefits everyone, since it allows us to use shortcuts to use the applications more efficiently. - Try to operate your application with the TAB key - Make sure that the tab order is correct - Start your application and do a common task without using the mouse Note where you had trouble and think about possible improvements in the UI or keyboard shortcuts that are missing Screen Reader ------------- There is a lot you can help with to make applications accessible to screen reader users. We refer to screen readers and other assistive technology often as AT. .. TODO:: Setup Screen Readers with KDE Gives detailed setup instructions for screen readers. Testing ------- This section gives a quick intro what to look for when testing an application with a screen reader. Once you have an application running with the screen reader: Make sure Orca says something intelligible for all elements. When it reads a GUI element it should say the label and type, eg: "File, Menu" or "OK, Button". When you have a button that does not have a label, maybe because it shows a picture only, add accessibility hints. Try navigating the more troublesome elements - comboboxes and lists and such. Fixing missing information -------------------------- For many things there are usually easy fixes involving no advanced programming skills but just fixing some details. For this tutorial we assume that you are dealing with a QWidget that is seen by the AT but does for example give not enough information. There are two important properties that every QWidget has: an "Accessible Name" and an "Accessible Description". The name is short, for example the label on a button. It should always be short. The description on the other hand is the more verbose "this button does foo and then bar". Qt will try hard to return something for the name. In case of a button, usually the text on the button is -returned. But if your button has text that makes only sense when seeing the -arrangement of buttons, or only has an image as label, you need to help the AT +returned. But if your button has text that only makes sense when seeing the +arrangement of buttons, or only has an image as label, then you need to help the AT read the button. If you don't, it will only say the type of the widget, "Button" -is not a very helpful information. +which is not very helpful information. Fixing Accessible Name and Description -------------------------------------- Fire up Qt designer if the app uses .ui files. You'll find the properties and can type the name/description right in. After saving the file, rebuild and install the application. You are done, submit a patch to fix the ui file. -If the widget is created in the code, just need to find where. Once you found -the widget, usually where it's created, add some code to it: +If the widget is created in the code, you just need to find where it's initialized. +Once you find it (usually where it's created), add some code to it: .. code-block:: c++ button->setAccessibleName(i18n("Open")); button->setAccessibleDescription(i18n("Opens a file dialog to select a new foo")); Send your patch. Sometimes you also want to override the label for a different reason. One of my test apps was the calculator example from Qt. It has a memory recall button labelled "MR". Orca will insist on this being the "Mister" button, unless told otherwise. Complex Widgets --------------- For some widgets the above is not enough. You will have to create QAccessibleInterfaces for widgets that you create yourself. For example Kate has an interface for its text editing area. Sometimes you need to inherit QAccessibleTextInterface or QAccessibleValueInterface in order to make the widgets properly accessible. Refer to the Qt documentation how to do this. QGraphicsView ------------- Currently there is no support for accessibility in QGraphicsView. Qt Quick (QML) -------------- For Qt 5, refer to the `documentation `_ on how to create accessible QML applications. The concepts are generally the same as for QWidget based applications. diff --git a/HIG/source/components/assistance/emblem.rst b/HIG/source/components/assistance/emblem.rst index 5db8e68..90280dd 100644 --- a/HIG/source/components/assistance/emblem.rst +++ b/HIG/source/components/assistance/emblem.rst @@ -1,61 +1,61 @@ Emblem ====== Purpose ------- -An *emblem* displays unusual or non-default status information about an icon +An emblem displays unusual or non-default status information about an icon or image. For example, an emblem could indicate that a folder is shared, that a disk is unmounted, or that an app has unread notifications. Examples -------- .. figure:: /img/emblem-public-on-folder.png :alt: An emblem indicating that a folder is shared on the network .. figure:: /img/emblem-notification-kmail.png :alt: An emblem indicating that a mail program has 15 unread emails Guidelines ---------- - Emblems are used to badge icons, images, or other visually discrete elements in a file manager, system tray, task manager, dock, image view, etc. Emblems should not be applied to textual content. - Use emblems to display that an icon or image has some unusual status - associated with it, or that there are unread notifications. Do not use + associated with it, or that there are unread notifications. Don't use emblems to display an element's normal, common, or typical status. For example, an emblem could indicate that a folder is read-only or is a symlink, or that a disk is unmounted or encrypted. An emblem should not be used to indicate that a folder is read-write or that a disk is mounted. - Emblems that indicate status should be placed in the bottom-right corner. If additional status emblems are needed, they should be placed in other corners in a clockwise order. - Emblems that indicate unread notifications should be located in the top-right corner. -- Use the minimum number of emblems and do not overwhelm the icon itself. +- Use the minimum number of emblems and don't overwhelm the icon itself. Three is usually too many. Appearance ---------- An emblem that indicates unread notifications should take the form of a light-colored number inside a blue circle. The circle can become "pill-shaped" if the number is very large. .. figure:: /img/emblem-notification-small.png :alt: Notification emblem .. figure:: /img/emblem-notification-large.png :alt: Notification emblem with a large number For symbolic icon emblems, see the :doc:`Breeze icon guidelines `. diff --git a/HIG/source/components/assistance/index.rst b/HIG/source/components/assistance/index.rst index 3a17f63..7398f75 100644 --- a/HIG/source/components/assistance/index.rst +++ b/HIG/source/components/assistance/index.rst @@ -1,33 +1,33 @@ -User assistance +User Assistance =============== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: emblem inline message progress statusbar tooltip User assistance --------------- User Assistance guidance considers interface elements that inform users of the application’s activity and status, as well as elements dedicated to user education. This includes online help, error alerts, and status alerts. Notification ~~~~~~~~~~~~ * :doc:`emblem` * :doc:`inline` * :doc:`message` * :doc:`progress` * :doc:`statusbar` Help ~~~~ * :doc:`tooltip` diff --git a/HIG/source/components/assistance/inline.rst b/HIG/source/components/assistance/inline.rst index aa49c1e..d09ca73 100644 --- a/HIG/source/components/assistance/inline.rst +++ b/HIG/source/components/assistance/inline.rst @@ -1,163 +1,165 @@ -Inline message +Inline Message ============== .. container:: intend |desktopicon| |mobileicon| Purpose ------- -A *inline message* is a small panel that informs users of a non-critical problem +A inline message is a small panel that informs users of a non-critical problem or special condition. It is embedded in the content and should not overlap content or controls. The panel has four visual style options which can be used for neutral messages, success conditions, warnings, and errors. It can also be given buttons. .. figure:: /img/Message5.png :alt: Different levels of inline messages. :scale: 80% The four different levels of inline messages. Examples -------- .. figure:: /img/Message-example.png :alt: An inline message is used for feeback after an upload has been completed. Guidelines ---------- - Use inline messages in cases of non-critical problems that user can solve. - - Use *negative feedback* (aka error) as a secondary indicator of - failure, e.g. if a transaction was not completed successfully - - Show the information on a warning level in case of relevant - information that do not concern the current workflow, e.g. No - Internet connection available. - - Use *positive feedback* to notify about user-initiated processes, - e.g. to indicate completion of background tasks - - Use *opportunistic interaction* (aka notification) to acknowledge + - Use :iconred:`negative feedback` (aka error) as a secondary indicator of + failure, e.g. if a transaction was not completed successfully. + + - Show the information on a warning level in case of relevant + information that does not concern the current workflow, e.g. No + Internet connection available. + + - Use :noblefir:`positive feedback` to notify about user-initiated processes, + e.g. to indicate completion of background tasks. + - Use :plasmablue:`opportunistic interaction` (aka notification) to acknowledge the user about options that he or she might be interested in, e.g. "Remember password?" - Display the information immediately. -- When users dismiss the inline message, do not display any other UI or start +- When users dismiss the inline message, don't display any other UI or start any other side effect. -- Do not add controls to the inline message other than action buttons +- 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. Is this the right control? / Behavior ------------------------------------- -Negative feedback +Negative Feedback ~~~~~~~~~~~~~~~~~ The inline message should be used as a secondary indicator of failure: the first indicator is for instance that the action the user expected to happen did not happen. Example: User fills a form, clicks "Submit". - Expected feedback: form closes - First indicator of failure: form stays there - Second indicator of failure: a inline message appears on top of the form, explaining the error condition When used to provide negative feedback, an inline message should be placed close to its context. In the case of a form, it should appear on top of the form entries. An inline message should get inserted in the existing layout. Space should not be reserved for it, otherwise it becomes "dead space", ignored by the user. An inline message should also not appear as an overlay to prevent blocking access to elements the user needs to interact with to fix the failure. -When used for negative feedback, do not offer a close button. The +When used for negative feedback, don't offer a close button. The message panel only closes when the problem it informs about (e.g. the error) is fixed. -Positive feedback +Positive Feedback ~~~~~~~~~~~~~~~~~ -An inline message can be used for positive feedback but it shouldn't be +An inline message can be used for positive feedback but it should not be overused. It is often enough to provide feedback by simply showing the results of an action. Examples of acceptable uses: - Confirm success of "critical" transactions - Indicate completion of background tasks Example of wrong uses: - Indicate successful saving of a file - Indicate a file has been successfully removed -Opportunistic interaction +Opportunistic Interaction ~~~~~~~~~~~~~~~~~~~~~~~~~ Opportunistic interaction is the situation where the application suggests to the user an action he could be interested in perform, either based on an action the user just triggered or an event which the application noticed. Example use cases: - A browser can propose remembering a recently entered password - A music collection can propose ripping a CD which just got inserted - A chat application may notify the user a "special friend" just connected Appearance ---------- A basic inline messages consists of an icon and text. It can contain an optional close button and :doc:`buttons <../navigation/pushbutton>`. .. figure:: /img/Message1.png :alt: Inline message with a custom icon and a close button. :scale: 80% Inline message with a custom icon and a close button. .. figure:: /img/Message2.png :alt: Inline message with two buttons. :scale: 80% Inline message with two buttons. If there is not enough space to display all the buttons, an overflow menu is shown instead. .. figure:: /img/Message3.png :alt: Inline message with overflow menu. :scale: 80% Inline message with overflow menu. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: InlineMessage ` .. literalinclude:: /../../examples/kirigami/InlineMessage.qml :language: qml Qt Widgets ~~~~~~~~~~ - :kwidgetsaddonsapi:`QtWidgets: KMessageWidget ` diff --git a/HIG/source/components/assistance/message.rst b/HIG/source/components/assistance/message.rst index d5c336e..f03a1b8 100644 --- a/HIG/source/components/assistance/message.rst +++ b/HIG/source/components/assistance/message.rst @@ -1,60 +1,54 @@ -Modal message dialog +Modal Message Dialog ==================== Purpose ------- If the processing has reached an unexpected or potentially dangerous condition, the user must make a decision. The correct presentation for this kind of -disruptive question is a *modal message dialog*: a secondary window that +disruptive question is a modal message dialog: a secondary window that interrupts user's current activity and blocks interaction until the user decides how to proceed. Use modal message dialogs sparingly. Users will learn to reflexively dismiss commonly-encountered modal message dialog without even reading them, defeating the purpose. - - - -Examples --------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use modal message dialogs only for critical or infrequent tasks that require completion before continuing. Avoid disrupting the user; workflow maintenance and, therefore, the prevention of errors should be the primary objective. - Modal message dialogs must offer choices regarding how to proceed; don’t use them dialogs simply to inform or warn the user. Instead, use an :doc:`inline message `. Behavior ~~~~~~~~ - Dialogs should be modal, and block user interaction with the rest of the - application until a choice has been made. Do not block the entire user + application until a choice has been made. Don't block the entire user interface for the whole system, though. - Create specific, actionable, user-centered error messages. Users should either perform an action or change their behavior as a result. - Never add a countdown timers or otherwise force user to read and understand the message within a few seconds. - For very long or complicated conditions, provide a short error message and complement it with a Details button that provides a lengthier explanation in the same dialog. Appearance ~~~~~~~~~~ - Tell the user the reason for the problem and offer help regarding how to solve the problem. - Phrase your messages clearly, in non-technical terms. Avoid obscure error codes. - Avoid wording that terrifies the user ("killed", "fatal", "illegal") or blames them for their behavior. Be polite. - Buttons should clearly indicate the available options using action verbs ("Delete", "Rename", "Close", "Accept", etc.) and allow the user to make an informed decision even if they have not read the message text. Never use "Yes" and "No" as button titles. - Follow the general guidelines for :doc:`dialogs <../navigation/dialog>`. diff --git a/HIG/source/components/assistance/progress.rst b/HIG/source/components/assistance/progress.rst index b108053..d23f416 100644 --- a/HIG/source/components/assistance/progress.rst +++ b/HIG/source/components/assistance/progress.rst @@ -1,53 +1,50 @@ -Progress indicator +Progress Indicator ================== Purpose ------- If a foreground task lasts longer than expected or when calculation -takes some time a *feedback on progress* should be given by the system. +takes some time, the system should provide some feedback on the task's progress. Users are aware of response times of over one second and shorter. Consequently, operations that take two seconds or longer to complete should be considered to be lengthy and need of some type of progress feedback. But even in cases of short delays the user should be assured that the system is not hung or waiting for user input. Such a feedback -is done by changing the mouse cursor to a *busy pointer* (aka throbber +is done by changing the mouse cursor to a busy pointer (aka throbber or spinner). When operation lasts longer the user should be able to anticipate when it’s finished. The appropriate graphical control for -this task is a *progress bar*. - -Examples --------- +this task is a progress bar. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Provide progress feedback when performing a lengthy operation. Users should never have to guess if progress is being made. - Show a busy pointer when the operation takes longer than 500 ms and a progress bar in case of 5 seconds or more. - Consider to move very long lasting operations to the background and notify on completion only. Behavior ~~~~~~~~ - User should be able to pause and cancel operations which last very long. - Clearly indicate real progress – and lack of progress. The progress bar must advance if progress is being made and not advance if no progress is being made. - Show progress by steps in respect to context. For instance, don't inform about the number of files that have been downloaded but rather the total size in bytes. - Provide additional progress information, but only if users can do something with it, e.g. cancel the processing, relate an error to a particular processing step, etc. Don't provide unnecessary details. - Don't use progress bars if the time needed to complete the task cannot be estimated, as well not per waiting bar (aka marquee style). In that case, if the task will likely take only a few seconds, use a spinner. If it takes longer, move the task to the background. - Don't combine a progress bar with a busy pointer. diff --git a/HIG/source/components/assistance/statusbar.rst b/HIG/source/components/assistance/statusbar.rst index f183d1a..ce23cb4 100644 --- a/HIG/source/components/assistance/statusbar.rst +++ b/HIG/source/components/assistance/statusbar.rst @@ -1,44 +1,44 @@ -Status bars +Status Bars =========== Purpose ------- -A *status bar* is an area at the bottom of a primary window that +A status bar is an area at the bottom of a primary window that displays information about the current window's state, background tasks, or other contextual information. KDE applications should not use a conventional status bar by default in favor of maximized space for content. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Omit the status bar in the main window to maximize vertical space for content. - - Do not show meaningless information like 'Ready'. + - Don't show meaningless information like 'Ready'. - Use a floating panel or :doc:`tooltips ` for short-term status information like full length text of links. - Move controls to the toolbar. - If you cannot find good replacements for status bar functions, please ask the usability team for support. -- Do not display a status bar in secondary or internal windows. +- Don't display a status bar in secondary or internal windows. - If a status bar is really necessary in your application consider to use a :doc:`toolbar <../navigation/toolbar>` with all customization features. Behavior ~~~~~~~~ -- Do not use the status bars or any kind of replacement for crucial +- Don't use the status bars or any kind of replacement for crucial information. Users should never have to know what is in the status bar. -- Do not use the status bar or any kind of replacement to display +- Don't use the status bar or any kind of replacement to display advisory messages in place of standard :doc:`tooltips `. -- Keep the status information plain; e.g. do not add icons. +- Keep the status information plain; e.g. don't add icons. .. for more info see http://user-prompt.com/what-is-a-status-bar-good-for/ diff --git a/HIG/source/components/assistance/tooltip.rst b/HIG/source/components/assistance/tooltip.rst index 11fabcf..3c201bb 100644 --- a/HIG/source/components/assistance/tooltip.rst +++ b/HIG/source/components/assistance/tooltip.rst @@ -1,71 +1,71 @@ Tooltip ======= Purpose ------- -A *tooltip* is a small pop-up window that provides more information on +A tooltip is a small pop-up window that provides more information on an element under the mouse cursor, such as toolbar controls without caption or command buttons. Tooltips provide additional descriptive text including formatting and icons. Tips eliminate the need to always have descriptive text on the screen. Novice users will use hovering to show tooltips to become familiar with the interface. This time-delay mechanism makes tips very convenient, but it also reduces their discoverability. When tips are used consistently they support user’s expectation and foster predictability. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use tips to label unlabeled controls and to provide additional information. - Don’t use tips for warnings. Behavior ~~~~~~~~ - Keep tips brief, typically five words or less for tool-tips. Whenever appropriate, provide keyboard short-cuts and default values. - Tooltips for a disabled control should include information regarding the disabled state of the control. Include this information even if the control is enabled. For instance: 'Go to the next unread message' in the case of enabled controls and 'Go to the next unread message (No unread messages left)' when disabled. - Consider adding small informational buttons for touch screen use. Appearance ~~~~~~~~~~ - Format and organize content in tooltips to make it easier to read and scan. The information should be: - concise: large, unformatted blocks of text are difficult to read and overwhelming - helpful: it should add information, not repeat information - supplemental: important information should be communicated using self-explanatory control labels or in-place supplemental text - static: tips should not change from one instance to the next -- Do not use icons and formattings for tips of unlabeled controls. +- Don't use icons and formattings for tips of unlabeled controls. - Use tool-tips with icons and formatting - if tips describe comprehensive functions, - when content is lengthy and formatting improves readability - for tips that are implemented primarily for joy of use. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: ApplicationWindow ` - `QML: MenuBar `_ Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ToolTip ` diff --git a/HIG/source/components/editing/card.rst b/HIG/source/components/editing/card.rst index 48e7be7..e2a084d 100644 --- a/HIG/source/components/editing/card.rst +++ b/HIG/source/components/editing/card.rst @@ -1,97 +1,98 @@ Card ==== Purpose ------- A card serves as overview and an entry point for more detailed information and can offer direct access to the most important actions on an item. -Example -------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Don't use a card to display long texts. - Cards can be used to display items with different content types, e.g. images text, videos. - Don't use cards for content that should be directly comparable, use a table view or a grid view for that. - If you would show more than 20 cards at a time, or if the user would have to scroll for more than three screen heights to see all of them, consider using a list instead. - Don't use cards with text input elements. - If your cards consist of just one image a grid with overlay actions might be more suitable. Behavior ~~~~~~~~ |desktopicon| Desktop ^^^^^^^^^^^^^^^^^^^^^ Cards are responsive. They resize to fit into the available space. .. raw:: html - + It is recommended that you adjust the number of cards displayed next to each other depending on the available space. .. raw:: html - + |mobileicon| Mobile ^^^^^^^^^^^^^^^^^^^ - Cards only resize to orientation changes. - The number of columns only adjust to orientation changes. Appearance ~~~~~~~~~~ It is recomended that you use the standard card layout for consistency, but cards can have a lot of different layouts. .. figure:: /img/Card6.qml.png - :alt: Default card layout + :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 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. - Use a well known aspect ratio for a header image - .. image:: /img/Card5.qml.png - :alt: Cards with 16x9, 4x3, 1x1 header image aspect ratio + .. figure:: /img/Card5.qml.png + :alt: Cards with 16×9, 4×3, 1×1 header image aspect ratio. + + Cards with 16×9, 4×3, 1×1 header image aspect ratio. - Add a padding of at least largeSpacing to the card, except for videos and images. These can ignore the padding and span the entire width or height of a card. - .. image:: /img/Card2.qml.png - :alt: Padding for text and buttons + .. figure:: /img/Card2.qml.png + :alt: Padding for text and buttons. + + Padding for text and buttons. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: Card ` - :kirigamiapi:`Kirigami: CardsGridView ` - :kirigamiapi:`Kirigami: CardsLayout ` - :kirigamiapi:`Kirigami: CardsListView ` diff --git a/HIG/source/components/editing/checkbox.rst b/HIG/source/components/editing/checkbox.rst index 35e127c..dc82c6d 100644 --- a/HIG/source/components/editing/checkbox.rst +++ b/HIG/source/components/editing/checkbox.rst @@ -1,212 +1,210 @@ Checkbox ======== Purpose ------- -A *checkbox* is a control that permits the user to make multiple +A checkbox is a control that permits the user to make multiple selections from a number of options. Checkboxes are used to toggle an option on or off, or to select or deselect an item. Users make a decision between two clearly opposite choices, e.g. 'on vs. off', 'apply vs. don't apply', 'show vs. hide'. -Example -------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use checkboxes for non-exclusive options that have clear alternatives. Mutually exclusive options should use a set of :doc:`radio buttons ` or a :doc:`combo box `. .. container:: flex .. container:: .. figure:: /img/Ambiguous_Opposite_Bad.qml.png :figclass: border - :iconred:`BAD` |br| - Do not use a checkbox if the opposite is ambiguous. + :iconred:`Don't.` |br| + Don't use a checkbox if the opposite is ambiguous. .. container:: .. figure:: /img/Ambiguous_Opposite_Good.qml.png :figclass: border - :noblefir:`GOOD` |br| - Using two radio buttons removes the need to guess. + :noblefir:`Do.` |br| + Use two radio buttons to remove the need to guess. - For more than five options, use either a :doc:`list view ` or the :doc:`dual-list pattern ` in case of multiple selections. -- Do not use the selection to perform commands. +- Don't use the selection to perform commands. .. container:: flex .. container:: .. figure:: /img/No_Command_2_Bad.qml.png :figclass: border - :iconred:`BAD` |br| - Do not use the selection to perform commands. + :iconred:`Don't.` |br| + Don't use the selection to perform commands. .. container:: .. figure:: /img/No_Command_2_Good.qml.png :figclass: border - :noblefir:`GOOD` |br| + :noblefir:`Do.` |br| Consider using a :doc:`push button <../navigation/pushbutton>` instead. Behavior ~~~~~~~~ - Checking a checkbox should always "enable" an option or change the state of an option to "on". Checking a negative or disabling option is a double negative and causes confusion and errors. .. container:: flex .. container:: .. figure:: /img/Checkbox_Enable_Bad.qml.png :figclass: border - :iconred:`BAD` + :iconred:`Don't.` |br| + Don't use checkboxes for negatives. .. container:: .. figure:: /img/Checkbox_Enable_Good.qml.png :figclass: border - :noblefir:`GOOD` + :noblefir:`Do.` |br| + Use checkboxes for positives. - Use the mixed state only to indicate that an option is set for some, but not all, child objects. Mixed state must not be used to represent a third state. .. image:: /img/Checkbox_Mixed_State.qml.png :alt: Example for mixed state. - Users must not be able to set a mixed state directly. - Clicking a mixed state checkbox enables all child objects. -- Do not use sliding switches in Desktop applications. They only offer +- Don't use sliding switches in Desktop applications. They only offer good user interaction on touch screens, so they should only be used in applications for mobile devices. .. container:: flex .. container:: .. figure:: /img/Checkbox_Switch_Desktop.qml.png - :iconred:`BAD` + :iconred:`Don't.` |br| + Don't use sliding switches on desktop. .. container:: .. figure:: /img/Checkbox_Switch_Mobile.qml.png - :noblefir:`GOOD` + :noblefir:`Do.` |br| + Do use sliding switches on mobile. Appearance ~~~~~~~~~~ -If you are using qt widgets you should use one of Qt's Layout Classes -like , that will take care of lay outing and spacing of your controls. +If you are using Qt Widgets you should use one of Qt's Layout classes, +which will take care of the layout and spacing of your controls. - The text of a checkbox is on the right of its tick rectangle, which can make it difficult to avoid blank areas on the left side of the form. To keep the layout of the form balanced you can use one of the following approaches: - Group checkboxes together in the widget column and add a label describing the group in the label column. .. image:: /img/Grouped_checkboxes.qml.png :alt: Grouped checkboxes - If all else fails, add a label describing the checkbox on the left side of the checkbox, then set the text of the checkbox to "Enabled", "On", or similar. .. image:: /img/Checkbox_separate_label.qml.png :alt: Using a separate title label for the checkbox. - When options are subordinate to a checkbox (e.g. Audio level can only be set if the Activate Audio option is selected), this relation should be visualized by indenting the sub-options. There are two options to do so: - When you are using a left-aligned checkbox, indent the sub-options by using a horizontal spacer of SizeType "Minimum". .. image:: /img/Suboption_spacer.qml.png :alt: Aligning sub-options with a horizontal spacer of SizeType "Minimum". - When you are using a checkbox that is placed right to its label, indent the sub-options in the same vertical axis as the checkbox. .. image:: /img/Suboption_right.qml.png :alt: Aligning sub-options with the same vertical axis as the checkbox itself.| - If activating a choice affects the appearance or the enabled state of other controls, place them next to the checkbox (group). - Align checkboxes vertically rather than horizontally, as this makes them easier to scan visually. Use horizontal or rectangular alignments only if they greatly improve the layout of the window. - If certain controls in a configuration dialog are only relevant if a certain checkbox is checked (i.e. they are dependent controls), disable them instead of hiding them if that checkbox is unchecked. - -- Do not separate checkbox and label. Clicking on both the box and the +- Don't separate checkbox and label. Clicking on both the box and the label should toggle the option. - - .. image:: /img/HIG_Checkbox5.png - :alt: Separate checkbox and label - -- Do not add line breaks. If necessary place an additional label below +- Don't add line breaks. If necessary, place an additional label below the checkbox. .. container:: flex .. container:: .. figure:: /img/Checkbox_Alignment_Bad.qml.png + :figclass: border - :iconred:`BAD` + :iconred:`Don't.` |br| + Don't use linebreaks in a checkbox's label. .. container:: .. figure:: /img/Checkbox_Alignment_Good.qml.png + :figclass: border - :noblefir:`GOOD` + :noblefir:`Do.` |br| + Add another label if more explanation is required. - Label a group of checkbox with a descriptive caption to the top left of the group (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - Use :doc:`sentence style capitalization ` for checkbox items. -- Do not use ending punctuation (neither dot nor colon) for group - label. Code ---- Kirigami ~~~~~~~~ - `QML: CheckBox `_ Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma CheckBox ` diff --git a/HIG/source/components/editing/combobox.rst b/HIG/source/components/editing/combobox.rst index 187a081..0030a67 100644 --- a/HIG/source/components/editing/combobox.rst +++ b/HIG/source/components/editing/combobox.rst @@ -1,93 +1,93 @@ -Combo box +Combo Box ========= .. figure:: /img/Combobox1.png :alt: Combobox :figclass: border A combination of a drop-down list and an edit control. Purpose ------- -A *combo box* is a combination of a drop-down list and an edit control, -thus allowing users to enter a value that isn't in the list. It behaves +A combo box is a combination of a drop-down list and an edit control, +thus allowing users to enter a value that is not in the list. It behaves like a drop-down list and allows the user to choose from a list of existing items but adds the option to type a value directly into the control. Newly typed items are usually added to the list and can be selected next time. Combo boxes are typically applied to provide auto-complete or auto-type functionality in a convenient way to the user. 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". The input field of the combo box ("editable" is true) marks the completed part of the item as selected, making it easy to change the completion. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +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 ` in case of read-only interaction. - Consider to replace the combo box by a :doc:`list view ` with a connected :doc:`edit control `. Behavior ~~~~~~~~ - Show a maximum of eight items at once. -- When possible apply changes immediately but do not initiate an action +- When possible apply changes immediately but don't initiate an action (like print, send, delete) when the user selects an item from the list. -- Do not add controls to the drop-down (e.g. checkboxes for each +- 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". -- Do not have blank list items; use meta-options, e.g. (None) instead +- Don't have blank list items; use meta-options, e.g. (None) instead. Appearance ~~~~~~~~~~ - Combo boxes are distinguished visually from drop-down lists (normally - by the raised or lowered bevel). Do not override the common + by the raised or lowered bevel). Don't override the common processing, e.g. by using a combo box and making it read only in order to simulate a simple drop-down list. - If activating a choice affects the appearance or the enabled state of other controls, place them next to the combo box. - 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 combo box 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/editing/date.rst b/HIG/source/components/editing/date.rst index 0600b47..3219dcf 100644 --- a/HIG/source/components/editing/date.rst +++ b/HIG/source/components/editing/date.rst @@ -1,45 +1,45 @@ -Date and time picker +Date and Time Picker ==================== Purpose ------- -The *date/time picker* is a control that provides a convenient way to +The date/time picker is a control that provides a convenient way to select a certain date or time. The time picker works just like a :doc:`spin box ` with an adopted mask. The date picker shows all days of a month in weekly columns, has small navigation buttons to access previous and next month or years as well as interactive controls to chose month and year directly. The user 'picks' the date per single click on a particular day. An additional 'today' button can be used to navigate back. The benefit of date/time picker is that these controls prevent format error and provide feedback on wrong input. Guidelines ---------- - Use a date/time picker as a convenient way to select a certain day or time. - In situations where users enter a date that they already know for certain (e.g. their birthday), use a KDateWidget. - If they want to enter a date and time they already know exactly, use a KDateTimeWidget. - If users want to choose a date and time using the application (e.g. while scheduling an appointment or choosing a date for a vacation), use the KDatePicker or KDateComboBox (depending on the amount of space available) and KTimeComboBox or KTimeComboBox. - If users want to browse through dates (for example when viewing a calendar or browsing a history based on the date), use a KDatePicker for convenient switching with a single click." - When user must select both start and end date/times, make the default end date/time aware of the start date/time: when the user sets a start date, switch the end date at least to the same date. - Avoid wrong input by restricting the period to a reasonable range (for instance when a range is being selected). -- Do not modify localization settings (i.e. first day of week, date +- Don't modify localization settings (i.e. first day of week, date label etc.) - Use controls consistently; either all date input should be done by date picker or none. - Insert current time or date into into input field on user reset. diff --git a/HIG/source/components/editing/dropdown.rst b/HIG/source/components/editing/dropdown.rst index 8b0b3a8..3e90fd3 100644 --- a/HIG/source/components/editing/dropdown.rst +++ b/HIG/source/components/editing/dropdown.rst @@ -1,100 +1,100 @@ -Drop-down +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 ~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 do not initiate an action +- 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. -- Do not add controls to the drop-down (e.g. checkboxes for each +- 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". -- Do not have blank list items; use meta-options, e.g. (None) instead +- 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/editing/grid.rst b/HIG/source/components/editing/grid.rst index 77e72ce..46f9936 100644 --- a/HIG/source/components/editing/grid.rst +++ b/HIG/source/components/editing/grid.rst @@ -1,45 +1,39 @@ Grid ==== .. image:: /img/Grid1.png :alt: Grid - -Purpose -------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ - Behavior ~~~~~~~~ -On mouse over the item "go darker" to emphasis the overlay buttons +On mouseover, items are darkened or highlighted +(depending on the active color scheme) to +emphasize their overlay buttons. -Overlay buttons +Overlay Buttons ^^^^^^^^^^^^^^^ -Overlay buttons only appear on mouse over. Overlay buttons should only -used for actions for this specific item, never for global actions -regarding other items in the grid +Overlay buttons only appear on mouseover. Overlay buttons should +only affect the item they are on. They should never affect other items. Appearance ~~~~~~~~~~ -- All items must have the same size +- 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 -- Grid has a PaperWhite background on desktop, an no background on - mobile +- Overlay buttons are placed at the bottom right corner of items. +- Grids have a PaperWhite background on desktop, and no background on + mobile. Code ---- Kirigami ~~~~~~~~ - `QML: GridView `_ - :kirigamiapi:`Kirigami: CardsGridView ` diff --git a/HIG/source/components/editing/index.rst b/HIG/source/components/editing/index.rst index f3bbbe7..4683139 100644 --- a/HIG/source/components/editing/index.rst +++ b/HIG/source/components/editing/index.rst @@ -1,52 +1,52 @@ -Editing and manipulation +Editing and Manipulation ======================== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: card checkbox combobox date dropdown grid lineedit list radiobutton slider spinbox tableview textedit togglebutton tree Editing and Manipulation considers the behaviors that result in persistent changes to user’s stored information. Behaviors in this layer can often be recognized by the following traits: they result in persistent, stored changes; they require an implicit or explicit save operation; and they typically require validation of the input data. Selection ~~~~~~~~~ * :doc:`card` * :doc:`checkbox` * :doc:`combobox` * :doc:`dropdown` * :doc:`grid` * :doc:`list` * :doc:`radiobutton` * :doc:`togglebutton` * :doc:`tree` -Unconstrained input +Unconstrained Input ~~~~~~~~~~~~~~~~~~~ * :doc:`lineedit` * :doc:`tableview` * :doc:`textedit` -Constrained input +Constrained Input ~~~~~~~~~~~~~~~~~ * :doc:`date` * :doc:`slider` * :doc:`spinbox` diff --git a/HIG/source/components/editing/lineedit.rst b/HIG/source/components/editing/lineedit.rst index 4fa4a9a..2237db0 100644 --- a/HIG/source/components/editing/lineedit.rst +++ b/HIG/source/components/editing/lineedit.rst @@ -1,67 +1,64 @@ -Line edit +Line Edit ========= .. figure:: /img/Lineedit1.png :alt: Lineedit :figclass: border Single line control to enter unconstrained text. Purpose ------- -The *line edit* control displays a single line of text to the user and +The line edit control displays a single line of text to the user and allow the user to enter unconstrained text. If more than one line is required a text edit is the right control. Because line edits are unconstrained and don’t accept valid data only, input validation and problem handling should be handled carefully. -Examples --------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use edits for input of single lines of unconstrained text. - In case of multiple lines of text or more than a few words, use a :doc:`text edit ` -- Do not use a line edit if only a specific type of data is valid. Use +- Don't use a line edit if only a specific type of data is valid. Use a control for constrained input. Behavior ~~~~~~~~ - Mask letters if edit is used to enter passwords. - When setting a new password, have it entered twice to prevent typos in passwords. - Provide a "Show password" checkbox to unmask the password both when setting new and when entering existing passwords. - Consider to use auto-complete feature to help users when entering data that is likely to be used repeatedly. - If the user enters a character that is known to be invalid, ignore the character and display an input problem hint that explains the valid characters (e.g. numbers vs. characters). - If the input data has a value or format that is known to be invalid, display an input problem hint when the text box loses input focus (e.g. wrong zip code format). - If the input data is inconsistent with other controls on the window, give an error message when the entire input is complete, such as when users click OK for a modal dialog box. -- Don't clear invalid input data unless users aren't able to correct +- Don't clear invalid input data unless users are not able to correct errors easily. Doing so allows users to correct mistakes without starting over. Appearance ~~~~~~~~~~ - When disabling the line edit, also disable any associated labels and buttons. - Label every line edit with a descriptive caption to the left (cf. :doc:`/layout/alignment`). - Create a buddy relation so access keys are assigned. diff --git a/HIG/source/components/editing/list.rst b/HIG/source/components/editing/list.rst index 5679260..274e614 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 +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 -~~~~~~~~~~~~~~~~~~~~~~~~~ +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. +- 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. Make sure sorting fits translation. -On demand actions +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 :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 +If only one action is available, most the time it is 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 +- Don't 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/components/editing/radiobutton.rst b/HIG/source/components/editing/radiobutton.rst index 2fd2c4b..58d4cc4 100644 --- a/HIG/source/components/editing/radiobutton.rst +++ b/HIG/source/components/editing/radiobutton.rst @@ -1,193 +1,201 @@ -Radio button +Radio Button ============ Purpose ------- -*Radio buttons* offer the user a choice of two or more mutually +Radio buttons offer the user a choice of two or more mutually exclusive options. Try to limit the number of radio buttons and radio button groups in a dialog. Offering a high number of radio buttons consumes screen space and adds to visual clutter. At the same time, showing all available options at once is an advantage if users are likely not to know possible alternatives. -Examples --------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use radio buttons for a few mutually exclusive options. If there are more than five options (or if there is not enough space to arrange four or five options), use a combo box or list instead. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Many_Bad.qml.png :figclass: border - :iconred:`BAD` + :iconred:`Don't.` |br| + Don't use radio buttons for more than five options. .. container:: .. figure:: /img/Radiobutton_Many_Good.qml.png :figclass: border - :noblefir:`GOOD` + :noblefir:`Do.` |br| + Use a combobox instead. - If there are only two options where one is the negation of the other - (e.g. "apply" vs. "do not apply"), consider replacing the radio + (e.g. "apply" vs. "don't apply"), consider replacing the radio buttons by one :doc:`checkbox `. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Negation_Bad.qml.png :figclass: border - :iconred:`BAD` + :iconred:`Don't.` |br| + Don't use radio buttons for do/don't operations. .. container:: .. figure:: /img/Radiobutton_Negation_Good.qml.png :figclass: border - :noblefir:`GOOD` + :noblefir:`Do.` |br| + Use a checkbox instead. - Use radio buttons if the user should see the choices without further interaction. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Visible_Bad.qml.png :figclass: border - :iconred:`BAD` + :iconred:`Don't.` |br| + Don't hide choices that the user should see from the start + in comboboxes. .. container:: .. figure:: /img/Radiobutton_Visible_Good.qml.png :figclass: border - :noblefir:`GOOD` + :noblefir:`Do.` |br| + Use radio buttons instead. -- Do not use a radio button to initiate an action. Consider using a +- Don't use a radio button to initiate an action. Consider using a :doc:`push button <../navigation/pushbutton>` instead. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Command_Bad.qml.png :figclass: border - :iconred:`BAD` |br| - Do not use the selection to perform commands. + :iconred:`Don't.` |br| + Don't use the selection to perform commands. .. container:: .. figure:: /img/No_Command_2_Good.qml.png :figclass: border - :noblefir:`GOOD` |br| + :noblefir:`Do.` |br| Consider using a :doc:`push button <../navigation/pushbutton>`. Behavior ~~~~~~~~ - Radio buttons are not dynamic; their content or labels should not change depending on the context. - Always have one radio button selected. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Default_Bad.qml.png :figclass: border - :iconred:`BAD` + :iconred:`Don't.` |br| + Don't forget a default option. .. container:: .. figure:: /img/Radiobutton_Default_Good.qml.png :figclass: border - :noblefir:`GOOD` + :noblefir:`Do.` |br| + Set a default option. - Make the first item the default option. .. container:: flex .. container:: .. figure:: /img/Radiobutton_First_Bad.qml.png :figclass: border - :iconred:`BAD` + :iconred:`Don't.` |br| + Don't have an option besides the first as the default. .. container:: .. figure:: /img/Radiobutton_First_Good.qml.png :figclass: border - :noblefir:`GOOD` + :noblefir:`Do.` |br| + Set the first option as default. Reorder your items if necessary. - When using a radio button and none of the options is a valid choice, add another option to reflect this choice, such as None or Does not apply. Appearance ~~~~~~~~~~ If you are using Qt widgets you should use one of `Qt's Layout Classes `_, -which will take care of laying out and spacing of your controls. +which will take care of the layout and spacing of your controls. - When options are subordinate to a radio box, this relation should be visualized by indenting the sub-options by using a horizontal spacer of SizeType "Minimum". - If activating a choice affects the appearance or the enabled state of other controls, place them next to the radio button (group). - Align radio buttons vertically rather than horizontally, as this makes them easier to scan visually. Use horizontal or rectangular alignments only if they greatly improve the layout of the window. - If certain controls in a configuration dialog are only relevant if a certain radio button is toggled on (i.e. they are dependent controls), disable them instead of hiding them if that radio button is toggled off. -- Do not separate radio button and label. Clicking on both the button +- Don't separate radio button and label. Clicking on both the button and the label should toggle the option. -- Do not add line breaks. If necessary place an additional label below +- Don't add line breaks. If necessary place an additional label below the checkbox. - Label a group of radio buttons with a descriptive caption to the top left of the group (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - Use :doc:`sentence style capitalization ` for radio buttons. -- Do not use ending punctuation (neither dot nor colon) for group +- Don't use ending punctuation (neither dot nor colon) for group label. Code ---- Kirigami ~~~~~~~~ - `QML: RadioButton `_ Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma RadioButton ` diff --git a/HIG/source/components/editing/slider.rst b/HIG/source/components/editing/slider.rst index b078e89..7dc5962 100644 --- a/HIG/source/components/editing/slider.rst +++ b/HIG/source/components/editing/slider.rst @@ -1,126 +1,126 @@ Slider ====== Purpose ------- -A *slider* is a widget with which a user may set a value by moving an +A slider is a widget with which a user may set a value by moving an indicator, usually in a horizontal fashion. The user may also click on a point on the slider to change the setting. It is different from a scrollbar in that it is typically used to adjust a value without changing the format of the display or the other information on the screen. A slider is used to set defined, contiguous values or a range of discrete values. It is a good choice when values have a relative quantity, not a numeric value. Usually, changes made on the slider are shown immediately. That instant feedback supports input that is not necessarily precise. Compared with spin controls a slider provides faster changes within a larger range but with lower accuracy. Sliders are almost solely operable by mouse. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a slider when adjusting the value relative to its current value is more important than choosing an absolute value. - Use a slider when it is useful for the user to control the rate of change of the value in real time. - If the value is open-ended on one or both ends, consider using a :doc:`Spin Box ` instead. Behavior ~~~~~~~~ - Try to give immediate feedback while the user makes a selection. - Size the control so that a user can easily set the desired value. -- Do not use a non-linear scale, e.g. logarithmic. +- Don't use a non-linear scale, e.g. logarithmic. Appearance ~~~~~~~~~~ - Label the slider with a text label to its left, using sentence capitalization. Provide an access key in the label that allows the user to give focus directly to the slider. - Align the label horizontally in line with the slider. - You can show the current value on the right of the slider or if space is very dense show it only as a tooltip when the slider is moved .. figure:: /img/Slider.value.qml.png :alt: Show value always or as tooltip Show value always or as tooltip - Add the unit to the current value caption, if appropriate. Slider with few steps ^^^^^^^^^^^^^^^^^^^^^ eg screen size, symbol-size .. figure:: /img/Slider.qml.png :alt: Spacing Spacing of slider components - Mark significant values along the length of the slider with text or checkmarks. Checkmark have a height of 4 px or 8 if you want to emphasize them. - Min/max labels are optional. Label min/max with real values, eg '640x480' and '5120×2880' in case of screen resolution. - Label the range of values; use checkmark and value label; don't label every checkmark. Slider with many steps ^^^^^^^^^^^^^^^^^^^^^^ eg volume control, mouse speed, brightness .. figure:: /img/Slider.Volume.qml.png :alt: Exact value is not important Exact value is not important - Don't show checkmarks if the exact value is not important - Don't show min/max label if the values don't give the user additional - information, eg. don't label them 0%, 100% + information, (eg. don't label them 0%, 100% when obvious) - If the exact value might be important to the user offer an input field instead of the current value label .. figure:: /img/Slider.Speed.qml.png :alt: Offer text input for exact value Offer text input for exact value Slider and Spinbox together ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Use both a slider and spin box when the value is constrained at both ends, and when there is a large range of values (more than 20 steps) but precise control over the value is needed nevertheless. -- Consider using only a slider *or* a spin box if a well-defined workflow +- Consider using only a slider or a spin box if a well-defined workflow makes the other redundant. - The values of the slider and spin box should be linked so changes to one are immediately reflect in another. - The spin box should be aligned with the long axis of the slider: if the slider is horizontal, the spin box should be to the right of the slider and aligned vertically with the center of the slider; if the slider is vertical, the spin box should be below the slider and aligned horizontally with the center of the slider. - Provide a single label using a text label above it or to the left of the widgets, using sentence capitalization. Provide an access key in the label that should give focus directly to the spin box. - Mark significant values along the length of the slider with text or tick marks. Code ---- Kirigami ~~~~~~~~ - `QML: Slider `_ -Plasma components +Plasma Components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma Slider ` diff --git a/HIG/source/components/editing/spinbox.rst b/HIG/source/components/editing/spinbox.rst index 847be58..55b5333 100644 --- a/HIG/source/components/editing/spinbox.rst +++ b/HIG/source/components/editing/spinbox.rst @@ -1,78 +1,78 @@ -Spin box +Spin Box ======== .. figure:: /img/Spinbox1.png :alt: Spinbox :figclass: border Control that accepts a range of values. Purpose ------- -A *spin box* is a line edit that accepts a range of values. It +A spin box is a line edit that accepts a range of values. It incorporates two arrow buttons that allow the user to increase or decrease the current value by a fixed amount. Spins are efficient for small changes of numeric values in a contiguous range. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use spin boxes for numerical input only. Use a list or option menu when you need the user to select from fixed data sets of other types. - Use a spin box if the numerical value is meaningful or useful for the user to know, and the valid input range is unlimited or fixed at one end only. For example, a control for specifying the number of iterations of some action, or a time-out value. - If the range is fixed at both ends, or the numerical values are arbitrary (for example, a volume control), use a :doc:`Slider ` control instead. - For cases where the values are constrained at both ends and there large ranges of integers (more than about 20) or floating-point values that require precise control, consider providing both a :doc:`Slider and Spin Box `. This allows the user to quickly set or fine-tune the setting more easily than they could with the slider control alone. Behavior ~~~~~~~~ - If the input data has a value that is known to be invalid, display an input problem hint when the spin edit loses input focus. - If the input data is inconsistent with other controls on the window, give an error message when the entire input is complete, such as when users click OK for a modal dialog box. -- Don't clear invalid input data unless users aren't able to correct - errors easily. Doing so allows users to correct mistakes without +- Only clear invalid input data when users are not able to correct errors + easily. Doing so allows users to correct mistakes without starting over. Appearance ~~~~~~~~~~ - Label the spin box with a text label to its left, using sentence capitalization. - Always append a suffix with the value's unit to the right. - Provide an access key in the label that allows the user to give focus directly to the spin box. - Right-justify the contents of spin boxes, unless the convention in the user's locale demands otherwise. This is useful in windows where the user might want to compare two numerical values in the same column of controls. In this case, ensure the right edges of the relevant controls are also aligned. Code ---- Kirigami ~~~~~~~~ - `QML: SpinBox `_ -Plasma components +Plasma Components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma SpinBox ` diff --git a/HIG/source/components/editing/tableview.rst b/HIG/source/components/editing/tableview.rst index b027166..040b899 100644 --- a/HIG/source/components/editing/tableview.rst +++ b/HIG/source/components/editing/tableview.rst @@ -1,65 +1,62 @@ -Table view +Table View ========== Purpose ------- -A *table* (also known as *grid* or spreadsheet) is a graphical control +A table (also known as grid or spreadsheet) is a graphical control to present data in an ordered arrangement of rows and columns. The intersection of a row and a column is a cell. The elements of a table may be grouped, segmented, or arranged in many different ways, and even nested recursively. It provides a familiar way to convey information that might otherwise not be obvious or readily understood. Tables provide inline editing with the advance of a concise layout since no additional control is needed for input. The approach is usually less error-prone because a list with direct input has no dependency to other controls (in contrast to the combination of a list with an edit which needs to be enabled or disabled appropriate to the list entry the user clicks). The drawback is reduced discoverability for lists with restricted editing function, at least when only a few cells can be changed. User does not know which cell is editable and which is not. -Example -------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a table to arrange data in two dimensions. - Use a table for a concise layout with inline editing feature. -- Do not use a table for read only purpose. In this case use a simple +- Don't use a table for read-only data. In this case use a simple :doc:`list view ` or a :doc:`tree view ` with multiple columns. Behavior ~~~~~~~~ - Switch from viewing mode to edit mode after single click on the editable cell. - Change appearance of cells when switching from viewing to editing. Editable cells have a lowered bevel; they look like they can be filled. - Mark currently changed cells with a red corner. - Define keyboard navigation within the table since the control receives focus as a whole. By pressing arrow-down key the next row is focused; respectively arrow-up for previous row. The arrow-left or - arrow-right key navigates to adjacent columns if available. Do not + arrow-right key navigates to adjacent columns if available. Don't change tab key navigation to allow users to switch to other controls. - Use the appropriate control for constrained input. Show the control’s UI (e.g. arrow for :doc:`drop-down list `) not until the cell is in edit mode. - Distinguish editable cells from those that are read-only. - Allow tables to be extended by users in both directions. - Provide copy/paste feature for single as well as multiple selected cells, if appropriate. Appearance ~~~~~~~~~~ - Avoid horizontal scrollbars. Size the table to a reasonable width. - Use fixed column header. - Label the table with a descriptive caption to the top left (cf. :doc:`/layout/alignment`). - Create a buddy relation so access keys are assigned. diff --git a/HIG/source/components/editing/textedit.rst b/HIG/source/components/editing/textedit.rst index 10a62d9..63104b2 100644 --- a/HIG/source/components/editing/textedit.rst +++ b/HIG/source/components/editing/textedit.rst @@ -1,44 +1,44 @@ -Text edit +Text Edit ========= .. figure:: /img/Textedit1.png :alt: Textedit :figclass: border Control to enter multiple lines of text. Purpose ------- -The *text edit* control displays multiple lines of text to the user and +The text edit control displays multiple lines of text to the user and allow the user to enter unconstrained text. In contrast to a line edit that is used to enter only one line of text the text edit is the right control for more than one line. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use text edits for input of unconstrained text with more than one line. -- Do not use a text edit for input of a few words. Use a :doc:`line edit ` +- Don't use a text edit for input of a few words. Use a :doc:`line edit ` to enter single lines of text. Behavior ~~~~~~~~ -- Do not make users scroll unnecessarily; size text boxes to eliminate +- Don't make users scroll unnecessarily; size text boxes to eliminate the need for scrolling. -- Do not put horizontal scroll bars on multi-line text boxes. +- Don't put horizontal scroll bars on multi-line text boxes. Appearance ~~~~~~~~~~ - When disabling the text edit, also disable any associated labels and buttons. - Label every text edit with a descriptive caption to the top left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. diff --git a/HIG/source/components/editing/togglebutton.rst b/HIG/source/components/editing/togglebutton.rst index 2808aa4..b6ee33b 100644 --- a/HIG/source/components/editing/togglebutton.rst +++ b/HIG/source/components/editing/togglebutton.rst @@ -1,53 +1,50 @@ -Toggle button +Toggle Button ============= .. figure:: /img/Togglebutton1.png :alt: Togglebutton :figclass: border Control to show a change of state. Purpose ------- -*Toggle buttons* look similar to regular buttons, but are used to show +Toggle buttons look similar to regular buttons, but are used to show or change a state rather than initiate an action. A toggle button's two states, set and unset, are shown by its appearing "pushed in" or "popped out" respectively. Toggle buttons are a valid option to indicate a state with the advance of using an icon. Compared to the related radio button or checkbox they are an efficient way to save screen space. But toggle buttons should be used with care outside a toolbar because the state is not clearly indicated. -Example -------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a toggle button to indicate a state if no other control apply, i.e. in case of the :doc:`toolbar <../navigation/toolbar>`. - Prefer :doc:`radio buttons ` or :doc:`checkboxes ` outside the toolbar. Behavior ~~~~~~~~ - Group toggle buttons in case of multiple selection. - Separate toggle buttons from other controls, so they are not mistaken for push buttons. -- Do not use a toggle button to initiate an action. -- Do not change the label according the button state. +- Don't use a toggle button to initiate an action. +- Don't change the label according the button state. Appearance ~~~~~~~~~~ - Align groups of toggle buttons horizontally rather than vertically. - Provide an access key in the label of all toggle buttons that allows the user to set or unset the button directly from the keyboard. diff --git a/HIG/source/components/editing/tree.rst b/HIG/source/components/editing/tree.rst index 4e9bfe4..7b50fc7 100644 --- a/HIG/source/components/editing/tree.rst +++ b/HIG/source/components/editing/tree.rst @@ -1,91 +1,83 @@ -Tree view +Tree View ========= Purpose ------- Tree view allows users to view and interact with objects arranged in hierarchical mode. Users can make single selections or multiple selections. Objects containing data are called *leaf nodes* and objects contianing sub-objects are called *container nodes*. The top-most container node is called the *root node*. .. image:: /img/TreeView.png :alt: TreeView.png -A tree view is an appropriate control for items that have a single, -natural, hierarchical categorization that's familiar to most users with -more than two levels (not including the root node). But having -hierarchical data doesn't mean a tree view must be used. Very often a -list view or a combination of list view and drop-down list is a simpler -and a more powerful choice. Tree views can present a challenge for users -when the level of complexity is not visually understood and users may -take longer to familiarize themselves with the tree and each item's -location. This can to confusion. Designers and developers must balance -the user's ability to easily discover contact with a predictable tree -view model that minimizes confusion. +A tree view is an appropriate control for data best represented as a tree, +such as nodes in HTML/XML and code outlines. If your data is not best represented +as a tree, consider using a list view or a dropdown list instead. Guidelines ---------- -Ask yourself "Is this the right control?" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Apply a tree view to large data sets that can be categorized into two or more levels. - A tree view should not have more than four sub-levels (not including the root node). The most commonly accessed objects should appear in the first two levels. - Use a natural hierarchical structure that is familiar to most users. Balance discoverability with a predictable user model that minimizes confusion. - Consider breaking down the hierarchical data. For example, into a selection by a :doc:`drop-down list ` with an associated :doc:`list view `. Behavior ~~~~~~~~ - Use double click to unfold items from the first item in the tree view list. Make double-click behavior redundant via button or context menu. - Use directional arrows to provide key-based navigation. Also enable the use of Home, End, Page Up, and Page Down. - Provide a context menu with relevant commands. - Provide a root node only if users need the ability to perform commands on the entire tree. - Users should always be able to expand and collapse container nodes by clicking expander buttons. - Use headers with a meaningful caption for each column. - Avoid using empty trees. - If the tree has alternative access methods such as a word search or an index, optimize the tree for browsing by focusing on the most useful content. Multi selection: - Use checkboxes to indicate multiple selections. - For checkboxes, use the mixed state to indicate that an option is set for some, but not all, child objects. Users should not be able to set a mixed state directly (cf. :doc:`checkboxes `). - Clicking a mixed state checkbox selects all child objects and the parent checkbox. - Don’t use checkboxes in single selection trees. Appearance ~~~~~~~~~~ - If high-level containers have similar contents, but have different purposes, consider using visual clues, e.g. icons to differentiate between them. - Use persistent tree view states so that users find the list the same way they left it. - Make controls large enough that it can show at least eight list items at a time without scrolling. - Label the tree view with a descriptive caption to the top left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - Make use of punctuation (Except for dot "." or colon ":") for a caption. - Use :doc:`sentence style capitalization ` for tree view items. diff --git a/HIG/source/components/formating/groupbox.rst b/HIG/source/components/formating/groupbox.rst index 4737a7e..041a01d 100644 --- a/HIG/source/components/formating/groupbox.rst +++ b/HIG/source/components/formating/groupbox.rst @@ -1,45 +1,42 @@ -Group box +Group Box ========= Purpose ------- -A *group box* is a labeled rectangular area that surrounds a set of -related controls. A *frame* (also known as a panel) is an unlabeled -rectangular area that can be used to mark relationship. +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. Group box and frame are a way to show visual relationships; it provides no additional functionality. -Example -------- - Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Always use a group box to arrange related controls. - Use a frame to arrange related controls that cannot be labeled. -- Do not group single controls. +- Don't group single controls. - Show relationship by layout only. Behavior ~~~~~~~~ -- Do not nest grouping elements; use layout to show relationships +- Don't nest grouping elements; use layout to show relationships within a group. -- Do not place controls in group box caption. -- Do not disable groups. To indicate that a group of controls doesn't +- Don't place controls in group box caption. +- Don't disable groups. To indicate that a group of controls does not currently apply, disable all the controls within the group, but not the group itself. - Put a :doc:`splitter` between aligned grouping controls. Appearance ~~~~~~~~~~ - Label the group box with a descriptive caption. -- Do not assign an access key to the group box caption. +- Don't assign an access key to the group box caption. - Set the group box or frame shadow to 'flat' to provide the consistent spacing required to convey relationship. diff --git a/HIG/source/components/formating/index.rst b/HIG/source/components/formating/index.rst index eb6c047..326bf14 100644 --- a/HIG/source/components/formating/index.rst +++ b/HIG/source/components/formating/index.rst @@ -1,13 +1,13 @@ -Formating -========= +Formatting +========== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: groupbox splitter * :doc:`groupbox` * :doc:`splitter` diff --git a/HIG/source/components/formating/splitter.rst b/HIG/source/components/formating/splitter.rst index 6a37f6a..207ab5e 100644 --- a/HIG/source/components/formating/splitter.rst +++ b/HIG/source/components/formating/splitter.rst @@ -1,32 +1,28 @@ Splitter ======== Purpose ------- -A *splitter* is a visual separator between two element groups. It allows +A splitter is a visual separator between two element groups. It allows the user to resize the adjacent groups. -Example -------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Always put a splitter between aligned, resizable grouping controls to - allow individualization for users. +- Always put a splitter between adjacent resizable views. Behavior ~~~~~~~~ - Remember position and adjust control size accordingly on next login. Appearance ~~~~~~~~~~ - Define a minimum size for areas that cannot be undercut by users. - Make splitters at least 5 pixels wide so that they can be easily clicked by any input device. diff --git a/HIG/source/components/index.rst b/HIG/source/components/index.rst index 2ed53ca..2d6e5da 100644 --- a/HIG/source/components/index.rst +++ b/HIG/source/components/index.rst @@ -1,82 +1,83 @@ Components ========== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: formating/index navigation/index assistance/index editing/index Formating --------- * :doc:`formating/groupbox` * :doc:`formating/splitter` Navigation ---------- * :doc:`navigation/actionbutton` * :doc:`navigation/commandlink` * :doc:`navigation/contextdrawer` * :doc:`navigation/contextmenu` * :doc:`navigation/dialog` * :doc:`navigation/globaldrawer` * :doc:`navigation/menubar` * :doc:`navigation/pushbutton` * :doc:`navigation/tab` * :doc:`navigation/toolbar` +* :doc:`navigation/scrim` -User assistance +User Assistance --------------- User Assistance guidance considers interface elements that inform users of the application’s activity and status, as well as elements dedicated to user education. This includes online help, error alerts, and status alerts. Notification ~~~~~~~~~~~~ * :doc:`assistance/emblem` * :doc:`assistance/inline` * :doc:`assistance/message` * :doc:`assistance/progress` * :doc:`assistance/statusbar` Help ~~~~ * :doc:`assistance/tooltip` -Editing and manipulation +Editing and Manipulation ------------------------ Editing and Manipulation considers the behaviors that result in persistent changes to user’s stored information. Selection ~~~~~~~~~ * :doc:`editing/card` * :doc:`editing/checkbox` * :doc:`editing/combobox` * :doc:`editing/dropdown` * :doc:`editing/grid` * :doc:`editing/list` * :doc:`editing/radiobutton` * :doc:`editing/togglebutton` * :doc:`editing/tree` -Unconstrained input +Unconstrained Input ~~~~~~~~~~~~~~~~~~~ * :doc:`editing/lineedit` * :doc:`editing/tableview` * :doc:`editing/textedit` -Constrained input +Constrained Input ~~~~~~~~~~~~~~~~~ * :doc:`editing/date` * :doc:`editing/slider` * :doc:`editing/spinbox` diff --git a/HIG/source/components/navigation/actionbutton.rst b/HIG/source/components/navigation/actionbutton.rst index b19c0d0..72da5fe 100644 --- a/HIG/source/components/navigation/actionbutton.rst +++ b/HIG/source/components/navigation/actionbutton.rst @@ -1,79 +1,79 @@ Primary Action Button ===================== .. figure:: /img/Actionbutton1.png :figclass: border :alt: Primary Action Button - Primary action, create a new address book entry. + Primary action - create a new address book entry. -When to use +When to Use ----------- Use a Primary Action Button whenever there is a primary action for a certain page of your application or for the whole application, which is executed frequently. Typical primary actions are "Create New", "Edit,", "Save" or "Send". Aditionally you can opt to define two secondary primary actions that are placed left and right to the main primary button. .. figure:: /img/Actionbutton2.png :figclass: border :alt: Primary Action Button with two secondary buttons Call, message and write an email as primary actions. If there is no primary action, you may opt to use the Primary Action Button as a shortcut to navigate back to the application's main page instead of omitting it completely. Do that if - navigating back to the main page is a frequent action in your application - or you use Primary Action buttons on some pages and would like to keep the layout consistent across pages - or drawers are frequently used - and the space occupied by the button is not urgently needed for the content If the primary action is clearly associated with a specific element on the user interface, place controls within the content instead. -How to use +How to Use ---------- - Provide a clear icon for the Primary Action Button since it has no text label - If the Primary Action Button changes its action within a page (for example switching to "save" when editing, change its icon as well - If you use the Primary Action Button as a shortcut for going to the main page, use the "go-home" icon from the actions category for it. -Desktop-specific +Desktop-Specific ~~~~~~~~~~~~~~~~ If your application is using :doc:`column-based navigation ` - If there is a global Primary Action, associate it with the first column - If there is a Primary action for the context of a specific column, associated with the respective page .. figure:: /img/Actionbutton3.png :figclass: border :alt: Primary Action Buttons on Desktop Primary Action Buttons are placed in a :doc:`toolbar ` Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` .. literalinclude:: /../../examples/kirigami/ActionButton.qml :language: qml diff --git a/HIG/source/components/navigation/commandlink.rst b/HIG/source/components/navigation/commandlink.rst index ff3b435..c2dea98 100644 --- a/HIG/source/components/navigation/commandlink.rst +++ b/HIG/source/components/navigation/commandlink.rst @@ -1,48 +1,45 @@ -Command link +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. -Example -------- - Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use command links for a set of mutually exclusive responses like navigation from hub to spoke pages. -- Do not present single command links. +- 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. -- Do not mix command links and command buttons at one place. +- 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. -- Do not use ellipsis. +- Don't use ellipsis. diff --git a/HIG/source/components/navigation/contextdrawer.rst b/HIG/source/components/navigation/contextdrawer.rst index 3052b7c..03b2622 100644 --- a/HIG/source/components/navigation/contextdrawer.rst +++ b/HIG/source/components/navigation/contextdrawer.rst @@ -1,78 +1,78 @@ -Context drawer +Context Drawer ============== .. container:: intend |desktopicon| |mobileicon| .. container:: available plasma qwidgets |nbsp| .. figure:: /img/Contextdrawer1.png :figclass: border :scale: 50 % :alt: Examples of a context drawer on mobile Examples of a context drawer on mobile Purpose ------- The Context Drawer is used to access controls that depend on the current context. This can be, for example, controls that affect a selected element in a list or that navigate through an opened document. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ Use a Context Drawer if your application has any functions which are only relevant in specific contexts, and which are not central enough to the application's main purpose to put them in the main user interface or in a toolbar. For actions which are always available, use the :doc:`Global Drawer `. Behavior ~~~~~~~~ - The Context Drawer is opened by swiping in from the left or right edge of the screen (depending on a system-wide setting) and closed by swiping in the other direction or tapping outside of it. - At the top of the drawer, state which object the controls affect (e.g. "Selected email") - By default, the Context Drawer simply contains a vertical list of action buttons which affect the currently selected/opened element - Center the list vertically instead of top-aligning, to allow an easier reach with the thumb - If needed, other controls related to the current context can be put in the Context Drawer - Try to keep the content of the context drawer in one page. If there two distinct "modes" of contextual actions (for example navigating through a PDF either by table of contents or thumbnails), consider using two :doc:`Tabs ` to separate them, but never use more than two tabs. .. figure:: /img/Contextdrawer2.png :figclass: border :scale: 50 % :alt: Examples of a context drawer on desktop Examples of a context drawer on desktop Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` .. literalinclude:: /../../examples/kirigami/AddressbookContextDrawer.qml :language: qml diff --git a/HIG/source/components/navigation/contextmenu.rst b/HIG/source/components/navigation/contextmenu.rst index 106cc03..fa65538 100644 --- a/HIG/source/components/navigation/contextmenu.rst +++ b/HIG/source/components/navigation/contextmenu.rst @@ -1,35 +1,32 @@ -Context menu +Context Menu ============ Purpose ------- A *context menu* displays a list of actions applicable to the current context. It is normally hidden from view (except :doc:`menu bars `) and drops down when the user right-clicks on something. Context menus should be considered accelerators for advanced desktop users. Many mouse users don't think to right-click on things. The right-click gesture required to show a context menus can be difficult to perform on many laptops, and it is flat-out impossible on a touch device. -Examples --------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Provide a context menu for any item with actions that can be performed on it. - Provide a context menu for common actions like 'Copy' and 'Paste' for textual controls, or navigation actions like 'Forward' and 'Backward. -- Do not use context menus as the only way to access functionality. Every item +- Don't use context menus as the only way to access functionality. Every item in a context menu must be available via a method that is somehow visible by default--typically the app's main :doc:`menu bar `, but also via toolbar buttons. -Behavior & Appearance -~~~~~~~~~~~~~~~~~~~~~ +Behavior and Appearance +~~~~~~~~~~~~~~~~~~~~~~~ See the guidelines for :doc:`menu bars `. diff --git a/HIG/source/components/navigation/dialog.rst b/HIG/source/components/navigation/dialog.rst index f1ef59a..ba5e283 100644 --- a/HIG/source/components/navigation/dialog.rst +++ b/HIG/source/components/navigation/dialog.rst @@ -1,87 +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, +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. -- Do not use dialogs if the flow must not get interrupted. In this case +- 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:`inline message <../assistance/inline>`. - Always use standard dialogs, if available. Behavior ~~~~~~~~ -- Do not apply dialog boxes that require the use of a scroll bar. -- Do not include a menu bar or status bar in dialogs. -- Do not display more than one owned choice dialog at a time from an - owner choice dialog. +- 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. -- Do not use dialogs to display non-critical messages which do not - require any further user interaction (typically dialogs with a single - "OK" or "Close" button). Consider to use +- 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>`. + :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 there is at least one third white space, do not overload - 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 `. +- 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/components/navigation/globaldrawer.rst b/HIG/source/components/navigation/globaldrawer.rst index bff65c2..5ea8583 100644 --- a/HIG/source/components/navigation/globaldrawer.rst +++ b/HIG/source/components/navigation/globaldrawer.rst @@ -1,110 +1,110 @@ -Global drawer +Global Drawer ============= Purpose ------- The Global Drawer is a standard element in KDE mobile applications. It contains an application's main menu, and any functions which are not part of the application's main usecases but are not specific to the current context either. .. container:: intend |desktopicon| |mobileicon| .. container:: available plasma qwidgets |nbsp| .. figure:: /img/Globaldrawer1.png :alt: Global drawer on mobile :figclass: border :scale: 40 % Global drawer on mobile Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: /img/Globaldrawer3.png :figclass: border :alt: Global drawer on desktop :scale: 40 % Global drawer on desktop Use a Global Drawer whenever your application has any functions which are not central enough to the application's main purpose to put them in the main user interface, and which are not dependent on the current context. For context-specific actions (e.g. those affecting a selected item), use the :doc:`Context Drawer ` Behavior ~~~~~~~~ .. figure:: /img/Globaldrawer2.png :alt: Global drawer on desktop :scale: 40 % :figclass: border Hamburger button on the toolbar on desktop. The Global Drawer is either opened by clicking on the hamburger button on the toolbar or by swiping from the left edge of the screen. It can be closed by swiping in the other direction, clicking the close button or tapping outside of it. A Global Drawer may contain the following controls: - :doc:`Tabs ` - A main menu - :doc:`Push Buttons ` to execute non-contextual actions - :doc:`Checkboxes <../editing/checkbox>` or :doc:`Radio Buttons <../editing/radiobutton>` to change settings which are commonly changed 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 ` 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 one level. -Do not use the Menu Drawer for navigation purposes. +Don't use the Menu Drawer for navigation purposes. |desktopicon| Collapsible """"""""""""""""""""""""" On the desktop, if the elements in the Global Drawer need to be accessed more often and enough space is available, the Global Drawer can default to showing a collapsed state, where the labels disappear but all actions continue to be available via icons-only ToolButtons. Pressing the hamburger menu button expands the Global Drawer to its full width and shows the actions' text labels. Pressing the close button or anywhere outside of it collapses it to its collapsed icons-only state. .. raw:: html Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: GlobalDrawer ` .. literalinclude:: /../../examples/kirigami/AddressbookGlobalDrawer.qml :language: qml diff --git a/HIG/source/components/navigation/index.rst b/HIG/source/components/navigation/index.rst index 719929d..4d176c8 100644 --- a/HIG/source/components/navigation/index.rst +++ b/HIG/source/components/navigation/index.rst @@ -1,29 +1,31 @@ Navigation ========== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: actionbutton commandlink contextdrawer contextmenu dialog globaldrawer menubar pushbutton + scrim tab toolbar * :doc:`actionbutton` * :doc:`commandlink` * :doc:`contextdrawer` * :doc:`contextmenu` * :doc:`dialog` * :doc:`globaldrawer` * :doc:`menubar` * :doc:`pushbutton` +* :doc:`scrim` * :doc:`tab` * :doc:`toolbar` diff --git a/HIG/source/components/navigation/menubar.rst b/HIG/source/components/navigation/menubar.rst index 38b3d8f..4a0efe2 100644 --- a/HIG/source/components/navigation/menubar.rst +++ b/HIG/source/components/navigation/menubar.rst @@ -1,93 +1,90 @@ -Menu bar +Menu Bar ======== Purpose ------- -A *menu bar* appears at the top of an application's main window. It provides +A menu bar appears at the top of an application's main window. It provides access to all commands and most of the settings available in an application. Users refer frequently to the menu bar, especially when they are seeking a function for which they know of no other interface. Ensuring that menus are well organized, are worded clearly, and behave correctly is crucial to the user’s ability to explore and access the functionality of the application. -Examples --------- - Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - A menu bar is mandatory for applications that have a :doc:`very complex command structure `, such as those used for content creation or editing, file manipulation, or other productivity work. - Menu bars are optional for simple apps that are able to expose all functionality using visible buttons and toolbars. If any functionality is not visible by default, err on the side of providing a menu bar. -- Do not display a menu bar in secondary or internal windows, like the +- Don't display a menu bar in secondary or internal windows, like the settings dialog or file dialog. Very small main windows are likewise usually poor candidates for menu bars. -- Do not include a menu bar in a convergent application's mobile user +- Don't include a menu bar in a convergent application's mobile user interface. Behavior ~~~~~~~~ -- Do not have more than nine menu categories within a menu bar. Too +- Don't have more than nine menu categories within a menu bar. Too many categories are overwhelming and makes the menu bar difficult to use. - At the minimum, all windows should have File, Edit, Settings, and Help menus. If they apply, the window can also have View, Insert, Format, Tools and, Window menus. -- Do not put more than 12 items within a single level of a menu. Add +- Don't put more than 12 items within a single level of a menu. Add separators between logical groups within a menu. Organize the menu items into groups of seven or fewer strongly related items. - Assign shortcut keys to the most frequently used menu items. Use `KStandardAction `_ and `KStandardShortcut `_ items for common functions, which will result in menu items automatically receiving consistent names, icons, and shortcut keys. Any tool or function that is accessible using a keyboard shortcut must have an item in the menu bar so that users can discover it. -- Do not hide the menu bar by default. If this is configurable, users should +- Don't hide the menu bar by default. If this is configurable, users should easily be able to make the menu bar viewable again. - Use submenus cautiously. Submenus add complexity to the interface and are physically more difficult to use, so you should take care not to overuse them. Appearance ~~~~~~~~~~ - Place the most frequently used items at the top of the menu. -- Provide icons for all menu items. Do not re-use the same icon for multiple +- Provide icons for all menu items. Don't re-use the same icon for multiple items. - For your menu items' text, follow the :doc:`general label guidelines `. -- Do not change menu items' labels dynamically. +- Don't change menu items' labels dynamically. - Choose single word names for menu categories. Using multiple words makes the separation between categories confusing. - Disable menu items that don't apply to the current context instead 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 ` 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). - For menu items that toggle some state on or off, always use the positive form. For example, use the text 'Show hidden files' instead of 'Hide hidden - files', and do not change the text when hidden files are shown. + files', and don't change the text when hidden files are shown. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: ApplicationWindow ` - `QML: MenuBar `_ .. literalinclude:: /../../examples/kirigami/AddressbookMenubar.qml :language: qml diff --git a/HIG/source/components/navigation/pushbutton.rst b/HIG/source/components/navigation/pushbutton.rst index 1e3c064..26e0e46 100644 --- a/HIG/source/components/navigation/pushbutton.rst +++ b/HIG/source/components/navigation/pushbutton.rst @@ -1,107 +1,107 @@ -Push button +Push Button =========== Purpose ------- A *push button* initiates an action when the user clicks it. .. image:: /img/Button-HIG.png :alt: Button-HIG.png Buttons have the benefit of affordance, i.e. their visual properties (they look like they can be pushed) suggest how they are used. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ Buttons are available in several flavors: -Command button +Command Button ^^^^^^^^^^^^^^ - Use a command button to initiate an immediate action. -- Do not use a command button for navigation to another page (prefer a +- Don't use a command button for navigation to another page (prefer a :doc:`link ` in this case). -- Do not use a command button embedded in a body of text. -- Do not use command buttons for a group of actions. Consider to use +- Don't use a command button embedded in a body of text. +- Don't use command buttons for a group of actions. Consider using radio buttons with one 'Apply' option or a menu button. -Menu button +Menu Button ^^^^^^^^^^^ .. container:: flex .. container:: .. image:: /img/MenuButton-closed.png :alt: MenuButton closed .. container:: .. image:: /img/MenuButton-open.png :alt: MenuButton open - Use a menu button when you need to execute one action out of a small set of related functions. - Indicate the menu by a single downward-pointing triangle. - Clicking the button will drop down the menu only. -- Do not use the delayed menu button pattern. +- Don't use the delayed menu button pattern. -Split button +Split Button ^^^^^^^^^^^^ .. image:: /img/Button_SplitButton.png :alt: Split Button - Apply a split button when one of the commands is used by default. - Clicking the left part (or right in case of RTL alignment) of a split button starts the default action; clicking the split area opens the menu. - Change the default item to the last action when the user is likely to repeat the command. -Toggle button +Toggle Button ^^^^^^^^^^^^^ - A toggle button is not a push button. Guidelines can be found :doc:`here <../editing/togglebutton>`. Behavior ~~~~~~~~ - Buttons are not dynamic: their icon and label should not change depending on the context (except special split buttons). -- Do not initiate an action on right-click or double-click. +- Don't initiate an action on right-click or double-click. - Provide feedback when user is not aware to results or when results are not available instantaneous. Display a busy pointer or present a progress bar to users (see :doc:`progress indicator <../assistance/progress>`). - Denote the relationship between buttons with other controls by placing them logically together. -- Do not use the delayed (menu) button pattern. +- Don't use the delayed (menu) button pattern. Appearance ~~~~~~~~~~ - Indicate a command that needs additional information (including confirmation) by adding an ellipsis at the end of the button label. -- Buttons have an elevated appearance; do not make buttons flat (except +- Buttons have an elevated appearance; don't make buttons flat (except in :doc:`toolbars `). -- Do not use icons for confirmation buttons like OK, Apply, or Cancel. +- Don't use icons for confirmation buttons like OK, Apply, or Cancel. - Passive actions like those in the "System Settings => Application - Appearance => Fonts" do not have icons (does not apply to toolbar + Appearance => Fonts" don't have icons (does not apply to toolbar buttons that always have an icon). - If icons are applied (or not), this style should be used consistently for a group of buttons. - For buttons with text labels, use a minimum button width of 96px and the standard button height. Don't use narrow, short, or tall buttons with text labels. - If the same button appears in more than one window, use the same label and access key. Locate them in approximately the same place in each window. - Use :doc:`title style capitalization ` for the label. - Use a verb or verb phrase for the title of a push button. diff --git a/HIG/source/components/navigation/scrim.rst b/HIG/source/components/navigation/scrim.rst new file mode 100644 index 0000000..d44e06e --- /dev/null +++ b/HIG/source/components/navigation/scrim.rst @@ -0,0 +1,28 @@ +Scrim +===== + +A scrim is a temporary effect applied to a surface for the purpose +of making content below it less prominent. + +Examples +-------- + +.. figure:: /img/drawer-scrim.png + :alt: A scrim being used to indicate that a drawer is modal. + + A scrim being used to indicate that a drawer is modal. + +.. figure:: /img/ImageCaption1.png + :alt: A scrim being overlaid on an image to allow a readable caption on top of it. + + A scrim being overlaid on an image to allow a readable caption on top of it. + +Is this the right control? +-------------------------- + +Most controls that require scrims will apply one themselves, such as drawers. + +Manually apply scrims only when: + +- Content would not be legible without them. +- Modal controls are overlaid on content. \ No newline at end of file diff --git a/HIG/source/components/navigation/tab.rst b/HIG/source/components/navigation/tab.rst index 6c528ff..080e6b1 100644 --- a/HIG/source/components/navigation/tab.rst +++ b/HIG/source/components/navigation/tab.rst @@ -1,147 +1,146 @@ Tabs ==== Purpose ------- A *tab control* is a way to present related information on separate pages. Tabs are used for dynamic window surface to increase the surface, to manage multiple documents within a single window, or as a view of exclusive options. .. image:: /img/Tabs-HIG.png :alt: Tabs-HIG.png Tabs have several advantages. Users can easily access available options or see which forms have been opened. Because foreground tabs are visually differentiated from background tabs the user knows what item is currently in use. Having tabs beyond the screen size may lead to visual clutter. General Guidelines ------------------ -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Use tabs +- Use tabs: - for many controls that can be organized within a few categories, like extended configuration settings - for a variable number of sections, like browser pages - to manage multiple documents -- Do not use tabs +- Don't use tabs: - - for only one page (but do not hide the tab when more pages are - expected, for example in web browser). + - for only one page (but show the tab bar when more pages are + expected, for example in a web browser). - for global application controls. - for sequential steps, like wizards. -Guidelines for desktop user interfaces +Guidelines for Desktop User Interfaces -------------------------------------- Behavior ~~~~~~~~ -- Do not abuse other controls to simulate tab behavior. +- Don't abuse other controls to simulate tab behavior. - Use horizontal tabs with seven or fewer tabs and all the tabs fit on one row. -- Do not use vertically stacked tabs. Tabs are drawn above the pages +- Don't use vertically stacked tabs. Tabs are drawn above the pages only (QTabWidget::TabPosition = North). -- Do not use too many tabs. Use a :doc:`list view <../editing/list>` with icons and +- Don't use too many tabs. Use a :doc:`list view <../editing/list>` with icons and associated pages if there are many pages or if you want to group static pages, e.g. in case of configuration content. This also gives ability to present hierarchy of pages as a tree. -- Do not use multiple tab rows. It leads to disorientation. -- Do not disable a tab when it doesn't apply to the current context; - disable the controls on the page. +- Don't use multiple tab bars. +- Don't disable a tab when it does not apply to the current context. + Instead, disable the controls on the page. - Make content from one page independent and differentiated from another through the use of tabs. -- Do not nest tabs. -- Make the tabs use scroll buttons, to scroll tabs when there are too - many tabs. +- Don't nest tabs. +- Display scroll buttons in the tab bar to allow navigating tabs when there + are too many to see at once. -Tabs with pages containing documents +Tabs with Pages Containing Documents ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Special considerations apply for tabs that contain documents rather than settings or controls. - Make it possible to re-order tabs. - Make tabs closable. - Provide a context menu on each tab if their pages contain documents. This menu should only include actions for manipulating the tab itself, such as Move Left, Move Right, Move to New Window, Close, Close All, Reload. -- Do not resize tabs when adding a status icon or when the content of the page +- Don't resize tabs when adding a status icon or when the content of the page changes. For applications where the tab title changes, like Dolphin or Konsole, it is recommended to have a fixed tab size for all tabs. -- Consider to provide 'add new tab' function if their pages contain - documents, not for static content. In this case the 'Add Tab' button - should be used as a corner widget placed on the right hand of the tab bar. - Have keyboard shortcuts or menu items for easy access, but do not displayed - the 'add tab' function in the application toolbar. +- Consider providing an 'Add New Tab' button on the right side of the tab bar + for tabs that contain documents or other user-editable content. In this case the + 'Add Tab' button should be used as a corner widget placed on the right hand + of the tab bar. Display keyboard shortcuts or menu items for easy access, + but don't show the 'Add Tab' function in the application toolbar. - Provide keyboard navigation to switch between tabs with Ctrl + Tab (Ctrl + Shift + Tab for backward navigation). For compatibility reasons it is recommended to also support Ctrl + PgDown (Ctrl + PgUp for backward navigation). Appearance ~~~~~~~~~~ - Make last used tab persistent. Otherwise, select the first page by default. -- Do not assign effects to changing tabs; tabs must be accessible in +- Don't assign effects to changing tabs; tabs must be accessible in any order. - Only use text in horizontal tabs and not icons. - Provide a label with an access key for each tab. Use nouns with :doc:`title capitalization ` to describe the content. -- Do not expand tabs to use empty space of the widget (see `expanding`_ +- Don't expand tabs to use empty space of the widget (see `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. -- Do not use :doc:`abbreviations ` +- Don't use :doc:`abbreviations ` (acronyms such as HTML are allowed). -- Do not use triangular shape of tabs. -Guidelines for phone user interfaces +Guidelines for Phone User Interfaces ------------------------------------ .. image:: /img/Tabs_in_drawer.png :alt: Tabs in global drawer Behavior ~~~~~~~~ -- Do not abuse other controls to simulate tab behavior. -- Do not nest tabs. +- Don't abuse other controls to simulate tab behavior. +- Don't nest tabs. - When the tabs are used to group controls, put them at the top of the - screen. Do not use more than three tabs. + screen. Don't use more than three tabs. - - Do not disable a tab when it doesn't apply to the current context; + - Don't disable a tab when it does not apply to the current context; disable the controls on the page. - Keep interdependent elements in the same tab. - When using tabs to open multiple documents (e.g. websites) in the same instance of an application, show them as a list at the top of the :doc:`global drawer ` - Offer the user the option to choose between "Use tabs" and "Use separate windows", the default of which is specified by the gobal setting, if it is set, otherwise the default is new windows unless users are used to tabs from existing apps of the same type (e.g. for web browsers). - Swiping on a tab away from the screen edge that the menu drawer is attached to (e.g. to the right if the drawer is on the left side) closes the tab. Appearance ~~~~~~~~~~ - Use short labels for tabs that group controls. - Use descriptive names for tabs, e.g. page titles for browser tabs. - Put a control to open a new tab below the list of tabs. diff --git a/HIG/source/components/navigation/toolbar.rst b/HIG/source/components/navigation/toolbar.rst index f7fc072..0e2485f 100644 --- a/HIG/source/components/navigation/toolbar.rst +++ b/HIG/source/components/navigation/toolbar.rst @@ -1,125 +1,123 @@ Toolbar ======= .. figure:: /img/Toolbar1.png :figclass: border :alt: Primary Action Buttons on Desktop Toolbar with the most important actions :doc:`toolbar ` and an overflow menu Purpose ------- A *toolbar* is a graphical presentation of commands optimized for fast access. A toolbar can be either be defined for a whole application or as part of another component. As an application toolbar it contains buttons that correspond to items in the application's menu, providing direct access to application's most frequently used functions. A good menu bar is a comprehensive catalog of all the available top-level commands, whereas a good toolbar gives quick, convenient access to frequently used commands. As part of another component, like a card or an inline mesage, it is used to allow quick access to the most important commands for a single, focused content item. -Guidelines for application --------------------------- +Guidelines for Applications +--------------------------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - For standard applications, show a toolbar by default. -- Provide a toolbar in addition to the menu bar, but do not replace +- Provide a toolbar in addition to the menu bar, but don't replace the menu bar. Behavior ~~~~~~~~ -- A toolbar should contain only a few, frequently used operations. If +- A toolbar should contain only a few frequently used operations. If the number of operations is above 5 they have to be grouped with separators. Not more than 3 of those sections should be implemented. -- Do not abuse the toolbar to expose application's features. Only the - most frequently functions should be add to the toolbar. -- Execute operations immediately; do not require additional input. +- Don't abuse the toolbar to expose hidden or esoteric features. Only the + most frequently-used functions should be accessible from the toolbar. +- Execute operations immediately; don't require additional input. - Try to avoid using :doc:`split buttons ` or :doc:`toggle buttons <../editing/togglebutton>` in order to keep the interaction with all buttons in the toolbar consistent. -- Do not hide toolbars by default. If configurable, users should +- Don't hide toolbars by default. If a toolbar can be hidden, users should easily be able to make the toolbar viewable again. -- Disable buttons that do not apply to the current context. -- Consider to provide customization for toolbars in respect to - position and content. -- Providing a label for each action is a good practice but define a meaningful icon too because the label could be hidden in mobile mode or if there isn't enough space when the window is resized. +- Disable buttons that don't apply to the current context. +- Consider making toolbar content and position customizable. +- Provide both a label and an icon for actions. -Guidelines for components +Guidelines for Components ------------------------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a toolbar only if an item has few actions or few frequently used actions. - Embed a toolbar only in another control that is clearly visually seperated like a card or an inline message. Behavior ~~~~~~~~ - A toolbar should contain only a few, frequently used operations. The number of operations should not exceed 3. -- Do not group with separators. -- Execute operations immediately; do not require additional input. -- Do not hide toolbars or make them configurable. +- Don't group with separators. +- Execute operations immediately; don't require additional input. +- Don't hide toolbars or make them configurable. - Toolbars can be responsive. If there is not enough space to display all the buttons, an overflow menu is shown instead. .. raw:: html Appearance ---------- -- Do not change the button style from the default, which is +- Don't change the button style from the default, which is :doc:`text beside icons `. - 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 `. -- Do not simulate Microsoft's ribbon controls. KDE stays plain and - simple.Microsoft's ribbon controls. KDE stays plain and simple. +- Don't simulate Microsoft's ribbon controls. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` - :kirigamiapi:`Kirigami: ActionToolBar ` -Application toolbar +Application Toolbar """"""""""""""""""" .. literalinclude:: /../../examples/kirigami/ApplicationToolbar.qml :language: qml -Component toolbar +Component Toolbar ^^^^^^^^^^^^^^^^^ .. literalinclude:: /../../examples/kirigami/ComponentToolbar.qml :language: qml -Plasma components +Plasma Components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ToolBar ` diff --git a/HIG/source/img/Ambiguous_Opposite_Bad.qml.png b/HIG/source/img/Ambiguous_Opposite_Bad.qml.png index bb9b82e..0946cea 100644 Binary files a/HIG/source/img/Ambiguous_Opposite_Bad.qml.png and b/HIG/source/img/Ambiguous_Opposite_Bad.qml.png differ diff --git a/HIG/source/img/Ambiguous_Opposite_Good.qml.png b/HIG/source/img/Ambiguous_Opposite_Good.qml.png index aae4e4f..009cf04 100644 Binary files a/HIG/source/img/Ambiguous_Opposite_Good.qml.png and b/HIG/source/img/Ambiguous_Opposite_Good.qml.png differ diff --git a/HIG/source/img/Breeze-icon-design-creative-backgrounds.png b/HIG/source/img/Breeze-icon-design-creative-backgrounds.png index 3109d7c..4980652 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/Breeze-icon-design-places.png b/HIG/source/img/Breeze-icon-design-places.png index 6704c58..ae9917e 100644 Binary files a/HIG/source/img/Breeze-icon-design-places.png and b/HIG/source/img/Breeze-icon-design-places.png differ diff --git a/HIG/source/img/Card2.qml.png b/HIG/source/img/Card2.qml.png index d54d013..701ddcd 100644 Binary files a/HIG/source/img/Card2.qml.png and b/HIG/source/img/Card2.qml.png differ diff --git a/HIG/source/img/Card5.qml.png b/HIG/source/img/Card5.qml.png index 0bdea3b..58eff5d 100644 Binary files a/HIG/source/img/Card5.qml.png and b/HIG/source/img/Card5.qml.png differ diff --git a/HIG/source/img/Card6.qml.png b/HIG/source/img/Card6.qml.png index ef70a97..35b050c 100644 Binary files a/HIG/source/img/Card6.qml.png and b/HIG/source/img/Card6.qml.png differ diff --git a/HIG/source/img/Checkbox_Alignment_Bad.qml.png b/HIG/source/img/Checkbox_Alignment_Bad.qml.png index 798a0d2..e03129b 100644 Binary files a/HIG/source/img/Checkbox_Alignment_Bad.qml.png and b/HIG/source/img/Checkbox_Alignment_Bad.qml.png differ diff --git a/HIG/source/img/Checkbox_Alignment_Good.qml.png b/HIG/source/img/Checkbox_Alignment_Good.qml.png index bbdfc4e..f0daae1 100644 Binary files a/HIG/source/img/Checkbox_Alignment_Good.qml.png and b/HIG/source/img/Checkbox_Alignment_Good.qml.png differ diff --git a/HIG/source/img/Checkbox_Enable_Bad.qml.png b/HIG/source/img/Checkbox_Enable_Bad.qml.png index 7fd027a..9dd0ced 100644 Binary files a/HIG/source/img/Checkbox_Enable_Bad.qml.png and b/HIG/source/img/Checkbox_Enable_Bad.qml.png differ diff --git a/HIG/source/img/Checkbox_Enable_Good.qml.png b/HIG/source/img/Checkbox_Enable_Good.qml.png index 3128f00..3477141 100644 Binary files a/HIG/source/img/Checkbox_Enable_Good.qml.png and b/HIG/source/img/Checkbox_Enable_Good.qml.png differ diff --git a/HIG/source/img/Dropdown1.png b/HIG/source/img/Dropdown1.png index 76a58e3..f39198f 100644 Binary files a/HIG/source/img/Dropdown1.png and b/HIG/source/img/Dropdown1.png differ diff --git a/HIG/source/img/HIG_Checkbox5.png b/HIG/source/img/HIG_Checkbox5.png deleted file mode 100644 index 5994e23..0000000 Binary files a/HIG/source/img/HIG_Checkbox5.png and /dev/null differ diff --git a/HIG/source/img/No_Command_2_Bad.qml.png b/HIG/source/img/No_Command_2_Bad.qml.png index 36100fc..598c2d6 100644 Binary files a/HIG/source/img/No_Command_2_Bad.qml.png and b/HIG/source/img/No_Command_2_Bad.qml.png differ diff --git a/HIG/source/img/No_Command_2_Good.qml.png b/HIG/source/img/No_Command_2_Good.qml.png index ad053bf..987694c 100644 Binary files a/HIG/source/img/No_Command_2_Good.qml.png and b/HIG/source/img/No_Command_2_Good.qml.png differ diff --git a/HIG/source/img/Radiobutton_Default_Bad.qml.png b/HIG/source/img/Radiobutton_Default_Bad.qml.png index 76ce79d..bdb31e1 100644 Binary files a/HIG/source/img/Radiobutton_Default_Bad.qml.png and b/HIG/source/img/Radiobutton_Default_Bad.qml.png differ diff --git a/HIG/source/img/Radiobutton_Default_Good.qml.png b/HIG/source/img/Radiobutton_Default_Good.qml.png index c4d354a..b1c0de9 100644 Binary files a/HIG/source/img/Radiobutton_Default_Good.qml.png and b/HIG/source/img/Radiobutton_Default_Good.qml.png differ diff --git a/HIG/source/img/Radiobutton_Many_Bad.qml.png b/HIG/source/img/Radiobutton_Many_Bad.qml.png index 4add410..b076ac4 100644 Binary files a/HIG/source/img/Radiobutton_Many_Bad.qml.png and b/HIG/source/img/Radiobutton_Many_Bad.qml.png differ diff --git a/HIG/source/img/Radiobutton_Many_Good.qml.png b/HIG/source/img/Radiobutton_Many_Good.qml.png index 53833ee..56ab294 100644 Binary files a/HIG/source/img/Radiobutton_Many_Good.qml.png and b/HIG/source/img/Radiobutton_Many_Good.qml.png differ diff --git a/HIG/source/img/Radiobutton_Visible_Bad.qml.png b/HIG/source/img/Radiobutton_Visible_Bad.qml.png index 1c7d6be..bffe81b 100644 Binary files a/HIG/source/img/Radiobutton_Visible_Bad.qml.png and b/HIG/source/img/Radiobutton_Visible_Bad.qml.png differ diff --git a/HIG/source/img/Radiobutton_Visible_Good.qml.png b/HIG/source/img/Radiobutton_Visible_Good.qml.png index 6ebd431..ed70e0f 100644 Binary files a/HIG/source/img/Radiobutton_Visible_Good.qml.png and b/HIG/source/img/Radiobutton_Visible_Good.qml.png differ diff --git a/HIG/source/img/Sample_color_icons.png b/HIG/source/img/Sample_color_icons.png index 2ce9b75..e2177df 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/Spinbox1.png b/HIG/source/img/Spinbox1.png index edba4dd..0f416cf 100644 Binary files a/HIG/source/img/Spinbox1.png and b/HIG/source/img/Spinbox1.png differ diff --git a/HIG/source/img/Typography-Heading-Do.png b/HIG/source/img/Typography-Heading-Do.png new file mode 100644 index 0000000..f88c623 Binary files /dev/null and b/HIG/source/img/Typography-Heading-Do.png differ diff --git a/HIG/source/img/Typography-Heading-Dont.png b/HIG/source/img/Typography-Heading-Dont.png new file mode 100644 index 0000000..fc41629 Binary files /dev/null and b/HIG/source/img/Typography-Heading-Dont.png differ diff --git a/HIG/source/img/drawer-scrim.png b/HIG/source/img/drawer-scrim.png new file mode 100644 index 0000000..8454f1c Binary files /dev/null and b/HIG/source/img/drawer-scrim.png differ diff --git a/HIG/source/index.rst b/HIG/source/index.rst index fb897d0..c347bfc 100644 --- a/HIG/source/index.rst +++ b/HIG/source/index.rst @@ -1,89 +1,89 @@ .. KDE HIG documentation master file, created by sphinx-quickstart on Tue Feb 6 13:29:47 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. KDE Human Interface Guidelines ============================== .. toctree:: :titlesonly: :hidden: introduction/index layout/index style/index components/index patterns/command/index patterns/content/index patterns/navigation/index accessibility/index plattform/index resources/about resources/contribute resources/glossary .. Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` The KDE Human Interface Guidelines (HIG) offer designers and developers a set of recommendations for producing beautiful, usable, and consistent user interfaces for convergent desktop and mobile applications and workspace widgets. Their aim is to improve the experience for users by making application and widget interfaces more consistent and hence more intuitive and learnable. .. figure:: /img/HIGDesignVisionFullBleed.png :scale: 50 % :alt: Different DPIs on desktop and mobile ''Simple by default, powerful when needed.'' Design Vision ------------- KDE's design vision focuses on two attributes of KDE software that connect its future to its history: - **Simple by default** - Simple and inviting. KDE software is pleasant to experience and easy to use. - **Powerful when needed** - Power and flexibility. KDE software allows users to be effortlessly creative and efficiently productive. Design Principles ----------------- The following design principles are used in support of the Design Vision. - **Simple by default** - *Make it easy to focus on what matters.* - Remove or minimize elements not crucial to the primary or main task. Use spacing to keep things organized. Use color to draw attention. Reveal additional information or optional functions only when needed. - *I know how to do that!* - Make things easier to learn by reusing design patterns from other applications. Other applications that use good design are a precedent to follow. - *Do the heavy lifting for me.* - Make complex tasks simple. Make novices feel like experts. Create ways in which your users can naturally feel empowered by your software. - **Powerful when needed** - *Solve a problem.* - Identify and make very clear to the user what need is addressed and how. - *Always in control.* - It should always be clear what can be done, what is currently happening, and what has just happened. The user should never feel at the mercy of the tool. Give the user the final say. - *Be flexible.* - Provide sensible defaults but consider optional - functionality and customization options that do not interfere with the + functionality and customization options that don't interfere with the primary task. .. note:: Note: KDE encourages developing and designing for customization, while providing good default settings. Integrating into other desktop environments is also a virtue, but ultimately we aim for perfection within our own Plasma desktop environment with the default themes and settings. This aim should not be compromised. diff --git a/HIG/source/introduction/architecture.rst b/HIG/source/introduction/architecture.rst index bcc8ab1..ba90718 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 :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 + 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/introduction/personas.rst b/HIG/source/introduction/personas.rst index 1125166..c0448ad 100644 --- a/HIG/source/introduction/personas.rst +++ b/HIG/source/introduction/personas.rst @@ -1,133 +1,133 @@ Personas ======== Personas are a simple way of grounding your design toward the type of people you consider your software's target user. In your design sessions, you can call out the names of these personas to help you and your team make changes to your software. That way, you can ensure that your design is consistent with KDE visual goals. Software that you write will not necessarily satisfy all personas. It should not be the case either that you look to meet every persona's expectations through your software. Instead, focus your efforts into the persona that best meets your target audience and work to strengthen your software toward that KDE-specific audience. KDE Personas: Background ------------------------ The question "Why should people switch to KDE?" was an important factor in the creation of our Personas – a crucial aspect if we want to extend the current user base. The "Technology Adoption Lifecycle" by Rogers (1962) deals with this question by splitting the overall user base in groups along a bell curve according to their willingness to adopt new technology. Looking at the "Technology Adoption Lifecycle", you'll find the following user groups: .. image:: /img/Introduction_KDE4_Vision_tal.png :scale: 30% :alt: Technology Adoption Lifecycle We suggest to move away from the *KDE is for everybody* approach to *KDE is for the more sophisticated 50% of computer users out there, who choose it because it perfectly suits their work and that they "want to have it".* Concentrating on this user base rather than everybody has both pragmatic and motivational reasons: Pragmatically, it will be hard to make KDE a favourite product for *laggards* and even the *late majority* within the next five years. Neither cutting away functionality nor hiding all the complexity behind *Advanced* buttons is an acceptable solution. Second, creating a desktop for ambitious users better fits the current motivation in the KDE development base. We don't want to be *simple and limited*, we want to develop a smart desktop with rich functionality! To avoid misunderstandings: KDE will still be an option for educational, -governmental or large enterprise usage – but it won't be the main focus +governmental or large enterprise usage – but it will not be the main focus when developing the default desktop. KDE as a configurable set of tools can still be adjusted to meet the needs of any other user base. Berna ----- .. image:: /img/Berna_small.jpg :scale: 50% :alt: Berna :align: right Berna works as an office clerk in a big insurance company. Although she is a very smart person, she is very often unsure how technology can help her. Berna's biggest daily task is to check on the details of insurance claims. She writes reports for her boss suggesting compensation payouts for the cases she deals with. Berna is a very detail oriented individual, and always resolves her tasks accurately. -Berna lost several hours of work twice because she didn't understand the -options she was offered with technology. Since then, she has been very careful when testing new functionality in the software she uses. She prefers to keep things simple. +On a few occassions, Berna has lost work because she misunderstood how a piece of technology worked. +Since then, she has been very careful when testing new functionality in the software she uses. She prefers to keep things simple. Matt ---- .. image:: /img/Matt_small.jpg :scale: 50% :alt: Matt :align: right Matt is a geology student in the last year of his undergraduate studies. For him, technology is meant to simplify annoying and repetitive tasks. For his student research projects, Matt has to do extensive research on the web, and has to manage a database of pictures of stones and other geologic materials. He gains credits by using his notes to create reports and presentations. Matt often struggles to keep track of all his notes. He is looking for an effective routine, so he can concentrate on the content rather than on finding information. Susan ----- .. image:: /img/Susan_small.jpg :scale: 50% :alt: Susan :align: right While Susan seldom uses her computer for work, it has become an essential part of her social life. With her computer, she can be creative and spread this creativity to the world. She chats with her friends, shares music, playlists and other media, creates videos and uploads them to her web space, and runs a blog with -her own style. She can't imagine a life without her laptop. +her own style. She can't imagine life without her laptop. She is a fun person and does not want to worry about technical details. She expects her machine to work. Santiago -------- .. image:: /img/Santiago_small.jpg :scale: 50% :alt: Santiago :align: right Santiago runs a medium-sized electric installations business. For him, technology needs to be comfortable and make him feel smart. As a manager with an engineering background, Santiago's main task is customer negotiations. However, to avoid costs, he is the administrator for the small network at the company, including a file server and fifteen PCs for his office clerks. He loves comfort, does not like to dive into manuals or use the command line to set up the small network. Santiago relies on the UI to achieve these results. The system has to be reliable and easy to use, so his employees get along with it. Philip ------ .. image:: /img/Philip_small.jpg :scale: 50% :alt: Philip :align: right Philip is a high-school student in his last year. He wants to go to college to study computer science. He loves the challenge of making technology do what he wants it to do. When he was 14, he tried different programming languages, and since then has implemented various applications he published under free licenses. He is convinced that Linux is the way to go and understands the benefits of free software. Philip is fancy about technology and is never discouraged if something does not work as expected. He feels that as a power user he can fix technical issues himself. diff --git a/HIG/source/introduction/research.rst b/HIG/source/introduction/research.rst index cae7968..773f136 100644 --- a/HIG/source/introduction/research.rst +++ b/HIG/source/introduction/research.rst @@ -1,95 +1,95 @@ Project User Research Profile ============================= Short summary description of the purpose of the application, who it is for, and what those people can do with it. Purpose ======= **About the Project User Research Template:** The purpose of this template is to provide a place to document an application's user research information for reference during development. Top level items are information everyone in the project should be aware of. Some of the details in the lower sections may take some work and discussion within the project to complete. Who is the application for? --------------------------- - List of types (groups) of users - User groups can be organized based on any type of dimension - Some groups may be broken down in to sub groups (Who is the application *not* for) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Sometimes it is easy to identify who the application is **not** for - This can help keep the scope of the project under control Sample User Profiles ~~~~~~~~~~~~~~~~~~~~ User Profile 1: For each group of users identified (or primary groups, or particularly special groups if many groups are defined), write a description of that user's characteristics based on a real user you know. What kinds of tasks will they complete -------------------------------------- - List of common tasks users will complete - This does not have to be a complete functional specification, but major tasks and specialty tasks should be listed - Include functionality that is planned but not yet implemented to help keep the future in focus (What kinds of functionality will the application *not* support) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - List tasks or functionality the application will not address - Sometimes it is useful to list this unintended functionality to help keep the scope of the application - For example, a certain functionality may not be implemented because it is out of scope with the primary goals of the project, another application with a different focus does it better, or it is an extreme edge case for a user type which is not primary Sample Use Scenarios and Cases ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use Scenario 1: For each task identified (or major tasks, or particularly special tasks if many tasks are defined), write a description of how that user would accomplish the task *independent* of how they would complete it within the application. Use Case 1: If a use scenario has been implemented, include a matching use case which describes how the task use scenario can be completed in the application. There may be branching or multiple ways to complete the task, and this is a good way to document it. -Environment Conditions & Requirements -------------------------------------- +Environmental Conditions and Requirements +----------------------------------------- - List of environmental conditions for the user or the application to consider - For example, an Internet-capable application would require an Internet connection More Information ---------------- `Short introduction to user personas on Usability.gov`_ `In-depth discussion about creating personas on Boxes and Arrows`_ .. _Short introduction to user personas on Usability.gov: http://www.usability.gov/analyze/personas.html .. _In-depth discussion about creating personas on Boxes and Arrows: http://www.boxesandarrows.com/view/making_personas_more_powerful_details_to_drive_strategic_and_tactical_design Still Need Help? ---------------- For more information and help you can find us on `Matrix `_, `IRC `_ or `Telegram `_ diff --git a/HIG/source/layout/alignment.rst b/HIG/source/layout/alignment.rst index c3aa5c2..77ad44b 100644 --- a/HIG/source/layout/alignment.rst +++ b/HIG/source/layout/alignment.rst @@ -1,105 +1,110 @@ Alignment ========= Purpose ------- One of the most important aspects of presentation is *alignment* and -*placement* of objects. Its theoretical foundation is based on Gestalt -psychology. Human perception tends to order experience in a manner that +*placement* of objects. Its theoretical foundation is based on `Gestalt psychology `_: +Human perception tends to order experience in a manner that is regular, orderly, symmetric, and simple. Visual impression is generated to an emergent whole based on several principles, called Gestalt laws. Two basic laws are: - Law of proximity: an assortment of objects that are close to each other are formed into a group - Law of similarity: objects will be perceptually grouped together if they are similar to each other Placement of objects should be carefully done according to Gestalt theory. .. raw:: html Principles ---------- Alignment pertains to the common-sense usage of visual positioning of text, images, controls in user interfaces. Alignment is an element of visual design that is easy to miss when done properly and easy to spot when it is not. Plasma seeks to achieve strong visual alignment in -applications so that users do not have to wonder where elements on a page +applications so that users don't have to wonder where elements on a page should go. Plasma seeks simplicity in alignment first. Alignment in Plasma is: ----------------------- - Simple: good alignment improves visual understanding and speed, and allows less thinking. Developers should strive to run alignment that is reduced to a minimum and build more of the UI from there on. - Coherent: Users will see elements aligned in a way that follows common, natural, human-like behavior. This can be likened to taking notes. Titles will go first, then sub-headings, etc. The objective is that ideas follow a natural progression. Developers must prioritize their UI to meet these ideas. - Reliable: Users will expect elements to be aligned the same across multiple applications. Users will come to expect that similar elements are grouped in a predictable fashion. - Powerful: Users will expect powerful controls close together that will allow them to complete complex operations with only a few clicks and low visual travel of the UI to locate such controls. General Alignment ----------------- -- Guides and Margins +- Guides and Margins |br| In Plasma, alignment behaves like most with a horizontal, vertical, top, bottom, and center guides. As developers look to place controls or UI elements on their applications, they must set their guides or margins first. -- Limits +- Limits |br| Using the note paradigm for aligning elements, developers should not go more than 3 layers with left justification. Beyond 3 layers seems messy and less clear to the user. -Good +:noblefir:`Do:` +^^^^^^^^^^^^^^^ Title Label Sub-label -Bad +*Limit hierarchy to three levels or less.* + +:iconred:`Don't:` +^^^^^^^^^^^^^^^^^ Title Label Sub-label Sub-label Sub-label +*Don't use more than three levels of hierarchy.* + This same structure should apply to controls. A General Note of Caution ------------------------- When working with elements on a page and text, it is tempting to maximize the use of space by placing as many controls and labels as possible within the UI. The Plasma team recommends that you first: - Organize your controls -- Prioritize them, +- Prioritize them - Remove redundancy -- Simplify your set And then work in the fashion previously suggested using verticality for -your controls. If your controls do not fit in one page because of the +your controls. If your controls don't fit on one page because of the vertical alignment chosen, consider options such as: - Using Tabs - Create an "Advanced" window with extra controls - Split your UI into smaller groups and categories This should be done in order to preserve alignment conventions. diff --git a/HIG/source/layout/metrics.rst b/HIG/source/layout/metrics.rst index 97745d9..e1c4e7f 100644 --- a/HIG/source/layout/metrics.rst +++ b/HIG/source/layout/metrics.rst @@ -1,133 +1,143 @@ -Metrics and placement +Metrics and Placement ===================== Purpose ------- -All controls have a default *height and width* to establish a harmonic -overall picture. Nevertheless, size is used to direct users' attention. +All controls should be sized and positioned to establish a harmonic +overall picture and direct users' attention. For instance, a list that captures most of screen’s space points to its -central role in the current work flow. And, size can be used to indicate -possible interactions. Smaller edits are probably constrained, for -instance. +central role in the current workflow. And, size can be used to indicate +possible interactions. For instance, most smaller text fields are constrained +in what data they can take. -Similar to size, the *space* between controls generates a visual +Similar to size, the space between controls generates a visual impression and supports layout. Space between controls indicates their relatedness. Objects with smaller distances are mentally associated -according to the Gestalt theory. *Whitespace* is an important element of +according to `Gestalt psychology `_. Whitespace is an important element of design which enables the objects in it to exist at all. The balance -between content and whitespace is key to *grouping*. +between content and whitespace is key to grouping. Please read :doc:`units` for more information which and how different units such as px, dpi independent pixels, smallSpacing and largeSpacing are used. Guidelines ---------- Size ~~~~ - If the control appears in a dialog or utility window, consider making the window and the control within it resizeable so that the user can choose how many items are visible at a time without scrolling. Each time the user opens this dialog, set its dimensions to those that the user last resized it to. -- Size controls with a minimum of - - - Icon:16x16px - - Buttons: 72 x 32px - - Line edits, Drop-downs, Combo boxes ≥80 x 32 px - - Text edits: ≥80 x ≥36 px (text should not exceed 80 characters per - line) - - Checkbox, Radio button including label: ≥80 x 24 px - - Group boxes: ≥120 x ≥96 px - - Tree view: ≥120 x ≥96 px - - List view: ≥80 px (per column) x ≥96 - KDE seeks to support XGA (1024x768px) or WXGA (1280x768px) at least. - Keep in mind that not everyone is provided with a high resolution display. - Avoid to have a large number of controls visible at once, which in turn requires a huge minimal size. - Keep in mind that the available screen area typically also will be - shrunk by panels and the window titlebar. Also, user's font might + shrunk by panels and the window titlebar. Also, the user's font might be bigger than yours (e.g. for accessibility reason). - You therefore should ideally preserve ~10% to catch those variables and try to not exceed 920x690px. +Minimum Control Sizes +^^^^^^^^^^^^^^^^^^^^^ +========================================================== ======================== +Control Size +========================================================== ======================== +Icons 16 × 16px +Buttons 72 × 32px +Line edits, drop-downs, combo boxes ≥80 × 32px +Text edits (text should not exceed 80 characters per line) ≥80 × ≥36px +Checkboxes, radio buttons including label ≥80 × 24px +Group boxes ≥120 × ≥96px +Tree views ≥120 × ≥96px +List views ≥80px (per column) × ≥96 +========================================================== ======================== + Space ~~~~~ -Qt widgets +Qt Widgets ^^^^^^^^^^ If you are using Qt widgets you should use one of -`Qt's Layout Classes `_, +`Qt's layout classes `_, which will take care of laying out and spacing of your controls. QML ^^^ For consistency you should try to use Kirigami and Plasma's -smallSpacing and largeSpacing for margins and paddings whenever possible. +``smallSpacing`` and ``largeSpacing`` for margins and paddings whenever possible. See :doc:`units` for more details. -Use multiples of smallSpacing or largeSpacing, where more spacing is required. +When more spacing is required, use multiples of ``smallSpacing`` or ``largeSpacing``. .. figure:: /img/Margin.qml.png :alt: Use of base units Use of base units -Recommended minimum paddings +Recommended Minimum Paddings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- A smallSpacing padding is the minimum recommended padding inside +- A ``smallSpacing`` padding is the minimum recommended padding inside elements (buttons, drop boxes, text fields, etc.) -- An 2 * smallSpacing padding is the minimum recommended padding +- A ``2 * smallSpacing`` padding is the minimum recommended padding inside grouping frames (group boxes, tabs, etc.) -- Use default spacing of - - related items within groups: 2 * smallSpacing - - label and item: smallSpacing - - related controls with same type (checkboxes / radio buttons): smallSpacing - - related controls with different type (checkbox / button): smallSpacing - - unrelated controls: ≥ 3 * smallSpacing +Default Minimum Paddings +^^^^^^^^^^^^^^^^^^^^^^^^ +============================================================ ====================== +Item Spacing +============================================================ ====================== +Related items within groups ``2 * smallSpacing`` +Labels and items ``smallSpacing`` +Related controls with same type (checkboxes / radio buttons) ``smallSpacing`` +Related controls with different type (checkbox / button) ``smallSpacing`` +Unrelated controls ≥ ``3 * smallSpacing`` +============================================================ ====================== .. figure:: /img/SpacingPadding.qml.png :alt: Sample spacing Sample spacing - In some cases it may be useful to visually separate groups of related options within one group to facilitate scanning of the dialog. In that case, put a vertical, fixed-size spacer of 18px height between the options. .. figure:: /img/SpacingSeperate.qml.png :alt: Separating groups of related options with a vertical spacer. Separating groups of related options with a vertical spacer. .. hint:: |designicon| It often helps to use a soft grid of 18px (gridUnit), when creating mockups. But only use this as a visual hint, since plasma components and icon - size are not multiples of the gridUnit, you won't be able to align everything to the + size are not multiples of the gridUnit, so you will not be able to align everything to the grid. -Resize -~~~~~~ +Resizing +~~~~~~~~ - Provide resizing for all primary and mode-less windows. - If form resizing is not provided disable border icons and adjust form style. - Define a minimum size for resizable forms. - Make the content area scrollable if size is too small for all controls; - do not scale controls. + don't scale controls. .. figure:: /img/Resize.qml.png - :alt: Give hints how to resize + :alt: Add hints on how to resize to your mockups. - Give hints how to resize + :noblefir:`Do.` |br| + Add hints on how to resize to your mockups. diff --git a/HIG/source/layout/onehand.rst b/HIG/source/layout/onehand.rst index 2bf4161..6248f15 100644 --- a/HIG/source/layout/onehand.rst +++ b/HIG/source/layout/onehand.rst @@ -1,32 +1,39 @@ -One-handed use +One-Handed Use ============== +Purpose +------- + According to `research`_, about half of users use their phone with just one hand in any given situation. This behavior limits the areas they can comfortably reach with their thumb. The safest way to hold a phone in one hand is resting the bottom end in the palm. Another 15% of people hold them in the palms with both hands. Both ways to hold a phone make the top of the screen harder to reach. +Kirigami +-------- + .. figure:: /img/HoldPhones_Figure-2.png Reachability of screen regions in one-handed use. |br| *Source:* `UXmatters`_ .. figure:: /img/HoldPhones_Figure-4.png Reachability of screen regions in two-thumbed use. |br| *Source:* `UXmatters`_ -As shown in the previous examples, the reachable areas of the phone focus on the green areas. +As shown in the examples above, the green areas of the phone are the most reachable. -Kirigami's phone components are optimized to favor the center or bottom of the screen for primary interactive elements, while placing secondary elements into drawers which can be opened from up to three different points of the screen and then again favor the bottom area of -the screen. +Accordingly, Kirigami's phone components are optimized to favor the center or bottom of the +screen for primary interactive elements, while placing secondary elements into drawers which +can be opened from up to three different points of the screen. Kirigami also features the "overscroll" feature, which allows you pull down the top part of the screen in case you have to reach e.g. the topmost items of a list. When using Kirigami on a phone, make sure that often-used controls are never placed at the top of the screen, and also avoid the screen corners in general. .. _research: http://www.uxmatters.com/mt/archives/2013/02/how-do-users-really-hold-mobile-devices.php .. _UXmatters: http://www.uxmatters.com/mt/archives/2013/02/how-do-users-really-hold-mobile-devices.php diff --git a/HIG/source/layout/units.rst b/HIG/source/layout/units.rst index a17e594..9473c70 100644 --- a/HIG/source/layout/units.rst +++ b/HIG/source/layout/units.rst @@ -1,268 +1,281 @@ -Units & measurements -==================== +Units and Measurements +====================== Purpose ------- -This pages gives an overview about different units used in KDE and -Plasma +This pages gives an overview about different units used in Plasma and applications using KDE frameworks. Pixel ----- -A (physical) pixel or dot is a physical point in a raster image, or the -smallest addressable element in an all points addressable display -device. +A physical pixel or dot is a physical point in a raster image. It is the +smallest permissible size for anything displayed by the device. .. caution:: - Be careful not to confuse it with DPI independent pixels + Be careful not to confuse physical pixels with DPI independent pixels. -DPI - pixels per inch +DPI - Pixels per Inch --------------------- -Pixel density is the number of (physical) pixels or dots that fit into an inch. Different screens have different DPI. screen density = screen width (or height) in pixels / screen width (or height) in inches +Pixel density is the number of physical pixels or dots that fit into one square inch on the screen. Different screens +have different DPIs. Screen density = screen width (or height) in pixels / screen width (or height) in inches. .. figure:: /img/Pixel.qml.png :scale: 50 % :alt: Different DPIs on desktop and mobile - Different DPIs on desktop and mobile + Different DPIs on desktop and mobile. -DPI is often used interchangeably with PPI, pixel per inch. +DPI is often used interchangeably with PPI, pixels per inch. .. hint:: - |designicon| Don't confuse this with the DPI setting in photoshop, krita, ... . For mockups you can just ignore this setting or choose a what ever value you like. + |designicon| Don't confuse this with the DPI setting in Photoshop, Krita, etc. For mockups you can just ignore this setting. -PPI / DPI independent pixels +PPI / DPI Independent Pixels ---------------------------- A DPI independet pixel is scaled to look uniform on any screen -regardless of the DPI. A lot of platforms, eg iOS, Android, the Web, -replaced the old (physical) px with a DPI px. So most the time you read -about pixel/px they actually talk about DPI independent pixels. Qt (and +regardless of its DPI. A lot of platforms, eg iOS, Android, the web, +replaced the old physical px with a DPI px. So most of the time you read +about pixel/px they're most likely talking about DPI independent pixels. Qt (and QML) support DPI independent pixels in newer versions, but because KDE -and Plasma support older versions of Qt too, one can not assume that +and software supports older versions of Qt as well, one can not assume that pixels used in Qt or QML apps are DPI independent. .. figure:: /img/DPI.qml.png :scale: 50 % :alt: Different DPIs on desktop and mobile Different DPIs on desktop and mobile A rectangle defined with :iconred:`physical pixels` and :noblefir:`DPI independent pixels`. .. hint:: - |devicon| Except explicilty stated otherwise, all HIG pages, draft, mockups, ... pixels/px are always DPI independent pixels. + |devicon| Unless explicitly stated otherwise, all HIG pages, draft, mockups, etc. use DPI independent pixels/px. -DPI independent pixels in KDE +DPI Independent Pixels in KDE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |devicon| As a developer, if you want to use DPI independent pixels in Plasma -use units.devicePixelRatio or Units.devicePixelRatio in Kirigami. +use ``units.devicePixelRatio`` or ``Units.devicePixelRatio`` in Kirigami. .. caution:: The use of devicePixelRatio should be avoided, but if you must, check the `documentation `_ and ask for more information in `Plasma `_ or `Kirigami `_ channel. Fonts ~~~~~ -Since KDE allows the user to change the font settings any dimensions -defined with px, no matter if they are DPI independent or not, make -problems together with text. +Since Plasma allows the user to change the font settings, any +objects with dimensions defined with px (DPI independent or not) +can have issues with text. .. figure:: /img/Font.qml.png :scale: 50 % :alt: Using DPI independet pixel with different font setting - Using :noblefir:`DPI independet pixel` with different font setting + Using :noblefir:`DPI independet pixels` with different font settings -Base units in Plasma and Kirigami +Base Units in Plasma and Kirigami --------------------------------- -There a two types of dpi independent base units in Kirigami: +There a two types of DPI independent base units in Kirigami: -- Units.gridUnit, is the height needed to display one line of text. +- ``Units.gridUnit`` is the height needed to display one line of text. Use this for defining height and width of an element. -- Units.smallSpacing and Units.largeSpacing are used to define paddings and margins. +- ``Units.smallSpacing`` and ``Units.largeSpacing`` are used to define paddings and margins. These base units are not only DPI independent, but scale according to the font settings too. While designing, be careful not to rely on the ratio -between Units.gridUnit and Units.smallSpacing / Units.largeSpacing because these change depending on font setting. +between ``Units.gridUnit`` and ``Units.smallSpacing``/``Units.largeSpacing`` because these change depending on the user's font settings. .. figure:: /img/Units.qml.png :scale: 50 % :alt: Using DPI independet pixel with different font setting A rectangle defined with :plasmablue:`Units.gridUnit`. .. attention:: - The px values are only for design and mockup, don't use them for development. + These px values are only for design and mockup purposes. Don't use them for development. These are the base units in Kirigami: -- Units.smallSpacing, 4px -- Units.largeSpacing, 8px -- Units.gridUnit, 18px - +====================== ===== +Units Value +====================== ===== +``Units.smallSpacing`` 4px +``Units.largeSpacing`` 8px +``Units.gridUnit`` 18px +====================== ===== + And in Plasma: -- units.smallSpacing, 4px -- units.largeSpacing, 18px -- units.gridUnit, 18px - +====================== ===== +Units Value +====================== ===== +``units.smallSpacing`` 4px +``units.largeSpacing`` 18px +``units.gridUnit`` 18px +====================== ===== Icon sizes in Plasma and Kirigami --------------------------------- There are several predefined icon sizes in Plasma and Kirigami. You should always use these icon sizes. .. attention:: - The px values are only for design and mockup, don't use them for development. + These px values are only for design and mockup purposes. Don't use them for development. Kirigami: -- Units.iconSizes.small, 16px -- Units.iconSizes.smallMedium, 22px -- Units.iconSizes.medium, 32px -- Units.iconSizes.large, 48px -- Units.iconSizes.huge, 64px -- Units.iconSizes.enormous, 128px +=============================== ===== +Units Value +=============================== ===== +``Units.iconSizes.small`` 16px +``Units.iconSizes.smallMedium`` 22px +``Units.iconSizes.medium`` 32px +``Units.iconSizes.large`` 48px +``Units.iconSizes.huge`` 64px +``Units.iconSizes.enormous`` 128px +=============================== ===== Plasma: -- units.iconSizes.tiny, 8px -- units.iconSizes.small, 16px -- units.iconSizes.smallMedium, 22px -- units.iconSizes.medium, 32px -- units.iconSizes.large, 48px -- units.iconSizes.huge, 64px -- units.iconSizes.enormous, 128px - - -From design to code +=============================== ===== +Units Value +=============================== ===== +``units.iconSizes.tiny`` 8px +``units.iconSizes.small`` 16px +``units.iconSizes.smallMedium`` 22px +``units.iconSizes.medium`` 32px +``units.iconSizes.large`` 48px +``units.iconSizes.huge`` 64px +``units.iconSizes.enormous`` 128px +=============================== ===== + +From Design to Code ------------------- -For any mockup, please help the developers by specifying all +For any mockup, help the developers by specifying all measurements, either in the mockup itself or in an extra guide to the mockup. It is a lot of work and it is error prone for developers trying to measure everything from a mockup. Even if the mockup is in a file format that would allow exact measurements, don't expect the developer -to know how to do it. +to know how to measure it. .. container:: flex .. container:: .. figure:: /img/Design.qml.png :scale: 80% - :iconred:`BAD` |br| - There are no measures. + :iconred:`Don't.` |br| + Don't create mockups without measurements. .. container:: .. figure:: /img/Design_Good.qml.png :scale: 80% - :noblefir:`GOOD` |br| - Try to be as detailed as necessary. + :noblefir:`Do.` |br| + Create mockups with detailed measurements. -You don't have to provide measurement for objects that can be easily calculated. For example the size of the dark rectangle can be easily obtained. +You don't have to provide measurement for objects that can be easily calculated. For example the size of the dark rectangle in the above example can be easily obtained. -Recomended spacings +Recomended Spacings ~~~~~~~~~~~~~~~~~~~ -If you design try to use the recomended values for margin and paddings, -to ensure a uniform appearance. See :doc:`placement and spacing ` for more +When you design, try to use the recomended values for margin and paddings, +to ensure a uniform appearance. See :doc:`Metrics and Placement ` for more details. .. figure:: /img/Margin.qml.png :alt: Use of base units Use of base units .. code:: qml :number-lines: Row { spacing: Units.largeSpacing Rectangle { ... } Rectangle { ... } } .. code:: qml :number-lines: Row { spacing: 2 * Units.smallSpacing Rectangle { ... } Rectangle { ... } } .. Arbitrary px values ~~~~~~~~~~~~~~~~~~~ When needed, you can use arbitrary px values for your mockups. As a developer you need to use Units.devicePixelRatio to make these values DPI independent. .. figure:: /img/Arbitrary.qml.png :alt: Use of arbitrary px values Use of arbitrary px values .. code:: qml :number-lines: Row { spacing: Units.smallSpacing Rectangle { height: Units.largeSpacing width: Math.floor(2 * Units.devicePixelRatio) } Text { ... } } -ratio +Ratio ~~~~~ Sometimes the ratio between dimensions is more important then the actually values. .. figure:: /img/Ratio.qml.png .. code:: qml :number-lines: Grid { columns: 3 ... Repeater { model: 9 ... Rectangle { width: grid.width / 3 height: grid.height / 3 ... } } } diff --git a/HIG/source/patterns/command/content.rst b/HIG/source/patterns/command/content.rst index c9f30ef..1fd9df1 100644 --- a/HIG/source/patterns/command/content.rst +++ b/HIG/source/patterns/command/content.rst @@ -1,11 +1,11 @@ -Controls within content +Controls within Content ======================= .. image:: /img/Content1.png :alt: Controls within content :scale: 70 % If controls are directly necessary for the primary tasks of an application (e.g. the "send message" button in a address book app) and there is space left in the content area, put them directly within the content. diff --git a/HIG/source/patterns/command/drawer.rst b/HIG/source/patterns/command/drawer.rst index f5c92bf..9fe9699 100644 --- a/HIG/source/patterns/command/drawer.rst +++ b/HIG/source/patterns/command/drawer.rst @@ -1,55 +1,55 @@ Drawers ======= -Drawers do not take away any room from the content, but need an extra -action to access, and should therefore not be used for controls that are +Drawers don't take away any room from the content, but they do require +user interaction to become visible, and should therefore not be used for controls that are part of an application's main tasks. -Global drawer +Global Drawer ------------- .. figure:: /img/Globaldrawer1.png :alt: Global drawer :scale: 40 % :figclass: border Global drawer on mobile The global drawer is used for global, context-independent controls. - The drawer is opened by an edge-swipe (the side is system-defined) and closed by swiping in the other direction or tapping outside of the panel - For the guidelines regarding its content, see :doc:`global drawer `. -Context drawer +Context Drawer -------------- .. figure:: /img/Contextdrawer1.png :alt: Context drawer :scale: 40 % :figclass: border Context drawer on mobile The context drawer (the side is system-defined) is used for context-specific controls that affect only the currently selected object (e.g. copy, delete etc.). - The drawer is opened by an edge-swipe and closed by swiping in the other direction or tapping outside of the panel - For the guidelines regarding its content, see the :doc:`context drawer `. -Bottom drawer and dialog sheet +Bottom Drawer and Dialog Sheet ------------------------------ .. image:: /img/Bottom_Drawer.png :alt: Bottom drawer :scale: 40 % For a full modal dialog, use a :doc:`dialog sheet `. For a quick choice, use a :doc:`bottom drawer `. diff --git a/HIG/source/patterns/command/index.rst b/HIG/source/patterns/command/index.rst index 75274a5..bec5e33 100644 --- a/HIG/source/patterns/command/index.rst +++ b/HIG/source/patterns/command/index.rst @@ -1,48 +1,48 @@ -Command patterns +Command Patterns ================ .. toctree:: :maxdepth: 1 :titlesonly: :hidden: content drawer menubar ondemand simple toolbar Command patterns are determined by the command structure chosen for the application. A command is any function performed by the application based on user input. Commands that perform similar functions may be grouped together. The collection of commands and command groups make up the command structure of the application. Command patterns can be combined with :doc:`navigation patterns ` and :doc:`content patterns ` to design the complete layout for your application. Guidelines ---------- When designing an application, it may be unclear what the command structure should be. - Start by assuming a simple command structure and select an associated command pattern. - As the design evolves, if the selected pattern becomes inadequate for completing the primary tasks of the application, consider a pattern for a more complex command structure. .. note:: |mobileicon| Considering the limited space available in mobile applications, there is always a trade-off between accessibility of controls and space available for the content. - :doc:`content` - :doc:`drawer` - :doc:`menubar` - :doc:`ondemand` - :doc:`simple` - :doc:`toolbar` diff --git a/HIG/source/patterns/command/menubar.rst b/HIG/source/patterns/command/menubar.rst index 4f80582..d57f4e5 100644 --- a/HIG/source/patterns/command/menubar.rst +++ b/HIG/source/patterns/command/menubar.rst @@ -1,18 +1,19 @@ Menubar ======= .. image:: /img/CP-MenuBar.png :alt: Menubar - Use the Menubar pattern when access to the full command structure is necessary to complete the primary tasks of the application. - Commands are also exposed using toolbars, context menus, a context panel or by direct manipulation of content. - Commands in the menubar should generally be globally applicable. Consider using a context panel or a context menu for commands that are specific to the current selection. -**Examples** +Examples +-------- IDE, Text Editor, Image editor, Audio/video editor, Document editor, Spreadsheet editor diff --git a/HIG/source/patterns/command/ondemand.rst b/HIG/source/patterns/command/ondemand.rst index dd324d9..d7aa138 100644 --- a/HIG/source/patterns/command/ondemand.rst +++ b/HIG/source/patterns/command/ondemand.rst @@ -1,66 +1,66 @@ -On-Demand controls +On-Demand Controls ================== .. container:: intend |desktopicon| |mobileicon| .. container:: flex .. container:: .. image:: /img/Slide_to_reveal.jpg :alt: 240px :scale: 25 % .. container:: .. image:: /img/Dolphin_hover.png :alt: 240px :scale: 80 % -When to use +When to Use ----------- Use on-demand controls for actions which directly relate to an element in a list or a grid, so they can be executed without selecting the element first (for example deleting or replying to an email right from the list). -How to use +How to Use ---------- -- Do not use on-demand controls as the only means to execute an action, +- Don't use on-demand controls as the only means to execute an action; they are only shortcuts. -- Do not use more than five (ideally not more than three) actions in +- Don't use more than five (ideally not more than three) actions in on-demand controls. If you need more actions, choose a different :doc:`command pattern `. - Only use on-demand controls, if the actions are the same for each item. - Since the actions don't have a label, don't use the on-demand pattern, if the actions are not clearly identifiable. .. caution:: Especially if only one action is available, it is often better to show the action directly or have the action as default on the item. Behavior --------- |desktopicon| Desktop ~~~~~~~~~~~~~~~~~~~~~ On-demand controls are shown when hovering over the item with the cursor. A handle can be added to enable touch screen support. As soon as the user taps anywhere else or the pointer is not any longer hovering the item, the on-demand controls are hiden again. |mobileicon| Mobile ~~~~~~~~~~~~~~~~~~~ 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. For futher guidelines see :doc:`list item `. diff --git a/HIG/source/patterns/command/simple.rst b/HIG/source/patterns/command/simple.rst index 1e8e485..ca22c5f 100644 --- a/HIG/source/patterns/command/simple.rst +++ b/HIG/source/patterns/command/simple.rst @@ -1,25 +1,25 @@ -Patterns for a simple command structure +Patterns for a Simple Command Structure ======================================= .. image:: /img/CP-Simple.png :alt: Simple command structure :scale: 80 % - Use Menu Button command pattern when there are few globally applicable commands. The menu button can overlay content. - Use Context Menu or Context Panel command patterns for commands specific to selected or currently visible content. - The menu button pattern can be combined with either of the context menu or context panel patterns. - Commands can also be exposed by direct manipulation of content (click, drag, buttons, search field, pan, zoom, etc). - For plasmoids, all commands must be exposed by direct manipulation of content - no menu button, context menu, or context panel. Examples -------- Contacts, Chat client, Video conference, Calculator, Terminal, Plasmoids (panel applets and desktop widgets), Maps, Games, Image browser, Document viewer, Music player, Video player, Software installer, System Settings diff --git a/HIG/source/patterns/content/duallist.rst b/HIG/source/patterns/content/duallist.rst index 76e58cc..8b84e01 100644 --- a/HIG/source/patterns/content/duallist.rst +++ b/HIG/source/patterns/content/duallist.rst @@ -1,67 +1,67 @@ -Dual-list +Dual-List ========= .. image:: /img/DualListOrdering.png :alt: Dual-list pattern Multiple selection in :doc:`lists ` with more than a few items might become difficult because selected as well as available items are not visible at once. As an alternative approach, the *dual-list pattern* (also known as list builder, or paired lists) was introduced. It consists of two standard :doc:`list ` boxes with the option to move items from one :doc:`list ` to the other and back. Dual-lists are useful for extended multiple selection in general, especially for huge sets of items or in case of elaborate selections. The trade-off is the rather large amount of space that is needed to show two adjoining lists. -When to use +When to Use ----------- - Use a dual-list pattern for multiple selection and in case of :doc:`large lists `. - In case of limited screen real estate, consider changing the workflow into repeated selections of smaller lists or by applying a hierarchy to the data. -- Do not use a dual-list to show data primarily. +- Don't use a dual-list to show data primarily. -How to use +How to Use ---------- - Label both lists view with a descriptive caption to the top. End each list label with a colon. - Use the left list to contain all available options. The right list should hold all currently active or in use items. - Ensure that the list boxes are of equal height and width. - Place move/remove buttons (right and left arrows) centered and in between the two lists. Disable a button if the list it is pointing away from is empty. - If an instance of one item can be repeated (such as a spacer), copy (rather than move) the item from the available pool of items to the list of current items. - If the list of current items can be reordered, place up/down buttons in between the two lists, above and below the left and right buttons. Only enable the up/down buttons when an item is selected and can be moved. -- Do not have blank list items; use meta-options, (e.g. "None") instead. +- 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. Implementation -------------- - Allow the user to drag-and-drop items between lists, or re-order items within a list (if applicable) - Double clicking on an item should add it to or remove it from the current list, respectively. - Allow multiple selection of items within one list. - Make both list controls large enough that it can show at least four items at a time without scrolling. - If the lists appears in a dialog or utility window, consider making the window and the lists within it resizeable so that the user can choose how many list items are visible at a time without scrolling. Each time the user opens this dialog, set its dimensions to those that the user last resized it to. - Create a buddy relation so access keys are assigned. - Use :doc:`sentence style capitalization ` for list view items. diff --git a/HIG/source/patterns/content/form.rst b/HIG/source/patterns/content/form.rst index b8899fb..91eb61c 100644 --- a/HIG/source/patterns/content/form.rst +++ b/HIG/source/patterns/content/form.rst @@ -1,104 +1,104 @@ Form ==== -A *Form layout* is used to help align and structure a layout containing many +A form layout is used to help align and structure a layout containing many control and input fields. -When to use +When to Use ----------- - Use a Form layout when there are many related controls and input fields. - Form layouts are ideal for :doc:`settings dialogs `. -How to use +How to Use ---------- - On |desktopicon| 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. - See the pages on :doc:`radio buttons ` and :doc:`checkboxes ` for detailed information regarding how to align these tricky controls in a Form layout. .. container:: flex .. container:: .. figure:: /img/Form_Align_KDE3.qml.png :scale: 80% - :iconred:`BAD` |br| - KDE3 form alignment + :iconred:`Don't.` |br| + Don't use KDE3-style form alignment .. container:: .. figure:: /img/Form_Align_KDE5.qml.png :scale: 80% - :noblefir:`GOOD` |br| - Plasma 5 form alignment + :noblefir:`Do.` |br| + Use Plasma 5-style form alignment. .. container:: flex .. container:: .. figure:: /img/Form_Align_OSX.qml.png :scale: 80% - :iconred:`BAD` |br| - OSX form alignment + :iconred:`Don't.` |br| + Don't use macOS-style form alignment. .. container:: .. figure:: /img/Form_Align_KDE5.qml.png :scale: 80% - :noblefir:`GOOD` |br| - Plasma 5 form alignment + :noblefir:`Do.` |br| + Use Plasma 5-style form alignment. - Position groups of items vertically rather than horizontally, as this makes them easier to scan visually. Use horizontal or rectangular positioning only if it would greatly improve the layout of the window. - Left align controls over multiple groups. This visual anchor facilitates scanning of content, and left-hand alignment fits as well forms that have been oversized individually. .. container:: flex .. container:: .. figure:: /img/Form_Align_NO.qml.png :scale: 80% - :iconred:`BAD` |br| - no alignment over controls + :iconred:`Don't.` |br| + Don't misalign controls. .. container:: .. figure:: /img/Form_Align_YES.qml.png :scale: 80% - :noblefir:`GOOD` |br| - left aligned controls + :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. .. figure:: /img/Form_Align_Long.qml.png :scale: 80% - :iconred:`BAD` |br| - Avoid very long captions + :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. - When using labels on top, labels and widgets should be left-aligned. .. image:: /img/Form_Align_YES_Mobile.qml.png :scale: 80% diff --git a/HIG/source/patterns/content/help.rst b/HIG/source/patterns/content/help.rst index 772be8c..1f7a9d6 100644 --- a/HIG/source/patterns/content/help.rst +++ b/HIG/source/patterns/content/help.rst @@ -1,32 +1,32 @@ -Help system +Help System =========== -The *help system* should be used as a secondary mechanism to support +The help system should be used as a secondary mechanism to support users’ complete and better understanding of tasks — the primary mechanism should be the user interface itself. Users consult the help -system only if they can't accomplish a task with the UI. +system only if they cannot accomplish a task with the UI. -When to use +When to Use ----------- Try to make Help unnecessary in the first place: - Make common tasks easy to discover and perform. - Provide clear main instructions as well as concise control labels that are goal- and task-oriented. - Provide supplemental instructions and explanations where needed. - Avoid problems by using controls constrained to valid choices, providing suitable default values, handling all input formats, and preventing errors. - Write error messages that provide a clear solution or action for the user to take. -How to use +How to Use ---------- - Usually, the help system is activated by F1 respectively Ctrl+F1 for context sensitive information and via menu. Implementation -------------- - http://www.kde.org/support/ diff --git a/HIG/source/patterns/content/iconandtext.rst b/HIG/source/patterns/content/iconandtext.rst index 00eaf3c..b894afe 100644 --- a/HIG/source/patterns/content/iconandtext.rst +++ b/HIG/source/patterns/content/iconandtext.rst @@ -1,30 +1,30 @@ -Icons and text +Icons and Text ============== -When to use +When to Use ----------- Combining icons and text can be used to identify data and actions in a user interface. Examples include toolbar actions, file and folder displays in a file manager, application listings, and notifications. The layout should be consistent. -How to use +How to Use ---------- .. image:: /img/HIGPatternIconsAndText.png :alt: Alignment of text and icons. .. attention:: Make sure to read about how :doc:`units and measurements ` are used for design and development. - Where icons are shown with text, use the layout guidelines above. Implementation -------------- - For 16x16px icons and smaller, the 8px margins may be reduced to 4px. - Where icons are shown without text, always provide tooltip text and alternate text for accessibility. - If Secondary Text is normally present, but is empty in a particular instance, align the Primary Text to the vertical center. diff --git a/HIG/source/patterns/content/index.rst b/HIG/source/patterns/content/index.rst index f544149..32d82d6 100644 --- a/HIG/source/patterns/content/index.rst +++ b/HIG/source/patterns/content/index.rst @@ -1,23 +1,23 @@ -Content patterns +Content Patterns ================ .. toctree:: :maxdepth: 1 :titlesonly: :hidden: duallist form iconandtext help picker settings viewingediting - :doc:`duallist` - :doc:`form` - :doc:`iconandtext` - :doc:`help` - :doc:`picker` - :doc:`settings` - :doc:`viewingediting` diff --git a/HIG/source/patterns/content/picker.rst b/HIG/source/patterns/content/picker.rst index da4caa5..df53906 100644 --- a/HIG/source/patterns/content/picker.rst +++ b/HIG/source/patterns/content/picker.rst @@ -1,58 +1,58 @@ Picker ====== Pickers implement a pattern to select multiple items from a list of available choices. The main component only displays the selected items, and more items can be added by choosing them from a list or grid in a dialog or overlay. In compairison to dual lists, they work well on desktop and mobile. Example ------- .. figure:: /img/LanguagePicker.png :alt: Picker in Language KCM :scale: 60% Use of a picker to select aditional languages. -When to use +When to Use ----------- - Use a picker for multiple selection and in case of large lists. - Don't use it if both selected and unselected items need to be visible at once. Use a dual list instead. -- Do not use a picker to show data primarily. +- Don't use a picker to show data primarily. - If selection state needs to change often, think about using a list with checkboxes or similar instead. -How to use +How to Use ---------- .. figure:: /img/PickerOverlay.png :alt: Using an overlay :scale: 60% Using an overlay to pick aditional items. - Use a :doc:`grid ` or a :doc:`list ` to display the selected elemets. - Open list of additional items to choose in a overlay sheet or a dialog - Allow the user to select multiple items at once. - Use either an on-demand control or display an button to allow the user to deselect items. - If the list of selected items can be reordered, place up/down buttons to the right of the list of current items. Only enable the up/down buttons when an item is selected and can be moved. -- Do not have blank list items; use meta-options, (e.g. "None") instead. +- 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 the lists or grids within it resizeable so that the user can choose how many list items are visible at a time without scrolling. - Use :doc:`sentence style capitalization ` for items. diff --git a/HIG/source/patterns/content/settings.rst b/HIG/source/patterns/content/settings.rst index 90a64d9..14bad7b 100644 --- a/HIG/source/patterns/content/settings.rst +++ b/HIG/source/patterns/content/settings.rst @@ -1,117 +1,117 @@ Settings ======== -A *settings page* provides the ability to customize how an application or +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 can't be +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 +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. -- Do not use settings pages to change the properties of a selected item. +- Don't use settings pages to change the properties of a selected item. Instead, use a properties dialog or a contextual editing panel. -- Do not use the settings page for potentially dangerous developer settings +- 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 +How to Use ---------- - **Simple by default**: Define smart and polite defaults so that your target :doc:`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 `_ for details. Implementation -------------- -- For a desktop app, put your settings page inside a dialog window and do not +- 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 `. 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 ` 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 ` (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. -- Do not change the settings page depending on the context. 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. -- Do not use a wizard to change settings. Only use a wizard if a group of +- 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, - do not hide the inapplicable ones. Instead, disable them and hint to the + 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. diff --git a/HIG/source/patterns/content/viewingediting.rst b/HIG/source/patterns/content/viewingediting.rst index cdac168..dca8df3 100644 --- a/HIG/source/patterns/content/viewingediting.rst +++ b/HIG/source/patterns/content/viewingediting.rst @@ -1,46 +1,43 @@ -Viewing vs editing -================== +Viewing vs. Editing +=================== In most cases, information should be presented by default for viewing, not editing. Presenting input controls to the user when they are not needed creates unnecessary clutter and distraction, interfering with effective presentation of the information. -When to use +When to Use ----------- Only show editing controls when appropriate. Examples include: - When an item is selected, contextually-appropriate editing controls can be shown in a toolbar or panel. - If an explicit editing mode is appropriate, then editing controls should not be shown until that mode is activated. -How to use +How to Use ---------- .. image:: /img/ViewMode.png :alt: Viewing -- Do not use input controls to show information unless there is an +- Don't use input controls to show information unless there is an explicit request to edit the information. - Follow the typography, alignment, and spacing guidelines to layout information in a way that is easy to understand. - Provide a clear visual hierarchy (where to look first, where to look next). The example above uses a large contact photo to anchor the layout and the contact name is set in large type to direct the users eye to next piece of information. - Provide a separate mode for editing the data when requested by the user (via a button, toolbutton or menu item): .. image:: /img/EditMode.png :alt: Editing - Alternatively, in-line editing can be provided to edit a single data element at a time when it is clicked on or selected: .. image:: /img/PartialEditMode.png - :alt: Line-in editing - -Implementation --------------- + :alt: Line-in editing \ No newline at end of file diff --git a/HIG/source/patterns/navigation/breadcrumb.rst b/HIG/source/patterns/navigation/breadcrumb.rst index f7978be..5cdde6e 100644 --- a/HIG/source/patterns/navigation/breadcrumb.rst +++ b/HIG/source/patterns/navigation/breadcrumb.rst @@ -1,57 +1,55 @@ Breadcrumbs =========== .. container:: intend |desktopicon| |mobileicon| -Pattern for n-deep content structure. - .. image:: /img/NP-n-deep.png :alt: Breadcrumb patterns The *breadcrumbs* pattern is a navigation aid for hierarchical content structures (e.g. home > documents > business). It provides information about the current position within the hierarchy, and offers shortcut links to jump to previous positions without using the Back button. .. raw:: html - -Use of breadcrumb navigation in Plasma Mobile. +*Use of breadcrumb navigation in Plasma Mobile.* -When to use +When to Use ----------- - Use a breadcrumb control for orientation and navigation in strictly hierarchical content. Apply other controls like tags for flat or less organized content. -- Make sure a breadcrumb control has only supportive functions. Do not use +- Make sure a breadcrumb control has only supportive functions. Don't use it as primary and exclusive navigation pattern. -- Do not use a breadcrumb control to just identify or label the position; +- Don't use a breadcrumb control to just identify or label the position; it must be interactive. -- Do not make the breadcrumb control dynamic by showing the user's past +- Don't make the breadcrumb control dynamic by showing the user's past interactions (known as 'path breadcrumbs'). Breadcrumbs should show the hierarchy, not the user's history. -How to use +How to Use ---------- - Link all breadcrumb steps to the appropriate page or position. Show the current position at the very end of the breadcrumb control. -- Keep breadcrumbs plain and textual; do not use icons or other controls. +- Keep breadcrumbs plain and textual; don't use icons or other controls. - Place a breadcrumb control above the content area, but below other navigation controls. -- Do not integrate a breadcrumb control into a toolbar or titlebar. +- Don't integrate a breadcrumb control into a toolbar or titlebar. Implementation -------------- - Consider providing a dropdown context menu full of alternative options for each breadcrumb item. But always offer one-click access by default. - Think of ways to make the breadcrumb control interactive in other creative ways. For example, it might permit content to be dragged-and-dropped onto a breadcrumb item to quickly move it there. diff --git a/HIG/source/patterns/navigation/column.rst b/HIG/source/patterns/navigation/column.rst index fe116ba..aa69619 100644 --- a/HIG/source/patterns/navigation/column.rst +++ b/HIG/source/patterns/navigation/column.rst @@ -1,70 +1,70 @@ Column-based navigation ======================= .. container:: intend |desktopicon| |mobileicon| .. container:: available plasma |nbsp| -Examples of column-based navigation in a phone and a desktop UI +Examples of column-based navigation in a phone and a desktop UI. .. image:: /img/Desktop.png :alt: Column-based navigation on the desktop :scale: 40% .. raw:: html - -When to use +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 For example: - Accounts ->Folders -> (Sub-Folders) -> Mails -> Invidual mail - Folders -> RSS Feeds -> Feed items -> Individual item - File system hirachy Kirigami implements this pattern in the form of a PageRow, which allows users to scroll horizontally through pages and allows the application to add and remove pages to and from the stack dynamically. This allows easy back and forward navigation through the hierarchy by swiping left-right on touch screens. A header with the title of the current page doubles as a breadcrumb trail which the user can scroll through and tap to go to a specific page. -How to use it +How to Use It ------------- General ~~~~~~~ - Use one page/column for each level of the hierarchy (or more generally, for each step of the navigation). - Pages can for example be :doc:`lists ` or :doc:`grids `, or a detail view of a particular item. - Make sure to set meaningful but short page titles, so they can create 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 - For the command structure, see the :doc:`command patterns `. Implementation -------------- If you use `ApplicationWindow `_ for your application, it automatically uses PageRow for its content. diff --git a/HIG/source/patterns/navigation/combination-3.rst b/HIG/source/patterns/navigation/combination-3.rst index 31f36c5..7e6083c 100644 --- a/HIG/source/patterns/navigation/combination-3.rst +++ b/HIG/source/patterns/navigation/combination-3.rst @@ -1,16 +1,16 @@ -Combination patterns -==================== +3-Deep Combination Patterns +=========================== .. container:: intend |desktopicon| -Patterns for a 3-deep content . +.. figure:: /img/NP-3-deep.png + :alt: Patterns for 3-deep content. -.. image:: /img/NP-3-deep.png - :alt: Combination patterns + Patterns for 3-deep content. - Navigation patterns could be combined to create a 3-deep navigation pattern. However, to maintain consistency across applications, we recommend always starting with a List-Detail pattern with a Collapsible List. A few examples are shown above. diff --git a/HIG/source/patterns/navigation/combination.rst b/HIG/source/patterns/navigation/combination.rst index 063731c..dd40ad2 100644 --- a/HIG/source/patterns/navigation/combination.rst +++ b/HIG/source/patterns/navigation/combination.rst @@ -1,16 +1,16 @@ -Combination patterns -==================== +2-Deep Combination Patterns +=========================== .. container:: intend |desktopicon| -Pattern for a 2-deep content structure. +.. figure:: /img/NP-2-deep-2.png + :alt: Pattern for a 2-deep content structure. -.. image:: /img/NP-2-deep-2.png - :alt: Combination patterns + Pattern for a 2-deep content structure. - Any two flat navigation patterns could be combined to create a 2-deep navigation pattern. However, to maintain visual consistency across applications we recommend always starting with the List-Detail pattern. A few examples are shown above. diff --git a/HIG/source/patterns/navigation/expandable.rst b/HIG/source/patterns/navigation/expandable.rst index 6c61a6f..4217fd2 100644 --- a/HIG/source/patterns/navigation/expandable.rst +++ b/HIG/source/patterns/navigation/expandable.rst @@ -1,20 +1,20 @@ -Expandable list +Expandable List =============== .. container:: intend |desktopicon| |mobileicon| - The expandable list is useful when additional details for individual elements in a list/group are to be shown alongside the other elements in the list - For example, use the expandable list pattern for a list of emails in a thread to allow the user to show long individual mails in full while retaining easy navigation through the whole thread - Make only list items that are higher than 1/4 of the visible list height expandable - Tapping an expandable list element once expands it, tapping it again collapses it - Add enough free space at the beginning and end of the list to allow users to scroll both the first and last item on the list to the center of the screen for easy interaction with it. diff --git a/HIG/source/patterns/navigation/grid.rst b/HIG/source/patterns/navigation/grid.rst index c5c82e6..76d2f81 100644 --- a/HIG/source/patterns/navigation/grid.rst +++ b/HIG/source/patterns/navigation/grid.rst @@ -1,42 +1,42 @@ Grid ==== .. container:: intend |desktopicon| |mobileicon| Pattern for a flat content structure. .. image:: /img/Grid.png :alt: Grid of items -When to use +When to Use ----------- Use a grid to show a set of elements which can best be represented graphically (as images with or without text), such as a gallery of pictures or video thumbnails, or the content of a store. For elements that are better represented by text, use a :doc:`list `. -How to use +How to Use ---------- - Make sure that the grid items are big enough and/or there is enough padding between them for users to easily tap items - Accompany images with a textual label if there is a chance that certain elements may be easier to recognize by their text than their graphical representation - If a grid is populated from an online source, use the "Pull to refresh" feature that allows users to update it simply by pulling it down beyond the first (i.e. newest) grid item Implementation -------------- - Use a GridView within a Page or ScrollablePage (if the grid can contain more elements than fit on the screen) to implement this pattern - Set supportsRefreshing: true on the ScrollablePage to allow "Pull to refresh" diff --git a/HIG/source/patterns/navigation/index.rst b/HIG/source/patterns/navigation/index.rst index c02f40c..1948c2b 100644 --- a/HIG/source/patterns/navigation/index.rst +++ b/HIG/source/patterns/navigation/index.rst @@ -1,101 +1,101 @@ -Navigation patterns +Navigation Patterns =================== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: single list expandable grid master combination tab unique combination-3 breadcrumb column Navigation Patterns depend on the structure of the application content. Navigation patterns can be combined with :doc:`command patterns ` and content patterns to design the complete layout for your application. -Patterns for desktop user interfaces +Patterns for Desktop User Interfaces ------------------------------------ -Patterns for a flat content structure +Patterns for a Flat Content Structure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: /img/IS-flat.png :alt: Flat structure When pieces of application content are not grouped, the content structure is flat. Examples include a playlist, a slideshow or a list of documents or contacts. - :doc:`Single item ` - :doc:`List ` - :doc:`Expandable list ` - :doc:`Grid ` - :doc:`Master detail ` -Patterns for a 2-deep content structure +Patterns for a 2-Deep Content Structure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: /img/IS-2-deep.png :alt: Patterns for a 2-deep content structure When all application content are grouped into top-level categories, the content structure is 2-deep. Examples include picture albums, music albums, email folders or tags. - :doc:`Combination patterns ` - :doc:`Tabs ` - :doc:`Unique 2-deep patterns ` -Patterns for a 3-deep content structure +Patterns for a 3-Deep Content Structure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: /img/IS-3-deep.png :alt: Patterns for a 3-deep content structure When all application content are grouped into categories, which are themselves be grouped into top-level categories, the content structure is 3-deep. .. caution:: Content structures this deep should generally be avoided. There are instances, however, where it may be difficult to avoid. Examples include a full music or video library or system settings. - :doc:`Combination patterns ` -Patterns for n-deep content structures +Patterns for N-Deep Content Structures ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: /img/IS-n-deep.png :alt: Patterns for n-deep content structures When content is infinitely groupable, the content is n-deep. .. caution:: Content structures this deep should be avoided. It is very difficult for the user to maintain awareness of their location in content structure relative to other content. There are instances, however, where this structure cannot be avoided. Examples include file systems and archives. - :doc:`Breadcrumbs ` - :doc:`Column-based navigation ` diff --git a/HIG/source/patterns/navigation/list.rst b/HIG/source/patterns/navigation/list.rst index 43c69a3..9dbb513 100644 --- a/HIG/source/patterns/navigation/list.rst +++ b/HIG/source/patterns/navigation/list.rst @@ -1,51 +1,51 @@ List ==== .. container:: intend |desktopicon| |mobileicon| Pattern for a flat content structure. .. image:: /img/List.png :alt: List of items :scale: 30% -When to use +When to Use ----------- Use a list to present a set of elements which are best presented in a textual manner (e.g. a list of emails). - The list pattern is useful when multiple pieces of content are intended to be shown at once. - All essential information about each piece of content is visible or accessible within the list without changing layout. - If list items may be longer than one quarter of the list height, consider using an expandable list -How to use it +How to Use It ------------- - Sort list items the way they make most sense for the user. For example, chronologically or alphabetically - If a list is populated from an online source, use the "Pull to refresh" feature that allows users to update it simply by pulling it down beyond the first (i.e. newest) list item - Make the whole area of each list item clickable to select the item (unless there is a "Slide to reveal" handle, see next bullet) - If you want actions to be available directly on a list item, use the :doc:`slide to reveal pattern `. - Add enough free space at the beginning and end of the list to allow users to scroll both the first and last item on the list to the center of the screen for easy interaction with it. Implementation -------------- - Use a ListView within a Page or ScrollablePage (if the list can contain more items than fit on the screen) to implement this pattern - Set supportsRefreshing: true on the ScrollablePage to allow "Pull to refresh" diff --git a/HIG/source/patterns/navigation/single.rst b/HIG/source/patterns/navigation/single.rst index cfacca4..081225a 100644 --- a/HIG/source/patterns/navigation/single.rst +++ b/HIG/source/patterns/navigation/single.rst @@ -1,30 +1,30 @@ -Single item +Single Item =========== .. container:: intend |desktopicon| |mobileicon| Pattern for a flat content structure. .. image:: /img/NP-flat-1b.png :alt: Single item - These patterns are useful when each piece of content is meant to be shown one at a time. - Controls are usually provided to allow the user to move from one piece of content to the next. - For media (dis)play, whether playback controls are shown depends on the type of media: - For audio, always show playback controls - For video, show playback controls only on tap (pausing the video) - |touchicon| For image galleries as well as playlists, use left/right swipe to switch between files to (dis)play - Examples include a slideshow, or a video or music playlist, or a single-page web browser. - Display properties of the currently shown object which are essential for the application's main task below the object, show additional properties on demand in the :doc:`context drawer `. diff --git a/HIG/source/patterns/navigation/tab.rst b/HIG/source/patterns/navigation/tab.rst index 0570f09..2133124 100644 --- a/HIG/source/patterns/navigation/tab.rst +++ b/HIG/source/patterns/navigation/tab.rst @@ -1,17 +1,17 @@ Tab === .. container:: intend |desktopicon| |mobileicon| Pattern for a 2-deep structure. - There are two different ways tabs can be used: - - One is for splitting a user interface that does not fit on a + - Splitting a user interface that does not fit on a single screen into several groups - - The other is for viewing multiple documents (e.g. websites in a + - Viewing multiple documents (e.g. websites in a browser) in the same application instance - See the :doc:`tab ` for details. diff --git a/HIG/source/patterns/navigation/unique.rst b/HIG/source/patterns/navigation/unique.rst index d5472e8..26d4560 100644 --- a/HIG/source/patterns/navigation/unique.rst +++ b/HIG/source/patterns/navigation/unique.rst @@ -1,20 +1,20 @@ -Unique 2-deep patterns +Unique 2-Deep Patterns ====================== .. container:: intend |desktopicon| |mobileicon| Pattern for a 2-deep content structure. .. figure:: /img/NP-2-deep-1a.png :alt: Unique 2-deep patterns - The Collapsible List pattern is a space-efficient way of showing 2-deep content. This pattern is useful for plasmoids and applications where the layout must be compact. A :doc:`tree view ` can be used to implement this pattern. - The Crossbar pattern arranges categories vertically and the content within the selected category horizontally. This pattern is often used for navigating video libraries. diff --git a/HIG/source/plattform/getnew.rst b/HIG/source/plattform/getnew.rst index fb12c11..39d45b5 100644 --- a/HIG/source/plattform/getnew.rst +++ b/HIG/source/plattform/getnew.rst @@ -1,49 +1,49 @@ Get New Stuff ============= Get New Stuff (GNS) is an integrated data service which allows users to share and download themes, templates, wallpapers, and more through a single click of a button in the application. Examples -------- .. figure:: /img/Systemsettings-LookAndFeel.png :scale: 40% Get New Stuff button in "Choose the Look and Feel theme" KCM Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ -Add a GNS button to an application or a KCM, if the user can install aditional -content from the integrated data service. You might want to accompany it by a -button that allows the user to install content from the local file system. +If the user can install additional content to customize the behavior or appearance of the software +(e.g. plugins, themes, scripts, etc.), use the GNS system and add a "Get New " button. Consider +adding a companion button to allow installation of additional content from the filesystem. Appearance ~~~~~~~~~~ The text of a GNS button should be made of these parts: - Use the get-hot-new-stuff.png icon .. image:: /img/get-hot-new-stuff.svg :width: 32 :height: 32 - Label the button with "Get New" and the type of content the user will download - Add an :doc:`ellipsis to the label `, to indicate the user must provide additional input to complete the task. The button should always be placed on the bottom right of the list or grid that can be ammended. If you want a button to install from the local file system, place it to the left og the GNS button. .. figure:: /img/Systemsettings-PlasmaTheme.png :scale: 40% Button placement at the bottom of the content grid diff --git a/HIG/source/plattform/index.rst b/HIG/source/plattform/index.rst index 62959fa..98099a9 100644 --- a/HIG/source/plattform/index.rst +++ b/HIG/source/plattform/index.rst @@ -1,18 +1,18 @@ Platform ========= .. toctree:: :titlesonly: :hidden: getnew notification tray This is an overview of how to integrate your application into the -:doc:`plasma workspaces `. +:doc:`Plasma Workspace `. * :doc:`getnew` * :doc:`notification` * :doc:`tray` diff --git a/HIG/source/plattform/notification.rst b/HIG/source/plattform/notification.rst index d7241a0..b0d6449 100644 --- a/HIG/source/plattform/notification.rst +++ b/HIG/source/plattform/notification.rst @@ -1,105 +1,105 @@ Notification ============ Notifications are a way to inform users of your app about events, even if the applications has no focus, is minimized, or is only running in the background. Examples -------- .. figure:: /img/Notification.png :alt: Update notification Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ Use notifications to inform the user of events that are of interest, even if your app is not in foreground, but don't spam the user with notifications. - Completion of long running tasks that the user has started manually - Incoming communication from other users - Hardware related events like low battery, lost network connection, running out of disk space Don't use a notification for: - Operations that don't require user interaction, such as background processes, syncing, or updates - Advertising, rating or feedback requests, or other annoyances - If an unexpected or potentially dangerous condition has been reached and the user must make a decision. Use an :doc:`/components/assistance/message` instead. - Don't send notifications if an user has never opened your application Behavior ~~~~~~~~ Notifications are provided by the system to the user, and foremost the user settings for notification govern the behavior and appearance of notifications. But there are several options to influence and enrich the behavior of your notifications. Persistence """"""""""" Making a notification persistent will prevent it from closing after a timeout. Your app must revoke the persistent notification, if the reason for the notification no longer applies, like a power adapter was plugged after a "Laptop battery is almost empty" notification. Urgency """"""" It is recommended that a notification carrys an urgency hint: - 0 – Low, “Matt is now online”, “You just plugged in your AC adapter” - 1 – Normal, “You have new mail” - 2 – Critical, “Laptop battery is almost empty” Actions """"""" You can add up to three action buttons to the notification to enable the user to react to the event without having to go to the app itself. Preview """"""" You can specify a URL to an image associated with the notification. The image will be displayed as a preview in the notification. .. figure:: /img/Notification2.png :alt: Notification with a preview image .. Quick Reply """"""""""" This enables the user to reply to an email or SMS from within the notification. A “Reply” text field is placed in the notification window whose content is eventually sent back to the application through the notification server. Code ---- .. code-block:: c++ KNotification *notification= new KNotification ( "contactOnline", widget ); notification->setText( i18n("The contact %1 has gone online", contact->name() ); notification->setPixmap( contact->pixmap() ); notification->setActions( QStringList( i18n( "Open chat" ) ) ); connect(notification, SIGNAL(activated(unsigned int )), contact , SLOT(slotOpenChat()) ); notification->sendEvent(); Use :knotificationsapi:`` to send notifications to the :doc:`Plasma Workspaces `. diff --git a/HIG/source/plattform/tray.rst b/HIG/source/plattform/tray.rst index 6cc36ba..2581acd 100644 --- a/HIG/source/plattform/tray.rst +++ b/HIG/source/plattform/tray.rst @@ -1,43 +1,43 @@ System Tray Icon ================ The system tray 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. See :doc:`architecture ` for an overview of plasma workspace components. Examples -------- .. figure:: /img/TrayWithPanel.png :alt: Tray icons with an open volume control panel. Guidelines ---------- -Is this the right control -~~~~~~~~~~~~~~~~~~~~~~~~~ +Is this the right control? +~~~~~~~~~~~~~~~~~~~~~~~~~~ An application should only add an icon to the System Tray if the user needs to frequently access the application, or if the user is intrested in status changes within the application. Behavior ~~~~~~~~ - On left click, open the application itself, or a panel that allows quick access to common features. - On right click, open a :doc:`context menu `. - For application like media players, enable the user to change the volume while scrolling over the icon. Appearance ~~~~~~~~~~ Use a :doc:`monochrome, Shade Black, icon ` and use color only to communicate state. diff --git a/HIG/source/qml/components/inlinemessage/Message2.qml b/HIG/source/qml/components/inlinemessage/Message2.qml index ec4fea4..bb80591 100644 --- a/HIG/source/qml/components/inlinemessage/Message2.qml +++ b/HIG/source/qml/components/inlinemessage/Message2.qml @@ -1,55 +1,55 @@ /* * Copyright 2018 Fabian Riethmayer * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU Library General Public License as * published by the Free Software Foundation; either version 2, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Library General Public License for more details * * You should have received a copy of the GNU Library General Public * License along with this program; if not, write to the * Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ import QtQuick 2.7 import QtQuick.Controls 2.2 import QtQuick.Layouts 1.2 import org.kde.kirigami 2.4 as Kirigami import "../../lib" as HIG Rectangle { id: root width: 600 height: 160 ColumnLayout { x: Kirigami.Units.gridUnit * 2 y: Kirigami.Units.gridUnit * 2 width: parent.width - 2 * Kirigami.Units.gridUnit * 2 Kirigami.InlineMessage { Layout.fillWidth: true visible: true text: "Remember password?" actions: [ Kirigami.Action { text: "Remember" icon.name: "dialog-ok-apply" }, Kirigami.Action { - text: "Do not remember" + text: "Don't remember" icon.name: "dialog-cancel" } ] } } HIG.Raster { z: 1 } } diff --git a/HIG/source/resources/about.rst b/HIG/source/resources/about.rst index 3736c2c..b0dde3e 100644 --- a/HIG/source/resources/about.rst +++ b/HIG/source/resources/about.rst @@ -1,145 +1,145 @@ About ===== Human interface guidelines (HIG) are software development documents that offer application developers a set of recommendations. Their aim is to improve the experience for users by making application interfaces more consistent and hence more intuitive and learnable. The quality and acceptance of a guideline depends to a large extent on its set-up. A good structure guarantees quick access to the information the reader looks for. Additional, links to the rationales behind the guideline as well as alternative solutions are helpful. A HIG should not only include widgets and their appearance but also core usability goals, generic design specifications, and user demands. To manage all these aspects we have chosen to adopt the “\ `Universal Model of a User Interface`_\ ” by Bob Baxley (2003) as basis for the new KDE HIG. This model has been slightly adjusted to account for more recent approaches to visual design guidelines. The central aim of KDE HIG is to create a consistent experience across the software compilation. This means to apply the same visual design and user experience as well as consistent access and predictable behavior of common elements in the interface – from simple ones such as buttons and icons up to more complex constructions, such as dialog boxes. The model consists of three tiers, each of which is made up of three layers: #. Structure Structure contains concept, design vision and principles, task flow and organization. It should answer question like: What constitutes KDE software?, Who is the user of KDE software?, and Where do we want to go in future? #. Design Vision and Principles There are almost always multiple solutions to any given user interface problem. Consistency in the choice of solutions and, ultimately, the experience of the user, is guided by a Design Vision. As such, the design vision is aspirational by definition; it is a high level description of the desired user experience in not just one application, but across multiple KDE applications and the KDE workspace. A set of Design Principles are derived from the design vision as a means to provide more specific guidance on how to achieve that desired user experience. #. Conceptual Model The conceptual model is the most fundamental aspect of the interface, describing the relationship between the interface and the outside world. The purpose of the conceptual model is to draw on the user’s past experiences so they can readily understand basic operations and accurately predict functionality. #. Organizational Model The organizational model describes how the system’s content and functionality are ordered and categorized. Also known as the information architecture, the organizational model encompasses both the classification scheme as well as the model of association, hierarchy versus index for example. #. Behaviour Behaviour includes viewing and navigation, editing and manipulation and user assistance. All elements of the Behaviour layer must satisfy the Design Principles. This layer is more like ‘traditional’ guidelines, addressing questions like: How should a button behave in case of…?, or What widget do I have to use for a selection of one out of a few items? All HIGs assume that the controls referenced in the following "Implementation" sections are used. Therefore they only contain guidelines for aspects which can be changed by the developer, to keep them as concise as possible. If you feel your application needs something which the referenced - standard KDE or Qt widget does not provide, do not create you own - custom replacement, because it might violate best practice which - is implemented in the standard widget. Instead, ask the KDE HIG + standard KDE or Qt widget does not provide, don't create your own + custom replacement, because it might violate the best practices which + are implemented in the standard widget. Instead, ask the KDE HIG team for advice on how to solve your specific problem. #. Viewing and Navigation The Viewing and Navigation layer encompasses the wide variety of behaviors and operations that allow users to navigate the interface and affect its presentation. #. Editing and Manipulation The Editing and Manipulation layer contains the behaviors that result in permanent changes to user’s stored information. … Behaviors in this layer can often be recognized by the following traits: they result in permanent, stored changes; they require an implicit or explicit save operation; and they typically require validation of the input data. #. User Assistance Interface elements that inform users of the application’s activity and status, as well as elements dedicated to user education, are all contained in the User Assistance layer. This includes online help, error alerts, and status alerts. #. Presentation Presentation deals with visual design of the user interface - layout, style and text. It’s all about the appearance of the application including the platform style’s margins and spacing, colours, fonts, icon designs, etc. These questions primarily concern designers, developers, translators and the promotion team. #. Layout The various design decisions governing the placement , ordering ans spacing of onscreen elements are expressed in the Layout layer. In addition to providing an ordered visual flow, the Layout layer also supports the Behavior tier by arranging elements in a manner that helps communicate behavior, importance, and usage. #. Style The Style layer is concerned with emotion, tone, and visual vocabulary. Because it is the most visible and concrete aspect of an interface, it typically accounts for people’s first impression of a product. Style is influenced by the use of color, the design of icons throughout the interface and the use of typography. All elements of the Style layer must satisfy the Design Principles. This allows the style to change as necessary while still preserving the user experience secured by the Design Principles. #. Text Contained within the Text layer are all the written, language-based elements of the interface. This includes the labels used to represent the organizational model, the names of the input and navigational controls contained in the Viewing and Navigation layer, and the alert messages and help text used by the User Assistance layer. .. _Universal Model of a User Interface: http://www.baxleydesign.com/pdfs/dux03_baxleyUIModel.pdf diff --git a/HIG/source/resources/contribute.rst b/HIG/source/resources/contribute.rst index fc784bf..c175f15 100644 --- a/HIG/source/resources/contribute.rst +++ b/HIG/source/resources/contribute.rst @@ -1,211 +1,217 @@ 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 `_ . If you are new to KDE devlopment, make sure to read `how to become a kde developer `_ first. -Getting started +Getting Started --------------- #. Install some tools with your distro's package manager: - * Arch/Antergos/Manjaro: ``sudo pacman -S git`` - * Debian/Ubuntu/Kubuntu/KDE Neon: ``sudo apt install git build-essential`` - * openSUSE: ``sudo zypper install git`` +================================== ================================ +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 requirements.txt ...or in your home directory: .. code-block:: sh pip install -r 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: #. 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 +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 ~~~~~~~~~~~~~~~~~~~~~~~~~ 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 +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 diff --git a/HIG/source/style/color/index.rst b/HIG/source/style/color/index.rst index 7d50236..84b7a1d 100644 --- a/HIG/source/style/color/index.rst +++ b/HIG/source/style/color/index.rst @@ -1,118 +1,116 @@ 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 +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 +.. _PlasmaCore.Theme: https://api.kde.org/frameworks/plasma-framework/html/classPlasma_1_1QuickTheme.html diff --git a/HIG/source/style/elevation.rst b/HIG/source/style/elevation.rst index 3fb5c2d..08d2612 100644 --- a/HIG/source/style/elevation.rst +++ b/HIG/source/style/elevation.rst @@ -1,27 +1,27 @@ Depth, Elevation and Shadows ============================ Athough in recent years "flat" design has taken over the mobile market, KDE has continued to use shadows as a means to provide depth and elevation to elements on the screen. KDE realizes that elevation and depth perception are intrinsic parts of working with computer and mobile interfaces. As you create applications, please be sure to use shadows in the style detailed below. Shadows should be horizontally-centered, but vertically offset, to provide the illusion that a light source is over the top of the screen. This would, in general, follow your eye position relative to the screen you are working on. The default shadow details should be: - Shadow color: Black (``#000000``) - Shadow opacity: 100% - Window shadow size: 48px -- Menu & tooltip shadows size: 20px +- Menu and tooltip shadows size: 20px .. image:: /img/Shadows_with_background.png :alt: Example for a shadows of window and menu -REMINDER: Shadows inside apps should use a size of 20px or below, so as not to -compete with the window shadows. +.. hint:: + Reminder: Shadows inside apps should use a size of 20px or below, so as not to compete with the window shadows. diff --git a/HIG/source/style/icon.rst b/HIG/source/style/icon.rst index adcb40a..f0857ad 100644 --- a/HIG/source/style/icon.rst +++ b/HIG/source/style/icon.rst @@ -1,402 +1,402 @@ Icon Design =========== Purpose ------- Icons are pictorial representations of functions and objects. They convey meaning that users perceive almost instantaneously and are an important part of a program's visual identity. Well-designed icons strongly impact users' overall impression of the design. Consistent use of icons also improves usability by making programs, objects, and actions easier to identify and learn. .. note:: See the `workflow tips on how to create an icon \ `_ if you are interested in designing icons for your application. Or you can ask the `KDE Visual Design Group \ `_ for help. General Guidelines ------------------ - Use icons from the system icon theme whenever possible. Avoid using custom icons. New icons should be added to an icon theme. - Design icons with a small number of metaphors that are understandable - independent of language and culture. Apply metaphors only once (e.g. do not + independent of language and culture. Apply metaphors only once (e.g. don't use a brush twice for different actions). - Simplify, but don't go overboard. Breeze icons are **not** "flat". - Avoid using text in icon designs; it cannot be localized and tends to look bad at small sizes. - Many icons come in multiple sizes. Each version should be visually optimized and pixel-perfect for its particular size. Larger sizes offer more opportunity for detail and visual pizazz, while smaller version should be stripped of everything not absolutely necessary. Monochrome icon style --------------------- .. image:: /img/HIGMonoIcons.png :alt: Monochrome icons Many Breeze icons employ a monochrome art style for their small 16px and 22px versions. This style should be avoided for icons larger than 22px. The monochrome style relies on distinct shapes and outlines instead of fine details and vibrant colors, and employs an intentionally limited color palette: #. |shadeblack| :doc:`Shade Black `: Used for icons in a normal state and non-destructive actions: back, forward, ok, home, etc. This is the most commonly used color. When in doubt, choose Shade Black. #. |iconred| :doc:`Icon Red`: Used for icons that depict actions: delete, remove, stop, etc. #. |bewareorange| :doc:`Beware Orange `: Used for icons that involve user input of some kind. #. |plasmablue| :doc:`Plasma Blue `: Used for icons that involve the action "select" or "insert". #. |iconyellow| :doc:`Icon Yellow `: Used for icons that involve a "warning" state or some sort. #. |noblefir| :doc:`Noble Fir `: Used to for icons that involve "connected", "secure" or "successful" actions. .. |shadeblack| image:: /img/Breeze-shade-black.svg .. |iconred| image:: /img/Breeze-icon-red.svg .. |bewareorange| image:: /img/Breeze-beware-orange.svg .. |plasmablue| image:: /img/Breeze-plasma-blue.svg .. |iconyellow| image:: /img/Breeze-icon-yellow.svg .. |noblefir| image:: /img/Breeze-noble-fir.svg Because monochrome icons are so small and simple, it is important that they be pixel-perfect, with their lines and objects aligned to a regular grid: .. image:: /img/Breeze-icon-design-3.png :alt: Newspaper icon .. image:: /img/Breeze-icon-design-1.png :alt: A pixel-perfect icon on the canvas. .. image:: /img/Breeze-icon-design-2.png :alt: A pixel-perfect icon in the app. *Pixel-perfect icons: On the canvas and in the app* Because monochrome icons usually depict actions, many include status or action emblems. These are always located in the bottom-right corner. The emblem should be a minimum of 5px wide and tall, and there must be 1px of blank space between the emblem and the rest of the icon. .. image:: /img/Breeze-icon-design-8.png :alt: Design for a 22px or 16px icon with an emblem in the bottom-right corner *A perfect monochrome icon with an emblem in the corner* Margins ~~~~~~~ .. image:: /img/icon_margins-monochrome-4x.png :alt: Canvas and graphic sizes :download:`Larger size ` Colorful icon style ------------------- .. image:: /img/Sample_color_icons.png :alt: Colorful icons Colorful Breeze icons make full use the :doc:`Breeze color palette `. They are **not** "flat" and incorporate shadows and smooth linear gradients going from darker on the bottom to lighter on top. Don't be afraid to add detail, vibrancy, and depth! Colorful Breeze icons generally consist of three parts: Background ~~~~~~~~~~ The background is a container and gives structure to the icon. It can have any shape or color in the Breeze color palette. Don't be afraid to get creative with the background shape! .. image:: /img/Breeze-icon-design-creative-backgrounds.png :alt: Creative backgrounds Foreground symbol ~~~~~~~~~~~~~~~~~ The foreground symbol offers contrast with its background and works with it to provide the bulk of the icon's meaning. The foreground symbol is optional; feel free to omit it if the background provides enough meaning on its own. Shadows ~~~~~~~ If present, the foreground symbol casts a long shadow angled 45° towards the bottom-right corner. This shadow always has the same gradient and takes up the whole object. .. image:: /img/Breeze-icon-design-10.png :alt: Using the grid for shadows In addition, colorful icons have a 1 px hard shadow on the bottom: .. image:: /img/Breeze-icon-design-12.png :alt: 48px icons can have more details Margins ~~~~~~~ .. image:: /img/icon_margins-color-4x.png :alt: Canvas and graphic sizes :download:`Larger size ` Application icons ----------------- Application icons come in a single size: 48px. They always use the colorful style. All application icons should have the same height: 40px tall, with four pixels of padding on the top and bottom. When creating a Breeze theme version of an existing app's icon, is critically important that the icon's existing brand and visual style be preserved. The goal is to create a Breeze version of the icon, not something completely new and different. .. image:: /img/Breeze-icon-design-15.png :alt: KDE app icon for Konsole *KDE app icon for Konsole* .. image:: /img/Breeze-icon-design-Kolourpaint.png :alt: KDE app icon for Kolourpaint *KDE app icon for Kolourpaint* .. image:: /img/Breeze-icon-design-11.png :alt: KDE app icon for Discover *KDE app icon for Discover* .. image:: /img/Breeze-icon-design-14.png :alt: 3rd party app icon for VLC *3rd party app icon for VLC* .. image:: /img/Breeze-icon-design-Telegram.png :alt: 3rd party app icon for Telegram *3rd party app icon for Telegram* .. image:: /img/Breeze-icon-design-Virtualbox.png :alt: 3rd party app icon for Virtualbox *3rd party app icon for Virtualbox* Places icons ------------ Places icons come in four sizes: 16px, 22px, 32px, and 64px. They use the colorful style for 32px and 64px sizes and the monochrome style for 22px and 16px sizes. Monochrome Places icons ~~~~~~~~~~~~~~~~~~~~~~~ Places icons are monochrome for their 16px and 22px versions. For these versions, the whole icon depicts the place itself or its typical contents. Beyond that, simply follow the general monochrome icon guidelines for 16px and 22px icons. .. image:: /img/Breeze-icon-design-places-monochrome.png :alt: Small monochrome Places icons *Small monochrome Places icons in Dolphin's Places panel* Colorful places icons ~~~~~~~~~~~~~~~~~~~~~ .. image:: /img/Breeze-icon-design-places.png :alt: Colorful Places icons For the colorful versions, the monochrome icon becomes the foreground symbol on top of a background depicting a folder. The foreground symbol's color is a darkened version of the background folder's color, and can consist of 1px lines, or filled-in areas. The foreground symbol should be centered within the folder background and take up 10x10px for the 32px icon size, and 20x20px for the 64px size. Note that for places icons, the foreground symbol does **not** cast a shadow. .. image:: /img/Breeze-icon-design-places-colorful.png :alt: Large colorful Places icons *20x20px foreground symbol in the center of a 64x64px Places icon* MIME type icons --------------- Like Places icons, MIME type icons come in four sizes: 16px, 22px, 32px, and 64px. They use the colorful style for 32px and 64px sizes, and the monochrome style for 22px and 16px sizes. Monochrome MIME type icons ~~~~~~~~~~~~~~~~~~~~~~~~~~ Like Places icons, the 16px and 22px monochrome versions of MIME type icons have no background image and consist entirely of a monochrome line-art depiction of the file type. .. image:: /img/Breeze-icon-design-19.png :alt: Small monochrome MIME type icon Monochrome MIME type icons are drawn with the primary color of the large colorful version rather than following the general monochrome icon color guidelines. .. image:: /img/Breeze-icon-design-mimetype-small.png :alt: Small monochrome document MIME types *Small MIME type icons use 1 px strokes and follow the colors of the larger versions* Colorful MIME type icons ~~~~~~~~~~~~~~~~~~~~~~~~ Like Places icons, the colorful versions consist of the monochrome icon used as a foreground symbol on top of a background. For archives, packages, compressed files, and disk images, the background is a square with a zipper going halfway down: .. image:: /img/Breeze-icon-design-mimetype-archive.png :alt: Large colorful archive MIME types For images, the background is a horizontal rectangle with the top-right corner folded over, and the fold casts a shadow: .. image:: /img/Breeze-icon-design-mimetype-image.png :alt: Large colorful image MIME types For video files, the background is a horizontal rectangle that looks like a filmstrip: .. image:: /img/Breeze-icon-design-mimetype-video.png :alt: Large colorful video MIME types For audio files, the background is a CD sleeve with a CD partially visible: .. image:: /img/Breeze-icon-design-mimetype-audio.png :alt: Large colorful video MIME types For documents and everything else, the background is a vertical rectangle with the top-right corner folded over, and the fold casts a shadow: .. image:: /img/Breeze-icon-design-mimetype-document.png :alt: Large colorful document MIME types As with the Places icons, the foreground symbol does not cast a shadow. Action and status icons ----------------------- Action and status icons come in two sizes: 16px and 22px. They always use the monochrome style. Action items should use Shade Black as much as possible: .. image:: /img/Breeze-icon-design-action.png :alt: Action icons Status icons can use a bit more color in their composition to connote status information: .. image:: /img/Breeze-icon-design-status.png :alt: Status icons Action and status icons dynamically change their colors when the user changes the system's color. To accomplish this, a special CSS stylesheet is embedded in the SVG, and then the actual shape definitions are tagged with the appropriate class. It looks like this: :: For more technical details, see `this blog post `_. Emblems ------- Emblems come in three sizes: 8px, 16px, and 22px and always use the colorful style. However, their color palette is limited to that of the monochromatic style. Unlike other icons, they are drawn with zero margins and touch the edges of the canvas. Emblem icons always have a colored background shape and a monochrome foreground symbol. Because of the extremely limited space available, it is critical that the foreground symbol be aligned to the pixel grid: .. image:: /img/Breeze-icon-design-emblem.png :alt: Pixel-perfect emblem icon 16px and 22px Emblems get a 60% opacity outline to ensure adequate contrast against whatever icon they are drawn on top of: .. image:: /img/Breeze-icon-design-emblem-16px.png :alt: 16px emblem icons *16px emblems* .. image:: /img/Breeze-icon-design-emblem-22px.png :alt: 22px emblem icons *22px emblems* -8px emblems do not have an outline, because there simply isn't enough room: +8px emblems don't have an outline, because there simply is not enough room: .. image:: /img/Breeze-icon-design-emblem-8px.png :alt: 8px emblem icons *8px emblems* diff --git a/HIG/source/style/imagery.rst b/HIG/source/style/imagery.rst index 4a89988..70fc9d9 100644 --- a/HIG/source/style/imagery.rst +++ b/HIG/source/style/imagery.rst @@ -1,38 +1,38 @@ Imagery ======= Purpose ------- Images can convey meaning and emotion. Preserving these characteristics is the primary focus of this guideline. Guidelines ---------- - Ensure images have the appropriate resolution for their containers. - Do not scale images beyond their native resolution; this will result - will be fuzzy or pixelated losing polish. + Don't scale images beyond their native resolution; they will end up + fuzzy or pixelated. - Don't be afraid of larger image sizes. Images are most effective when they can be seen. Tiny images lose much of their meaning (unless they are specifically crafted for small sizes). - For example, consider a large contact photo (left) instead of a tiny thumbnail image (right). People recognize faces faster than names, therefore, making an image bigger, will connect with the user faster and make it more recognizable. .. image:: /img/ImageSIze1.png :alt: ImageSIze1.png - Captions can be placed on the image (left) instead of outside of the image (right) allowing the image to be larger and the content to be more immersive showing belonging. .. image:: /img/ImageCaption1.png :alt: ImageCaption1.png -- Use a semi-transparent background behind the caption text to preserve +- Use a :doc:`scrim ` behind the caption text to preserve contrast for legibility. - Try to preserve the image aspect ratio. If preserving the aspect ratio is a challenge, consider cropping the image to fill the container instead. diff --git a/HIG/source/style/theme.rst b/HIG/source/style/theme.rst index 5bab77f..470cb42 100644 --- a/HIG/source/style/theme.rst +++ b/HIG/source/style/theme.rst @@ -1,26 +1,28 @@ Theme ===== -Application specific theme +Application-Specific Theme -------------------------- -- Only set a custom color scheme, never set a custom widget theme. -- It's recommended to use the global color theme. +Summary +^^^^^^^ +- Never set a custom widget theme. +- It is recommended to use the global color theme. If your application focuses on visual content, e.g. creating or working with images or videos, you might switch the app to a dark color theme corresponding to the global color theme. e.g. switch from *Breeze* to *Breeze Dark*, but don't switch from "Oxygen" to "Breeze Dark" Provide the option for the user to disable switching to the app specific color theme and use the global color theme instead. You can offer an option for the user to switch to any of the other installed color themes. Place the option to switch theme in Settings > Designs. .. figure:: /img/Switch-theme.jpeg :alt: kritas theme switcher :scale: 50% - Kritas theme switcher. + Krita's theme switcher. diff --git a/HIG/source/style/typography.rst b/HIG/source/style/typography.rst index 3aaec53..c40f153 100644 --- a/HIG/source/style/typography.rst +++ b/HIG/source/style/typography.rst @@ -1,115 +1,137 @@ Typography ========== The guideline helps ensure that typography is always in harmony with the overall visual design. These guidelines apply to application and widgets, but not to documents. It is fine to use a wider range of different font sizes and formatings in documents. Typeface Styles --------------- KDE's default font is *Hack* for monospace and *Noto Sans* for everything else. The default font size is 10pt. KDE Plasma and Applications display seven variants of this typeface. .. figure:: /img/Typography1.png :alt: Show different typefaces in KDE :figclass: border The seven default typeface styles Typeface settings can be adjusted by the user and have :doc:`great influence on sizing and spacing ` in KDE's workspace and applications. +Summary +^^^^^^^ * The monospace typeface should be used for code content, filenames, file paths. * Typography is treated like any other visual element when considering :doc:`spacing ` and :doc:`alignment `. * Multi-line blocks of text should be either left or right aligned; avoid center alignment. * Limit the range of any dynamic type resizing to preserve the intended visual hierarchy. For example, don't resize body text to be bigger than the heading text. Or don't resize the section heading text to fit more words - so that it's smaller than the body text. Or don't resize text of relatively - lesser importance so that it's bigger than text or other visual elements that + so that it is smaller than the body text. Or don't resize text of relatively + lesser importance so that it is bigger than text or other visual elements that should be of relatively greater importance. .. warning:: - |devicon| Never use **Text{}** in Kirigami or Plasma, because it - doesn't follow the system font rendering settings. See :ref:`typography-code` + |devicon| Never use ``Text { }`` in Kirigami or Plasma, because it + does not follow the system font settings. See :ref:`typography-code` for implemntation. .. warning:: |devicon| Never use a hardcoded value of px or pt to define a font size. See the entry about :doc:`units ` for more information. .. hint:: |designicon| The px values are only for design and mockup; don't use them for development. - Header 1: Noto Sans 18px - Header 2: Noto Sans 13px - Header 3: Noto Sans 12px - Header 4: Noto Sans 11px - Body: Noto Sans 10px - Code: Hack 10px - Small: Noto Sans 8px Guidelines ---------- Components ^^^^^^^^^^ Most :doc:`components ` have a recommended typeface style. If you create a new component you should give it the same typeface style as similar existing components. Content ^^^^^^^ You can use any typeface styles to structure your content, but try not to overuse the larger headings. When the visual design calls for an area of exceptional focus, a larger typeface size may be used. In this case use a Light typeface weight to keep the stroke width similar to other styles throughout the interface. All other typeface characteristics for the typographic category should be maintained. For such exceptions to be effective, they must be very rare. +.. container:: flex + + .. container:: + + .. figure:: /img/Typography-Heading-Dont.png + :scale: 80% + + :iconred:`Don't.` |br| + Don't use the same type scale for everything in your application. + + .. container:: + + .. figure:: /img/Typography-Heading-Do.png + :scale: 80% + + :noblefir:`Do.` |br| + Vary the type scale appropriately in your application. + + + Text Color and Contrast ^^^^^^^^^^^^^^^^^^^^^^^ The text :doc:`color <./color/index>` and :doc:`background color <./color/index>` can be varied to provide additional hierarchical hints (e.g. selected text). However, the contrast between the text and background color must be sufficient to preserve legibility of the text. -Words per line +Words per Line ^^^^^^^^^^^^^^ Unless the content is long-form text like a book or a report, try to keep line lengths to no more than about eight to ten words per line. For styles requiring the use of an all-caps typeface, try to keep line lengths to no more than about three to four words per line. .. _typography-code: Code ---- Kirigami ^^^^^^^^ .. literalinclude:: /../../examples/kirigami/Typography.qml :language: qml Plasma ^^^^^^ .. literalinclude:: /../../examples/plasma/Typography.qml :language: qml diff --git a/HIG/source/style/writing/capitalization.rst b/HIG/source/style/writing/capitalization.rst index 57c2dff..037c300 100644 --- a/HIG/source/style/writing/capitalization.rst +++ b/HIG/source/style/writing/capitalization.rst @@ -1,62 +1,62 @@ Capitalization ============== Purpose ------- -*Capitalization* is a feature of case-sensitive languages to foster +Capitalization is a feature of case-sensitive languages to foster relevance by drawing attention to words with capital letters. For a consistent look and feel of the software, it is important to implement capitalization consistently. Guidelines ---------- There are two types of capitalization, title capitalization and sentence style capitalization: Title Capitalization ~~~~~~~~~~~~~~~~~~~~ Title capitalization is when every word in a sentence, statement, phrase, or label is capitalized except for certain words. Use title capitalization primarily for titles and headers, but also for command labels. For example: - Titles and headers on windows, dialog boxes, tabs, lists, group boxes, tree views, etc. - Menu titles and menu item labels - Button labels -Do not capitalize: +Don't capitalize: - Articles: a, an, the - Coordinating conjunctions: and, but, or, for, nor, etc. - Prepositions (fewer than five letters): on, at, to, from, by, etc. Capitalize everything else. Sentence Style Capitalization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sentence style capitalization is when the first letter of the sentence, statement, phrase, or label is capitalized and all other words are lower case. The only exception to this is proper nouns which are always capitalized. Use sentence style capitalization for text that is or could be read as a sentence, or that is part of a sentence in conjunction with other elements. For example: - Tooltip text - Placeholder text in text fields - Checkbox labels - Labels to the left of controls in a Form Layout - Descriptions of anything Acronyms/Initialisms, Internet ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Words such as URL, JPEG, or LDAP should be written in capital letters - Internet (if referring to *the* Internet) takes a capital I. diff --git a/HIG/source/style/writing/labels.rst b/HIG/source/style/writing/labels.rst index 5a6363d..84b2bb9 100644 --- a/HIG/source/style/writing/labels.rst +++ b/HIG/source/style/writing/labels.rst @@ -1,128 +1,128 @@ Labels ====== Purpose ------- Common controls should behave ‘common’ and look like everyday controls. Therefore, it is much recommended to use standard font. Bold or italic font should not be applied to control labels. Guidelines ---------- - Keep labels short; be aware that :doc:`translated ` English text can expand up to 30% in some languages. -- Do not shorten your labels to the point of losing meaning. However, a +- Don't shorten your labels to the point of losing meaning. However, a three-word label that provides clear information is better than a one-word label that is ambiguous or vague. Try to find the fewest possible words to satisfactorily convey the meaning of your label. - When the label is associated with another control, like a line edit, be sure to set the the line edit as the `buddy `_ of the label. Dialogs ~~~~~~~ - If a dialog is user-initiated, identify it using the command or feature name. - If it is application- or system-initiated (and therefore out of context), label it using the program or feature name to provide context. -- Do not use the title to explain what to do in the dialog – that's the +- Don't use the title to explain what to do in the dialog – that is the purpose of the main instruction. Menus ~~~~~ - Prefer verb-based names; Avoid generic, unhelpful verbs, such as *Change* or *Manage*. - Use singular nouns for commands that apply to a single object, otherwise use plural nouns. - For pairs of complementary commands, choose clearly complementary names. Examples: *Add/Remove*, *Show/Hide*, or *Insert/Delete*. - Choose menu item names based on user goals and tasks, not on technology. - Assign access keys to all menu items (Alt+Letter). Buttons ~~~~~~~ - Label command buttons with an imperative verb. -- Do not use ending punctuation for labels. +- Don't use ending punctuation for labels. - Describe the action that the button performs in a tooltip. - End the label with an ellipsis if the command requires additional information to execute. - Assign access keys to all buttons (Alt+Letter). Links ~~~~~ - Choose a concise, self-explanatory label that clearly communicates and differentiates what the command link does. -- Do not use ellipses. +- Don't use ellipses. Tabs ~~~~ - Label tabs based on their pattern. Use nouns rather than verbs, without ending punctuation. -- Do not assign an access key. Tabs are accessible through their +- Don't assign an access key. Tabs are accessible through their shortcut keys (Ctrl+Tab, Ctrl+Shift+Tab). Checkboxes and Radio buttons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Label every checkbox or radio button. Do not leave checkboxes or +- Label every checkbox or radio button. Don't leave checkboxes or radio buttons unlabeled. - Assign a unique access key to each label. - Labels must start with an active verb clearly defining the state to be enabled or disabled. - For a group, use parallel phrasing and try to keep the length about the same for all labels. - For a group, focus the label text on the differences among the options. -- Use affirmative phrases. Do not use negative phrases such as "Don't - enable wifi". Use rather "Enable wifi". -- Describe just the option with the label. Keep labels brief so it's +- Use affirmative phrases. Don't use negative phrases such as "Don't + enable wifi". Instead, write "Enable Wifi". +- Describe just the option with the label. Keep labels brief so it is easy to refer to them in messages and documentation. Group box ~~~~~~~~~ - Use group labels to explain the purpose of the group, not how to make the selection. - End each label with a colon to show a relationship. -- Do not assign an access key to the label. +- Don't assign an access key to the label. - For a selection of one or more dependent choices, explain the requirement on the label. Using Ellipses in Labels ~~~~~~~~~~~~~~~~~~~~~~~~ Ellipses are used to indicate that a button or menu item will perform an action that always requires additional user input before completing. Use an ellipsis at the end of a menu item or button's label only when the following circumstances apply: - The menu item or button must perform an action. Actions always begin with a verb, (e.g. "Show", "Configure", "Adjust") and have a definite start and end - That action must always require additional user input to complete Here are examples of menu items and buttons whose labels typically have ellipses: - Find... - Find and Replace... - Open... - Print... - Replace... - Save As... - Send To... - Configure [something]... -Here are examples of menu items and buttons whose labels typically do not have ellipses, along with the reason why: +Here are examples of menu items and buttons whose labels typically don't have ellipses, along with the reason why: - About — *not an action* - Advanced Options — *not an action* - Close or Quit — *action does not always require additional user input* - Delete or Remove — *action does not always require additional user input* - Help — *not an action* - Print Preview — *not an action* - Properties — *not an action* - Toolboxes — *not an action* diff --git a/HIG/source/style/writing/localization.rst b/HIG/source/style/writing/localization.rst index 49e2739..0eb8e42 100644 --- a/HIG/source/style/writing/localization.rst +++ b/HIG/source/style/writing/localization.rst @@ -1,29 +1,27 @@ Localization ============ Purpose ------- KDE address a world wide audience and is therefore fully localized. Localization means to adopt language, text layout, numerals as well as cultural aspects and regulatory compliance. Guidelines ---------- - Provide bidirectional mode dependent to language (left-to-right vs. right-to-left). - Make sure your GUI displays correctly in languages written from right-to-left -- Allow translation with - [http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#Plural-forms\ \| - multiple plural forms]. +- Allow translation with `multiple plural forms `_. - Design GUI with enough room for long captions. - Respect system-wide locale settings (unit systems, date and time format, currencies etc.). - Take cultural comprehension of icons (Red Cross vs. Red Crescent) into account. -- Do not localize standard `short-cuts`_. +- Don't localize standard `short-cuts`_. - Be aware of intercultural (mis-)comprehension of acronyms. .. _short-cuts: KDE_Visual_Design_Group/HIG/Keyboard_Shortcuts diff --git a/HIG/source/style/writing/placeholder.rst b/HIG/source/style/writing/placeholder.rst index 3a3bcbc..2ce1395 100644 --- a/HIG/source/style/writing/placeholder.rst +++ b/HIG/source/style/writing/placeholder.rst @@ -1,39 +1,39 @@ Placeholder =========== Purpose ------- A placeholder can be shown on an input element that expects text input. It can either contain an example of the expected format, or a hint about the action that will be triggered when the user types in the input element. Guidelines ---------- Example ~~~~~~~ - A placeholder with an example is not a replacement for a label, but should give the user only an additional hint about what kind of data is expected. .. image:: /img/Placeholder-1.png :alt: Placeholders showing an example of what to enter in fields Actions ~~~~~~~ - A placeholder with an action replaces the label. - Use an ellipsis (...) after the text. - Show visiual feedback as soon as the user types, e.g. trigger the action or show a menu with autocompletion suggestions. - Keep the text as short as possible. -- Since the placeholder won't be visible anymore as soon as the user types, +- Since the placeholder will not be visible anymore as soon as the user types, you should only use it on standalone input elements, not in groups of input elements such as forms. - Use :doc:`sentence style capitalization `. .. figure:: /img/Krunner-1.png :alt: Krunner showing a placeholder instead of a label with an action. Krunner showing a placeholder instead of a label with an action. diff --git a/HIG/source/style/writing/static.rst b/HIG/source/style/writing/static.rst index a7c89d8..1a021de 100644 --- a/HIG/source/style/writing/static.rst +++ b/HIG/source/style/writing/static.rst @@ -1,24 +1,24 @@ -Static text +Static Text =========== Users tend to read only interactive control labels, especially those that appear relevant to completing the task at hand. By contrast, users -read *static text* when they think they need to. +read static text when they think they need to. Guidelines ---------- - Use the inverted pyramid for text. Start with the the conclusion and the fundamental "takeaway" that readers must have. Then fill in progressively more detail that readers may be interested in - perhaps just to scan. - Remove redundant text. Leave full text in main instructions and interactive controls, and remove any redundancy from the other places. - Avoid large blocks of UI text by chunking text into shorter sentences and paragraphs or providing help links to useful, but not essential, information. - Use bold font sparingly to draw attention to text users must read. A different font, e.g. bold or italic, can be used to attract attention when changes to UI design are not applicable or not efficient enough. diff --git a/HIG/source/style/writing/wording.rst b/HIG/source/style/writing/wording.rst index 986b0ff..513d779 100644 --- a/HIG/source/style/writing/wording.rst +++ b/HIG/source/style/writing/wording.rst @@ -1,33 +1,33 @@ Wording ======= Purpose ------- Every word displayed in an application is part of a conversation with users. This conversation is an opportunity to provide clarity and to help people feel comfortable in the system. Guidelines ---------- - Use terminology that is familiar and easy to understand for the target audience (i.e. Persona) of your application. - Start your sentence with the most important objective first. - Use short words, active verbs and common nouns. - Avoid :doc:`contraction` such as "Don't", "Won't", etc. - Avoid abbreviations (including ampersand instead of 'and'), acronyms, and tech-babble. - Use an informal and friendly tone, but not too informal or humorous. - Avoid popular, but transient, words and phrases. - Keep information short and consistent; avoid redundancy or wordiness. - e.g. Do not repeat the dialog title in the dialog text. + e.g. Don't repeat the dialog title in the dialog text. - Don't abuse :doc:`capitalization` because it draws people’s attention. - For date and time information, consider that your app may potentially - be used for several years; do not use immutable date references like + be used for several years; don't use immutable date references like *this year* unless it is algorithmically determined. - Follow system-wide wording conventions for basic functions to keep wording consistent. - In general, exclamation points should be used sparingly in user-interface strings. In particular, they should not be used for error messages, to avoid an effect upon the user similar to WRITING IN ALL-CAPS. diff --git a/Kirigami/source/style/color.rst b/Kirigami/source/style/color.rst index 0d72e21..2b070e5 100644 --- a/Kirigami/source/style/color.rst +++ b/Kirigami/source/style/color.rst @@ -1,105 +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. +on the platform it is running on (i.e. Plasma Desktop, Plasma Mobile, +GNOME, Android, etc.). 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 +avoided; if it is 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 chrome such as toolbars or dialogs), for instance +an hardcoded "black" foreground cannot 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 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 +wants to force a specific color set) so it is 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: .. 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: .. literalinclude:: /../../examples/kirigami/InheritTheme.qml :language: qml .. TODO:: screenshot of a comparison between a button that inherits and one - that doesn't + that does not 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: .. literalinclude:: /../../examples/kirigami/CustomColors.qml :language: qml .. TODO:: Screenshot diff --git a/examples/kirigami/CustomColors.qml b/examples/kirigami/CustomColors.qml index 9427dea..5aa0bed 100644 --- a/examples/kirigami/CustomColors.qml +++ b/examples/kirigami/CustomColors.qml @@ -1,22 +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 + // NOTE: regardless of the color set used, it is 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/UseColorsets.qml b/examples/kirigami/UseColorsets.qml index eba51ff..552922a 100644 --- a/examples/kirigami/UseColorsets.qml +++ b/examples/kirigami/UseColorsets.qml @@ -1,59 +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 + // Do not 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 + // Do not 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") } } } }