diff --git a/source/components/assistance/inline.rst b/source/components/assistance/inline.rst index 2d2aa18..bc4b60a 100644 --- a/source/components/assistance/inline.rst +++ b/source/components/assistance/inline.rst @@ -1,184 +1,181 @@ Inline message ============== .. container:: intend |desktopicon| |mobileicon| Purpose ------- A *inline message* is a small panel that informs users of a non-critical problem or special condition. It is embedded in the content and should not overlap content or controls. The panel has four visual style options which can be used for neutral messages, success conditions, warnings, and errors. It can also be given buttons. .. figure:: /img/Message5.png :alt: Different levels of inline messages. :scale: 80% The four different levels of inline messages. Examples -------- .. figure:: /img/Message-example.png :alt: An inline message is used for feeback after an upload has been completed. Guidelines ---------- - Use inline messages in cases of non-critical problems that user can solve. - Use *negative feedback* (aka error) as a secondary indicator of failure, e.g. if a transaction was not completed successfully - Show the information on a warning level in case of relevant information that do not concern the current workflow, e.g. No Internet connection available. - Use *positive feedback* to notify about user-initiated processes, e.g. to indicate completion of background tasks - Use *opportunistic interaction* (aka notification) to acknowledge 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 <../navigation/pushbutton>`. .. figure:: /img/Message1.png :alt: Inline message with a custom icon and a close button. :scale: 80% Inline message with a custom icon and a close button. .. figure:: /img/Message2.png :alt: Inline message with two buttons. :scale: 80% Inline message with two buttons. If there is not enough space to display all the buttons, an overflow menu is shown instead. .. figure:: /img/Message3.png :alt: Inline message with overflow menu. :scale: 80% Inline message with overflow menu. Code ---- -API -~~~ +Kirigami +~~~~~~~~ - :kirigamiapi:`Kirigami: InlineMessage ` - :kwidgetsaddons:`QtWidgets: KMessageWidget ` -Kirigami -~~~~~~~~ - .. code-block:: qml ... import QtQuick.Controls 2.2 as Controls import org.kde.kirigami 2.4 as Kirigami ... Kirigami.InlineMessage { visible: true text: i18n("&Remember password?") type: Kirigami.MessageType.Positive showCloseButton: true ... actions: [ Kirigami.Action { text: i18n("&Remember") icon.name: "dialog-ok-apply" }, Kirigami.Action { text: i18n("&Do not remember") icon.name: "dialog-cancel" } ] } diff --git a/source/components/editing/card.rst b/source/components/editing/card.rst index 2e57b3c..48e7be7 100644 --- a/source/components/editing/card.rst +++ b/source/components/editing/card.rst @@ -1,97 +1,97 @@ Card ==== Purpose ------- A card serves as overview and an entry point for more detailed information and can offer direct access to the most important actions on an item. Example ------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Don't use a card to display long texts. - Cards can be used to display items with different content types, e.g. images text, videos. - Don't use cards for content that should be directly comparable, use a table view or a grid view for that. - If you would show more than 20 cards at a time, or if the user would have to scroll for more than three screen heights to see all of them, consider using a list instead. - Don't use cards with text input elements. - If your cards consist of just one image a grid with overlay actions might be more suitable. Behavior ~~~~~~~~ |desktopicon| Desktop ^^^^^^^^^^^^^^^^^^^^^ Cards are responsive. They resize to fit into the available space. .. raw:: html It is recommended that you adjust the number of cards displayed next to each other depending on the available space. .. raw:: html |mobileicon| Mobile ^^^^^^^^^^^^^^^^^^^ - Cards only resize to orientation changes. - The number of columns only adjust to orientation changes. Appearance ~~~~~~~~~~ It is recomended that you use the standard card layout for consistency, but cards can have a lot of different layouts. .. figure:: /img/Card6.qml.png :alt: Default card layout Default card layout with a header image, text content and optional actions. The only common requirement is the container around it. While cards can have a lot of different layouts, each should focus only on one bit of information or content. Here are some general recommendations for card layouts: - Use images, icons or video elements to create visually immersive cards. Feel free to use different text sizes, cards are not a control for plain text. - Use a well known aspect ratio for a header image .. image:: /img/Card5.qml.png :alt: Cards with 16x9, 4x3, 1x1 header image aspect ratio - Add a padding of at least largeSpacing to the card, except for videos and images. These can ignore the padding and span the entire width or height of a card. .. image:: /img/Card2.qml.png :alt: Padding for text and buttons Code ---- -API -~~~ +Kirigami +~~~~~~~~ - :kirigamiapi:`Kirigami: Card ` - :kirigamiapi:`Kirigami: CardsGridView ` - :kirigamiapi:`Kirigami: CardsLayout ` - :kirigamiapi:`Kirigami: CardsListView ` diff --git a/source/components/editing/checkbox.rst b/source/components/editing/checkbox.rst index 282bce2..0b05fad 100644 --- a/source/components/editing/checkbox.rst +++ b/source/components/editing/checkbox.rst @@ -1,207 +1,207 @@ 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. - 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 <../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. Code ---- -API -~~~ +Kirigami +~~~~~~~~ - `QML: CheckBox `_ diff --git a/source/components/editing/combobox.rst b/source/components/editing/combobox.rst index 45a28d0..16d8217 100644 --- a/source/components/editing/combobox.rst +++ b/source/components/editing/combobox.rst @@ -1,88 +1,88 @@ 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. 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. Code ---- -API -~~~ +Kirigami +~~~~~~~~ - `QML: ComboBox `_ diff --git a/source/components/editing/grid.rst b/source/components/editing/grid.rst index 42f1a43..77e72ce 100644 --- a/source/components/editing/grid.rst +++ b/source/components/editing/grid.rst @@ -1,45 +1,45 @@ Grid ==== .. image:: /img/Grid1.png :alt: Grid Purpose ------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ Behavior ~~~~~~~~ On mouse over the item "go darker" to emphasis the overlay buttons Overlay buttons ^^^^^^^^^^^^^^^ Overlay buttons only appear on mouse over. Overlay buttons should only used for actions for this specific item, never for global actions regarding other items in the grid Appearance ~~~~~~~~~~ - All items must have the same size - All rows, except the last one, have the same number of items - Overlay buttons are placed at the bottom right corner - Grid has a PaperWhite background on desktop, an no background on mobile Code ---- -API -~~~ +Kirigami +~~~~~~~~ - `QML: GridView `_ - :kirigamiapi:`Kirigami: CardsGridView ` diff --git a/source/components/editing/list.rst b/source/components/editing/list.rst index 1130348..7e8fb4b 100644 --- a/source/components/editing/list.rst +++ b/source/components/editing/list.rst @@ -1,354 +1,351 @@ 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 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. On demand actions ^^^^^^^^^^^^^^^^^ List items can uses an :doc:`on-demand pattern ` as an alternative to always-visible controls. If the user often performs tasks on single items of a list, you can add on-demand controls to the list item for these. .. image:: /img/Slide_to_reveal.jpg :alt: Slide to reveal actions :scale: 30 % |desktopicon| Desktop """"""""""""""""""""" If only one action is available, most the time it's better to not use the on-demand pattern and instead show the action right away. .. raw:: html On-demand controls are shown when hovering over the item with the cursor. A handle is shown to support devices with touch screens. Swiping the handle right to left reveals the actions. As soon as the user taps anywhere else or the pointer is no longer hovering over the item, the handle is slid back. |mobileicon| Mobile """"""""""""""""""" .. raw:: html On-demand controls are revealed by sliding a handle from right to left to reveal them. As soon as the user taps anywhere else, the handle is slid back. Selection ^^^^^^^^^ List items can contain a checkbox to enable the selection of multiple items at the same time. Clicking on the checkbox should not trigger an action, but only change the selection. Place buttons below the list to perform actions on the selected items. If the selection is the only action a user can execute on the items, there is no need for a checkbox. Change the background item color to toggle selection state. .. figure:: /img/PickerOverlay.png :alt: Picker in Language KCM :scale: 60% Multiple selected items in a picker overlay. - Do *not* provide extended multiple selections with Shift+Click or Ctrl+Click to select groups of contiguous or non-adjacent values, respectively. Instead, use the :doc:`dual-list pattern ` or the :doc:`picker pattern ` if multiple items have to be selected, because it allows users to easily see which items are selected at any point, without having to scroll through the available options, and it can be used with only the mouse. Picker ^^^^^^ Lists can be used for the :doc:`picker pattern `. Place a button below the list to add items to the list. To remove items from the list, either add an remove action on the item, or give the user the possibility to select items and add a global remove button at the bottom of the list. Ordering ^^^^^^^^ Allow drag and drop of items, if the the order of the items can be changed by the user. |desktopicon| Desktop """"""""""""""""""""" If you use a :doc:`dual-list pattern ` and want to be able to re-order the items in the selected list you can add aditional up and down buttons. .. figure:: /img/DualListOrdering.png :scale: 50 % :alt: Dual-list pattern with up and down buttons Dual-list pattern with up and down buttons Appearance ~~~~~~~~~~ - Alternate row color (use theme settings). Use different keys (e.g. page up/down) when more lists should be accessible. - Show at least four list view items at any time without the need for scrolling. - Make windows and the list within a dialog or utility window resizeable so that users can choose how many list items are visible at a time without scrolling. Make these windows remember last used dimensions. - If selections affect the appearance or control states, place these controls next to the list view. - Disable controls in a dialog if not in use rather than hide, or remove them from the list (i.e. they are dependent controls), - Label the list view with a descriptive caption to the top left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - End each label with a colon. ":" - Use :doc:`sentence style capitalization ` for list view items. |desktopicon| Desktop ^^^^^^^^^^^^^^^^^^^^^ .. figure:: /img/Listview6.png :alt: Several different lists :scale: 40 % :figclass: border List items with and without icons List items can have a lot of different styles and sizes, but should always be coherent in a list. .. container:: flex .. container:: .. figure:: /img/Listview3.png :alt: Default padding of an item :scale: 40 % :figclass: border Default padding of a SwipeListItem on desktop Items have a padding of :doc:`Units.smallSpacing ` on the top and bottom and a padding of :doc:`2 * Units.smallSpacing ` on the left. .. container:: .. figure:: /img/Listview4.png :alt: Label is vertically centered :scale: 40 % :figclass: border Label is vertically centered Labels are vertically centered within the list item. If the list item includes an icon, add a :doc:`2 * Units.smallSpacing ` margin between the icon and the label. |mobileicon| Mobile ^^^^^^^^^^^^^^^^^^^ .. container:: flex .. container:: .. figure:: /img/Listview1.png :alt: Default padding of an item :scale: 50 % :figclass: border Default padding of a SwipeListItem on mobile Items have a padding of :doc:`Units.largeSpacing ` on the top and bottom and a padding of :doc:`2 * Units.largeSpacing ` on the left. .. container:: .. figure:: /img/Listview2.png :alt: Label is vertically centered :scale: 50 % :figclass: border Label is vertically centered Labels are vertically centered within the list item. If the list item includes an icon, add a :doc:`2 * Units.largeSpacing ` margin between the icon and the label. Selection ^^^^^^^^^ Checkboxes should be placed to the left of the item. .. figure:: /img/Listview5.png :alt: List items with checkboxes :scale: 40 % :figclass: border List items with checkboxes for multi selection. Add a :doc:`2 * Units.largeSpacing ` margin between the checkbox and the icon or the label. If you change the background color to toggle selection state, use Kirigami.Theme.highlightColor to indicate an active item. Picker ^^^^^^ Place the button to add items to the bottom right of list. .. figure:: /img/ListPicker.png :alt: Picker :scale: 40 % :figclass: border Add button at the bottom right of a list For deselection you can either add a remove button for seleted icons next to the add button or use an icon on the list item. .. figure:: /img/ListPickerRemoveItem.png :alt: Remove from a picker :scale: 40 % :figclass: border Using an on-demand pattern to display a "Remove" icon. Ordering ^^^^^^^^ Code ---- -API -~~~ +Kirigami +~~~~~~~~ - `QML: ListView `_ - :kirigamiapi:`Kirigami: CardsListView ` - :kirigamiapi:`Kirigami: AbstractListItem ` - :kirigamiapi:`Kirigami: BasicListItem ` - :kirigamiapi:`Kirigami: SwipeListItem ` - -Kirigami -~~~~~~~~ .. code-block:: qml ... ListView { ... delegate: Kirigami.SwipeListItem { id: lineItem contentItem: Row { spacing: lineItem.leftPadding Item { width: Kirigami.Units.iconSizes.medium height: width Image { id: avatar width: parent.width height: width source: "..." visible: false } OpacityMask { anchors.fill: avatar source: avatar maskSource: Rectangle { height: avatar.width width: height radius: height / 2 } } } Label { anchors.verticalCenter: parent.verticalCenter text: "..." } } actions: [ Kirigami.Action { text: i18n("&Make call") iconName: "call-start" }, Kirigami.Action { text: i18n("&Write mail") iconName: "mail-message" } ] } ... } ... diff --git a/source/components/editing/radiobutton.rst b/source/components/editing/radiobutton.rst index 5e47281..6b93081 100644 --- a/source/components/editing/radiobutton.rst +++ b/source/components/editing/radiobutton.rst @@ -1,188 +1,188 @@ 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 <../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 <../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. Code ---- -API -~~~ +Kirigami +~~~~~~~~ - `QML: RadioButton `_ diff --git a/source/components/editing/slider.rst b/source/components/editing/slider.rst index c0ad710..921bfd2 100644 --- a/source/components/editing/slider.rst +++ b/source/components/editing/slider.rst @@ -1,121 +1,121 @@ Slider ====== Purpose ------- A *slider* is a widget with which a user may set a value by moving an indicator, usually in a horizontal fashion. The user may also click on a point on the slider to change the setting. It is different from a scrollbar in that it is typically used to adjust a value without changing the format of the display or the other information on the screen. A slider is used to set defined, contiguous values or a range of discrete values. It is a good choice when values have a relative quantity, not a numeric value. Usually, changes made on the slider are shown immediately. That instant feedback supports input that is not necessarily precise. Compared with spin controls a slider provides faster changes within a larger range but with lower accuracy. Sliders are almost solely operable by mouse. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a slider when adjusting the value relative to its current value is more important than choosing an absolute value. - Use a slider when it is useful for the user to control the rate of change of the value in real time. - If the value is open-ended on one or both ends, consider using a :doc:`Spin Box ` instead. Behavior ~~~~~~~~ - Try to give immediate feedback while the user makes a selection. - Size the control so that a user can easily set the desired value. - Do not use a non-linear scale, e.g. logarithmic. Appearance ~~~~~~~~~~ - Label the slider with a text label to its left, using sentence capitalization. Provide an access key in the label that allows the user to give focus directly to the slider. - Align the label horizontally in line with the slider. - You can show the current value on the right of the slider or if space is very dense show it only as a tooltip when the slider is moved .. figure:: /img/Slider.value.qml.png :alt: Show value always or as tooltip Show value always or as tooltip - Add the unit to the current value caption, if appropriate. Slider with few steps ^^^^^^^^^^^^^^^^^^^^^ eg screen size, symbol-size .. figure:: /img/Slider.qml.png :alt: Spacing Spacing of slider components - Mark significant values along the length of the slider with text or checkmarks. Checkmark have a height of 4 px or 8 if you want to emphasize them. - Min/max labels are optional. Label min/max with real values, eg '640x480' and '5120×2880' in case of screen resolution. - Label the range of values; use checkmark and value label; don't label every checkmark. Slider with many steps ^^^^^^^^^^^^^^^^^^^^^^ eg volume control, mouse speed, brightness .. figure:: /img/Slider.Volume.qml.png :alt: Exact value is not important Exact value is not important - Don't show checkmarks if the exact value is not important - Don't show min/max label if the values don't give the user additional information, eg. don't label them 0%, 100% - If the exact value might be important to the user offer an input field instead of the current value label .. figure:: /img/Slider.Speed.qml.png :alt: Offer text input for exact value Offer text input for exact value Slider and Spinbox together ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Use both a slider and spin box when the value is constrained at both ends, and when there is a large range of values (more than 20 steps) but precise control over the value is needed nevertheless. - Consider using only a slider *or* a spin box if a well-defined workflow makes the other redundant. - The values of the slider and spin box should be linked so changes to one are immediately reflect in another. - The spin box should be aligned with the long axis of the slider: if the slider is horizontal, the spin box should be to the right of the slider and aligned vertically with the center of the slider; if the slider is vertical, the spin box should be below the slider and aligned horizontally with the center of the slider. - Provide a single label using a text label above it or to the left of the widgets, using sentence capitalization. Provide an access key in the label that should give focus directly to the spin box. - Mark significant values along the length of the slider with text or tick marks. Code ---- -API -~~~ +Kirigami +~~~~~~~~ - `QML: Slider `_ diff --git a/source/components/editing/spinbox.rst b/source/components/editing/spinbox.rst index cc22dcf..45ff5d4 100644 --- a/source/components/editing/spinbox.rst +++ b/source/components/editing/spinbox.rst @@ -1,73 +1,73 @@ Spin box ======== .. figure:: /img/Spinbox1.png :alt: Spinbox :figclass: border Control that accepts a range of values. Purpose ------- A *spin box* is a line edit that accepts a range of values. It incorporates two arrow buttons that allow the user to increase or decrease the current value by a fixed amount. Spins are efficient for small changes of numeric values in a contiguous range. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use spin boxes for numerical input only. Use a list or option menu when you need the user to select from fixed data sets of other types. - Use a spin box if the numerical value is meaningful or useful for the user to know, and the valid input range is unlimited or fixed at one end only. For example, a control for specifying the number of iterations of some action, or a time-out value. - If the range is fixed at both ends, or the numerical values are arbitrary (for example, a volume control), use a :doc:`Slider ` control instead. - For cases where the values are constrained at both ends and there large ranges of integers (more than about 20) or floating-point values that require precise control, consider providing both a :doc:`Slider and Spin Box `. This allows the user to quickly set or fine-tune the setting more easily than they could with the slider control alone. Behavior ~~~~~~~~ - If the input data has a value that is known to be invalid, display an input problem hint when the spin edit loses input focus. - If the input data is inconsistent with other controls on the window, give an error message when the entire input is complete, such as when users click OK for a modal dialog box. - Don't clear invalid input data unless users aren't able to correct errors easily. Doing so allows users to correct mistakes without starting over. Appearance ~~~~~~~~~~ - Label the spin box with a text label to its left, using sentence capitalization. - Always append a suffix with the value's unit to the right. - Provide an access key in the label that allows the user to give focus directly to the spin box. - Right-justify the contents of spin boxes, unless the convention in the user's locale demands otherwise. This is useful in windows where the user might want to compare two numerical values in the same column of controls. In this case, ensure the right edges of the relevant controls are also aligned. Code ---- -API -~~~ +Kirigami +~~~~~~~~ - `QML: SpinBox `_ diff --git a/source/components/navigation/actionbutton.rst b/source/components/navigation/actionbutton.rst index 33d613b..6d71982 100644 --- a/source/components/navigation/actionbutton.rst +++ b/source/components/navigation/actionbutton.rst @@ -1,109 +1,108 @@ Primary Action Button ===================== .. figure:: /img/Actionbutton1.png :figclass: border :alt: Primary Action Button Primary action, create a new address book entry. When to use ----------- Use a Primary Action Button whenever there is a primary action for a certain page of your application or for the whole application, which is executed frequently. Typical primary actions are "Create New", "Edit,", "Save" or "Send". Aditionally you can opt to define two secondary primary actions that are placed left and right to the main primary button. .. figure:: /img/Actionbutton2.png :figclass: border :alt: Primary Action Button with two secondary buttons Call, message and write an email as primary actions. If there is no primary action, you may opt to use the Primary Action Button as a shortcut to navigate back to the application's main page instead of omitting it completely. Do that if - navigating back to the main page is a frequent action in your application - or you use Primary Action buttons on some pages and would like to keep the layout consistent across pages - or drawers are frequently used - and the space occupied by the button is not urgently needed for the content If the primary action is clearly associated with a specific element on the user interface, place controls within the content instead. How to use ---------- - Provide a clear icon for the Primary Action Button since it has no text label - If the Primary Action Button changes its action within a page (for example switching to "save" when editing, change its icon as well - If you use the Primary Action Button as a shortcut for going to the main page, use the "go-home" icon from the actions category for it. Desktop-specific ~~~~~~~~~~~~~~~~ If your application is using :doc:`column-based navigation ` - If there is a global Primary Action, associate it with the first column - If there is a Primary action for the context of a specific column, associated with the respective page .. figure:: /img/Actionbutton3.png :figclass: border :alt: Primary Action Buttons on Desktop Primary Action Buttons are placed in a :doc:`toolbar ` Code ---- -API -~~~ +Kirigami +~~~~~~~~ - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` - -Kirigami -^^^^^^^^ - .. code-block:: qml ... import QtQuick.Controls 2.2 as Controls import org.kde.kirigami 2.4 as Kirigami ... Kirigami.ApplicationWindow { ... pageStack.initialPage: Kirigami.ScrollablePage { ... actions { left: Kirigami.Action { iconName: "mail-message" text: i18n("&Write mail") } main: Kirigami.Action { iconName: "call-start" text: i18n("&Make call") } right: Kirigami.Action { iconName: "kmouth-phrase-new" text: i18n("&Write SMS") } } } ... } + + + diff --git a/source/components/navigation/contextdrawer.rst b/source/components/navigation/contextdrawer.rst index 18a5d0d..5c26244 100644 --- a/source/components/navigation/contextdrawer.rst +++ b/source/components/navigation/contextdrawer.rst @@ -1,124 +1,127 @@ Context drawer ============== .. container:: intend |desktopicon| |mobileicon| .. container:: available plasma qwidgets |nbsp| .. figure:: /img/Contextdrawer1.png :figclass: border :scale: 50 % :alt: Examples of a context drawer on mobile Examples of a context drawer on mobile Purpose ------- The Context Drawer is used to access controls that depend on the current context. This can be, for example, controls that affect a selected element in a list or that navigate through an opened document. -Is this the right control? --------------------------- +Guidelines +---------- + +Is this the right control +~~~~~~~~~~~~~~~~~~~~~~~~~ Use a Context Drawer if your application has any functions which are only relevant in specific contexts, and which are not central enough to the application's main purpose to put them in the main user interface or in a toolbar. For actions which are always available, use the :doc:`Global Drawer `. -Guidelines ----------- +Behavior +~~~~~~~~ - The Context Drawer is opened by swiping in from the left or right edge of the screen (depending on a system-wide setting) and closed by swiping in the other direction or tapping outside of it. - At the top of the drawer, state which object the controls affect (e.g. "Selected email") - By default, the Context Drawer simply contains a vertical list of action buttons which affect the currently selected/opened element - Center the list vertically instead of top-aligning, to allow an easier reach with the thumb - If needed, other controls related to the current context can be put in the Context Drawer - Try to keep the content of the context drawer in one page. If there two distinct "modes" of contextual actions (for example navigating through a PDF either by table of contents or thumbnails), consider using two :doc:`Tabs ` to separate them, but never use more than two tabs. .. figure:: /img/Contextdrawer2.png :figclass: border :scale: 50 % :alt: Examples of a context drawer on desktop Examples of a context drawer on desktop Code ---- +Kirigami +~~~~~~~~ + - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` -Kirigami -^^^^^^^^ - .. code-block:: qml ... import QtQuick.Controls 2.2 as Controls import org.kde.kirigami 2.4 as Kirigami ... Kirigami.ApplicationWindow { ... pageStack.initialPage: Kirigami.ScrollablePage { ... actions { ... contextualActions: [ Kirigami.Action { iconName: "favorite" text: i18n("&Select as favorite") }, Kirigami.Action { iconName: "document-share" text: i18n("&Share") }, Kirigami.Action { iconName: "document-edit" text: i18n("&Edit") }, Kirigami.Action { iconName: "edit-image-face-add" text: i18n("&Choose photo") }, Kirigami.Action { iconName: "im-kick-user" text: i18n("&Block number") }, Kirigami.Action { iconName: "delete" text: i18n("&Delete contact") }, Kirigami.Action { iconName: "edit-clear-history" text: i18n("&Delete history") } ] ... } } ... contextDrawer: Kirigami.ContextDrawer { } ... } diff --git a/source/components/navigation/globaldrawer.rst b/source/components/navigation/globaldrawer.rst index 400fecf..801a698 100644 --- a/source/components/navigation/globaldrawer.rst +++ b/source/components/navigation/globaldrawer.rst @@ -1,150 +1,150 @@ Global drawer ============= +Purpose +------- + +The Global Drawer is a standard element in KDE mobile applications. It +contains an application's main menu, and any functions which are not +part of the application's main usecases but are not specific to the +current context either. + .. container:: intend |desktopicon| |mobileicon| .. container:: available plasma qwidgets |nbsp| .. figure:: /img/Globaldrawer1.png :alt: Global drawer on mobile :figclass: border :scale: 40 % Global drawer on mobile -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. +Guidelines +---------- Is this the right control? --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: /img/Globaldrawer3.png :figclass: border :alt: Global drawer on desktop :scale: 40 % Global drawer on desktop Use a Global Drawer whenever your application has any functions which are not central enough to the application's main purpose to put them in the main user interface, and which are not dependent on the current context. For context-specific actions (e.g. those affecting a selected item), use the :doc:`Context Drawer ` -Guidelines ----------- +Behavior +~~~~~~~~ .. figure:: /img/Globaldrawer2.png :alt: Global drawer on desktop :scale: 40 % :figclass: border Hamburger button on the toolbar on desktop. The Global Drawer is either opened by clicking on the hamburger button on the toolbar or by swiping from the left edge of the screen. It can be closed by swiping in the other direction, clicking the close button or tapping outside of it. A Global Drawer may contain the following controls: - :doc:`Tabs ` - A main menu - :doc:`Push Buttons ` to execute non-contextual actions - :doc:`Checkboxes <../editing/checkbox>` or :doc:`Radio Buttons <../editing/radiobutton>` to change settings which are commonly changed The main menu - Must not have more than three levels - Should if possible not contain more elements than fit on the screen - Should contain an entry :doc:`Settings ` in the last position if the application has settings which are not commonly changed - Selecting an entry in the menu either executes an action or goes down one level, replacing the menu with the items in the selected submenu - In lower menu levels, below the entries there is a button to go up one level. Do not use the Menu Drawer for navigation purposes. |desktopicon| Collapsible -^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""" On the desktop, if the elements in the Global Drawer need to be accessed more often and enough space is available, the Global Drawer can default to showing a collapsed state, where the labels disappear but all actions continue to be available via icons-only ToolButtons. Pressing the hamburger menu button expands the Global Drawer to its full width and shows the actions' text labels. Pressing the close button or anywhere outside of it collapses it to its collapsed icons-only state. .. raw:: html Code ---- -API -~~~ +Kirigami +~~~~~~~~ - :kirigamiapi:`Kirigami: GlobalDrawer ` -Kirigami -^^^^^^^^ - .. code-block:: qml ... import QtQuick.Controls 2.2 as Controls import org.kde.kirigami 2.4 as Kirigami ... Kirigami.ApplicationWindow { ... globalDrawer: Kirigami.GlobalDrawer { title: "..." titleIcon: "..." topContent: [ ... ] actions: [ Kirigami.Action { iconName: "list-import-user" text: i18n("&Import") }, Kirigami.Action { iconName: "list-export-user" text: i18n("&Export") }, Kirigami.Action { iconName: "user-group-delete" text: i18n("&Merge contacts") }, Kirigami.Action { iconName: "user-group-new" text: i18n("&Search dupplicate contacts") }, Kirigami.Action { iconName: "configure" text: i18n("&Settings") } ] } ... } diff --git a/source/components/navigation/menubar.rst b/source/components/navigation/menubar.rst index efacf07..09e4e94 100644 --- a/source/components/navigation/menubar.rst +++ b/source/components/navigation/menubar.rst @@ -1,131 +1,128 @@ Menu bar ======== Purpose ------- A *menu bar* appears at the top of an application's main window. It provides access to all commands and most of the settings available in an application. Users refer frequently to the menu bar, especially when they are seeking a function for which they know of no other interface. Ensuring that menus are well organized, are worded clearly, and behave correctly is crucial to the user’s ability to explore and access the functionality of the application. Examples -------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - A menu bar is mandatory for applications that have a :doc:`very complex command structure `, such as those used for content creation or editing, file manipulation, or other productivity work. - Menu bars are optional for simple apps that are able to expose all functionality using visible buttons and toolbars. If any functionality is not visible by default, err on the side of providing a menu bar. - Do not display a menu bar in secondary or internal windows, like the settings dialog or file dialog. Very small main windows are likewise usually poor candidates for menu bars. - Do not include a menu bar in a convergent application's mobile user interface. Behavior ~~~~~~~~ - Do not have more than nine menu categories within a menu bar. Too many categories are overwhelming and makes the menu bar difficult to use. - At the minimum, all windows should have File, Edit, Settings, and Help menus. If they apply, the window can also have View, Insert, Format, Tools and, Window menus. - Do not put more than 12 items within a single level of a menu. Add separators between logical groups within a menu. Organize the menu items into groups of seven or fewer strongly related items. - Assign shortcut keys to the most frequently used menu items. Use `KStandardAction `_ and `KStandardShortcut `_ items for common functions, which will result in menu items automatically receiving consistent names, icons, and shortcut keys. Any tool or function that is accessible using a keyboard shortcut must have an item in the menu bar so that users can discover it. - Do not hide the menu bar by default. If this is configurable, users should easily be able to make the menu bar viewable again. - Use submenus cautiously. Submenus add complexity to the interface and are physically more difficult to use, so you should take care not to overuse them. Appearance ~~~~~~~~~~ - Place the most frequently used items at the top of the menu. - Provide icons for all menu items. Do not re-use the same icon for multiple items. - For your menu items' text, follow the :doc:`general label guidelines `. - Do not change menu items' labels dynamically. - Choose single word names for menu categories. Using multiple words makes the separation between categories confusing. - Disable menu items that don't apply to the current context instead of removing them from view. **Exception:** It is acceptable to hide menu items completely if they are permanently unavailable on the user's system due to missing hardware capabilities. - Assign :doc:`shortcut keys ` to the most frequently used menu items (Ctrl+). For well-known shortcut keys, use standard assignments. Use function keys for commands that have a small-scale effect (F2 = Rename) and ctrl key for large-scale effect (Ctrl+S = Save). - For menu items that toggle some state on or off, always use the positive form. For example, use the text 'Show hidden files' instead of 'Hide hidden files', and do not change the text when hidden files are shown. Code ---- -API -~~~ +Kirigami +~~~~~~~~ - :kirigamiapi:`Kirigami: ApplicationWindow ` - `QML: MenuBar `_ -Kirigami -^^^^^^^^ - .. code-block:: qml ... import QtQuick.Controls 2.2 as Controls import org.kde.kirigami 2.4 as Kirigami ... Kirigami.ApplicationWindow { ... menuBar: MenuBar { Menu { title: i18n("&File") Action { text: i18n("&New...") } Action { text: i18n("&Import") } Action { text: i18n("&Export") } } Menu { title: i18n("&Edit") Action { text: i18n("&Merge contacts") } Action { text: i18n("&Search dupplicate contacts") } Action { text: i18n("&Export") } } Menu { title: i18n("&Settings") Action { text: i18n("&Settings") } Action { text: i18n("&Configure shortcuts") } } Menu { title: i18n("&Help") Action { text: i18n("&Report Bug...") } Action { text: i18n("&Donate") } Action { text: i18n("&About Addressbook") } Action { text: i18n("&About KDE") } } } ... } diff --git a/source/components/navigation/toolbar.rst b/source/components/navigation/toolbar.rst index 4b40b79..3130845 100644 --- a/source/components/navigation/toolbar.rst +++ b/source/components/navigation/toolbar.rst @@ -1,167 +1,165 @@ Toolbar ======= .. figure:: /img/Toolbar1.png :figclass: border :alt: Primary Action Buttons on Desktop Toolbar with the most important actions :doc:`toolbar ` and an overflow menu Purpose ------- A *toolbar* is a graphical presentation of commands optimized for fast access. A toolbar can be either be defined for a whole application or as part of another component. As an application toolbar it contains buttons that correspond to items in the application's menu, providing direct access to application's most frequently used functions. A good menu bar is a comprehensive catalog of all the available top-level commands, whereas a good toolbar gives quick, convenient access to frequently used commands. As part of another component, like a card or an inline mesage, it is used to allow quick access to the most important commands for a single, focused content item. Guidelines for application -------------------------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - For standard applications, show a toolbar by default. - Provide a toolbar in addition to the menu bar, but do not replace the menu bar. Behavior ~~~~~~~~ - A toolbar should contain only a few, frequently used operations. If the number of operations is above 5 they have to be grouped with separators. Not more than 3 of those sections should be implemented. - Do not abuse the toolbar to expose application's features. Only the most frequently functions should be add to the toolbar. - Execute operations immediately; do not require additional input. - Try to avoid using :doc:`split buttons ` or :doc:`toggle buttons <../editing/togglebutton>` in order to keep the interaction with all buttons in the toolbar consistent. - Do not hide toolbars by default. If configurable, users should easily be able to make the toolbar viewable again. - Disable buttons that do not apply to the current context. - Consider to provide customization for toolbars in respect to position and content. - Providing a label for each action is a good practice but define a meaningful icon too because the label could be hidden in mobile mode or if there isn't enough space when the window is resized. Guidelines for components ------------------------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a toolbar only if an item has few actions or few frequently used actions. - Embed a toolbar only in another control that is clearly visually seperated like a card or an inline message. Behavior ~~~~~~~~ - A toolbar should contain only a few, frequently used operations. The number of operations should not exceed 3. - Do not group with separators. - Execute operations immediately; do not require additional input. - Do not hide toolbars or make them configurable. - Toolbars can be responsive. If there is not enough space to display all the buttons, an overflow menu is shown instead. .. raw:: html Appearance ---------- - Do not change the button style from the default, which is :doc:`text beside icons `. - Use and design toolbar icons with special care. Users remember location of an object but rely as well on icon properties. - A distinct association between the underlying function and its visual depiction is crucial. Follow the advices for :doc:`icon design `. - Do not simulate Microsoft's ribbon controls. KDE stays plain and simple.Microsoft's ribbon controls. KDE stays plain and simple. Code ---- -API -~~~ +Kirigami +~~~~~~~~ - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` - :kirigamiapi:`Kirigami: ActionToolBar ` -Kirigami -~~~~~~~~ - + Application toolbar -^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""" .. code-block:: qml ... import QtQuick.Controls 2.2 as Controls import org.kde.kirigami 2.4 as Kirigami ... Kirigami.ApplicationWindow { ... pageStack.initialPage: Kirigami.ScrollablePage { ... actions { left: Kirigami.Action { iconName: "mail-message" text: i18n("&Write mail") } main: Kirigami.Action { iconName: "call-start" text: i18n("&Make call") } right: Kirigami.Action { iconName: "kmouth-phrase-new" text: i18n("&Write SMS") } } } ... } Component toolbar ^^^^^^^^^^^^^^^^^ .. code-block:: qml ... import QtQuick.Controls 2.2 as Controls import org.kde.kirigami 2.4 as Kirigami ... Kirigami.ActionToolBar { ... actions: [ Kirigami.Action { iconName: "favorite" text: i18n("&Select as favorite") }, Kirigami.Action { iconName: "document-share" text: i18n("&Share") } ] ... } ... diff --git a/source/resources/contribute.rst b/source/resources/contribute.rst index 78490bb..9eb2f1e 100644 --- a/source/resources/contribute.rst +++ b/source/resources/contribute.rst @@ -1,171 +1,167 @@ Contribute ========== The HIG is written in `reStructuredText `_, a lightweight markup language. For example the chapter heading together with the first paragraph looks like this in reStructuredText:: Contribute ========== The HIG is written in `reStructuredText `_, a light weight markup language. For example the chapter heading together with the first paragraph looks like this in reStructuredText The restructuredText of the full HIG is organized into several source files. You can view and modify these source files with any text editor. The source files are hosted in a `Git repo `_. `Sphinx `_ is used to generate HTML pages from these source files. Tasks and changes are organized via `https://invent.kde.org `_. .. note:: On every page of the HIG, there is a *View page source* link in the top right corner. For more information and help you can find us on `Matrix `_, `IRC `_ or `Telegram `_ . If you are new to KDE devlopment, make sure to read `how to become a kde developer `_ first. Getting started --------------- #. Install some tools with your distro's package manager: * Arch/Antergos/Manjaro: ``sudo pacman -S git python-sphinx python-sphinx_rtd_theme`` * Debian/Ubuntu/Kubuntu/KDE Neon: ``sudo apt install git build-essential python3-sphinx python3-sphinx-rtd-theme`` * openSUSE: ``sudo zypper in git python3-Sphinx python3-sphinx_rtd_theme`` #. Clone HIG repositories into an empty folder ``git clone https://anongit.kde.org/websites/hig-kde-org.git`` Now you are ready to contribute to the HIG! To preview changes on your local machine, do the following: #. ``cd`` to your git checkout of the HIG repository #. Run ``make html`` to create the HTML pages #. Open ``build/html/index.html`` in your browser (e.g. run ``firefox build/html/index.html``) Page structure -------------- This defines the structure that should be used for writing pattern and component pages for the HIG. Pattern ^^^^^^^ :: Pattern name ============== Give a short into into the pattern. Examples -------- Showcase the pattern with videos or images. When to use ----------- Describe when to use this pattern and when not to use it. How to use ---------- Describe how to use this pattern. Pages about patterns should not include any details on implementation, about behavior or appearance, but rather link to the corresponding components needed to implement a pattern. Optional: you can add subsections for desktop and mobile. :: When to use ----------- Desktop ^^^^^^^ Mobile ^^^^^^ Component ^^^^^^^^^ :: Component name ============== Purpose ------- A very short description on why and how to use the component. This should primarily link to the corresponding pattern pages. Example ------- Showcase the component with a video or image. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ Describe when to use a component and when not. Behavior ~~~~~~~~ Describe the behavior of the component. Appearance ~~~~~~~~~~ Describe the appearance of the component. Code ---- Kirigami ~~~~~~~~ - Example code how to use the component with QML and Kirigami. + Link to the API and example code how to use the component with QML and + Kirigami. Qt Widgets ~~~~~~~~~~ - Example code how to use the component with Qt Widgets. - - API - ~~~ - - Link to KDE and Qt API pages. + Link to the API and example code how to use the component with Qt Widgets. Optional: you can add subsections for desktop and mobile. :: Behavior ~~~~~~~~ Desktop """"""" Mobile """"""