diff --git a/source/components/checkbox.rst b/source/components/checkbox.rst index 2010412..154e9a1 100644 --- a/source/components/checkbox.rst +++ b/source/components/checkbox.rst @@ -1,198 +1,198 @@ -Check box -========= +Checkbox +======== Purpose ------- -A *check box* is a control that permits the user to make multiple -selections from a number of options. Check boxes are used to toggle an +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 ~~~~~~~~~~~~~~~~~~~~~~~~~ -- Use check boxes for non-exclusive options that have clear +- 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 check box if the opposite is ambiguous. + Do not 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. - 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. .. container:: flex .. container:: .. figure:: /img/No_Command_2_Bad.qml.png :figclass: border :iconred:`BAD` |br| Do not use the selection to perform commands. .. container:: .. figure:: /img/No_Command_2_Good.qml.png :figclass: border :noblefir:`GOOD` |br| Consider using a :doc:`push button ` instead. Behavior ~~~~~~~~ -- Checking a check box should always "enable" an option or change the +- 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` .. container:: .. figure:: /img/Checkbox_Enable_Good.qml.png :figclass: border :noblefir:`GOOD` - 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 check box enables all child objects. +- Clicking a mixed state checkbox enables all child objects. - Do not 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` .. container:: .. figure:: /img/Checkbox_Switch_Mobile.qml.png :noblefir:`GOOD` 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. -- The text of a check box is on the right of its tick rectangle, which +- 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 check boxes together in the widget column and add a label + - 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 check box (e.g. Audio level can +- 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 check box, indent the + - 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 check box that is placed right to its label, - indent the sub-options in the same vertical axis as the check box. + - 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 check box (group). -- Align check boxes vertically rather than horizontally, as this makes + 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 check box is checked (i.e. they are dependent controls), - disable them instead of hiding them if that check box is unchecked. + certain checkbox is checked (i.e. they are dependent controls), + disable them instead of hiding them if that checkbox is unchecked. -- Do not separate check box and label. Clicking on both the box and the +- Do not separate checkbox and label. Clicking on both the box and the label should toggle the option. .. image:: /img/HIG_Checkbox5.png - :alt: Separate check box and label + :alt: Separate checkbox and label - Do not add line breaks. If necessary place an additional label below - the check box. + the checkbox. .. container:: flex .. container:: .. figure:: /img/Checkbox_Alignment_Bad.qml.png :iconred:`BAD` .. container:: .. figure:: /img/Checkbox_Alignment_Good.qml.png :noblefir:`GOOD` -- Label a group of check box with a descriptive caption to the top left +- 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 check box items. +- Use :doc:`sentence style capitalization ` + for checkbox items. - Do not use ending punctuation (neither dot nor colon) for group label. diff --git a/source/components/combobox.rst b/source/components/combobox.rst index 3180eb2..d1f30ed 100644 --- a/source/components/combobox.rst +++ b/source/components/combobox.rst @@ -1,80 +1,80 @@ 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 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 (like print, send, delete) when the user selects an item from the list. -- Do not add controls to the drop-down (e.g. check boxes for each +- Do not 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 Appearance ~~~~~~~~~~ - Combo boxes are distinguished visually from drop-down lists (normally by the raised or lowered bevel). Do not 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. diff --git a/source/components/dropdown.rst b/source/components/dropdown.rst index a3b8528..edac0f0 100644 --- a/source/components/dropdown.rst +++ b/source/components/dropdown.rst @@ -1,87 +1,87 @@ 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 (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. check boxes for each +- Do not 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 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. diff --git a/source/components/lineedit.rst b/source/components/lineedit.rst index 228e63d..4fa4a9a 100644 --- a/source/components/lineedit.rst +++ b/source/components/lineedit.rst @@ -1,67 +1,67 @@ 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 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 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" check box to unmask the password both + - 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 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/source/components/radiobutton.rst b/source/components/radiobutton.rst index d7438d6..7dff37c 100644 --- a/source/components/radiobutton.rst +++ b/source/components/radiobutton.rst @@ -1,179 +1,179 @@ Radio button ============ Purpose ------- *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 ~~~~~~~~~~~~~~~~~~~~~~~~~ - 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` .. container:: .. figure:: /img/Radiobutton_Many_Good.qml.png :figclass: border :noblefir:`GOOD` - 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 - buttons by one :doc:`check box `. + buttons by one :doc:`checkbox `. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Negation_Bad.qml.png :figclass: border :iconred:`BAD` .. container:: .. figure:: /img/Radiobutton_Negation_Good.qml.png :figclass: border :noblefir:`GOOD` - 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` .. container:: .. figure:: /img/Radiobutton_Visible_Good.qml.png :figclass: border :noblefir:`GOOD` - Do not use a radio button to initiate an action. Consider using a :doc:`push button ` instead. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Command_Bad.qml.png :figclass: border :iconred:`BAD` |br| Do not use the selection to perform commands. .. container:: .. figure:: /img/No_Command_2_Good.qml.png :figclass: border :noblefir:`GOOD` |br| Consider using a :doc:`push button `. 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` .. container:: .. figure:: /img/Radiobutton_Default_Good.qml.png :figclass: border :noblefir:`GOOD` - Make the first item the default option. .. container:: flex .. container:: .. figure:: /img/Radiobutton_First_Bad.qml.png :figclass: border :iconred:`BAD` .. container:: .. figure:: /img/Radiobutton_First_Good.qml.png :figclass: border :noblefir:`GOOD` - 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. - 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 and the label should toggle the option. - Do not add line breaks. If necessary place an additional label below - the check box. + 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 label. diff --git a/source/components/togglebutton.rst b/source/components/togglebutton.rst index 5ff4dd5..d97d44a 100644 --- a/source/components/togglebutton.rst +++ b/source/components/togglebutton.rst @@ -1,53 +1,53 @@ 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 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 check box they +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 ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a toggle button to indicate a state if no other control apply, i.e. in case of the :doc:`toolbar `. -- Prefer :doc:`radio buttons ` or :doc:`check boxes ` +- 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. 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/source/components/tree.rst b/source/components/tree.rst index 412203d..4e9bfe4 100644 --- a/source/components/tree.rst +++ b/source/components/tree.rst @@ -1,91 +1,91 @@ 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. Guidelines ---------- Ask yourself "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 check boxes to indicate multiple selections. -- For check boxes, use the mixed state to indicate that an option is +- 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:`check boxes `). -- Clicking a mixed state check box selects all child objects and the - parent check box. -- Don’t use check boxes in single selection trees. + 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/source/layout/alignment.rst b/source/layout/alignment.rst index 63baed0..5391b76 100644 --- a/source/layout/alignment.rst +++ b/source/layout/alignment.rst @@ -1,131 +1,131 @@ Alignment ========= Purpose ------- One of the most important aspects of presentation is *alignment* and *placement* of controls. 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 controls should be carefully done according to Gestalt theory. Guidelines ---------- Labels on the left ~~~~~~~~~~~~~~~~~~ On |desktopicon| Desktop it is recomended to place the labels to the left of the connected widgets. .. container:: flex .. container:: .. figure:: /img/Form_Align_KDE3.qml.png :scale: 80% :iconred:`BAD` |br| KDE3 form alignment .. container:: .. figure:: /img/Form_Align_KDE5.qml.png :scale: 80% :noblefir:`GOOD` |br| Plasma 5 form alignment - The labels that are to the left of their connected widgets should be right-aligned. This makes the whole group of form widgets appear to be center-aligned. In Qt5, using a QFormLayout handles this correctly for you. Controls ~~~~~~~~ - Align groups of items 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. - Align a group of widgets to the left. This makes use of space more efficiently. .. container:: flex .. container:: .. figure:: /img/Form_Align_OSX.qml.png :scale: 80% :iconred:`BAD` |br| OSX form alignment .. container:: .. figure:: /img/Form_Align_KDE5.qml.png :scale: 80% :noblefir:`GOOD` |br| Plasma 5 form alignment - Left align controls over multiple groups (in case of right-to-left languages mirror the alignment). The 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 .. container:: .. figure:: /img/Form_Align_YES.qml.png :scale: 80% :noblefir:`GOOD` |br| left aligned controls - Keep track on label size; avoid big differences in text length (even after translation), that could result in much whitespace for multiple aligned controls. .. figure:: /img/Form_Align_Long.qml.png :scale: 80% :iconred:`BAD` |br| Avoid very long captions Labels on top ~~~~~~~~~~~~~ For |mobileicon| mobile, or if only narrow space is available, it is recomended to place the labels above the connected widgets. .. image:: /img/Form_Align_YES_Mobile.qml.png :scale: 80% - Labels and widgets align left - Minimize label length. Avoid multi-line labels. -Check boxes and Radio buttons +Checkboxes and Radio buttons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For more details on alignment of :doc:`radio buttons ` and :doc:`checkboxes `, see the detailed HIG pages. diff --git a/source/layout/metrics.rst b/source/layout/metrics.rst index 4079a5c..dead397 100644 --- a/source/layout/metrics.rst +++ b/source/layout/metrics.rst @@ -1,133 +1,133 @@ 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. 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. 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 design which enables the objects in it to exist at all. The balance 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) - - Check box, Radio button including label: ≥80 x 24 px + - 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 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. Space ~~~~~ Qt widgets ^^^^^^^^^^ 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. QML ^^^ For consistency you should try to use Kirigami and Plasma's 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. .. figure:: /img/Margin.qml.png :alt: Use of base units Use of base units Recommended minimum paddings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 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 (check boxes / radio buttons): smallSpacing - - related controls with different type (check box / button): 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 grid. Resize ~~~~~~ - 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. .. figure:: /img/Resize.qml.png :alt: Give hints how to resize Give hints how to resize diff --git a/source/style/writing/capitalization.rst b/source/style/writing/capitalization.rst index eb528cc..a15d7b8 100644 --- a/source/style/writing/capitalization.rst +++ b/source/style/writing/capitalization.rst @@ -1,82 +1,82 @@ Capitalization ============== Purpose ------- *Capitalization* is a feature of case-sensitive languages to foster relevance. In terms of software it draws attention to words with capital letters. For a consistent look and feel of the software it is important to implement capitalization consistently. On the other hand, capitalization slows down translation and increases the risk of inconsistent terminology. 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 are capitalized except for certain words. Words with less than five letters are generally lowercase in titles, unless they are the first or last words in a title. Do not capitalize: - Articles: a, an, the - Coordinating Conjunctions: and, but, or, for, nor, etc. - Prepositions (fewer than five letters): on, at, to, from, by, etc. Always capitalize - Nouns (man, bus, book) - Adjectives (angry, lovely, small) - Verbs (run, eat, sleep) - Adverbs (slowly, quickly, quietly) - Pronouns (he, she, it) - Subordinating conjunctions (as, because, that) Use title capitalization in the following cases: - Window and dialog box titles - Group box / group line labels - Button labels - Tab labels - Listview column headers - Menu titles / menu items - Derivatives of KCommand - Combobox items - Listbox items - Tree list items - Other heading/title text 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 in the following cases: - Edit box labels - List box labels - Combo box labels - Spin box labels -- Check box labels +- Checkbox labels - Option button labels - Slider labels - Pop-up hint text - Dialog header/description - Other non heading/title text 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/source/style/writing/labels.rst b/source/style/writing/labels.rst index 9091cd5..f9796c7 100644 --- a/source/style/writing/labels.rst +++ b/source/style/writing/labels.rst @@ -1,136 +1,136 @@ Lables ====== 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 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 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. - 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. 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 shortcut keys (Ctrl+Tab, Ctrl+Shift+Tab). -Check boxes and Radio buttons +Checkboxes and Radio buttons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Label every check box or radio button. Do not leave check boxes or +- Label every checkbox or radio button. Do not 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 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. - For a selection of one or more dependent choices, explain the requirement on the label. Using Ellipses in Labels ~~~~~~~~~~~~~~~~~~~~~~~~ - Use an ellipsis (...) after menu items and button labels which require user’s input before completing their action. - Do not use an ellipsis if no further user input is required to complete the action - Do not use an ellipsis for selections which result in actions (such as Save or Print Preview) or do not require user input (such as configuration dialogs). - Do not use an ellipsis for an action which may require confirmation before it is completed (such as a Deletion confirmation), but no other input. - Use an ellipsis for the following menu items and buttons: - Find... - Find and Replace... - Open... - Print... - Replace... - Save As... - Send To... - Do not use an ellipsis for the following menu items and buttons: - About - Advanced Options - Check Spelling - Close or Quit - Configure [something] - Delete or Remove - Help - Preferences - Print Preview - Properties - Toolboxes