diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index 133509b37fb63e46457419b5a8e9b32bad64eb7a..1fa39d137c2b35cf484593d5c0ce0e731e550dda 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -1,9 +1,9 @@ --- title: "Getting Started with KDE Frameworks" linkTitle: "Getting Started" -weight: 1 +weight: 2 description: > - Discover KDE Frameworks and start building your first application + Discover KDE Frameworks and start building your first classic KDE desktop application. group: "getting-started" --- diff --git a/content/docs/kirigami/_index.md b/content/docs/kirigami/_index.md index b7fdb36acd21f2531a25ce3251ea8763243dbf27..496bd1741101af8e93ec851e38f8230258c014aa 100644 --- a/content/docs/kirigami/_index.md +++ b/content/docs/kirigami/_index.md @@ -1,7 +1,7 @@ --- title: "Getting started with Kirigami" linkTitle: "Kirigami" -weight: 2 +weight: 1 layout: home groups: - name: "Introduction" diff --git a/content/docs/kirigami/components-actions.md b/content/docs/kirigami/components-actions.md index c4ad708a47d87ee332be92c77d15e073fc3cc135..0ed9944cb495af6ed5f251bcdb9980bad8566a54 100644 --- a/content/docs/kirigami/components-actions.md +++ b/content/docs/kirigami/components-actions.md @@ -7,10 +7,10 @@ description: > --- ## Actions -A Kirigami Action encapsulates a user interface action. We can use these to provide our applications with easy-to-reach actions that are essential to its functionality. +A Kirigami Action encapsulates a user interface action. We can use these to provide our applications with easy-to-reach actions that are essential to their functionality. {{< alert title="Note" color="info" >}} -It inherits from [Qt Quick Controls 2 Action](docs:qtquickcontrols;QtQuick.Controls.Action) and +Kirigami actions inherit from [Qt Quick Controls 2 Action](docs:qtquickcontrols;QtQuick.Controls.Action) and can be assigned shortcuts. {{< /alert >}} @@ -29,6 +29,12 @@ Kirigami.Action { } ``` +{{< alert title="Note" color="info" >}} + +The `icon.name` property takes names for system-wide icons per the FreeDesktop specification. These icons and icon names can be viewed with KDE's CuttleFish application, or by visiting [FreeDesktop's icon naming specification](https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html). + +{{< /alert >}} + One feature offered by Kirigami Actions on top of QtQuick Actions is the possibility to nest actions. @@ -70,12 +76,11 @@ Kirigami.Action { } ``` -## Using actions +## Using actions in other components ### Page -In the [previous tutorial](../introduction-pages), we learned about pages, and one of -the features of pages is that Actions can be added to them. +One of the features of pages is that Actions can be added to them. You can add a main action, a left and right action and additional context actions that are displayed on the toolbar if there is enough place or in a hamburger menu @@ -180,6 +185,8 @@ Kirigami.ApplicationWindow { {{< figure class="text-center" caption="Global Drawers actions on a mobile device" src="mobile_global_drawers.png" >}} {{< /compare >}} +You can read more about Global Drawers in the [documentation page for drawers](../components-drawers/). + ### ActionTextFields A [Kirigami ActionTextField](docs:kirigami2;ActionTextField) is used to add some contextual @@ -277,6 +284,8 @@ Kirigami.ActionToolBar { ![](action_tool_bar.png) +You can read more about ActionToolBar components in their [dedicated documentation page](../components-actiontoolbar/). + ### Cards -The cards components can also take an action. For more information consult the component page for Cards. +The cards components can also take an action. For more information consult the [component page for Cards](../components-card/). diff --git a/content/docs/kirigami/components-actiontoolbar.md b/content/docs/kirigami/components-actiontoolbar.md new file mode 100644 index 0000000000000000000000000000000000000000..3b8e360a847c6964b146264f6e3e50bad6de3e6d --- /dev/null +++ b/content/docs/kirigami/components-actiontoolbar.md @@ -0,0 +1,103 @@ +--- +title: Action Tool Bars +weight: 110 +description: Create your own customisable tool bars with the ActionToolBar component +group: components +--- + +While Kirigami pages allow you to easily place a set of actions in the page header, there are times when you might prefer to have something more flexible. + +Kirigami provides the component `Kirigami.ActionToolBar`. It will display a list of `Kirigami.Action` objects and will display as many of them as possible, providing an overflow menu for the ones that don't fit. The ActionToolBar is dynamic and will move actions in and out of the overflow menu depending on the size available to it. + +{{< alert title="Note" color="info" >}} +This page assumes you are familiar with `Kirigami.Action` objects. If you are not, you can learn all about them in our beginner tutorial or in [the dedicated documentation page for them](../components-actions/). +{{< /alert >}} + +## Creating our first ActionToolBar + +The layout and location of your `Kirigami.ActionToolBar` are really up to you, though for the sake of user-friendliness it is usually a good idea to stick to UI conventions and put your toolbar near the top or bottom of your page and to have it spread width-wise. + +Like most other action-holding components, `Kirigami.ActionToolBar` has an `actions` property. We can assign an array of `Kirigami.Action` components to this property. + +```qml +import QtQuick 2.6 +import QtQuick.Controls 2.0 as Controls +import QtQuick.Layouts 1.2 +import org.kde.kirigami 2.13 as Kirigami + +Kirigami.Page { + + Kirigami.ActionToolBar { + anchors.fill: parent + + actions: [ + Kirigami.Action { + text: "Beep" + icon.name: "notifications" + onTriggered: showPassiveNotification("BEEP!") + }, + Kirigami.Action { + text: "Action Menu" + icon.name: "overflow-menu" + + Kirigami.Action { + text: "Deet"; + icon.name: "notifications" + onTriggered: showPassiveNotification("DEET!") + } + Kirigami.Action { + text: "Doot"; + icon.name: "notifications" + onTriggered: showPassiveNotification("DOOT!") + } + }, + Kirigami.Action { + icon.name: "search" + displayComponent: Kirigami.SearchField { } + } + ] + } + +} +``` + +{{< compare >}} +{{< figure class="text-center" caption="ActionToolBar with enough space for all children" src="actiontoolbar.png" >}} +{{< figure class="text-center" caption="ActionToolBar with overflow menu containing children" src="actiontoolbar-overflow.png" >}} +{{< /compare >}} + +### Alignment + +By default, actions in the ActionToolBar will be left aligned. This might not be desirable in all situations. Thankfully we can change this with the `alignment` property. We can set this property to a range of values, but the three most relevant ones for an ActionToolBar are `Qt.AlignLeft`, `Qt.AlignCenter`, and `Qt.AlignRight` (which deal with horizontal alignment). + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.GroupBox { + Layout.fillWidth: true + + Kirigami.ActionToolBar { + anchors.fill: parent + + alignment: Qt.AlignCenter + + actions: [ + Kirigami.Action { + text: "Beep" + icon.name: "notifications" + onTriggered: showPassiveNotification("BEEP!") + } + ] + } + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![ActionToolBar with children center-aligned](actiontoolbar-alignment.png) + +{{< /section-right >}} +{{< /sections >}} diff --git a/content/docs/kirigami/components-actiontoolbar/actiontoolbar-alignment.png b/content/docs/kirigami/components-actiontoolbar/actiontoolbar-alignment.png new file mode 100644 index 0000000000000000000000000000000000000000..14da3ab99c4844ec35184a1a8b0d205ab7660f48 Binary files /dev/null and b/content/docs/kirigami/components-actiontoolbar/actiontoolbar-alignment.png differ diff --git a/content/docs/kirigami/components-actiontoolbar/actiontoolbar-overflow.png b/content/docs/kirigami/components-actiontoolbar/actiontoolbar-overflow.png new file mode 100644 index 0000000000000000000000000000000000000000..adb453af8b803e5401d5060393e4634d4b56e411 Binary files /dev/null and b/content/docs/kirigami/components-actiontoolbar/actiontoolbar-overflow.png differ diff --git a/content/docs/kirigami/components-actiontoolbar/actiontoolbar.png b/content/docs/kirigami/components-actiontoolbar/actiontoolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..1c97a9f52ff6a2804fff348d3b38ee4399fa4239 Binary files /dev/null and b/content/docs/kirigami/components-actiontoolbar/actiontoolbar.png differ diff --git a/content/docs/kirigami/components-card.md b/content/docs/kirigami/components-card.md index 634900b7cc8cd088d59a8e9acb4044c3e6fae52c..be11ddcfe443d75e90c02c79ba5b1fb48113dbc1 100644 --- a/content/docs/kirigami/components-card.md +++ b/content/docs/kirigami/components-card.md @@ -1,19 +1,18 @@ --- title: Cards -weight: 102 +weight: 104 group: "components" description: > 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. --- +The Kirigami types [`Kirigami.AbstractCard`](docs:kirigami2;org::kde::kirigami::AbstractCard) and [`Kirigami.Card`](docs:kirigami2;org::kde::kirigami::Card) are used to implement the popular card component used on many mobile and web platforms. Cards can be used to display a collection of information or actions in an attractive and distinctive way. -The Kirigami types [AbstractCard](docs:kirigami2;org::kde::kirigami::AbstractCard) and [Card](docs:kirigami2;org::kde::kirigami::Card) are used to implement the popular Card pattern used on many mobile and web platforms that is used to display a collection of information or actions. - -Besides the Card components, Kirigami offers also 3 kinds of views and positioners to help to present cards with beautiful and responsive layouts. +Kirigami also offers 3 kinds of views and positioners to aid you in presenting your cards with beautiful and responsive layouts. ## AbstractCard -An [AbstractCard](docs:kirigami2;org::kde::kirigami::Card) is the simplest form of card. It's just a rectangle with a shadow, which can contain any Item in it. It can also have items assigned to the Header or Footer properties. In this case a [Heading](docs:kirigami2;org::kde::kirigami::Heading) is its header and a [Label](docs:qtquickcontrols;QtQuick.Controls.Label) with WordWrap is the contentItem. +A [`Kirigami.AbstractCard`](docs:kirigami2;Card) is the simplest type of card. It's just a rectangle with a shadow, which can contain any `Item` in it. It can also have items assigned to its `header` or `footer` properties. In this case a [`Kirigami.Heading`](docs:kirigami2;Heading) is its header and a [`Controls.Label`](docs:qtquickcontrols;QtQuick.Controls.Label) with `wrapMode` set to `Text.WordWrap` is the card's `contentItem`. {{< sections >}} {{< section-left >}} @@ -40,7 +39,7 @@ Kirigami.AbstractCard { ## Card -A [Card](docs:kirigami2;org::kde::kirigami::Card) inherits from [AbstractCard](docs:kirigami2;org::kde::kirigami::AbstractCard) and provides more features out of the box. A card has a header composed of a banner, a footer composed of [Actions](docs:kirigami2;org::kde::kirigami::Action) and the main content. +A [`Kirigami.Card`](docs:kirigami2;Card) inherits from [`Kirigami.AbstractCard`](docs:kirigami2;AbstractCard) and provides more features out of the box. A card has a header composed of a `banner` and a footer composed of [`Kirigami.Action`](docs:kirigami2;Action) objects alongside its main content. {{< sections >}} {{< section-left >}} @@ -79,11 +78,15 @@ Kirigami.Card { ## CardsLayout -Use a [CardsLayout](docs:kirigami2;org::kde::kirigami::CardsLayout) when the cards are not instantiated by a model or by a model which has always very few items (In the case of a big model [CardsListView](docs:kirigami2;org::kde::kirigami::CardsListView) or [CardsGridView](docs:kirigami2;org::kde::kirigami::CardsGridView) should be used instead). They are presented as a grid of two columns which will remain centered if the application is really wide, or become a single column if there is not enough space for two columns, such as a mobile phone screen. +A [`Kirigami.CardsLayout`](docs:kirigami2;CardsLayout) is most useful when the cards being presented are not instantiated by a model or by a model which always has very few items. They are presented as a grid of two columns which will remain centered if the application is really wide, or become a single column if there is not enough space for two columns, such as a mobile phone screen. + +{{< alert title="Note" color="info" >}} +[`Kirigami.CardsListView`](docs:kirigami2;CardsListView) or [`Kirigami.CardsGridView`](docs:kirigami2;CardsGridView) are better suited for larger models. +{{< /alert >}} -A CardsLayout should always be contained within a ColumnLayout. +**A CardsLayout should always be contained within a ColumnLayout.** -A card can optionally be oriented horizontally. In this case it will be wider than tall, so is fit to be used in a ColumnLayout. If you need to put it in a CardsLayout, it will have a columnSpan of 2 by default. +A card can optionally be oriented horizontally. In this case it will be wider than tall, and is better suited to being placed in a ColumnLayout. If you must put it in a CardsLayout, it will have a columnSpan of 2 by default. {{< sections >}} {{< section-left >}} @@ -121,13 +124,11 @@ ColumnLayout { ## CardsListView -A [CardsListView](docs:kirigami2;org::kde::kirigami::CardsListView) is a list view of [AbstractCard](docs:kirigami2;org::kde::kirigami::AbstractCard) subclasses with a custom layout inside is needed. - -CardsListView should be used only with cards which can look good at any horizontal size, so it is recommended to use directly AbstractCard with an appropriate layout inside, because they are stretching for the whole list width. +A [`Kirigami.CardsListView`](docs:kirigami2;CardsListView) is a list view that can be used with [`Kirigami.AbstractCard`](docs:kirigami2;AbstractCard) components. -Therefore it's discouraged to use it with the Card type, unless it has `Horizontal` as `headerOrientation`. +A `Kirigami.CardsListView` will stretch child cards to its own width. This component should therefore only be used with cards which will look good at any horizontal size. Using a `Kirigami.CardsListView` the `Kirigami.Card` component is discouraged, unless it has `Qt.Horizontal` as its `headerOrientation` property. -The choice between using this view with AbstractCard or a normal ListView with [AbstractListItem](docs:kirigami2;org::kde::kirigami::AbstractListItem)/[BasicListItem](docs:kirigami2;org::kde::kirigami::BasicListItem) is purely aesthetical. +The choice between using this view with `Kirigami.AbstractCard` components or a conventional `ListView` with [`AbstractListItem`](docs:kirigami2;AbstractListItem)/[BasicListItem](docs:kirigami2;BasicListItem) components is purely an aesthetic one. {{< sections >}} {{< section-left >}} @@ -180,13 +181,13 @@ Kirigami.CardsListView { ## CardsGridView -Use a [CardsGridView](docs:kirigami2;org::kde::kirigami::CardsGridView) for displaying cards in a grid. +Use a [`Kirigami.CardsGridView`](docs:kirigami2;org::kde::kirigami::CardsGridView) to display cards in a grid. -The behavior is the same as a CardsLayout, and it allows cards to be put in one or two columns depending on the available width. +Its behavior is the same as a `Kirigami.CardsLayout`, and it allows cards to be put in one or two columns depending on the available width. -CardsGridView has the limitation that every Card must have the same exact height, so `cellHeight` must be manually set to a value for which the content fits for every item. +CardsGridView has the limitation that every card must have the same exact height, so `cellHeight` must be manually set to a value for which the content must fit for every child card. -If possible use CardsGridView only when you need to instantiate many cards. If you only instantiate a few cards, use CardsLayout with a Repeater instead. +If possible use `Kirigami.CardsGridView` only when you need to instantiate many cards. If you are only going to instantiate a few cards, opt for a `Kirigami.CardsLayout` with a `Repeater` instead. {{< sections >}} {{< section-left >}} diff --git a/content/docs/kirigami/components-controls.md b/content/docs/kirigami/components-controls.md new file mode 100644 index 0000000000000000000000000000000000000000..b0d4bfae48d8f28b6d2dcacb9ad50b1ef6069c8a --- /dev/null +++ b/content/docs/kirigami/components-controls.md @@ -0,0 +1,296 @@ +--- +title: Controls and interactive elements +weight: 107 +description: Make your apps more interactive by using buttons, selection controls, sliders, and text fields. +group: components +--- + + +Kirigami offers a wide selection of different interactive elements that you can use in your applications. Each different type has slightly different interaction styles, visual styles, and functionality. Using the right type of control in your application can help make your user interface more responsive and intuitive. + +## Buttons + +In Kirigami apps, we use buttons from QtQuick Controls. Using them is pretty straightforward: we set the text to the `text` property and any action we want it to perform is set to the `onClicked` property. + +{{< sections >}} +{{< section-left >}} + +```qml +import QtQuick 2.0 +import QtQuick.Controls 2.2 as Controls +import QtQuick.Layouts 1.2 +import org.kde.kirigami 2.5 + +Kirigami.Page { + + Controls.Button { + text: "Beep!" + onClicked: showPassiveNotification("Boop!") + } + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A freshly-clicked button](controls-button.png) + +{{< /section-right >}} +{{< /sections >}} + +### Toggleable buttons + +Buttons' behaviour can be changed to make them toggleable: in this mode, they will stay pressed until clicked on once more. This mode can be activated by setting the `checkable` property to `true`; we can also set buttons to be toggled on by default by setting the `checked` property to `true`. + +We can get the most out of toggleable buttons by using the `onCheckedChanged` property. It works similarly to `onClicked`, except here the assigned action will be executed when the button's `checked` property changes. `checked` is a boolean property, which can come in handy for specific use-cases. + +In this example, we set the visibility of an in-line drawer according to the status of a toggleable button: + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.Button { + text: "Toggle!!" + checkable: true + checked: true + onCheckedChanged: myDrawer.visible = checked +} + +Kirigami.OverlayDrawer { + id: myDrawer + edge: Qt.BottomEdge + modal: false + + contentItem: Controls.Label { + text: "Peekaboo!" + } +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A toggleable button](controls-togglebutton.png) + +{{< /section-right >}} +{{< /sections >}} + +{{< alert title="Note" color="info" >}} + +With the default Breeze theme in KDE Plasma it can be hard to tell whether a button is toggled, since buttons are coloured blue when they are clicked on. Make sure you take this into account when creating your application: a different control might be more user-friendly. + +{{< /alert >}} + +### Toolbar buttons + +There is a specific button type meant for use in toolbars, `Controls.ToolButton`. The most obvious difference between this and a conventional button is the styling, with toolbuttons being flat (though this is alterable with the boolean property `flat`). + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.ToolButton { + text: "Tool beep..." + onClicked: showPassiveNotification("Tool boop!") +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A tool button](controls-toolbutton.png) + +{{< /section-right >}} +{{< /sections >}} + +## Selection controls + +Selection controls let users make a choice or pick an option. There are different types that are best suited to different situations. + +### Checkboxes + +Checkboxes are meant for options where the choices are non-exclusive and where each option has a clear alternative. + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.CheckBox { + text: "Beep!" + checked: true +} +Controls.CheckBox { + text: "Boop!" + checked: false +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A set of checkboxes](controls-checkbox.png) + +{{< /section-right >}} +{{< /sections >}} + +As you can see, they are simple to use. The property `checked` holds a boolean value determining whether or not they have been checked. + +### Radio buttons + +Radio buttons are designed for situations where the user must choose one option from a set of several options. + +Radio buttons are exclusive by default: only one button can be checked in the same parent item. + +Like checkboxes, they can be set to be checked or unchecked by default with the `checked` property. + +{{< sections >}} +{{< section-left >}} + +```qml +ColumnLayout { + Controls.RadioButton { + text: "Tick!" + checked: true + } + Controls.RadioButton { + text: "Tock!" + checked: false + } +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A set of radio buttons](controls-radiobutton.png) + +{{< /section-right >}} +{{< /sections >}} + +### Switches + +Switches are primarily designed for use on mobile devices. + +On the desktop, changing settings usually involves changing the setting and then applying the setting by clicking on an 'Apply' or 'OK' button. On mobile, we can use switches instead. + +Switches can be toggled between an on and off state. They can be clicked or tapped on to toggle them, or they can be dragged towards the 'on' or 'off' position. Once again, switches can be set to be on or off by default with the `checked` property. + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.Switch { + text: "Switchy" + checked: true +} +Controls.Switch { + text: "Swootchy" + checked: false +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A set of switches](controls-switch.png) + +{{< /section-right >}} +{{< /sections >}} + +## Sliders + +Sliders allow users to select certain values by sliding a handle along a track. Thanks to QtQuick Controls, there are several types that you can choose from depending on the values you'd like your users to choose from in your application. + +### Standard and tickmarked sliders + +A standard slider provides the user with very fine control over the selection they wish to make. + +By default, sliders go left to right to increase (and bottom up to increase when vertical). The coloration provides a visual indicator of how large the value you are selecting is. + +Sliders have a few important properties we must pay attention to: + +- `value`: contains the value at which the handle is placed, and can also be set manually to provide a default starting value +- `to`: defines the range of the slider by specifying the maximum value it can go to +- `orientation`: allows the slider to be set to a vertical orientation with `Qt.Vertical` + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.Slider { + id: normalSlider + orientation: Qt.Vertical + value: 5.0 + to: 10.0 +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A set of sliders](controls-sliders.png) + +{{< /section-right >}} +{{< /sections >}} + +Another useful property we can use is `stepSize`. Setting this to a numerical value allows us to create a slider that snaps onto values that are multiples of the specified `stepSize`, with these multiples being indicated by tickmarks. Therefore if we set this property to `2.0`, when the user drags the slider handle, they will only be able to select `0.0`, `2.0`, `4.0`, etc. up to the value specified in the `to` property. + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.Slider { + id: tickmarkedSlider + value: 6.0 + to: 10.0 + stepSize: 2.0 +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A set of tickmarked sliders](controls-tickmarkedsliders.png) + +{{< /section-right >}} +{{< /sections >}} + +### Range slider + +QtQuick Controls also provides ranged sliders. These have two handles, hence allowing you to define a range of numbers between the two handles. + +Two new properties are important to keep in mind: `first.value` and `second.value`, which hold the values of the two handles. Like the `value` property of the standard sliders, these can be pre-set. + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.RangeSlider { + id: rangeSlider + to: 10.0 + first.value: 3.0 + second.value: 6.0 +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A set of range sliders](controls-rangesliders.png) + +{{< /section-right >}} +{{< /sections >}} + +We can also make it a tickmarked slider by setting the `stepSize` property value to a number, in the exact same way as a standard slider. + +```qml +Controls.RangeSlider { + id: rangeTickmarkedSlider + to: 10.0 + first.value: 4.0 + second.value: 6.0 + stepSize: 2.0 +} +``` diff --git a/content/docs/kirigami/components-controls/controls-button.png b/content/docs/kirigami/components-controls/controls-button.png new file mode 100644 index 0000000000000000000000000000000000000000..b3cc32dd7d886bc0cfe590a89d063a51d910f3b1 Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-button.png differ diff --git a/content/docs/kirigami/components-controls/controls-checkbox.png b/content/docs/kirigami/components-controls/controls-checkbox.png new file mode 100644 index 0000000000000000000000000000000000000000..42b57ab0564116ce7f8a8dc73e1b950a7a22f437 Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-checkbox.png differ diff --git a/content/docs/kirigami/components-controls/controls-radiobutton.png b/content/docs/kirigami/components-controls/controls-radiobutton.png new file mode 100644 index 0000000000000000000000000000000000000000..7031e22d5de3181b91965ce25b34fa5e20c4d4a0 Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-radiobutton.png differ diff --git a/content/docs/kirigami/components-controls/controls-rangesliders.png b/content/docs/kirigami/components-controls/controls-rangesliders.png new file mode 100644 index 0000000000000000000000000000000000000000..f342569693dbabd67b358192771c78f350cb486f Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-rangesliders.png differ diff --git a/content/docs/kirigami/components-controls/controls-sliders.png b/content/docs/kirigami/components-controls/controls-sliders.png new file mode 100644 index 0000000000000000000000000000000000000000..dfda82b100dea68674ec015ab86a856500b86310 Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-sliders.png differ diff --git a/content/docs/kirigami/components-controls/controls-switch.png b/content/docs/kirigami/components-controls/controls-switch.png new file mode 100644 index 0000000000000000000000000000000000000000..07e4bd17e78162e32adfaa227d2d82b39caa0f0e Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-switch.png differ diff --git a/content/docs/kirigami/components-controls/controls-tickmarkedsliders.png b/content/docs/kirigami/components-controls/controls-tickmarkedsliders.png new file mode 100644 index 0000000000000000000000000000000000000000..67de65eb8e84a06209eaab163ff26091950dd7b0 Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-tickmarkedsliders.png differ diff --git a/content/docs/kirigami/components-controls/controls-togglebutton.png b/content/docs/kirigami/components-controls/controls-togglebutton.png new file mode 100644 index 0000000000000000000000000000000000000000..c8ff37c6b6d246ae64aa4ba668f03b6aa1822619 Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-togglebutton.png differ diff --git a/content/docs/kirigami/components-controls/controls-toolbutton.png b/content/docs/kirigami/components-controls/controls-toolbutton.png new file mode 100644 index 0000000000000000000000000000000000000000..b1dfb230c2d5c2efda7369db45a48349e175f280 Binary files /dev/null and b/content/docs/kirigami/components-controls/controls-toolbutton.png differ diff --git a/content/docs/kirigami/components-drawers.md b/content/docs/kirigami/components-drawers.md new file mode 100644 index 0000000000000000000000000000000000000000..f6c77744e300676fb9aca1bba940eb0d6599add0 --- /dev/null +++ b/content/docs/kirigami/components-drawers.md @@ -0,0 +1,297 @@ +--- +title: Drawers +weight: 105 +description: Drawers provide applications with quick access to controls and pages of your application. +group: components +--- + +Drawers are panels that slide out of the sides of the application window. They can be populated with interactive elements such as Kirigami Actions, buttons, text, and more. + +Drawers come in different types, shapes, and forms. In this page we will go over each type and provide an overview of their characteristics. + +## Global drawer + +The global drawer is a standard feature in KDE's mobile applications and can sometimes be found in their desktop incarnations too. It contains an application's main menu: included here are any functions that are not specific to the current page but still significant to general navigation or interaction within the application. + +`Kirigami.GlobalDrawer` components are what we use to create such drawers. These are set to the `globalDrawer` property of the `Kirigami.ApplicationWindow` that forms the basis of our Kirigami application. + +{{< sections >}} +{{< section-left >}} + +```qml +Kirigami.ApplicationWindow { + + globalDrawer: Kirigami.GlobalDrawer { + actions: [ + Kirigami.Action { + text: "Kirigami Action 1" + }, + Kirigami.Action { + text: "Kirigami Action 2" + }, + Kirigami.Action { + text: i18n("Quit") + icon.name: "gtk-quit" + shortcut: StandardKey.Quit + onTriggered: Qt.quit() + } + ] + } + + ... + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![Our new global drawer](globaldrawer_simple.png) + +{{< /section-right >}} +{{< /sections >}} + +### Header + +Headers can be used to place sticky components at the top of your global drawer. Header components will stay in place even if your global drawer contains nested Kirigami actions that replace the current layer on the global drawer. + +Your chosen header component can be set with the global drawer's `header` property. + +{{< sections >}} +{{< section-left >}} + +```qml +globalDrawer: Kirigami.GlobalDrawer { + + header: Kirigami.AbstractApplicationHeader { + + contentItem: Kirigami.SearchField { + id: searchField + Layout.fillWidth: true + } + + } + + actions: [ + Kirigami.Action { + text: "Kirigami Action 1" + }, + Kirigami.Action { + text: "Kirigami Action 2" + }, + Kirigami.Action { + text: i18n("Quit") + icon.name: "application-exit" + shortcut: StandardKey.Quit + onTriggered: Qt.quit() + } + ] +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![Search bar header global drawer](globaldrawer_header.png) + +Our global drawer now shows the search bar component we set as the header. + +{{< /section-right >}} +{{< /sections >}} + + +### Adapting for the desktop + +While panel-style global drawers can be useful in mobile environments, they might be too large on the desktop. + +Thankfully, Kirigami global drawers provide an `isMenu` property. When set to `true`, our global drawers turn into more traditional menus only on the desktop. + +{{< alert title="Note" color="info" >}} + +In this menu mode, headers and banners are not visible. + +{{< /alert >}} + +{{< sections >}} +{{< section-left >}} + +```qml +globalDrawer: Kirigami.GlobalDrawer { + isMenu: true + + actions: [ + Kirigami.Action { + text: "Kirigami Action 1" + }, + Kirigami.Action { + text: "Kirigami Action 2" + }, + Kirigami.Action { + text: i18n("Quit") + icon.name: "application-exit" + shortcut: StandardKey.Quit + onTriggered: Qt.quit() + } + ] +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![Global drawer as a menu on the desktop](globaldrawer_menu.png) + +{{< /section-right >}} +{{< /sections >}} + +### Banners + +Banners allow you to display a title and an icon at the top of your global drawer (even above the header). + +Titles, set with the `title` property, can be used to pretty up your global drawer and make it seem less sparse. More importantly, it can remind your users that this is a global and app-wide drawer rather than a local drawer. + +There is also a `titleIcon` property, which can be paired with your title to make the global drawer even more aesthetically pleasing. This icon will be placed to the left of the title. + +{{< sections >}} +{{< section-left >}} + +```qml +globalDrawer: Kirigami.GlobalDrawer { + title: "My Global Drawer" + titleIcon: "kde" + + actions: [ + Kirigami.Action { + text: "Kirigami Action 1" + }, + Kirigami.Action { + text: "Kirigami Action 2" + }, + Kirigami.Action { + text: i18n("Quit") + icon.name: "application-exit" + shortcut: StandardKey.Quit + onTriggered: Qt.quit() + } + ] +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![Global drawer with title and icon in banner](globaldrawer-banner.png) + +{{< /section-right >}} +{{< /sections >}} + +{{< alert title="Note" color="info" >}} + +The `titleIcon` property takes names for system-wide icons per the FreeDesktop specification. These icons and icon names can be viewed with KDE's CuttleFish application, or by visiting [FreeDesktop's icon naming specification](https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html). + +{{< /alert >}} + +However, by default, banners are only visible on mobile environments. You can change this by setting the global drawer component's `bannerVisible` property to `true`. + +## Modal and Inline drawers + +Kirigami offers two aditional types of drawers, modal drawers and inline drawers. They are quite similar to each other: both span the entirety of the application's width or height and can be placed on the edges of the app window. However, they do react differently to user interaction. + +- Modal drawers darken the rest of the application and, like overlay sheets, will be dismissed when clicking on a darkened area. +- Inline drawers allow the user to still interact with the rest of the application without being dismissed, and do not darken other areas. + +These two drawers are so similar because they are, in fact, the same Kirigami component: `Kirigami.OverlayDrawer`. Important properties of this component to keep in mind: + +- `modal` controls whether the drawer will be modal or inline depending on a boolean value +- `edge` controls which edge of the application window the drawer will appear on; options for this property are `Qt.TopEdge`, `Qt.RightEdge`, `Qt.BottomEdge`, and `Qt.LeftEdge` +- `contentItem` contains the component that will form the content of your drawer + +{{< sections >}} +{{< section-left >}} + +```qml +Kirigami.Page { + + Kirigami.OverlayDrawer { + id: bottomDrawer + edge: Qt.BottomEdge + // Set modal to false to make this drawer inline! + modal: true + + contentItem: RowLayout { + Layout.fillWidth: true + + Kirigami.Label { + Layout.fillWidth: true + text: "Say hello to my little drawer!" + } + Controls.Button { + text: "Close" + onClicked: bottomDrawer.close() + } + } + } + + Controls.Button { + text: "Open bottomDrawer" + onClicked: bottomDrawer.open() + } + +} +``` +{{< /section-left >}} +{{< section-right >}} + +{{< compare >}} +{{< figure class="text-center" caption="Modal drawer on the bottom edge of the screen." src="modal_drawer.png" >}} +{{< figure class="text-center" caption="Inline drawer on the bottom edge of the screen." src="inline_drawer.png" >}} +{{< /compare >}} + +{{< /section-right >}} +{{< /sections >}} + +### A usecase for overlay bottom drawers: NeoChat + +NeoChat uses bottom overlay drawers to provide user with a number of actions they can perform on a message they have long-pressed. Here is a simplified example of what that looks like: + +```qml +Kirigami.Page { + ListView { + model: App.MessageModel + delegate: MessageDelegate { + onPressAndHold: bottomDrawer.open() + } + } + + Kirigami.OverlayDrawer { + id: bottomDrawer + height: popupContent.implicitHeight + edge: Qt.BottomEdge + padding: 0 + leftPadding: 0 + rightPadding: 0 + bottomPadding: 0 + topPadding: 0 + + parent: applicationWindow().overlay + + ColumnLayout { + id: popupContent + width: parent.width + spacing: 0 + + // Message information + ... + + // Message actions + Kirigami.BasicListItem { + text: "Reply" + onClicked: { + bottomDrawer.close(); + } + } + ... + } + } +} +``` diff --git a/content/docs/kirigami/components-drawers/globaldrawer-banner.png b/content/docs/kirigami/components-drawers/globaldrawer-banner.png new file mode 100644 index 0000000000000000000000000000000000000000..f2a7b7ca3742f11f8e88dc97033bdcd044074e7e Binary files /dev/null and b/content/docs/kirigami/components-drawers/globaldrawer-banner.png differ diff --git a/content/docs/kirigami/components-drawers/globaldrawer_header.png b/content/docs/kirigami/components-drawers/globaldrawer_header.png new file mode 100644 index 0000000000000000000000000000000000000000..b9b265250678da9ad3fe79aafdb689d45d52f5fe Binary files /dev/null and b/content/docs/kirigami/components-drawers/globaldrawer_header.png differ diff --git a/content/docs/kirigami/components-drawers/globaldrawer_menu.png b/content/docs/kirigami/components-drawers/globaldrawer_menu.png new file mode 100644 index 0000000000000000000000000000000000000000..ea949d74df3e3b7a15b21144df3c7e97ac399c8a Binary files /dev/null and b/content/docs/kirigami/components-drawers/globaldrawer_menu.png differ diff --git a/content/docs/kirigami/components-drawers/globaldrawer_simple.png b/content/docs/kirigami/components-drawers/globaldrawer_simple.png new file mode 100644 index 0000000000000000000000000000000000000000..faa5ce7f1b89fd3bd8941b6b7e4fb40bb133c888 Binary files /dev/null and b/content/docs/kirigami/components-drawers/globaldrawer_simple.png differ diff --git a/content/docs/kirigami/components-drawers/inline_drawer.png b/content/docs/kirigami/components-drawers/inline_drawer.png new file mode 100644 index 0000000000000000000000000000000000000000..3e54c5d04e566e66a382302777401a825f97e1cc Binary files /dev/null and b/content/docs/kirigami/components-drawers/inline_drawer.png differ diff --git a/content/docs/kirigami/components-drawers/modal_drawer.png b/content/docs/kirigami/components-drawers/modal_drawer.png new file mode 100644 index 0000000000000000000000000000000000000000..122b63c7c73fe150c13dd5192620c6c6b7f430a0 Binary files /dev/null and b/content/docs/kirigami/components-drawers/modal_drawer.png differ diff --git a/content/docs/kirigami/components-formlayouts.md b/content/docs/kirigami/components-formlayouts.md new file mode 100644 index 0000000000000000000000000000000000000000..4974f8355b47c43b6da4c5c5df8cc17e152ae7c9 --- /dev/null +++ b/content/docs/kirigami/components-formlayouts.md @@ -0,0 +1,187 @@ +--- +title: Form Layouts +weight: 108 +description: Easily create attractive interaction areas with Kirigami FormLayouts +group: components +--- + +`Kirigami.FormLayout` components make it easy for you to create forms that conform to the KDE Human Interface Guidelines. They are optimal for settings dialogs and for large groups of controls and input fields that are related to each other. + +When provided with enough space, form layouts will take up two columns. The column on the left will be occupied by the labels provided for the form's children components, while the right will be taken up by the children itself. In more space-constrained windows (or on mobile), forms will consist of a single vertical column with children components' labels being placed above their respective component. + +## Simple form + +`Kirigami.FormLayout` components are similar in use to QtQuick Layout components such as `ColumnLayout` or `RowLayout`. The child components will be automatically arranged according to the size available to the form layout. + +Children of a `Kirigami.FormLayout` have a property named `Kirigami.FormData.label`. This property lets you set the label that will be provided for the child component in question. + +{{< sections >}} +{{< section-left >}} + +```qml +import QtQuick 2.6 +import QtQuick.Layouts 1.2 +import QtQuick.Controls 2.2 as Controls +import org.kde.kirigami 2.4 as Kirigami + +Kirigami.Page { + + Kirigami.FormLayout { + id: layout + Layout.fillWidth: true + + Controls.TextField { + Kirigami.FormData.label: "TextField 1:" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 2:" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 3:" + } + } + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A simple formlayout](formlayouts-simple.png) + +{{< /section-right >}} +{{< /sections >}} + +## Sections and separators + +FormLayouts can also be divided into sections. Setting where a section starts is as easy as setting a child component's `Kirigami.FormData.isSection` to true. This will provide the component with some extra margin at the top to demarcate the start of the new section. + +`Kirigami.Separator` components are best suited for starting new sections. A `Kirigami.Separator` will draw a thin horizontal line, demarcating the end of a section. If you would rather not have a line drawn between sections, you can use a standard QML `Item` property. Alternatively you could use the `Kirigami.FormData.isSection` property on any other component. + +However, this is not recommended. On components where `Kirigami.FormData.isSection` is set to true, the label text provided for this component's `Kirigami.FormData.label` property will be displayed as the section's header text. **This does not apply to every component, hence the recommendation that you use `Kirigami.Separator` or `Item` components in places where you would like to use a header text.** This header text is larger than the normal label text, and provides users with a nice visual cue of what the form layout section is about. + +{{< sections >}} +{{< section-left >}} + +```qml +Kirigami.FormLayout { + id: layout + Layout.fillWidth: true + + Controls.TextField { + Kirigami.FormData.label: "TextField 1:" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 2:" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 3:" + } + Kirigami.Separator { + Kirigami.FormData.isSection: true + Kirigami.FormData.label: "New Section!" + } + ColumnLayout { + Kirigami.FormData.label: "Radio buttons" + Controls.RadioButton { + text: "Radio 1" + checked: true + } + Controls.RadioButton { + text: "Radio 2" + } + Controls.RadioButton { + text: "Radio 3" + } + } + Item { + Kirigami.FormData.isSection: true + Kirigami.FormData.label: "Another Section! (lineless though)" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 4:" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 5:" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 5:" + } +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A formlayout with sections](formlayouts-sections.png) + +{{< /section-right >}} +{{< /sections >}} + + +## Checkable children + +A handy feature of `Kirigami.FormLayout` is that you can add checkboxes to its children. This can be useful in settings pages where you might want to let the user enable or disable a setting, and also want the user to provide some extra information in a component such as a textfield. + +```qml +Kirigami.FormLayout { + id: layout + Layout.fillWidth: true + + Controls.TextField { + Kirigami.FormData.label: "First name:" + } + Controls.TextField { + Kirigami.FormData.label: "Middle name:" + Kirigami.FormData.checkable: true + enabled: Kirigami.FormData.checked + } + Controls.TextField { + Kirigami.FormData.label: "Last name:" + } +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A formlayout with sections](formlayouts-checkable.png) + +{{< /section-right >}} +{{< /sections >}} + +## Forcing a desktop or mobile layout + +If you would rather have your form layout stay consistent regardless of your application's environment, you can use the `wideMode` property of the `Kirigami.FormLayout` component. `wideMode` is a boolean property: + +- When set to `true`, the form layout will be structured in a desktop-optimized widescreen (double-column) layout +- When set to `false`, the form layout will be structured in a mobile layout (single column) + +{{< sections >}} +{{< section-left >}} + +```qml +Kirigami.FormLayout { + id: layout + Layout.fillWidth: true + wideMode: false + + Controls.TextField { + Kirigami.FormData.label: "TextField 1:" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 2:" + } + Controls.TextField { + Kirigami.FormData.label: "TextField 3:" + } +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A formlayout with forced mobile layout](formlayouts-widemode.png) + +{{< /section-right >}} +{{< /sections >}} diff --git a/content/docs/kirigami/components-formlayouts/formlayouts-checkable.png b/content/docs/kirigami/components-formlayouts/formlayouts-checkable.png new file mode 100644 index 0000000000000000000000000000000000000000..b490f5a5b0c4b3751bd3c7328a6f56167cc3ed5e Binary files /dev/null and b/content/docs/kirigami/components-formlayouts/formlayouts-checkable.png differ diff --git a/content/docs/kirigami/components-formlayouts/formlayouts-sections.png b/content/docs/kirigami/components-formlayouts/formlayouts-sections.png new file mode 100644 index 0000000000000000000000000000000000000000..4b3128ea501541fd1f469a7a4525d3a68804c98f Binary files /dev/null and b/content/docs/kirigami/components-formlayouts/formlayouts-sections.png differ diff --git a/content/docs/kirigami/components-formlayouts/formlayouts-simple.png b/content/docs/kirigami/components-formlayouts/formlayouts-simple.png new file mode 100644 index 0000000000000000000000000000000000000000..08fc56820b20e38fe302a331ccc25ca01dcb4504 Binary files /dev/null and b/content/docs/kirigami/components-formlayouts/formlayouts-simple.png differ diff --git a/content/docs/kirigami/components-formlayouts/formlayouts-widemode.png b/content/docs/kirigami/components-formlayouts/formlayouts-widemode.png new file mode 100644 index 0000000000000000000000000000000000000000..457947764f14916f1cfd7553fe9f21a124bb30fc Binary files /dev/null and b/content/docs/kirigami/components-formlayouts/formlayouts-widemode.png differ diff --git a/content/docs/kirigami/components-inlinemessages.md b/content/docs/kirigami/components-inlinemessages.md new file mode 100644 index 0000000000000000000000000000000000000000..98d09aaf39671973b78275f8430f4a3ade9c0fce --- /dev/null +++ b/content/docs/kirigami/components-inlinemessages.md @@ -0,0 +1,222 @@ +--- +title: Inline messages +weight: 109 +description: Display messages related to the content in your application +group: components +--- + +Inline messages provide an immediate way for you to notify your users about something that happened while using the application. + +## Basic inline message + +`Kirigami.InlineMessage` components have two important properties to be mindful of: +- `visible`: by default this is set to false, so that the message only appears when you explicitly want it to. This can be overriden if you wish by setting it to true. When a hidden inline message is set to be visible, you get a nice animation. +- `text`: here is where you set the text of your inline message. + +{{< sections >}} +{{< section-left >}} + +```qml +import QtQuick 2.6 +import QtQuick.Layouts 1.2 +import QtQuick.Controls 2.2 as Controls +import org.kde.kirigami 2.4 as Kirigami + +Kirigami.Page { + + ColumnLayout { + Kirigami.InlineMessage { + id: inlineMessage + Layout.fillWidth: true + text: "Hello! I am a siiiiiiimple lil' inline message!" + } + + Controls.Button { + text: "Show inline message!" + onClicked: inlineMessage.visible = !inlineMessage.visible + } + } + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A simple inline message and button](inlinemessages-simple.png) + +{{< /section-right >}} +{{< /sections >}} + +## Different types + +Standard inline messages are like the ones above: they have a blue background and a default icon. We can change that with the `type` property, which lets us set our inline message to a different type. There are four types we can choose from: + +- **Information** (`Kirigami.MessageType.Information`): the default. Has a blue background, an 'i' icon, and is used to announce a result or tell the user something general. It is not necessary to manually set it. +- **Positive** (`Kirigami.MessageType.Positive`): has a green background, tick icon, and indicates that something went well. +- **Warning** (`Kirigami.MessageType.Warning`): has an orange background, an exclamation-mark icon, and can be used to warn the user about something they should be mindful of. +- **Error** (`Kirigami.MessageType.Error`): has a red background, a cross icon, and can be used to tell the user that something has gone wrong. + +{{< sections >}} +{{< section-left >}} + +```qml +ColumnLayout { + + Kirigami.InlineMessage { + Layout.fillWidth: true + text: "Hello! Let me tell you something interesting!" + visible: true + } + + Kirigami.InlineMessage { + Layout.fillWidth: true + text: "Hey! Let me tell you something positive!" + type: Kirigami.MessageType.Positive + visible: true + } + + Kirigami.InlineMessage { + Layout.fillWidth: true + text: "Hmm... You should keep this in mind!" + type: Kirigami.MessageType.Warning + visible: true + } + + Kirigami.InlineMessage { + Layout.fillWidth: true + text: "Argh!!! Something went wrong!!" + type: Kirigami.MessageType.Error + visible: true + } + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![Different inline message types](inlinemessages-types.png) + +{{< /section-right >}} +{{< /sections >}} + +## Customising text and icons + +Inline messages support rich text, which can be defined with simple HTML-like markup. This allows you to add some formatting to your inline message's text or even include an external web link if you want to. + +{{< sections >}} +{{< section-left >}} + +```qml +Kirigami.InlineMessage { + Layout.fillWidth: true + // Note that when you use quotes in a string you will have to escape them! + text: "Check out KDE's website!" + onLinkActivated: Qt.openUrlExternally(link) + visible: true +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![An inline message with rich text](inlinemessages-richtext.png) + +{{< /section-right >}} +{{< /sections >}} + +You can also customise the icon that appears on the top-left of your message by providing a system icon name for the `icon.source` property. These icon names should correspond to icons installed on your system; you can use an application such as Cuttlefish to browse and search the icons available on your system, and what their names are. + +{{< sections >}} +{{< section-left >}} + +```qml +Kirigami.InlineMessage { + Layout.fillWidth: true + text: "Look at me! I look SPECIAL!" + icon.source: "actor" + visible: true +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![An inline message with a specified icon](inlinemessages-icon.png) + +{{< /section-right >}} +{{< /sections >}} + +## Using actions in inline messages + +If your messages need to be interactive, you can attach Kirigami actions to your inline messages. Like with pages, you can do this by setting the inline message's `actions` property to either a `Kirigami.Action` or an array containing `Kirigami.Action` components. + +{{< sections >}} +{{< section-left >}} + +```qml +ColumnLayout { + + Kirigami.InlineMessage { + id: actionsMessage + Layout.fillWidth: true + visible: true + + readonly property string initialText: "Something is hiding around here..." + text: initialText + + actions: [ + Kirigami.Action { + enabled: actionsMessage.text == actionsMessage.initialText + text: qsTr("Add text") + icon.name: "list-add" + onTriggered: { + actionsMessage.text = actionsMessage.initialText + " Peekaboo!"; + } + }, + Kirigami.Action { + enabled: actionsMessage.text != actionsMessage.initialText + text: qsTr("Reset text") + icon.name: "list-remove" + onTriggered: actionsMessage.text = actionsMessage.initialText + } + ] + } + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![An inline message with two actions](inlinemessages-actions.png) + +{{< /section-right >}} +{{< /sections >}} + +## Close buttons + +Inline messages provide a close button that can be used to easily dismiss them. + +By default, this close button is hidden, but this can be overridden by setting the `showCloseButton` property to `true`. + +{{< sections >}} +{{< section-left >}} + +```qml +Kirigami.InlineMessage { + Layout.fillWidth: true + text: "Please don't dismiss me..." + showCloseButton: true + visible: true +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![An inline message with close button showing](inlinemessages-closebutton.png) + +{{< /section-right >}} +{{< /sections >}} diff --git a/content/docs/kirigami/components-inlinemessages/inlinemessages-actions.png b/content/docs/kirigami/components-inlinemessages/inlinemessages-actions.png new file mode 100644 index 0000000000000000000000000000000000000000..48a155332e87abd5cc2a27418042043ccfb66e1c Binary files /dev/null and b/content/docs/kirigami/components-inlinemessages/inlinemessages-actions.png differ diff --git a/content/docs/kirigami/components-inlinemessages/inlinemessages-closebutton.png b/content/docs/kirigami/components-inlinemessages/inlinemessages-closebutton.png new file mode 100644 index 0000000000000000000000000000000000000000..6784f80fddab28df5cb84598ab4e37f77312642d Binary files /dev/null and b/content/docs/kirigami/components-inlinemessages/inlinemessages-closebutton.png differ diff --git a/content/docs/kirigami/components-inlinemessages/inlinemessages-richtext.png b/content/docs/kirigami/components-inlinemessages/inlinemessages-richtext.png new file mode 100644 index 0000000000000000000000000000000000000000..7633d983182a33f1257c7d1ede438ac0155b0928 Binary files /dev/null and b/content/docs/kirigami/components-inlinemessages/inlinemessages-richtext.png differ diff --git a/content/docs/kirigami/components-inlinemessages/inlinemessages-simple.png b/content/docs/kirigami/components-inlinemessages/inlinemessages-simple.png new file mode 100644 index 0000000000000000000000000000000000000000..e2a4679141ee71b408e2a4d0977f513a2d8228bc Binary files /dev/null and b/content/docs/kirigami/components-inlinemessages/inlinemessages-simple.png differ diff --git a/content/docs/kirigami/components-inlinemessages/inlinemessages-types.png b/content/docs/kirigami/components-inlinemessages/inlinemessages-types.png new file mode 100644 index 0000000000000000000000000000000000000000..e966e450d37c22ca94cd979a666a6a1c2d9785bf Binary files /dev/null and b/content/docs/kirigami/components-inlinemessages/inlinemessages-types.png differ diff --git a/content/docs/kirigami/components-inlinemessages/inlinemessges-icon.png b/content/docs/kirigami/components-inlinemessages/inlinemessges-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..409dc7bf04845a10282d7c609cb82338f0b2af05 Binary files /dev/null and b/content/docs/kirigami/components-inlinemessages/inlinemessges-icon.png differ diff --git a/content/docs/kirigami/components-listview.md b/content/docs/kirigami/components-listview.md new file mode 100644 index 0000000000000000000000000000000000000000..dcd2b96da142e0d8b70f760fb3cc892164537b51 --- /dev/null +++ b/content/docs/kirigami/components-listview.md @@ -0,0 +1,169 @@ +--- +title: List views +weight: 112 +group: "components" +description: > + A list view can help you easily display many components dynamically. +--- + +Listviews can help you display objects from a model in an attractive way. To use a list view, you have to keep track of three things: + +1. The **model**, which contains the data you want your list view to display +2. The **delegate**, which defines how each element in the model will be displayed +3. The **list view** itself, which will display information from the model according to the delegate + +If you would like further clarification, the Qt documentation has [an informative page](https://doc.qt.io/qt-5/qtquick-modelviewsdata-modelview.html) on the topic. + +## Creating a basic listview + +A list view has two essential properties we must pay attention to: + +- `model`, which accepts the data or the `id` of the object that holds the data +- `delegate`, which accepts the component we will use to display the data in the model + +{{< sections >}} +{{< section-left >}} + +```qml +import QtQuick 2.6 +import QtQuick.Controls 2.0 as Controls +import QtQuick.Layouts 1.2 +import org.kde.kirigami 2.13 as Kirigami + +Kirigami.Page { + + ListView { + id: myList + + // Providing a number for the model property + // will generate that number of data entries + // starting from 0. + model: 200 + + delegate: Kirigami.BasicListItem { + label: "Item " + modelData + } + } + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A simple listview](listview-simple.png) + +{{< /section-right >}} +{{< /sections >}} + +In cases where your model data only contain a single piece of data, like in the example above, you can just grab the data in the model by referencing `modelData`. + +A note on delegates: if your model contains objects with data in named properties, the name of these properties will be automatically exposed to your delegate and you will only need to use these names in your delegate. + +```qml +ListModel { + id: myModel + ListElement { type: "Item"; number: 0 } + ListElement { type: "Item"; number: 1 } + ListElement { type: "Item"; number: 2 } + ListElement { type: "Item"; number: 3 } +} + +ListView { + id: myList + + model: myModel + + delegate: Kirigami.BasicListItem { + label: type + " " + number + } +} +``` + +Kirigami offers a number of components that have been designed specifically for use in list views, such as `Kirigami.BasicListItem`, `Kirigami.CheckableListItem` and `Kirigami.SwipeListItem`, all of which build upon `Kirigami.AbstractListItem`. There are also `Kirigami.CheckDelegate`, `Kirigami.RadioDelegate`, and `Kirigami.SwitchDelegate`, which are designed to take advantage of those specific controls. + +However, you are not limited to using these components and can choose whichever ones you wish - though this may mean some tweaking to your layout. + +## Placeholder messages + +In some cases, you might want to use a list view that is empty until the user does something. In these situations, using a `Kirigami.PlaceholderMessage` can be an attractive way of telling your user that the list is empty and that they can do something about it. + +You will generally want to place a PlaceholderMessage in the center of the ListView and you will want it to not span the entire width of the ListView either. You will obviously also want it to not be visible once the ListView's model becomes populated with data: thankfully, ListViews have a property named `count` that makes doing this quite easy. + +You might also want to add a helpful action to your placeholder message. This can be done by attaching an action to the `Kirigami.PlaceHolderMessage`'s `helpfulAction` property. + +{{< sections >}} +{{< section-left >}} + +```qml +ListView { + id: myList + + model: ListModel { id: myModel } + + delegate: Kirigami.BasicListItem { + label: text + } + + Kirigami.PlaceholderMessage { + anchors.centerIn: parent + width: parent.width - (Kirigami.Units.largeSpacing * 4) + + visible: myList.count === 0 + text: "Add something to me!" + helpfulAction: Kirigami.Action { + icon.name: "list-add" + text: "Add" + onTriggered: myModel.append({"text": "Hello!!"}) + } + } +} + +``` + +{{< /section-left >}} +{{< section-right >}} + +![A list view with a placeholder message](listview-placeholdermessage.png) + +{{< /section-right >}} +{{< /sections >}} + +## List headers + +ListViews also support header components with the `header` property, and Kirigami provides an attractive component for this purpose: `Kirigami.ItemViewHeader`. We provide this component with text for the `title` property and with an image location for the `backgroundImage.source` property and we are set. + +An interesting property of the list view is `headerPositioning`. This affects the way that our header will move when we are interacting with a long list view that expands beyond the height of the page. `headerPositioning` can be set to three different settings: + +- `ListView.OverlayHeader`: In this setting, the header will contract once we start scrolling down but will remain visible in a more compact state. +- `ListView.PullBackHeader`: The header will disappear as we scroll down, but will reappear as we scroll back up, even if we haven'tyet reached the top of the list view. +- `ListView.InlineHeader`: The header will act like a part of the listview and remain at the top of the listview. + +{{< sections >}} +{{< section-left >}} + +```qml +ListView { + id: myList + + headerPositioning: ListView.OverlayHeader + header: Kirigami.ItemViewHeader { + backgroundImage.source: "../banner.jpg" + title: "LongListView" + } + + model: 200 + + delegate: Kirigami.BasicListItem { + label: "Item " + modelData + } +} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A listview with a header](listview-header.png) + +{{< /section-right >}} +{{< /sections >}} diff --git a/content/docs/kirigami/components-listview/listview-header.png b/content/docs/kirigami/components-listview/listview-header.png new file mode 100644 index 0000000000000000000000000000000000000000..b9b4ab72b44f3237832b60b2a3b9853927e7a8a6 Binary files /dev/null and b/content/docs/kirigami/components-listview/listview-header.png differ diff --git a/content/docs/kirigami/components-listview/listview-placeholdermessage.png b/content/docs/kirigami/components-listview/listview-placeholdermessage.png new file mode 100644 index 0000000000000000000000000000000000000000..ced396111062bc268ebd7d51a65413d83e4f6e3d Binary files /dev/null and b/content/docs/kirigami/components-listview/listview-placeholdermessage.png differ diff --git a/content/docs/kirigami/components-listview/listview-simple.png b/content/docs/kirigami/components-listview/listview-simple.png new file mode 100644 index 0000000000000000000000000000000000000000..b9c6299e0f0833c61a8948e53169174b8731cbe5 Binary files /dev/null and b/content/docs/kirigami/components-listview/listview-simple.png differ diff --git a/content/docs/kirigami/components-overlaysheets.md b/content/docs/kirigami/components-overlaysheets.md new file mode 100644 index 0000000000000000000000000000000000000000..8b8c9d4eadfe9f2c3796785cd274d6258cb0b404 --- /dev/null +++ b/content/docs/kirigami/components-overlaysheets.md @@ -0,0 +1,208 @@ +--- +title: Overlay sheets +weight: 106 +description: Overlay sheets can serve a variety of uses for both serving and inputting data. +group: components +--- + +Overlay sheets provide a simple component that you can use to supplement the content being displayed on an application's page. They are designed to display long, vertical content and can accomodate content longer than the application window itself. + +They can be dismissed by clicking or tapping outside of their area or by clicking the 'x' icon on sheets' headers. + +## Learning about the sheet + +In order to use an overlay sheet, we should create it inside the Kirigami Page we want it to appear in. + +{{< sections >}} +{{< section-left >}} +```qml +import QtQuick 2.0 +import QtQuick.Controls 2.0 as Controls +import QtQuick.Layouts 1.2 +import org.kde.kirigami 2.5 as Kirigami + +Kirigami.Page { + id: page + Layout.fillWidth: true + + Kirigami.OverlaySheet { + id: mySheet + Controls.Label { + Layout.fillWidth: true + wrapMode: Text.WordWrap + text: "Weeeeee, overlay sheet!" + } + } +} +``` +{{< /section-left >}} + +{{< section-right >}} + +![Simple overlay sheet](sheet_simple.png) + +{{< /section-right >}} +{{< /sections >}} + +Overlay sheets come with methods we can use to open (`mySheet.open()`) or close (`mySheet.close()`) them as we see fit. By default overlay sheets are hidden, so at the very least we will need to use the `open()` method. + +```qml +Controls.Button { + text: "Open mySheet" + onClicked: mySheet.open() +} +``` + +When opened, this overlay sheet will appear centered vertically and horizontally within its parent page. Horizontally it will be bounded by its parent even if its contents' width exceeds its parent's. If the sheet's vertical length exceeds its' parent's, then the sheet will be displayed from its top position, and will be scrollable. + +## Global sheet + +If you want to display the sheet as a global sheet — one that spans across the entire width of the application, regardless of the page it is a child to — we have to reparent our overlay sheet to our application window's overlay property. We can do this with the `parent` property. + +{{< sections >}} +{{< section-left >}} +```qml +Kirigami.OverlaySheet { + id: mySheet + + parent: applicationWindow().overlay + + Controls.Label { + Layout.fillWidth: true + wrapMode: Text.WordWrap + text: "Weeeeee, overlay sheet!" + } +} +``` +{{< /section-left >}} + +{{< section-right >}} + +{{< compare >}} +{{< figure class="text-center" caption="Non-global overlay sheet" src="sheet_global_before.png" >}} +{{< figure class="text-center" caption="Global overlay sheet" src="sheet_global_after.png" >}} +{{< /compare >}} + +{{< /section-right >}} +{{< /sections >}} + +## Fixed sizing + +A sheet is greedy and will take the maximum amount of available width in a page if needed. We can avoid this by specifying an `implicitWidth` or a `Layout.preferredWidth` for its child elements, which will limit how much the sheet will grow width-wise. + +{{< sections >}} +{{< section-left >}} +```qml +Kirigami.OverlaySheet { + id: mySheet + Controls.Label { + Layout.preferredWidth: Kirigami.Units.gridUnit * 25 + wrapMode: Text.WordWrap + text: "Weeeeee, overlay sheet! I'm so excited!! WEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE WEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE WEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE WEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE WEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE!!!!!" + } +} +``` +{{< /section-left >}} + +{{< section-right >}} + +{{< compare >}} +{{< figure class="text-center" caption="Non-fixed width overlay sheet" src="sheet_fixedwidth_before.png" >}} +{{< figure class="text-center" caption="Fixed width overlay sheet" src="sheet_fixedwidth_after.png" >}} +{{< /compare >}} + +{{< /section-right >}} +{{< /sections >}} + +## Headers and footers + +Overlay sheets come by default with a header which only contains a button for closing our overlay sheet. We can add a Kirigami heading as a title in our header to make it easy for users to understand what the sheet is for. This is done by setting the `header` property to contain our Kirigami heading component. + +{{< sections >}} +{{< section-left >}} +```qml +Kirigami.OverlaySheet { + id: mySheet + + header: Kirigami.Heading { + text: "My Overlay Sheet" + } + + Controls.Label { + Layout.fillWidth: true + wrapMode: Text.WordWrap + text: "Weeeeee, overlay sheet!" + } +} +``` +{{< /section-left >}} + +{{< section-right >}} + +![Sheet header](sheet_header.png) + +{{< /section-right >}} +{{< /sections >}} + +We can also provide our overlay sheet with a footer. Footers in overlay sheets are quite flexible, but most often they are used to provide overlay sheets with some sort of quick interactive input similar to that provided by modal dialogs (e.g. buttons for 'Apply', 'Ok', 'Cancel', 'Close', etc.) + +Footers are set in much the same way as headers: + +{{< sections >}} +{{< section-left >}} +```qml +Kirigami.OverlaySheet { + id: mySheet + + header: Kirigami.Heading { + text: "My Overlay Sheet" + } + + footer: Controls.DialogButtonBox { + standardButtons: DialogButtonBox.Close + onRejected: mySheet.close() + } + + Controls.Label { + Layout.fillWidth: true + wrapMode: Text.WordWrap + text: "Weeeeee, overlay sheet!" + } +} +``` +{{< /section-left >}} + +{{< section-right >}} + +![Sheet footer](sheet_footer.png) + +{{< /section-right >}} +{{< /sections >}} + +## Using delegate / model views + +Since overlay sheets are designed to display vertical content, they can be especially useful when used in conjunction with components such as ListViews. When displaying content longer than the application window itself, the overlay sheet becomes scrollable: + +{{< sections >}} +{{< section-left >}} +```qml +Kirigami.OverlaySheet { + id: mySheet + + ListView { + model: 100 + implicitWidth: Kirigami.Units.gridUnit * 30 + delegate: Kirigami.BasicListItem { + label: "Item in sheet " + modelData + } + } +} +``` +{{< /section-left >}} + +{{< section-right >}} + +![Sheet with a listview](sheet_listview.png) + +{{< /section-right >}} +{{< /sections >}} diff --git a/content/docs/kirigami/components-overlaysheets/sheet_fixedwidth_after.png b/content/docs/kirigami/components-overlaysheets/sheet_fixedwidth_after.png new file mode 100644 index 0000000000000000000000000000000000000000..f0cef929ecbfb9a465bf2c829ac779855fcf0983 Binary files /dev/null and b/content/docs/kirigami/components-overlaysheets/sheet_fixedwidth_after.png differ diff --git a/content/docs/kirigami/components-overlaysheets/sheet_fixedwidth_before.png b/content/docs/kirigami/components-overlaysheets/sheet_fixedwidth_before.png new file mode 100644 index 0000000000000000000000000000000000000000..25637647a72b55acb495d7092933b9eeb35cdf2f Binary files /dev/null and b/content/docs/kirigami/components-overlaysheets/sheet_fixedwidth_before.png differ diff --git a/content/docs/kirigami/components-overlaysheets/sheet_footer.png b/content/docs/kirigami/components-overlaysheets/sheet_footer.png new file mode 100644 index 0000000000000000000000000000000000000000..09a2a698c3c42da7cb2b9fafc6e24e9515a77a49 Binary files /dev/null and b/content/docs/kirigami/components-overlaysheets/sheet_footer.png differ diff --git a/content/docs/kirigami/components-overlaysheets/sheet_global_after.png b/content/docs/kirigami/components-overlaysheets/sheet_global_after.png new file mode 100644 index 0000000000000000000000000000000000000000..dec57ca697ac487795d3052b833243a2d1607cdf Binary files /dev/null and b/content/docs/kirigami/components-overlaysheets/sheet_global_after.png differ diff --git a/content/docs/kirigami/components-overlaysheets/sheet_global_before.png b/content/docs/kirigami/components-overlaysheets/sheet_global_before.png new file mode 100644 index 0000000000000000000000000000000000000000..19d3229588369d9b65da5ea4ed6e431198045338 Binary files /dev/null and b/content/docs/kirigami/components-overlaysheets/sheet_global_before.png differ diff --git a/content/docs/kirigami/components-overlaysheets/sheet_header.png b/content/docs/kirigami/components-overlaysheets/sheet_header.png new file mode 100644 index 0000000000000000000000000000000000000000..78a866cb9047bc6db74405602f8229185ab72a55 Binary files /dev/null and b/content/docs/kirigami/components-overlaysheets/sheet_header.png differ diff --git a/content/docs/kirigami/components-overlaysheets/sheet_listview.png b/content/docs/kirigami/components-overlaysheets/sheet_listview.png new file mode 100644 index 0000000000000000000000000000000000000000..fa5a4c8d6c9cb42de101871715680dc4c16e1e81 Binary files /dev/null and b/content/docs/kirigami/components-overlaysheets/sheet_listview.png differ diff --git a/content/docs/kirigami/components-overlaysheets/sheet_simple.png b/content/docs/kirigami/components-overlaysheets/sheet_simple.png new file mode 100644 index 0000000000000000000000000000000000000000..a13685c6de5a6c3c038593cdb139157da7073ece Binary files /dev/null and b/content/docs/kirigami/components-overlaysheets/sheet_simple.png differ diff --git a/content/docs/kirigami/manipulate-pages.md b/content/docs/kirigami/components-pagerow_pagestack.md similarity index 50% rename from content/docs/kirigami/manipulate-pages.md rename to content/docs/kirigami/components-pagerow_pagestack.md index 83f8f531dbb42621d13375cc24f237f304ad8024..3734aef2f42dc95ea14fd6b39c20c34601ff0b85 100644 --- a/content/docs/kirigami/manipulate-pages.md +++ b/content/docs/kirigami/components-pagerow_pagestack.md @@ -1,34 +1,32 @@ --- -title: Pages manipulation -description: "Add flow to your application: Add, remove and replace pages" -weight: 103 +title: Pagerows and page stacks +description: "Add flow to your application: Add, remove and replace pages in different ways" +weight: 102 group: introduction --- ## The PageRow The [PageRow](docs:kirigami2;PageRow) is a container that lays out items -horizontally in a row, when not all items fit in the PageRow, it will behave -like a Flickable and will be a scrollable view which shows only a determined -number of columns. +horizontally in a row. If all child items don't fit in the PageRow, it will behave +like a `Flickable` surface and will become a horizontal scrollable view of columns. -A PageRow can show a single page or a multiple set of columns, depending on -the window width: on a phone, a single column should be fullscreen, while on -a tablet or a desktop more than one column should be visible. +A PageRow can show a single page or several of them as columns, depending on +the window width. On a phone, a single column will be viewable, while on +a tablet or a desktop more than one column should be visible at once. The columns can either all have the same fixed size, size themselves with -implicitWidth, or automatically expand to take all the available width: by -default the last column will always be the expanding one. +`implicitWidth`, or automatically expand to take up all available width. By +default, the last column will expand to take up all available space. {{< img alt="Screenshot of a PageRow" src="columnview.png" >}} -You can access the column view methods from the `pageStack` property from your +You can access the column view methods from the `pageStack` property of your [Kirigami.ApplicationWindow](docs:kirigami2;ApplicationWindow) element or from anywhere else using `applicationWindow().pageStack`. -The initial page is added with the `pageStack.initialPage` property. For -example in a simple application that requires a user to authenticate themselves -with a server, the initial page should be the login page. +The initial page is added with the `pageStack.initialPage` property. As an example: in a simple application +that required the user to authenticate themselves, the initial page would be a login page. ```qml Kirigami.ApplicationWindow { @@ -36,11 +34,11 @@ Kirigami.ApplicationWindow { } ``` -Once the user logs into the application, we need to replace the login -page with the home page of the application. For this, we will use -`pageStack.replace`, to remove the LoginPage and replace it with an HomePage. +Once the user logged into the application, you would need to replace the login +page with the home page of the application. To do this, you would use +`pageStack.replace`, removing the LoginPage and replacing it with a HomePage. -``` +```qml // LoginPage.qml Kirigami.Page { // login formular @@ -50,7 +48,7 @@ Kirigami.Page { const user = Backend.authentificate(usernameField.text, passwordField.text); if (user) { applicationWindow().pageStack.replace("qrc:/HomePage.qml", { - user: user, // give the registerd user information to the homepage + user: user, // give the registered user information to the homepage }); } else { // display error message @@ -61,12 +59,12 @@ Kirigami.Page { ``` {{< alert color="info" title="Note" >}} -`pageStack.replace` takes either an url to a qml file or a QML Component. +`pageStack.replace` accepts either a QML Component or aurl to a QML file. {{< /alert >}} -Now let's imagine we have a configuration page and we want the user to -access it from the HomePage. Here we want the user to go back to the -HomePage, so we can't use `replace` and instead we will use `push` to +Now let's imagine you had a configuration page you wanted the user to +access from the HomePage. You'd want the user to go back to the +HomePage, so you can't use `replace`. Instead, you would use `push` to push a new page in the stack. ```qml @@ -76,20 +74,21 @@ Kirigami.Page { } ``` -```js +```qml // HomePage.qml applicationWindow().pageStack.push("qrc:/MyPage.qml", { 'var1': 'Hello', }); ``` -A page row provides more than just the `replace` and `push` method. You can also [pop](docs:kirigami2;PageRow::pop) -a page, or use [insertPage](docs:kirigami2;PageRow::insertPage) to insert a page at a specific -position in the stack, use [movePage](docs:kirigami2;PageRow::movePage) to move pages or -[clear](docs:kirigami2;PageRow::clear) to remove all the page from stack. +You can also: +- [pop](docs:kirigami2;PageRow::pop) a page (which removes the last page in the stack) or +- use [insertPage](docs:kirigami2;PageRow::insertPage) to insert a page at a specific position in the stack, +- use [movePage](docs:kirigami2;PageRow::movePage) to move specific pages within the stack, or +- [clear](docs:kirigami2;PageRow::clear) all pages from the stack. -You can also modify `currentIndex` to change the currently active page programmatically or -use [flickBack](docs;Kirigami2;PageRow::flickBack) to simulate moving a page back in the +You can also modify `currentIndex` to change the currently active page programmatically, or +use [flickBack](docs;Kirigami2;PageRow::flickBack) to simulate moving a page backwards in the stack. ## Layers diff --git a/content/docs/kirigami/components-progressbars.md b/content/docs/kirigami/components-progressbars.md new file mode 100644 index 0000000000000000000000000000000000000000..8c79d75945488884c0f898634fd4155bd836746c --- /dev/null +++ b/content/docs/kirigami/components-progressbars.md @@ -0,0 +1,75 @@ +--- +title: Progress Bars and Indicators +weight: 111 +description: Provide your users with loading state information using progress bars. +group: components +--- + +Whenever your application does something that takes a noticeable amount of time, you will want to use a visual element that tells the user that something is happening in the background. + +QtQuick Controls provides two useful components that you can use to this end. + +## Progress bar + +`Controls.ProgressBar` is a component that lets you easily include progress bars in your application. There are four main properties you will need to use: + +- `from`: the minimum value represented by the start of the progress bar +- `to`: the maximum value represented by the end of the progress bar +- `value`: the current value of the action that is in progress (e.g. 50% loaded) +- `indeterminate`: if the action that is in process currently has no clear progress value, you can set this property to true to show the user something is happening but its progress is not yet clear (but will be soon). + +{{< sections >}} +{{< section-left >}} + +```qml +import QtQuick 2.6 +import QtQuick.Controls 2.0 as Controls +import QtQuick.Layouts 1.2 +import org.kde.kirigami 2.13 as Kirigami + +Kirigami.Page { + + Controls.ProgressBar { + from: 0 + to: 100 + value: 50 + indeterminate: false + } + +} +``` + +{{< /section-left >}} +{{< section-right >}} + +{{< figure class="text-center" caption="Above: progress bar at 50%; Below: indeterminate progress bar" src="progressbar-both.png" >}} + +{{< /section-right >}} +{{< /sections >}} + +## Busy indicator + +In cases where loading times are shorter or measuring progress is not feasible, you can instead use `Controls.BusyIndicator`. This component provides a simple spinning wheel that shows users that something is happening. + +{{< sections >}} +{{< section-left >}} + +```qml +Controls.BusyIndicator {} +``` + +{{< /section-left >}} +{{< section-right >}} + +![A busy indicator](busyindicator.png) + +{{< /section-right >}} +{{< /sections >}} + +If you want the indicator to stop running, you can do so by setting the `running` property to false. + +```qml +Controls.BusyIndicator { + running: false +} +``` diff --git a/content/docs/kirigami/components-progressbars/busyindicator.png b/content/docs/kirigami/components-progressbars/busyindicator.png new file mode 100644 index 0000000000000000000000000000000000000000..a234020442eb0956fde0ae79c826aec4630e2c2b Binary files /dev/null and b/content/docs/kirigami/components-progressbars/busyindicator.png differ diff --git a/content/docs/kirigami/components-progressbars/progressbar-both.png b/content/docs/kirigami/components-progressbars/progressbar-both.png new file mode 100644 index 0000000000000000000000000000000000000000..78fcdb4b185394485fe3f33cf2d1a61b7110c6a2 Binary files /dev/null and b/content/docs/kirigami/components-progressbars/progressbar-both.png differ diff --git a/content/docs/kirigami/components-scrollable_pages.md b/content/docs/kirigami/components-scrollablepages_listviews.md similarity index 55% rename from content/docs/kirigami/components-scrollable_pages.md rename to content/docs/kirigami/components-scrollablepages_listviews.md index 73cc9fe619a390c3906a7163b6df1fca1d2435f7..06a2b1a316856fec71045bd54a32e789f6f789be 100644 --- a/content/docs/kirigami/components-scrollable_pages.md +++ b/content/docs/kirigami/components-scrollablepages_listviews.md @@ -1,18 +1,18 @@ --- -title: Scrollable Pages -weight: 104 +title: Scrollable Pages and List Views +weight: 103 group: components -description: Scrollable page are special Kirigami Pages that can contains scrollable content. +description: Scrollable pages are useful when combined with vertical components or dynamic components such as List Views. --- ## `Kirigami.ScrollablePage` -A [ScrollablePage](docs:kirigami2;ScrollablePage) -is a Page that holds scrollable content, such as ListViews. Scrolling and scrolling indicators will -be automatically managed. +A [`Kirigami.ScrollablePage`](docs:kirigami2;ScrollablePage) +is a page that holds scrollable content, such as `ListView`s. Scrolling and scrolling indicators are +automatically managed. ```qml -ScrollablePage { +Kirigami.ScrollablePage { id: root //The rectangle will automatically be scrollable Rectangle { @@ -22,32 +22,35 @@ ScrollablePage { } ``` +In almost every other way, a scrollable page is the same as a normal page. + {{< alert color="danger" title="Warning" >}} -Do not put a ScrollView inside of a ScrollablePage; children of a -ScrollablePage are already inside a ScrollView. +Do not put a `ScrollView` inside of a `Kirigami.ScrollablePage`; children of a +`Kirigami.ScrollablePage` are already inside a `ScrollView`. {{< /alert >}} -## ListView in ScrollPage +## ListView in a ScrollablePage -If a ScrollablePage contains a single direct child item and this child item -is a ListView when the ListView covers the entire page and adds a scrollbar -to the right. +When a `Kirigami.ScrollablePage`'s direct children extend vertically beyond the size of the +page itself, a scrollbar appears at the right edge of the page and the page +will be scrollable. {{< figure src="neochatscrollablepage.png" alt="NeoChat Scrollable Page Screenshot" - caption="Two scrollable pages containing both a ListView with custom contents (Screenshot of NeoChat)" >}} + caption="Two scrollable pages, both containing a ListView with custom contents (Screenshot of NeoChat)" >}} -Often you have more than one child in your ScrollablePage, there are two -ways to fix this. +Often you have more than one child in your `Kirigami.ScrollablePage`, and positioning items +can be tricky - especially in combination with a `ListView`. -* For non-visual objects having them inside the ListView element won't change - the visual of the page. So we can move them inside the ListView. Same for - elements anchored to the center of the page. +* For non-visual components, having them inside the `ListView` element won't change + the visuals of the page. So we can move them inside the `ListView`. Same for + elements anchored to the center of the page, such as placeholder messages for + empty `ListView`s. * For other items, it might make sense to move them to the header or footer - of the ScrollablePage. This is often the case for search bars. + of the `Kirigami.ScrollablePage`. This is often the case for search bars. ### PlaceholderMessage -It is possible to add a [Placeholder Message](docs:kirigami2;PlaceholderMessage) +It is possible to add a [`Kirigami.PlaceholderMessage`](docs:kirigami2;PlaceholderMessage) with some instructions in case the list view is empty. ```qml @@ -71,9 +74,9 @@ Kirigami.ScrollablePage { ### Search in the ListView -A search field is often added to a ScrollablePage to filter the ListView. +A search field is often added to a `Kirigami.ScrollablePage` to filter the `ListView`. This can be done by changing the default `titleDelegate` to use a -[Kirigami.SearchField](docs:kirigami2;SearchField) instead. +[`Kirigami.SearchField`](docs:kirigami2;SearchField) instead. ```qml Kirigami.ScrollablePage { @@ -96,15 +99,14 @@ Kirigami.ScrollablePage { {{< alert title="Hint" color="info" >}} You can use [KSortFilterProxyModel](docs:kitemmodels;SortFilterModel) from [KItemModel](https://api.kde.org/frameworks/kitemmodels/html/) to easily add -filtering capability directly in QML without any need for C++. +filtering capability directly in QML without any need for C++ code. {{< /alert >}} ### Pull to refresh -Another behavior added by this class is a "pull to refresh" behavior. +Another function provided by this component is a "pull to refresh" action. To use this, activate it as follows: - ```qml Kirigami.ScrollablePage { id: view @@ -127,5 +129,5 @@ Kirigami.ScrollablePage { } ``` -By pulling down, you can also activate a special mode with a larger top margin -making single-handed usage of the application easier. +By pulling down, you can also activate a special mode with a larger top margin which +makes single-handed use of the application easier. diff --git a/content/docs/kirigami/components-scrollable_pages/neochatscrollablepage.png b/content/docs/kirigami/components-scrollablepages_listviews/neochatscrollablepage.png similarity index 100% rename from content/docs/kirigami/components-scrollable_pages/neochatscrollablepage.png rename to content/docs/kirigami/components-scrollablepages_listviews/neochatscrollablepage.png diff --git a/content/docs/kirigami/introduction-getting_started/src/main.cpp b/content/docs/kirigami/introduction-getting_started/src/main.cpp index a2ce1b9c370961e08d5ffae5043f416db564f56f..68f8d32e589590019f88a245c56ff58f3c5a88b5 100644 --- a/content/docs/kirigami/introduction-getting_started/src/main.cpp +++ b/content/docs/kirigami/introduction-getting_started/src/main.cpp @@ -8,7 +8,7 @@ int main(int argc, char *argv[]) { QGuiApplication::setAttribute(Qt::AA_EnableHighDpiScaling); - QGuiApplication app(argc, argv); + QApplication app(argc, argv); KLocalizedString::setApplicationDomain("helloworld"); QCoreApplication::setOrganizationName("KDE"); QCoreApplication::setOrganizationDomain("kde.org"); diff --git a/content/docs/kirigami/introduction-next_steps.md b/content/docs/kirigami/introduction-next_steps.md index b93a7d89dfa7656c974cd0b50ec18488f56e1d3e..57b760d1087af089388e42ccf3d303a8122b6982 100644 --- a/content/docs/kirigami/introduction-next_steps.md +++ b/content/docs/kirigami/introduction-next_steps.md @@ -1,14 +1,14 @@ --- title: Next steps group: introduction -weight: 6 +weight: 7 description: > What to do after finishing your first simple Kirigami application --- ## What we have built -Over the past few tutorials we have built a basic but functional Kirigami application that lets you add, edit, and delete date countdowns. In doing so we have learned about Kirigami and QtQuick components, some of QML's systems, basic application layouts, and more. Not bad at all! +Over the past few tutorials you have built a basic but functional Kirigami application that lets you add, edit, and delete date countdowns. In doing so we have learned about Kirigami and QtQuick components, some of QML's systems, basic application layouts, and more. Not bad at all! You now have a grasp of the basics that make up many of KDE's most popular applications. You might be asking yourself: what now? @@ -90,6 +90,12 @@ The Qt project is extensive, and so are QML and QtQuick. There is a lot of funct - If you want to look up what specific components do, look no further than [Qt's official QML documentation.](https://doc.qt.io/qt-5/qtquick-index.html) - If you are looking for a more guided approach to learning, [the QMLBook](https://qmlbook.github.io/) is a great place to start. +### More Kirigami + +This documentation includes a lot more about Kirigami. You can poke through some of the Components pages to find out more about some of the QML components that Kirigami provides for you to use. + +We recommend you also take a look at Kirigami Gallery (`kirigami2gallery`), an application designed by KDE developers to demonstrate kirigami's tools and capabilities. It provides both interactive examples of Kirigami components and easy links to the source code of these examples so you can see how they were built. + # The sky is the limit! Don't be intimidated by all the material on here! No one starts off being able to create something like Plasma from scratch. But KDE is no multi-billion dollar company with a high barrier for entry - we have no five-round coding interviews! - and as long as you are nice, you will be welcomed.