diff --git a/source/components/assistance/index.rst b/source/components/assistance/index.rst new file mode 100644 --- /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 rename from source/components/inline.rst rename to source/components/assistance/inline.rst --- a/source/components/inline.rst +++ b/source/components/assistance/inline.rst @@ -116,7 +116,7 @@ ---------- 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. diff --git a/source/components/message.rst b/source/components/assistance/message.rst rename from source/components/message.rst rename to source/components/assistance/message.rst --- a/source/components/message.rst +++ b/source/components/assistance/message.rst @@ -47,7 +47,7 @@ - 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 ~~~~~~~~ diff --git a/source/components/progress.rst b/source/components/assistance/progress.rst 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 rename from source/components/statusbar.rst rename to source/components/assistance/statusbar.rst --- a/source/components/statusbar.rst +++ b/source/components/assistance/statusbar.rst @@ -29,7 +29,7 @@ - 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 ~~~~~~~~ diff --git a/source/components/tooltip.rst b/source/components/assistance/tooltip.rst 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 rename from source/components/checkbox.rst rename to source/components/editing/checkbox.rst --- a/source/components/checkbox.rst +++ b/source/components/editing/checkbox.rst @@ -42,8 +42,9 @@ 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 @@ -62,7 +63,7 @@ :figclass: border :noblefir:`GOOD` |br| - Consider using a :doc:`push button ` instead. + Consider using a :doc:`push button <../navigation/pushbutton>` instead. Behavior ~~~~~~~~ diff --git a/source/components/combobox.rst b/source/components/editing/combobox.rst 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 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 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 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 --- /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 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 rename from source/components/list.rst rename to source/components/editing/list.rst --- a/source/components/list.rst +++ b/source/components/editing/list.rst @@ -36,7 +36,8 @@ - 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 diff --git a/source/components/radiobutton.rst b/source/components/editing/radiobutton.rst rename from source/components/radiobutton.rst rename to source/components/editing/radiobutton.rst --- a/source/components/radiobutton.rst +++ b/source/components/editing/radiobutton.rst @@ -81,7 +81,7 @@ :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 @@ -99,7 +99,7 @@ :figclass: border :noblefir:`GOOD` |br| - Consider using a :doc:`push button `. + Consider using a :doc:`push button <../navigation/pushbutton>`. Behavior ~~~~~~~~ diff --git a/source/components/slider.rst b/source/components/editing/slider.rst 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 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 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 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 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 rename from source/components/togglebutton.rst rename to source/components/editing/togglebutton.rst --- a/source/components/togglebutton.rst +++ b/source/components/editing/togglebutton.rst @@ -32,7 +32,7 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~ - 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:`check boxes ` outside the toolbar. diff --git a/source/components/tree.rst b/source/components/editing/tree.rst 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 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 --- /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 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 --- a/source/components/index.rst +++ b/source/components/index.rst @@ -6,68 +6,75 @@ :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 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 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 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 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 rename from source/components/dialog.rst rename to source/components/navigation/dialog.rst --- a/source/components/dialog.rst +++ b/source/components/navigation/dialog.rst @@ -29,7 +29,8 @@ - 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 @@ -48,15 +49,17 @@ 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 ~~~~~~~~~~ @@ -78,7 +81,7 @@ - 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 rename from source/components/globaldrawer.rst rename to source/components/navigation/globaldrawer.rst --- a/source/components/globaldrawer.rst +++ b/source/components/navigation/globaldrawer.rst @@ -35,7 +35,8 @@ - :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 diff --git a/source/components/navigation/index.rst b/source/components/navigation/index.rst new file mode 100644 --- /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 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 rename from source/components/pushbutton.rst rename to source/components/navigation/pushbutton.rst --- a/source/components/pushbutton.rst +++ b/source/components/navigation/pushbutton.rst @@ -25,7 +25,7 @@ - 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. @@ -68,7 +68,7 @@ ^^^^^^^^^^^^^ - A toggle button is not a push button. Guidelines can be found - :doc:`here `. + :doc:`here <../editing/togglebutton>`. Behavior ~~~~~~~~ @@ -78,7 +78,7 @@ - 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. diff --git a/source/components/tab.rst b/source/components/navigation/tab.rst rename from source/components/tab.rst rename to source/components/navigation/tab.rst --- a/source/components/tab.rst +++ b/source/components/navigation/tab.rst @@ -49,7 +49,7 @@ 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. diff --git a/source/components/toolbar.rst b/source/components/navigation/toolbar.rst rename from source/components/toolbar.rst rename to source/components/navigation/toolbar.rst --- a/source/components/toolbar.rst +++ b/source/components/navigation/toolbar.rst @@ -36,7 +36,7 @@ - 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. diff --git a/source/layout/alignment.rst b/source/layout/alignment.rst --- a/source/layout/alignment.rst +++ b/source/layout/alignment.rst @@ -120,4 +120,6 @@ Check boxes and Radio buttons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For more details on alignment of :doc:`radio buttons ` and :doc:`checkboxes ` see the detailed HIG pages. +For more details on alignment of +: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 --- a/source/patterns/command/drawer.rst +++ b/source/patterns/command/drawer.rst @@ -18,7 +18,7 @@ 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 -------------- @@ -34,14 +34,16 @@ - 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 --- a/source/patterns/command/ondemand.rst +++ b/source/patterns/command/ondemand.rst @@ -63,4 +63,4 @@ 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 --- a/source/patterns/content/sliderspin.rst +++ b/source/patterns/content/sliderspin.rst @@ -4,10 +4,10 @@ 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. diff --git a/source/patterns/navigation/grid.rst b/source/patterns/navigation/grid.rst --- a/source/patterns/navigation/grid.rst +++ b/source/patterns/navigation/grid.rst @@ -18,7 +18,7 @@ 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 ---------- diff --git a/source/patterns/navigation/single.rst b/source/patterns/navigation/single.rst --- a/source/patterns/navigation/single.rst +++ b/source/patterns/navigation/single.rst @@ -26,4 +26,5 @@ 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 --- a/source/patterns/navigation/tab.rst +++ b/source/patterns/navigation/tab.rst @@ -14,4 +14,4 @@ - 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 --- a/source/patterns/navigation/unique.rst +++ b/source/patterns/navigation/unique.rst @@ -12,8 +12,9 @@ - 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.