diff --git a/source/components/assistance/index.rst b/source/components/assistance/index.rst new file mode 100644 index 0000000..2466819 --- /dev/null +++ b/source/components/assistance/index.rst @@ -0,0 +1,31 @@ +User assistance +=============== + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :hidden: + + 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:`inline` +* :doc:`message` +* :doc:`progress` +* :doc:`statusbar` + +Help +~~~~ + +* :doc:`tooltip` diff --git a/source/components/inline.rst b/source/components/assistance/inline.rst similarity index 98% rename from source/components/inline.rst rename to source/components/assistance/inline.rst index a50e4ed..ef849ba 100644 --- a/source/components/inline.rst +++ b/source/components/assistance/inline.rst @@ -1,139 +1,139 @@ Inline message ============== Purpose ------- A *inline message* is a small pop-up panel shown at top of the current form that informs users of a non-critical problem or special condition. The panel shows information on four levels indicated by different colors and icons, and provides standard action that users might want to initiate. .. figure:: /img/Message5.qml.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 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 any other side effect. - Do not 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 ~~~~~~~~~~~~~~~~~ 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 message panel only closes when the problem it informs about (e.g. the error) is fixed. Positive feedback ~~~~~~~~~~~~~~~~~ An inline message can be used for positive feedback but it shouldn't 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 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 `. +close button and :doc:`buttons <../navigation/pushbutton>`. .. figure:: /img/Message1.qml.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.qml.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.qml.png :alt: Inline message with overflow menu. :scale: 80% Inline message with overflow menu. diff --git a/source/components/message.rst b/source/components/assistance/message.rst similarity index 98% rename from source/components/message.rst rename to source/components/assistance/message.rst index 1a6a12d..0ff4ab8 100644 --- a/source/components/message.rst +++ b/source/components/assistance/message.rst @@ -1,108 +1,108 @@ Message ======= Purpose ------- If the processing has reached an unexpected condition that needs interaction, a disruptive message alerts the user of a problem. Not any disruptive message concerns a serious problem. Sometimes, the user is just notified that proceeding is dangerous. A typical example is the “Save changes before closing?” alert box that appears when a user tries to close a module with modified content. The adequate presentation method for disruptive information is a *modal message dialog*. A modal dialog is a secondary window that interrupts user's current activity and blocks interaction until user either simply acknowledge the information by clicking Ok or decides how to proceed (e.g. Yes/No). Effective error messages inform users that a problem occurred, explain why it happened, and provide a solution so users can fix the problem. Users should either perform an action or change their behavior as the result of an error message. Modal dialogs are error-prone. An alert dialog that appears unexpectedly or which is dismissed automatically (because the user has developed a habit) will not protect from the dangerous action. Examples -------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Avoid disruptive messages; workflow maintenance and, therefore, the prevention of errors should be the primary objective. - Use modal dialogs only for critical or infrequent, one-off tasks that require completion before continuing. Don’t use modal error message dialogs at the normal work flow to inform or warn the user. - Use an :doc:`inline message ` for non-critical messages which do not require any further user interaction (typically dialogs with a single "OK" or "Close" button). - Create specific, actionable, user-centered error messages. Users should either perform an action or change their behavior as the result of the message. - Provide only a short error message and complement it by a Details button that provides more a detailed explanation in the same error dialog. -- Follow the guidelines of :doc:`dialogs ` in general. +- Follow the guidelines of :doc:`dialogs <../navigation/dialog>` in general. Behavior ~~~~~~~~ Messages should be: - Informative and constructive: - Tell the user the reason for a problem and - help on how to solve the problem. - Understandable: - Phrase your messages clearly, in non-technical terms and avoid obscure error codes. - Readable: - User has to be able to read the message in his/her own pace, think about it, understand it. - It is not acceptable to add countdown timers (visible or not) or to force user to read and understand the message within a few seconds. - Specific instead of general: - If the message is reporting a problem concerning a specific object or application, use the object or application name when referring to it. - Polite, non-terrifying and non-blaming: - Avoid wording that terrifies the user ("fatal", "illegal"), blames him for his behavior, and be polite. Appearance ~~~~~~~~~~ - Apply confirmation button labels when no further input is required: - To close a warning or error message that does not require further user interaction, provide a Close button. Do not use an OK button. Users may get confused if they are asked to confirm an error. - Apply confirmation button labels when further interaction is required: - Use buttons which match the type of statement or question made in the warning or error message. For example, do no ask a Yes/No question but then provide OK/Cancel buttons. - Apply confirmation button labels when the user must choose between two actions to continue: - Use descriptive button labels instead of standard Yes/No or OK/Cancel buttons. For example, if the user must choose to continue or stop an action, provide the buttons "Continue" and "Cancel". diff --git a/source/components/progress.rst b/source/components/assistance/progress.rst similarity index 100% rename from source/components/progress.rst rename to source/components/assistance/progress.rst diff --git a/source/components/statusbar.rst b/source/components/assistance/statusbar.rst similarity index 94% rename from source/components/statusbar.rst rename to source/components/assistance/statusbar.rst index 6d25fd6..f183d1a 100644 --- a/source/components/statusbar.rst +++ b/source/components/assistance/statusbar.rst @@ -1,44 +1,44 @@ Status bars =========== Purpose ------- 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ - Omit the status bar in the main window to maximize vertical space for content. - Do not 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. - If a status bar is really necessary in your application consider to - use a :doc:`toolbar ` with all customization features. + use a :doc:`toolbar <../navigation/toolbar>` with all customization features. Behavior ~~~~~~~~ - Do not 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 advisory messages in place of standard :doc:`tooltips `. - Keep the status information plain; e.g. do not add icons. .. for more info see http://user-prompt.com/what-is-a-status-bar-good-for/ diff --git a/source/components/tooltip.rst b/source/components/assistance/tooltip.rst similarity index 100% rename from source/components/tooltip.rst rename to source/components/assistance/tooltip.rst diff --git a/source/components/checkbox.rst b/source/components/editing/checkbox.rst similarity index 96% rename from source/components/checkbox.rst rename to source/components/editing/checkbox.rst index 154e9a1..18e4427 100644 --- a/source/components/checkbox.rst +++ b/source/components/editing/checkbox.rst @@ -1,198 +1,199 @@ Checkbox ======== Purpose ------- 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 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. .. 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. +- 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. + 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` .. 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 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 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 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 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 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. diff --git a/source/components/combobox.rst b/source/components/editing/combobox.rst similarity index 100% rename from source/components/combobox.rst rename to source/components/editing/combobox.rst diff --git a/source/components/date.rst b/source/components/editing/date.rst similarity index 100% rename from source/components/date.rst rename to source/components/editing/date.rst diff --git a/source/components/dropdown.rst b/source/components/editing/dropdown.rst similarity index 100% rename from source/components/dropdown.rst rename to source/components/editing/dropdown.rst diff --git a/source/components/grid.rst b/source/components/editing/grid.rst similarity index 100% rename from source/components/grid.rst rename to source/components/editing/grid.rst diff --git a/source/components/editing/index.rst b/source/components/editing/index.rst new file mode 100644 index 0000000..d613936 --- /dev/null +++ b/source/components/editing/index.rst @@ -0,0 +1,51 @@ +Editing and manipulation +======================== + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :hidden: + + checkbox + combobox + date + dropdown + grid + lineedit + list + radiobutton + slider + spinbox + swipelistitem + 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:`checkbox` +* :doc:`combobox` +* :doc:`dropdown` +* :doc:`grid` +* :doc:`list` +* :doc:`radiobutton` +* :doc:`swipelistitem` +* :doc:`togglebutton` +* :doc:`tree` + +Unconstrained input +~~~~~~~~~~~~~~~~~~~ + +* :doc:`lineedit` +* :doc:`tableview` +* :doc:`textedit` + +Constrained input +~~~~~~~~~~~~~~~~~ +* :doc:`date` +* :doc:`slider` +* :doc:`spinbox` diff --git a/source/components/lineedit.rst b/source/components/editing/lineedit.rst similarity index 100% rename from source/components/lineedit.rst rename to source/components/editing/lineedit.rst diff --git a/source/components/list.rst b/source/components/editing/list.rst similarity index 96% rename from source/components/list.rst rename to source/components/editing/list.rst index 228b769..abb4ad6 100644 --- a/source/components/list.rst +++ b/source/components/editing/list.rst @@ -1,76 +1,77 @@ List View ========= Purpose ------- 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 - Do *not* 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 ` if multiple items + respectively. Instead, use the + :doc:`dual-list 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. (Once the list view is being revised this guideline is subject of change.) Behavior ~~~~~~~~ - Do not 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. - For lists with more than one column, use headers and allow sorting. Show these controls in the header. 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. diff --git a/source/components/radiobutton.rst b/source/components/editing/radiobutton.rst similarity index 97% rename from source/components/radiobutton.rst rename to source/components/editing/radiobutton.rst index 7dff37c..aa39d1e 100644 --- a/source/components/radiobutton.rst +++ b/source/components/editing/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:`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. + :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. .. container:: .. figure:: /img/No_Command_2_Good.qml.png :figclass: border :noblefir:`GOOD` |br| - Consider using a :doc:`push button `. + 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` .. 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 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/slider.rst b/source/components/editing/slider.rst similarity index 100% rename from source/components/slider.rst rename to source/components/editing/slider.rst diff --git a/source/components/spinbox.rst b/source/components/editing/spinbox.rst similarity index 100% rename from source/components/spinbox.rst rename to source/components/editing/spinbox.rst diff --git a/source/components/swipelistitem.rst b/source/components/editing/swipelistitem.rst similarity index 100% rename from source/components/swipelistitem.rst rename to source/components/editing/swipelistitem.rst diff --git a/source/components/tableview.rst b/source/components/editing/tableview.rst similarity index 100% rename from source/components/tableview.rst rename to source/components/editing/tableview.rst diff --git a/source/components/textedit.rst b/source/components/editing/textedit.rst similarity index 100% rename from source/components/textedit.rst rename to source/components/editing/textedit.rst diff --git a/source/components/togglebutton.rst b/source/components/editing/togglebutton.rst similarity index 95% rename from source/components/togglebutton.rst rename to source/components/editing/togglebutton.rst index d97d44a..2808aa4 100644 --- a/source/components/togglebutton.rst +++ b/source/components/editing/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 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 `. + 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. 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/editing/tree.rst similarity index 100% rename from source/components/tree.rst rename to source/components/editing/tree.rst diff --git a/source/components/groupbox.rst b/source/components/formating/groupbox.rst similarity index 100% rename from source/components/groupbox.rst rename to source/components/formating/groupbox.rst diff --git a/source/components/formating/index.rst b/source/components/formating/index.rst new file mode 100644 index 0000000..eb6c047 --- /dev/null +++ b/source/components/formating/index.rst @@ -0,0 +1,13 @@ +Formating +========= + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :hidden: + + groupbox + splitter + +* :doc:`groupbox` +* :doc:`splitter` diff --git a/source/components/splitter.rst b/source/components/formating/splitter.rst similarity index 100% rename from source/components/splitter.rst rename to source/components/formating/splitter.rst diff --git a/source/components/index.rst b/source/components/index.rst index f26a435..d2d1347 100644 --- a/source/components/index.rst +++ b/source/components/index.rst @@ -1,73 +1,80 @@ Components ========== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: - actionbutton - checkbox - combobox - commandlink - contextdrawer - contextmenu - date - dialog - dropdown - globaldrawer - grid - groupbox - inline - lineedit - list - menubar - message - progress - pushbutton - radiobutton - slider - spinbox - splitter - statusbar - swipelistitem - tab - tableview - textedit - togglebutton - toolbar - tooltip - tree - -* :doc:`actionbutton` -* :doc:`checkbox` -* :doc:`combobox` -* :doc:`commandlink` -* :doc:`contextdrawer` -* :doc:`contextmenu` -* :doc:`date` -* :doc:`dialog` -* :doc:`dropdown` -* :doc:`globaldrawer` -* :doc:`grid` -* :doc:`groupbox` -* :doc:`inline` -* :doc:`lineedit` -* :doc:`list` -* :doc:`menubar` -* :doc:`message` -* :doc:`progress` -* :doc:`pushbutton` -* :doc:`radiobutton` -* :doc:`slider` -* :doc:`spinbox` -* :doc:`splitter` -* :doc:`statusbar` -* :doc:`swipelistitem` -* :doc:`tab` -* :doc:`tableview` -* :doc:`textedit` -* :doc:`togglebutton` -* :doc:`toolbar` -* :doc:`tooltip` -* :doc:`tree` + 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` + +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/inline` +* :doc:`assistance/message` +* :doc:`assistance/progress` +* :doc:`assistance/statusbar` + +Help +~~~~ + +* :doc:`assistance/tooltip` + +Editing and manipulation +------------------------ + +Editing and Manipulation considers the behaviors that result in persistent changes to user’s stored information. + +Selection +~~~~~~~~~ +* :doc:`editing/checkbox` +* :doc:`editing/combobox` +* :doc:`editing/dropdown` +* :doc:`editing/grid` +* :doc:`editing/list` +* :doc:`editing/radiobutton` +* :doc:`editing/swipelistitem` +* :doc:`editing/togglebutton` +* :doc:`editing/tree` + +Unconstrained input +~~~~~~~~~~~~~~~~~~~ + +* :doc:`editing/lineedit` +* :doc:`editing/tableview` +* :doc:`editing/textedit` + +Constrained input +~~~~~~~~~~~~~~~~~ +* :doc:`editing/date` +* :doc:`editing/slider` +* :doc:`editing/spinbox` diff --git a/source/components/actionbutton.rst b/source/components/navigation/actionbutton.rst similarity index 100% rename from source/components/actionbutton.rst rename to source/components/navigation/actionbutton.rst diff --git a/source/components/commandlink.rst b/source/components/navigation/commandlink.rst similarity index 100% rename from source/components/commandlink.rst rename to source/components/navigation/commandlink.rst diff --git a/source/components/contextdrawer.rst b/source/components/navigation/contextdrawer.rst similarity index 100% rename from source/components/contextdrawer.rst rename to source/components/navigation/contextdrawer.rst diff --git a/source/components/contextmenu.rst b/source/components/navigation/contextmenu.rst similarity index 100% rename from source/components/contextmenu.rst rename to source/components/navigation/contextmenu.rst diff --git a/source/components/dialog.rst b/source/components/navigation/dialog.rst similarity index 87% rename from source/components/dialog.rst rename to source/components/navigation/dialog.rst index 75fc4e8..f1ef59a 100644 --- a/source/components/dialog.rst +++ b/source/components/navigation/dialog.rst @@ -1,84 +1,87 @@ Dialog ====== .. image:: /img/Dialog1.png :alt: Dialog :scale: 50% Purpose ------- A *dialog* is a secondary window that allows users to perform a command, asks users a question, or provides users with information or progress feedback. Dialogs can be modal and require users to complete and close before continuing with the owner window, or modeless, i.e. users can switch between dialogs and parent window. Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a dialog to structure the work flow. For instance, the functions Open, Save, Advanced Search need user input or confirmation. In particular, dialogs are expected by users for configuration. - Do not use dialogs if the flow must not get interrupted. In this case prefer inline controls. - Consider to use alternative ways for communication with users like - :doc:`tooltip ` or a :doc:`inline message `. + :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. - 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 :doc:`tooltip ` or a - :doc:`inline message `. + "OK" or "Close" button). Consider to use + :doc:`tooltip <../assistance/tooltip>` or a + :doc:`inline message <../assistance/inline>`. - 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 `. + 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 `. The actions are grouped along their context of use, not + :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/source/components/globaldrawer.rst b/source/components/navigation/globaldrawer.rst similarity index 94% rename from source/components/globaldrawer.rst rename to source/components/navigation/globaldrawer.rst index 3e4aede..3c14a1e 100644 --- a/source/components/globaldrawer.rst +++ b/source/components/navigation/globaldrawer.rst @@ -1,52 +1,53 @@ Global drawer ============= .. figure:: /img/Menu_Drawer.png :alt: Examples of different global drawers Examples of different global drawers 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. Is this the right control? -------------------------- 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 ` Guidelines ---------- The Global 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. A Global Drawer may contain the following controls: - :doc:`Tabs ` - A main menu - :doc:`Push Buttons ` to execute non-contextual actions -- :doc:`Checkboxes ` or :doc:`Radio Buttons ` +- :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. diff --git a/source/components/navigation/index.rst b/source/components/navigation/index.rst new file mode 100644 index 0000000..719929d --- /dev/null +++ b/source/components/navigation/index.rst @@ -0,0 +1,29 @@ +Navigation +========== + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :hidden: + + actionbutton + commandlink + contextdrawer + contextmenu + dialog + globaldrawer + menubar + pushbutton + tab + toolbar + +* :doc:`actionbutton` +* :doc:`commandlink` +* :doc:`contextdrawer` +* :doc:`contextmenu` +* :doc:`dialog` +* :doc:`globaldrawer` +* :doc:`menubar` +* :doc:`pushbutton` +* :doc:`tab` +* :doc:`toolbar` diff --git a/source/components/menubar.rst b/source/components/navigation/menubar.rst similarity index 100% rename from source/components/menubar.rst rename to source/components/navigation/menubar.rst diff --git a/source/components/pushbutton.rst b/source/components/navigation/pushbutton.rst similarity index 95% rename from source/components/pushbutton.rst rename to source/components/navigation/pushbutton.rst index 89add08..1e3c064 100644 --- a/source/components/pushbutton.rst +++ b/source/components/navigation/pushbutton.rst @@ -1,107 +1,107 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ Buttons are available in several flavors: Command button ^^^^^^^^^^^^^^ - Use a command button to initiate an immediate action. - Do not use a command button for navigation to another page (prefer a - `link`_ in this case). + :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 radio buttons with one 'Apply' option or a 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. 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 ^^^^^^^^^^^^^ - A toggle button is not a push button. Guidelines can be found - :doc:`here `. + :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. - 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 `). + 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. 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 in :doc:`toolbars `). - Do not 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 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/source/components/tab.rst b/source/components/navigation/tab.rst similarity index 98% rename from source/components/tab.rst rename to source/components/navigation/tab.rst index 859d6e8..b407311 100644 --- a/source/components/tab.rst +++ b/source/components/navigation/tab.rst @@ -1,137 +1,137 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 - for only one page (but do not hide the tab when more pages are expected, for example in web browser). - for global application controls. - for sequential steps, like wizards. Guidelines for desktop user interfaces -------------------------------------- Behavior ~~~~~~~~ - Do not 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 only (QTabWidget::TabPosition = North). -- Do not use too many tabs. Use a :doc:`list view ` with icons and +- Do not 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. - Make content from one page independent and differentiated from another through the use of tabs. - Do not nest tabs. - Make tabs movable (possible to reorder), if their pages contain documents, but not if their pages contain static application's user interface. - Make tabs closable, if their pages contain documents, but not if their pages contain application's user interface. - Make the tabs use scroll buttons, to scroll tabs when there are too many tabs. - 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. - 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. 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 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`_ 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 ` (acronyms such as HTML are allowed). - Do not use triangular shape of tabs. 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. - When the tabs are used to group controls, put them at the top of the screen. Do not use more than three tabs. - Do not disable a tab when it doesn't 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/source/components/toolbar.rst b/source/components/navigation/toolbar.rst similarity index 97% rename from source/components/toolbar.rst rename to source/components/navigation/toolbar.rst index 4fedf88..3dd2feb 100644 --- a/source/components/toolbar.rst +++ b/source/components/navigation/toolbar.rst @@ -1,57 +1,57 @@ Tool bar ======== Purpose ------- A *tool bar* is a graphical presentation of commands optimized for fast access. Typically, a toolbar contains buttons that correspond to items in an 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 tool bar gives quick, convenient access to frequently used commands. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - For standard applications, apply a tool bar by default. - Provide a tool bar in addition to the menu bar, but do not replace the menu bar. Behavior ~~~~~~~~ - A tool bar 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 tool bar to expose application's features. Only the most frequently functions should be add to the tool bar. - Execute operations immediately; do not require additional input from user. - Do not use :doc:`menu buttons ` in tool bars. They do not fit well the concept of fast access. - Try to avoid using :doc:`split buttons ` - or :doc:`toggle buttons ` in order to + or :doc:`toggle buttons <../editing/togglebutton>` in order to keep the interaction with all buttons in the tool bar consistent. - Do not hide tool bars by default. If configurable, users should easily be able to make the tool bar viewable again. - Disable buttons that do not apply to the current context. - Consider to provide customization for tool bars in respect to position and content. Appearance ~~~~~~~~~~ - Do not change the button style (QToolbar::toolButtonStyle) from the default. The default is currently text beside icons. - Use and design tool bar 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. diff --git a/source/layout/alignment.rst b/source/layout/alignment.rst index 5391b76..0b6bba3 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. Checkboxes and Radio buttons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For more details on alignment of -:doc:`radio buttons ` and -:doc:`checkboxes `, see the detailed HIG pages. +:doc:`radio buttons ` and +:doc:`checkboxes `, see the detailed HIG pages. diff --git a/source/patterns/command/drawer.rst b/source/patterns/command/drawer.rst index 8f68e24..096639a 100644 --- a/source/patterns/command/drawer.rst +++ b/source/patterns/command/drawer.rst @@ -1,47 +1,49 @@ 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 part of an application's main tasks. Global drawer ------------- .. image:: /img/Menu_drawer_single.jpg :alt: Global drawer :scale: 40 % 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 `. + :doc:`global drawer `. Context drawer -------------- .. image:: /img/Context_drawer.jpg :alt: Context drawer :scale: 40 % 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 `. + :doc:`context drawer `. 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 `. +For a full modal dialog, use a +:doc:`dialog sheet `. +For a quick choice, use a +:doc:`bottom drawer `. diff --git a/source/patterns/command/ondemand.rst b/source/patterns/command/ondemand.rst index dc22599..f1d8a84 100644 --- a/source/patterns/command/ondemand.rst +++ b/source/patterns/command/ondemand.rst @@ -1,66 +1,66 @@ 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 ----------- 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 ---------- - Do not 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 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:`swipe list item `. +For futher guidelines see :doc:`swipe list item `. diff --git a/source/patterns/content/sliderspin.rst b/source/patterns/content/sliderspin.rst index 73863b2..1ead848 100644 --- a/source/patterns/content/sliderspin.rst +++ b/source/patterns/content/sliderspin.rst @@ -1,46 +1,46 @@ Slider and spin box =================== Purpose ------- -:doc:`Spin boxes ` allow a user to enter a specific +:doc:`Spin boxes ` allow a user to enter a specific value, and gives users fine control over which value is chosen, but are slow when moving over large ranges of values. -:doc:`Sliders ` allow for quickly changing values +:doc:`Sliders ` allow for quickly changing values over long ranges, but make it harder to select very specific values. In cases where both are necessary, combing the two is sometimes a good approach. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 to use only slider *or* spin box if a well defined workflow makes the other redundant. Behavior ~~~~~~~~ - The values of the slider and spin box should be linked so changes to one are immediately reflect in another. - Make sure that all requirements from slider and spin box are met. Appearance ~~~~~~~~~~ - The spin box should be aligned with the long axis of the slider. So 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. diff --git a/source/patterns/navigation/grid.rst b/source/patterns/navigation/grid.rst index 6c4b071..c5c82e6 100644 --- a/source/patterns/navigation/grid.rst +++ b/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 ----------- 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 `. +:doc:`list `. 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/source/patterns/navigation/single.rst b/source/patterns/navigation/single.rst index 70793e6..cfacca4 100644 --- a/source/patterns/navigation/single.rst +++ b/source/patterns/navigation/single.rst @@ -1,29 +1,30 @@ 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 `. + properties on demand in the + :doc:`context drawer `. diff --git a/source/patterns/navigation/tab.rst b/source/patterns/navigation/tab.rst index 3291540..0570f09 100644 --- a/source/patterns/navigation/tab.rst +++ b/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 single screen into several groups - The other is for viewing multiple documents (e.g. websites in a browser) in the same application instance -- See the :doc:`tab ` for details. +- See the :doc:`tab ` for details. diff --git a/source/patterns/navigation/unique.rst b/source/patterns/navigation/unique.rst index 8635e80..d5472e8 100644 --- a/source/patterns/navigation/unique.rst +++ b/source/patterns/navigation/unique.rst @@ -1,19 +1,20 @@ 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. + 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.