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

KDE's Doxygen guidelines are available online.