Commit b6e329de authored by Claudio Cambra's avatar Claudio Cambra Committed by Carl Schwan
Browse files

Add documentation for more Kirigami components

This merge request contains a number of new pages for the Kirigami
documentation about an assortment of Kirigami components.

There are also tweaks to the layout of the kirigami documentation
as a whole.

BUG: 432356
parent 5370505e
---
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"
---
......
---
title: "Getting started with Kirigami"
linkTitle: "Kirigami"
weight: 2
weight: 1
layout: home
groups:
- name: "Introduction"
......
......@@ -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/).
---
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 >}}
---
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 >}}
......
---
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
}
```
---
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