diff --git a/.gitignore b/.gitignore index 50036ea..006ee3d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ /env build +*.qmlc diff --git a/source/components/combobox.rst b/source/components/combobox.rst index b57aff7..3180eb2 100644 --- a/source/components/combobox.rst +++ b/source/components/combobox.rst @@ -1,73 +1,80 @@ Combo box ========= +.. figure:: /img/Combobox1.png + :alt: Combobox + :figclass: border + + A combination of a drop-down list and an edit control. + + Purpose ------- A *combo box* is a combination of a drop-down list and an edit control, thus allowing users to enter a value that isn't in the list. It behaves like a drop-down list and allows the user to choose from a list of existing items but adds the option to type a value directly into the control. Newly typed items are usually added to the list and can be selected next time. Combo boxes are typically applied to provide auto-complete or auto-type functionality in a convenient way to the user. The list provides auto-complete feature for the whole string, independently of the "editable" property. Given the items of "bike", "boat", and "car": - If one types "b", the list selects "bike". - If one (rapidly) types "bo", it selects "boat". - If one types "c", it selects "car". The input field of the combo box ("editable" is true) marks the completed part of the item as selected, making it easy to change the completion. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a combo box for single selection of one out of many items of lists that can be extended by the user. Prefer a simple :doc:`drop-down list ` in case of read-only interaction. - Consider to replace the combo box by a :doc:`list view ` with a connected :doc:`edit control `. Behavior ~~~~~~~~ - Show a maximum of eight items at once. - When possible apply changes immediately but do not initiate an action (like print, send, delete) when the user selects an item from the list. - Do not add controls to the drop-down (e.g. check boxes for each item). - Place options that represent general options (e.g. all, none) at the beginning of the list. - Sort list items in a logical order. Make sure sorting fits translation. - Make sure the items are easily accessible via keyboard by moving distinctive letters to the beginning of each option. For example, in a list of countries on continents, write "Germany (Europe)" instead of "Europe/Germany". - Do not have blank list items; use meta-options, e.g. (None) instead Appearance ~~~~~~~~~~ - Combo boxes are distinguished visually from drop-down lists (normally by the raised or lowered bevel). Do not override the common processing, e.g. by using a combo box and making it read only in order to simulate a simple drop-down list. - If activating a choice affects the appearance or the enabled state of other controls, place them next to the combo box. - If certain controls in a configuration dialog are only relevant if a certain item is selected (i.e. they are dependent controls), disable them instead of hiding. - Label the combo box with a descriptive caption to the left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - End each label with a colon. - Use :doc:`sentence style capitalization ` for items. diff --git a/source/components/dialog.rst b/source/components/dialog.rst index 19e0594..75fc4e8 100644 --- a/source/components/dialog.rst +++ b/source/components/dialog.rst @@ -1,79 +1,84 @@ Dialog ====== +.. image:: /img/Dialog1.png + :alt: Dialog + :scale: 50% + + Purpose ------- A *dialog* is a secondary window that allows users to perform a command, 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 `. - 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 `. - 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 `. 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 along technical relations. - Provide a title to each section. - Follow the guidelines for :doc:`alignment `. diff --git a/source/components/dropdown.rst b/source/components/dropdown.rst index 817fad7..a3b8528 100644 --- a/source/components/dropdown.rst +++ b/source/components/dropdown.rst @@ -1,80 +1,87 @@ Drop-down ========= +.. figure:: /img/Dropdown1.png + :alt: Dropdown + :figclass: border + + Control which allows the user to choose one value from a list. + + Purpose ------- A *drop-down list* is a GUI control which allows the user to choose one value from a list. When a drop-down list is inactive, it displays a single value. When activated, it displays (drops down) a list of values, from which the user may select one. When the user selects a new value, the control reverts to its inactive state, displaying the selected value. A drop-down list works similar to a list box but hides the complete list until the user initiate the drop down. The disadvantage of drop-down lists compared to related controls like radio buttons or lists is that the options are not visible without further interaction. The list provides auto-complete feature for the whole string, independently of the "editable" property. Given the items of "bike", "boat", and "car": - If one types "b", the list selects "bike". - If one (rapidly) types "bo", it selects "boat". - If one types "c", it selects "car". One can repeatedly type a letter to cycle through items of the (read-only) drop-down list starting with this letter. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a drop-down list for single selection of one out of many items. If users should be able to add items use a :doc:`combo box `. - For only a few options, consider to use a set of :doc:`radio buttons `. - For a single selection out of a large number of items (n>20), use a :doc:`list view `. - Prefer controls that show the options without further user interaction, except for the following cases: - the list of options may change over time, - the contents are obvious from the label and the one selected item, for example *Month* and *January* - the control is part of a related sequence of controls. For example, to set a reminder to ring 5 hours or minutes before or after an event. Behavior ~~~~~~~~ - Show a maximum of eight items at once (maxVisibleItems=8). - When possible apply changes immediately but do not initiate an action (like print, send, delete) when the user selects an item from a drop-down list. - Do not add controls to the drop-down (e.g. check boxes for each item). - Place options that represent general options (e.g. all, none) at the beginning of the list. - Sort list items in a logical order. Make sure sorting fits translation. - Make sure the items are easily accessible via keyboard by moving distinctive letters to the beginning of each option. For example, in a list of countries on continents, write "Germany (Europe)" instead of "Europe/Germany". - Do not have blank list items; use meta-options, e.g. (None) instead Appearance ~~~~~~~~~~ - If activating a choice affects the appearance or the enabled state of other controls, place them next to the drop down. - If certain controls in a configuration dialog are only relevant if a certain item is selected (i.e. they are dependent controls), disable them instead of hiding. - Label the drop down with a descriptive caption to the left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - End each label with a colon. - Use :doc:`sentence style capitalization ` for items. diff --git a/source/components/grid.rst b/source/components/grid.rst index d0fe8f2..150cd58 100644 --- a/source/components/grid.rst +++ b/source/components/grid.rst @@ -1,35 +1,36 @@ Grid ==== -Purpose -------- +.. image:: /img/Grid1.png + :alt: Grid -Example + +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 diff --git a/source/components/lineedit.rst b/source/components/lineedit.rst index d2e6a09..228e63d 100644 --- a/source/components/lineedit.rst +++ b/source/components/lineedit.rst @@ -1,60 +1,67 @@ Line edit ========= +.. figure:: /img/Lineedit1.png + :alt: Lineedit + :figclass: border + + Single line control to enter unconstrained text. + + Purpose ------- The *line edit* control displays a single line of text to the user and allow the user to enter unconstrained text. If more than one line is required a text edit is the right control. Because line edits are unconstrained and don’t accept valid data only, input validation and problem handling should be handled carefully. Examples -------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use edits for input of single lines of unconstrained text. - In case of multiple lines of text or more than a few words, use a :doc:`text edit ` - Do not use a line edit if only a specific type of data is valid. Use a control for constrained input. Behavior ~~~~~~~~ - Mask letters if edit is used to enter passwords. - When setting a new password, have it entered twice to prevent typos in passwords. - Provide a "Show password" check box to unmask the password both when setting new and when entering existing passwords. - Consider to use auto-complete feature to help users when entering data that is likely to be used repeatedly. - If the user enters a character that is known to be invalid, ignore the character and display an input problem hint that explains the valid characters (e.g. numbers vs. characters). - If the input data has a value or format that is known to be invalid, display an input problem hint when the text box loses input focus (e.g. wrong zip code format). - If the input data is inconsistent with other controls on the window, give an error message when the entire input is complete, such as when users click OK for a modal dialog box. - Don't clear invalid input data unless users aren't able to correct errors easily. Doing so allows users to correct mistakes without starting over. Appearance ~~~~~~~~~~ - When disabling the line edit, also disable any associated labels and buttons. - Label every line edit with a descriptive caption to the left (cf. :doc:`/layout/alignment`). - Create a buddy relation so access keys are assigned. diff --git a/source/components/spinbox.rst b/source/components/spinbox.rst index b6cd0b3..36f11b9 100644 --- a/source/components/spinbox.rst +++ b/source/components/spinbox.rst @@ -1,58 +1,65 @@ 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. diff --git a/source/components/textedit.rst b/source/components/textedit.rst index 76eb1cf..10a62d9 100644 --- a/source/components/textedit.rst +++ b/source/components/textedit.rst @@ -1,37 +1,44 @@ Text edit ========= +.. figure:: /img/Textedit1.png + :alt: Textedit + :figclass: border + + Control to enter multiple lines of text. + + Purpose ------- The *text edit* control displays multiple lines of text to the user and allow the user to enter unconstrained text. In contrast to a line edit that is used to enter only one line of text the text edit is the right control for more than one line. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use text edits for input of unconstrained text with more than one line. - Do not use a text edit for input of a few words. Use a :doc:`line edit ` to enter single lines of text. Behavior ~~~~~~~~ - Do not make users scroll unnecessarily; size text boxes to eliminate the need for scrolling. - Do not put horizontal scroll bars on multi-line text boxes. Appearance ~~~~~~~~~~ - When disabling the text edit, also disable any associated labels and buttons. - Label every text edit with a descriptive caption to the top left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. diff --git a/source/components/togglebutton.rst b/source/components/togglebutton.rst index d091d24..5ff4dd5 100644 --- a/source/components/togglebutton.rst +++ b/source/components/togglebutton.rst @@ -1,46 +1,53 @@ Toggle button ============= +.. figure:: /img/Togglebutton1.png + :alt: Togglebutton + :figclass: border + + Control to show a change of state. + + Purpose ------- *Toggle buttons* look similar to regular buttons, but are used to show or change a state rather than initiate an action. A toggle button's two states, set and unset, are shown by its appearing "pushed in" or "popped out" respectively. Toggle buttons are a valid option to indicate a state with the advance of using an icon. Compared to the related radio button or check box they are an efficient way to save screen space. But toggle buttons should be used with care outside a toolbar because the state is not clearly indicated. Example ------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a toggle button to indicate a state if no other control apply, i.e. in case of the :doc:`toolbar `. - Prefer :doc:`radio buttons ` or :doc:`check boxes ` 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/img/Combobox1.png b/source/img/Combobox1.png new file mode 100644 index 0000000..40a91f3 Binary files /dev/null and b/source/img/Combobox1.png differ diff --git a/source/img/Dialog1.png b/source/img/Dialog1.png new file mode 100644 index 0000000..ed901d6 Binary files /dev/null and b/source/img/Dialog1.png differ diff --git a/source/img/Dropdown1.png b/source/img/Dropdown1.png new file mode 100644 index 0000000..76a58e3 Binary files /dev/null and b/source/img/Dropdown1.png differ diff --git a/source/img/Grid1.png b/source/img/Grid1.png new file mode 100644 index 0000000..8570a72 Binary files /dev/null and b/source/img/Grid1.png differ diff --git a/source/img/Lineedit1.png b/source/img/Lineedit1.png new file mode 100644 index 0000000..a77b09f Binary files /dev/null and b/source/img/Lineedit1.png differ diff --git a/source/img/Spinbox1.png b/source/img/Spinbox1.png new file mode 100644 index 0000000..edba4dd Binary files /dev/null and b/source/img/Spinbox1.png differ diff --git a/source/img/Textedit1.png b/source/img/Textedit1.png new file mode 100644 index 0000000..11d9a04 Binary files /dev/null and b/source/img/Textedit1.png differ diff --git a/source/img/Togglebutton1.png b/source/img/Togglebutton1.png new file mode 100644 index 0000000..79af9cc Binary files /dev/null and b/source/img/Togglebutton1.png differ diff --git a/source/qml/components/combobox/Combobox1.qml b/source/qml/components/combobox/Combobox1.qml new file mode 100644 index 0000000..97ee549 --- /dev/null +++ b/source/qml/components/combobox/Combobox1.qml @@ -0,0 +1,54 @@ +/* + * Copyright 2018 Fabian Riethmayer + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Library General Public License as + * published by the Free Software Foundation; either version 2, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Library General Public License for more details + * + * You should have received a copy of the GNU Library General Public + * License along with this program; if not, write to the + * Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +import QtQuick 2.6 +import QtQuick.Controls 2.2 +import org.kde.kirigami 2.4 as Kirigami + +Rectangle { + width: 320 + height: 180 + + Row { + x: Kirigami.Units.gridUnit + y: Kirigami.Units.gridUnit + spacing: 4 * Kirigami.Units.largeSpacing + + ComboBox { + editable: true + model: [ "", "Item2", "Item3" ] + focus: true + } + ComboBox { + id: cbx + editable: true + model: [ "Item1", "Item2", "Item3" ] + } + } + + // HACK __popup is internal and might change in future versions + Timer { + interval: 1000 + repeat: false + running: true + onTriggered: { + cbx.popup.open() + } + } +} diff --git a/source/qml/components/dropdown/Dropdown1.qml b/source/qml/components/dropdown/Dropdown1.qml new file mode 100644 index 0000000..ecd59d6 --- /dev/null +++ b/source/qml/components/dropdown/Dropdown1.qml @@ -0,0 +1,53 @@ +/* + * Copyright 2018 Fabian Riethmayer + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Library General Public License as + * published by the Free Software Foundation; either version 2, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Library General Public License for more details + * + * You should have received a copy of the GNU Library General Public + * License along with this program; if not, write to the + * Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +import QtQuick 2.6 +import QtQuick.Controls 2.2 +import org.kde.kirigami 2.4 as Kirigami + +Rectangle { + width: 320 + height: 180 + + Row { + x: Kirigami.Units.gridUnit + y: Kirigami.Units.gridUnit + spacing: 4 * Kirigami.Units.largeSpacing + + ComboBox { + model: [ "Item1", "Item2", "Item3" ] + } + ComboBox { + id: cbx + model: [ "Item1", "Item2", "Item3" ] + focus: true + } + + } + + // HACK __popup is internal and might change in future versions + Timer { + interval: 1000 + repeat: false + running: true + onTriggered: { + cbx.popup.open() + } + } +} diff --git a/source/qml/components/lineedit/Lineedit1.qml b/source/qml/components/lineedit/Lineedit1.qml new file mode 100644 index 0000000..46506e4 --- /dev/null +++ b/source/qml/components/lineedit/Lineedit1.qml @@ -0,0 +1,37 @@ +/* + * Copyright 2018 Fabian Riethmayer + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Library General Public License as + * published by the Free Software Foundation; either version 2, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Library General Public License for more details + * + * You should have received a copy of the GNU Library General Public + * License along with this program; if not, write to the + * Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +import QtQuick 2.6 +import QtQuick.Controls 2.2 +import org.kde.kirigami 2.4 as Kirigami + +Rectangle { + width: 240 + height: 120 + + Item { + x: Kirigami.Units.gridUnit + y: Kirigami.Units.gridUnit + + TextField { + placeholderText: "user@example.com" + focus: true; + } + } +} diff --git a/source/qml/components/spinbox/Spinbox1.qml b/source/qml/components/spinbox/Spinbox1.qml new file mode 100644 index 0000000..4fdcb19 --- /dev/null +++ b/source/qml/components/spinbox/Spinbox1.qml @@ -0,0 +1,36 @@ +/* + * Copyright 2018 Fabian Riethmayer + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Library General Public License as + * published by the Free Software Foundation; either version 2, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Library General Public License for more details + * + * You should have received a copy of the GNU Library General Public + * License along with this program; if not, write to the + * Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +import QtQuick 2.6 +import QtQuick.Controls 2.2 +import org.kde.kirigami 2.4 as Kirigami + +Rectangle { + width: 120 + height: 80 + + Item { + x: Kirigami.Units.gridUnit + y: Kirigami.Units.gridUnit + + SpinBox { + focus: true; + } + } +} diff --git a/source/qml/components/textedit/Textedit1.qml b/source/qml/components/textedit/Textedit1.qml new file mode 100644 index 0000000..c3b6fe0 --- /dev/null +++ b/source/qml/components/textedit/Textedit1.qml @@ -0,0 +1,39 @@ +/* + * Copyright 2018 Fabian Riethmayer + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Library General Public License as + * published by the Free Software Foundation; either version 2, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Library General Public License for more details + * + * You should have received a copy of the GNU Library General Public + * License along with this program; if not, write to the + * Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +import QtQuick 2.6 +import QtQuick.Controls 2.2 +import org.kde.kirigami 2.4 as Kirigami + +Rectangle { + width: 240 + height: 180 + + Item { + x: Kirigami.Units.gridUnit + y: Kirigami.Units.gridUnit + + TextEdit { + width: 200 + focus: true; + wrapMode: TextEdit.WordWrap + text: "The text edit control displays multiple lines of text to the user and allow the user to enter unconstrained text..." + } + } +}