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

KDE's Doxygen guidelines are available online.