Kirigami2

BasicListItem.qml
1 /*
2  * SPDX-FileCopyrightText: 2010 Marco Martin <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 
7 import QtQuick 2.8
8 import QtQuick.Layouts 1.2
9 import QtQuick.Controls 2.0 as QQC2
10 import org.kde.kirigami 2.12
11 
12 /**
13  * @brief A BasicListItem provides a simple list item design that can handle the
14  * most common list item usecases.
15  *
16  * @image html BasicListItemTypes.svg "The styles of the BasicListItem. From left to right top to bottom: light icon + title + subtitle, dark icon + title + subtitle, light icon + label, dark icon + label, light label, dark label." width=50%
17  */
18 AbstractListItem {
19  id: listItem
20 
21 //BEGIN properties
22  /**
23  * @brief This property holds the text of this list item's label.
24  *
25  * If a subtitle is provided, the label will behave as a title and will be styled
26  * accordingly. Every list item should have a label.
27  *
28  * @property string label
29  */
30  property alias label: listItem.text
31 
32  /**
33  * @brief This property holds an optional subtitle that can appear under the label.
34  * @since 5.70
35  * @since org.kde.kirigami 2.12
36  */
37  property alias subtitle: subtitleItem.text
38 
39  /**
40  * @brief This property holds an item that will be displayed before the title and subtitle.
41  * @note The leading item is allowed to expand infinitely horizontally, and should be bounded by the user.
42  * @since org.kde.kirigami 2.15
43  */
44  property Item leading
45 
46  /**
47  * @brief This property holds the padding after the leading item.
48  * @since org.kde.kirigami 2.15
49  */
50  property real leadingPadding: Units.largeSpacing
51 
52  // TODO KF6: remove this property and instead implement leading and trailing
53  // item positioning in such a way that they fill vertically, but a fixed
54  // height can be manually specified without needing to wrap it in an Item
55  /**
56  * @brief This property sets whether or not to stretch the leading item to fit all available vertical space.
57  *
58  * If false, you will be responsible for setting a height for the
59  * item or ensuring that its default height works.
60  *
61  * default: ``true``
62  *
63  * @warning This property will likely be removed in KF6
64  * @since 5.83
65  * @since org.kde.kirigami 2.15
66  */
67  property bool leadingFillVertically: true
68 
69  /**
70  * @brief This property holds an item that will be displayed after the title and subtitle
71  * @note The trailing item is allowed to expand infinitely horizontally, and should be bounded by the user.
72  * @since org.kde.kirigami 2.15
73  */
74  property Item trailing
75 
76  /**
77  * @brief This property holds the padding before the trailing item.
78  * @since org.kde.kirigami 2.15
79  */
80  property real trailingPadding: Units.largeSpacing
81 
82  // TODO KF6: remove this property and instead implement leading and trailing
83  // item positioning in such a way that they fill vertically, but a fixed
84  // height can be manually specified without needing to wrap it in an Item
85  /**
86  * @brief This propery sets whether or not to stretch the trailing item to fit all available vertical space.
87  *
88  * If false, you will be responsible for setting a height for the
89  * item or ensuring that its default height works.
90  *
91  * default: ``true``
92  *
93  * @warning This property will likely be removed in KF6
94  * @since 5.83
95  * @since org.kde.kirigami 2.15
96  */
97  property bool trailingFillVertically: true
98 
99  /**
100  * @brief This property sets whether list item's text should render in bold.
101  *
102  * default: ``false``
103  *
104  * @since 5.71
105  * @since org.kde.kirigami 2.13
106  */
107  property bool bold: false
108 
109  /**
110  * @code ts
111  * interface IconGroup {
112  * name: string,
113  * source: string,
114  * width: int,
115  * height: int,
116  * color: color,
117  * }
118  *
119  * type Icon = string | IconGroup | URL
120  * @endcode
121  *
122  * The icon that will render on this list item.
123  *
124  * This can either be an icon name, a URL, or an object with the following properties:
125  *
126  * If the type of the icon is a string containing an icon name, the icon will be looked up from the
127  * platform icon theme.
128  *
129  * Using an icon object allows you to specify more granular attributes of the icon,
130  * such as its color and dimensions.
131  *
132  * If the icon is a URL, the icon will be attempted to be loaded from the
133  * given URL.
134  */
135  property var icon
136 
137  /**
138  * @brief This property sets the size at which the icon will render.
139  *
140  * This will not affect icon lookup, unlike the icon group's width and height properties, which will.
141  *
142  * @property int iconSize
143  * @since 2.5
144  */
145  property alias iconSize: iconItem.size
146 
147  /**
148  * @brief This property holds the color of the icon.
149  *
150  * If the icon's original colors should be left intact, set this to the default value, "transparent".
151  * Note that this colour will only be applied if the icon can be recoloured, (e.g. you can use Kirigami.Theme.foregroundColor to change the icon's colour.)
152  *
153  * @property color iconColor
154  * @since 2.7
155  */
156  property alias iconColor: iconItem.color
157 
158  /**
159  * @brief This property sets whether or not the icon has a "selected" appearance.
160  *
161  * Can be used to override the icon coloration if the list item's background and
162  * text are also being overridden, to ensure that the icon never becomes invisible.
163  *
164  * @since 5.91
165  * @since org.kde.kirigami 2.19
166  * @property bool iconSelected
167  */
168  property alias iconSelected: iconItem.selected
169 
170  /**
171  * @brief This property sets whether or not to reserve space for the icon, even if there is no icon.
172  * @image html BasicListItemReserve.svg "Left: reserveSpaceForIcon: false. Right: reserveSpaceForIcon: true" width=50%
173  * @property bool reserveSpaceForIcon
174  */
175  property alias reserveSpaceForIcon: iconItem.visible
176 
177  /**
178  * @brief This property sets whether or not the label of the list item should fill width.
179  *
180  * Setting this to false is useful if you have other items in the list item
181  * that should fill width instead of the label.
182  *
183  * @property bool reserveSpaceForLabel
184  */
185  property alias reserveSpaceForLabel: labelItem.visible
186 
187  /**
188  * @brief This property holds whether the list item's height should account for
189  * the presence of a subtitle.
190  *
191  * default: ``false``
192  *
193  * @since 5.77
194  * @since org.kde.kirigami 2.15
195  */
196  property bool reserveSpaceForSubtitle: false
197 
198  /**
199  * @brief This property holds the spacing between the label row and subtitle row.
200  * @since 5.83
201  * @since org.kde.kirigami 2.15
202  * @property real textSpacing
203  */
204  property alias textSpacing: labelColumn.spacing
205 
206  /**
207  * @brief This property holds sets whether to make the icon and labels have a disabled look.
208  *
209  * This can be used to tweak whether the content elements are visually active
210  * while preserving an active appearance for any leading or trailing items.
211  *
212  * default: ``false``
213  *
214  * @since 5.83
215  * @since org.kde.kirigami 2.15
216  */
217  property bool fadeContent: false
218 
219  /**
220  * @brief This property holds the label item, for accessing the usual Text properties.
221  * @property QtQuick.Controls.Label labelItem
222  * @since 5.84
223  * @since org.kde.kirigami 2.16
224  */
225  property alias labelItem: labelItem
226 
227  /**
228  * @brief This property holds the subtitle item, for accessing the usual Text properties.
229  * @property QtQuick.Controls.Label subtitleItem
230  * @since 5.84
231  * @since org.kde.kirigami 2.16
232  */
233  property alias subtitleItem: subtitleItem
234 
235  default property alias _basicDefault: layout.data
236 //END properties
237 
238 //BEGIN signal handlers
239  onLeadingChanged: {
240  if (!!listItem.leading) {
241  listItem.leading.parent = contItem
242  listItem.leading.anchors.left = listItem.leading.parent.left
243  listItem.leading.anchors.top = listItem.leadingFillVertically ? listItem.leading.parent.top : undefined
244  listItem.leading.anchors.bottom = listItem.leadingFillVertically ? listItem.leading.parent.bottom : undefined
245  listItem.leading.anchors.verticalCenter = listItem.leadingFillVertically ? undefined : listItem.leading.parent.verticalCenter
246  layout.anchors.left = listItem.leading.right
247  layout.anchors.leftMargin = Qt.binding(function() { return listItem.leadingPadding })
248  } else {
249  layout.anchors.left = contentItem.left
250  layout.anchors.leftMargin = 0
251  }
252  }
253 
254  onTrailingChanged: {
255  if (!!listItem.trailing) {
256  listItem.trailing.parent = contItem
257  listItem.trailing.anchors.right = listItem.trailing.parent.right
258  listItem.trailing.anchors.top = listItem.trailingFillVertically ? listItem.trailing.parent.top : undefined
259  listItem.trailing.anchors.bottom = listItem.trailingFillVertically ? listItem.trailing.parent.bottom : undefined
260  listItem.trailing.anchors.verticalCenter = listItem.trailingFillVertically ? undefined : listItem.trailing.parent.verticalCenter
261  layout.anchors.right = listItem.trailing.left
262  layout.anchors.rightMargin = Qt.binding(function() { return listItem.trailingPadding })
263  } else {
264  layout.anchors.right = contentItem.right
265  layout.anchors.rightMargin = 0
266  }
267  }
268 
269  Keys.onEnterPressed: action ? action.trigger() : clicked()
270  Keys.onReturnPressed: action ? action.trigger() : clicked()
271 //END signal handlers
272 
273  icon: action ? action.icon.name || action.icon.source : undefined
274 
275  contentItem: Item {
276  id: contItem
277  implicitWidth: (listItem.leading || {implicitWidth: 0}).implicitWidth + layout.implicitWidth + (listItem.trailing || {implicitWidth: 0}).implicitWidth
278  Binding on implicitHeight {
279  value: Math.max(iconItem.size, (!subtitleItem.visible && listItem.reserveSpaceForSubtitle ? (labelItem.implicitHeight + labelColumn.spacing + subtitleItem.implicitHeight): labelColumn.implicitHeight) )
280  delayed: true
281  }
282 
283  RowLayout {
284  id: layout
285  spacing: LayoutMirroring.enabled ? listItem.rightPadding : listItem.leftPadding
286  anchors.left: contItem.left
287  anchors.leftMargin: listItem.leading ? listItem.leadingPadding : 0
288  anchors.right: contItem.right
289  anchors.rightMargin: listItem.trailing ? listItem.trailingPadding : 0
290  anchors.verticalCenter: parent.verticalCenter
291 
292  Icon {
293  id: iconItem
294  source: {
295  if (!listItem.icon) {
296  return undefined
297  }
298  if (listItem.icon.hasOwnProperty) {
299  if (listItem.icon.hasOwnProperty("name") && listItem.icon.name !== "")
300  return listItem.icon.name;
301  if (listItem.icon.hasOwnProperty("source"))
302  return listItem.icon.source;
303  }
304  return listItem.icon;
305  }
306  property int size: subtitleItem.visible || reserveSpaceForSubtitle ? Units.iconSizes.medium : Units.iconSizes.smallMedium
307  Layout.minimumHeight: size
308  Layout.maximumHeight: size
309  Layout.minimumWidth: size
310  Layout.maximumWidth: size
311  selected: (listItem.highlighted || listItem.checked || (listItem.pressed && listItem.supportsMouseEvents))
312  opacity: listItem.fadeContent ? 0.4 : 1.0
313  visible: source !== undefined
314  }
315  ColumnLayout {
316  id: labelColumn
317  spacing: 0
318  Layout.fillWidth: true
319  Layout.alignment: Qt.AlignVCenter
320  QQC2.Label {
321  id: labelItem
322  text: listItem.text
323  Layout.fillWidth: true
324  Layout.alignment: subtitleItem.visible ? Qt.AlignLeft | Qt.AlignBottom : Qt.AlignLeft | Qt.AlignVCenter
325  color: (listItem.highlighted || listItem.checked || (listItem.pressed && listItem.supportsMouseEvents)) ? listItem.activeTextColor : listItem.textColor
326  elide: Text.ElideRight
327  font.weight: listItem.bold ? Font.Bold : Font.Normal
328  opacity: listItem.fadeContent ? 0.4 : 1.0
329  }
330  QQC2.Label {
331  id: subtitleItem
332  Layout.fillWidth: true
333  Layout.alignment: subtitleItem.visible ? Qt.AlignLeft | Qt.AlignTop : Qt.AlignLeft | Qt.AlignVCenter
334  color: (listItem.highlighted || listItem.checked || (listItem.pressed && listItem.supportsMouseEvents)) ? listItem.activeTextColor : listItem.textColor
335  elide: Text.ElideRight
336  font: Theme.smallFont
337  opacity: listItem.bold
338  ? (listItem.fadeContent ? 0.3 : 0.9)
339  : (listItem.fadeContent ? 0.1 : 0.7)
340  visible: text.length > 0
341  }
342  }
343  }
344  }
345 }
int largeSpacing
QQmlPropertyMap iconSizes
Class for rendering an icon in UI.
Definition: icon.h:26
QVariant source
The source of this icon.
Definition: icon.h:56
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Fri Aug 19 2022 04:08:31 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.