Differential D28033 Diff 79366 src/declarativeimports/plasmaextracomponents/qml/ExpandableListItem.qml

Changeset View

Standalone View

View Options

src/declarativeimports/plasmaextracomponents/qml/ExpandableListItem.qml

  • This file was added.
1​/*
2​ * Copyright 2020 Nate Graham <nate@kde.org>
3​ *
4​ * This program is free software; you can redistribute it and/or modify
5​ * it under the terms of the GNU Library General Public License as
6​ * published by the Free Software Foundation; either version 2, or
7​ * (at your option) any later version.
8​ *
9​ * This program is distributed in the hope that it will be useful,
10​ * but WITHOUT ANY WARRANTY; without even the implied warranty of
11​ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12​ * GNU Library General Public License for more details
13​ *
14​ * You should have received a copy of the GNU Library General Public
15​ * License along with this program; if not, write to the
16​ * Free Software Foundation, Inc.,
17​ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18​ */
19​
20​import QtQuick 2.6
21​import QtQuick.Layouts 1.1
22​import org.kde.plasma.core 2.0 as PlasmaCore
23​import org.kde.plasma.components 2.0 as PlasmaComponents // for Highlight
24​import org.kde.plasma.components 3.0 as PlasmaComponents3
25​import org.kde.plasma.extras 2.0 as PlasmaExtras
26​
27​/**
28​ * A list item that expands when clicked to show additional actions or a custom
29​ * view. The list item has a standardized appearance, with an icon on the left
30​ * badged with an optional emblem, a title and optional subtitle to the right,
31​ * an optional default action button, and a button to expand and collapse the
32​ * list item.
33​ *
34​ * When expanded, the list item shows one of two views:
35​ * - A list of contextually-appropriate actions if contextualActionsModel has
36​ * been defined and customExpandedViewContent has not been defined.
37​ * - A custom view if customExpandedViewContent has been defined and
38​ * contextualActionsModel has not been defined.
39​ *
40​ * It is not valid to define both or neither; only define one.
41​ *
42​ * Note: this component should only be used for lists where the maximum number
43​ * of items is very low, ideally less than 10. For longer lists, consider using
44​ * a different paradigm.
45​ *
46​ *
47​ * Example usage:
48​ *
49​ * @code
50​ * import org.kde.plasma.extras 2.0 as PlasmaExtras
51​ * [...]
52​ * PlasmaExtras.ScrollArea {
53​ * ListView {
54​ * anchors.fill: parent
55​ * focus: true
56​ * currentIndex: -1
57​ * clip: true
58​ * model: myModel
59​ * highlight: PlasmaComponents.Highlight {}
60​ * highlightMoveDuration: units.longDuration
61​ * highlightResizeDuration: units.longDuration
62​ * delegate: PlasmaExtras.ExpandableListItem {
63​ * icon: model.iconName
64​ * iconEmblem: model.isPaused ? "emblem-pause" : ""
65​ * title: model.name
66​ * subtitle: model.subtitle
67​ * isDefault: model.isDefault
68​ * defaultActionButtonAction: Action {
69​ * icon.name: model.isPaused ? "media-playback-start" : "media-playback-pause"
70​ * text: model.isPaused ? i18n("Resume") : i18n("Pause")
71​ * onTriggered: {
72​ * if (model.isPaused) {
73​ * model.resume(model.name);
74​ * } else {
75​ * model.pause(model.name);
76​ * }
77​ * }
78​ * }
79​ * contextualActionsModel: [
80​ * Action {
81​ * icon.name: "configure"
82​ * text: i18n("Configure...")
83​ * onTriggered: model.configure(model.name);
84​ * }
85​ * ]
86​ * }
87​ * }
88​ * }
89​ * [...]
90​ * @endcode
91​ */
92​MouseArea {
93​ id: listItem
94​
95​ /*
96​ * icon: string
97​ * The name of the icon used in the list item.
98​ *
99​ * Required.
100​ */
101​ property alias icon: listItemIcon.source
102​
103​ /*
104​ * iconUsesPlasmaSVG: bool
105​ * Whether to load the icon from the Plasma theme instead of the icon theme.
106​ *
107​ * Optional, defaults to false.
108​ */
109​ property bool iconUsesPlasmaSVG: false
110​
111​ /*
112​ * iconEmblem: string
113​ * The name of the emblem to badge the icon with.
114​ *
115​ * Optional, defaults to nothing, in which case there is no emblem.
116​ */
117​ property alias iconEmblem: iconEmblem.source
118​
119​ /*
120​ * title: string
121​ * The name or title for this list item.
122​ *
123​ * Optional; if not defined, there will be no title and the subtitle will be
124​ * vertically centered in the list item.
125​ */
126​ property alias title: listItemTitle.text
127​
128​ /*
129​ * subtitle: string
130​ * The subtitle for this list item, displayed under the title.
131​ *
132​ * Optional; if not defined, there will be no subtitle and the title will be
133​ * vertically centered in the list item.
134​ */
135​ property alias subtitle: listItemSubtitle.text
136​
137​ /*
138​ * subtitleCanWrap: bool
139​ * Whether to allow the subtitle to become a multi-line string instead of
140​ * eliding when the text is very long.
141​ *
142​ * Optional, defaults to false.
143​ */
144​ property bool subtitleCanWrap: false
145​
146​ /*
147​ * subtitleColor: color
148​ * The color of the subtitle text
149​ *
150​ * Optional; if not defined, the subtitle will use the default text color
151​ */
152​ property alias subtitleColor: listItemSubtitle.color
153​
154​ /*
155​ * allowStyledText: bool
156​ * Whether to allow the title, subtitle, and tooltip to contain styled text.
157​ * For performance and security reasons, keep this off unless needed.
158​ *
159​ * Optional, defaults to false.
160​ */
161​ property bool allowStyledText: false
162​
163​ /*
164​ * defaultActionButtonAction: Action
165​ * The Action to execute when the default button is clicked.
166​ *
167​ * Optional; if not defined, no default action button will be displayed.
168​ */
169​ property alias defaultActionButtonAction: defaultActionButton.action
170​
171​ /*
172​ * defaultActionButtonVisible: bool
173​ * When/whether to show to default action button. Useful for making it
174​ * conditionally appear or disappear.
175​ *
176​ * Optional; defaults to true
177​ */
178​ property bool defaultActionButtonVisible: true
179​
180​ /*
181​ * contextualActionsModel: list<QtObject>
182​ * A list of Action objects that describes additional actions that can be
183​ * performed on this list item. The actions should define appropriate
184​ * "text:", icon.name:", and "onTriggered:" properties. For example:
185​ *
186​ * @code
187​ * contextualActionsModel: [
188​ * Action {
189​ * text: i18n("Do something")
190​ * icon.name: "document-edit"
191​ * onTriggered: doSomething()
192​ * }
193​ * Action {
194​ * text: i18n("Do something else")
195​ * icon.name: "draw-polygon"
196​ * onTriggered: doSomethingElse()
197​ * }
198​ * Action {
199​ * text: i18n("Do something completely different")
200​ * icon.name: "games-highscores"
201​ * onTriggered: doSomethingCompletelyDifferent()
202​ * }
203​ * ]
204​ * @endcode
205​ *
206​ * Optional; if not defined, no contextual actions will be displayed and
207​ * you should instead assign a custom view to customExpandedViewContent,
208​ * which will be shown when the user expands the list item.
209​ */
210​ property list<QtObject> contextualActionsModel
211​
212​ /*
213​ * menu: PlasmaComponents.Menu
214​ * The context menu to show when the user right-clicks on this list item.
215​ * For example:
216​ *
217​ * @code
218​ * contextMenu: PlasmaComponents.Menu {
219​ * PlasmaComponents.MenuItem {
220​ * text: i18n("Do something")
221​ * icon: "document-edit"
222​ * onClicked: doSomething()
223​ * }
224​ * PlasmaComponents.MenuItem {
225​ * text: i18n("Do something else")
226​ * icon: "draw-polygon"
227​ * onClicked: doSomethingElse()
228​ * }
229​ * PlasmaComponents.MenuItem {
230​ * text: i18n("Do something completely different")
231​ * icon: "games-highscores"
232​ * onClicked: doSomethingCompletelyDifferent()
233​ * }
234​ * }
235​ * @endcode
236​ *
237​ * Optional; if not defined, no context menu will be displayed when the user
238​ * right-clicks on the list item.
239​ */
240​ property var contextMenu
241​
242​ /*
243​ * A custom view to display when the user expands the list item.
244​ *
245​ * This component must define width: and height: values. Width: should be
246​ * equal to the width of the list item itself, while height: will depend
247​ * on the component itself.
248​ *
249​ * Optional; if not defined, the expanded view will show contextual actions
250​ * instead.
251​ */
252​ property var customExpandedViewContent: actionsListComponent
253​
254​ /*
255​ * isBusy: bool
256​ * Whether or not to display a busy indicator on the list item. Set to true
257​ * while the item should be non-interactive because things are processing.
258​ *
259​ * Optional; defaults to false.
260​ */
261​ property bool isBusy: false
262​
263​ /*
264​ * isEnabled: bool
265​ * Whether or not this list item should be enabled and interactive.
266​ *
267​ * Optional; defaults to true.
268​ */
269​ property bool isEnabled: true
270​
ratijasUnsubmitted
Not Done

Why simply Item::enabled wasn't enough? Is there a real use-case that justifies an extra property with overlapping name? Should be documented if there is one.

ratijas: Why simply Item::enabled wasn't enough? Is there a real use-case that justifies an extra…
ngrahamAuthorUnsubmitted
Not Done

It was nothing more than a bad API design decision on my part.

ngraham: It was nothing more than a bad API design decision on my part.
ratijasUnsubmitted
Not Done

Luckily, it is easily fixable, with an alias for backward compatibility. However, I don't know how to enforce deprecation warnings on aliases. It might be possible in Qt/QML 6 though.

ratijas: Luckily, it is easily fixable, with an alias for backward compatibility. However, I don't know…
271​ /*
272​ * isDefault: bool
273​ * Whether or not this list item should be considered the "default" or
274​ * "Current" item in the list. When set to true, and the list itself has
275​ * more than one item in it, the list item's title and subtitle will be
276​ * drawn in a bold style.
277​ *
278​ * Optional; defaults to false.
279​ */
280​ property bool isDefault: false
281​
282​ /*
283​ * expand()
284​ * Show the expanded view, growing the list item to its taller size.
285​ */
286​ function expand() {
287​ expandedView.visible = true
288​ listItem.itemExpanded(listItem)
289​ }
290​
291​ /*
292​ * collapse()
293​ * Hide the expanded view and collapse the list item to its shorter size.
294​ */
295​ function collapse() {
296​ expandedView.visible = false
297​ listItem.itemExpanded(null)
298​ }
299​
300​ /*
301​ * toggleExpanded()
302​ * Expand or collapse the list item depending on its current state.
303​ */
304​ function toggleExpanded() {
305​ expandedView.visible ? listItem.collapse() : listItem.expand()
306​ }
307​
308​ signal itemExpanded(variant item)
309​
310​ width: parent.width // Assume that we will be used as a delegate, not placed in a layout
311​ height: mainLayout.height
312​
313​ acceptedButtons: Qt.LeftButton | Qt.RightButton
314​ hoverEnabled: true
315​ cursorShape: Qt.PointingHandCursor // To indicate that the whole thing is clickable
316​
317​ onContainsMouseChanged: listItem.ListView.view.currentIndex = (containsMouse ? index : -1)
318​
319​ onIsEnabledChanged: if (!listItem.isEnabled) { collapse() }
320​
321​ onClicked: {
322​ // Item is disabled: do nothing
323​ if (!listItem.isEnabled) return
324​
325​ // Left click: toggle expanded state
326​ if (mouse.button & Qt.LeftButton) {
327​ listItem.toggleExpanded()
328​ }
329​
330​ // Right-click: show context menu, if defined
331​ if (contextMenu != undefined) {
332​ if (mouse.button & Qt.RightButton) {
333​ contextMenu.visualParent = parent
334​ contextMenu.prepare();
335​ contextMenu.open(mouse.x, mouse.y)
336​ return
337​ }
338​ }
339​ }
340​
341​ ColumnLayout {
342​ id: mainLayout
343​
344​ anchors.top: parent.top
345​ anchors.left: parent.left
346​ anchors.right: parent.right
347​
348​ spacing: 0
349​
350​ RowLayout {
351​ id: mainRowLayout
352​
353​ Layout.fillWidth: true
354​ Layout.margins: units.smallSpacing
355​ // Otherwise it becomes taller when the button appears
356​ Layout.minimumHeight: defaultActionButton.height
357​
358​ // Icon and optional emblem
359​ PlasmaCore.IconItem {
360​ id: listItemIcon
361​
362​ usesPlasmaTheme: listItem.iconUsesPlasmaSVG
363​
364​ implicitWidth: units.iconSizes.medium
365​ implicitHeight: units.iconSizes.medium
366​
367​ PlasmaCore.IconItem {
368​ id: iconEmblem
369​
370​ visible: source != undefined && source.length > 0
371​
372​ anchors.right: parent.right
373​ anchors.bottom: parent.bottom
374​
375​ implicitWidth: units.iconSizes.small
376​ implicitHeight: units.iconSizes.small
377​ }
378​ }
379​
380​ // Title and subtitle
381​ ColumnLayout {
382​ Layout.fillWidth: true
383​ Layout.alignment: Qt.AlignVCenter
384​
385​ spacing: 0
386​
387​ PlasmaExtras.Heading {
388​ id: listItemTitle
389​
390​ visible: text.length > 0
391​
392​ Layout.fillWidth: true
393​
394​ level: 5
395​
396​ textFormat: listItem.allowStyledText ? Text.StyledText : Text.PlainText
397​ elide: Text.ElideRight
398​ maximumLineCount: 1
399​
400​ // Even if it's the default item, only make it bold when
401​ // there's more than one item in the list, or else there's
402​ // only one item and it's bold, which is a little bit weird
403​ font.weight: listItem.isDefault && listItem.ListView.count > 1
404​ ? Font.Bold
405​ : Font.Normal
406​ }
407​
408​ PlasmaComponents3.Label {
409​ id: listItemSubtitle
410​
411​ enabled: false
412​ visible: text.length > 0
413​
414​ Layout.fillWidth: true
415​
416​ textFormat: listItem.allowStyledText ? Text.StyledText : Text.PlainText
417​ elide: Text.ElideRight
418​ maximumLineCount: subtitleCanWrap ? 9999 : 1
419​ wrapMode: subtitleCanWrap ? Text.WordWrap : Text.NoWrap
420​ }
421​ }
422​
423​ // Default action button
424​ PlasmaComponents3.Button {
425​ id: defaultActionButton
426​
427​ enabled: listItem.isEnabled
428​ visible: defaultActionButtonAction
429​ && listItem.defaultActionButtonVisible
430​ && listItem.containsMouse
431​ && !busyIndicator.visible
432​
433​ icon.width: units.iconSizes.smallMedium
434​ icon.height: units.iconSizes.smallMedium
435​ }
436​
437​ PlasmaComponents3.BusyIndicator {
438​ id: busyIndicator
439​
440​ visible: listItem.isBusy
441​
442​ // Otherwise it makes the list item taller when it appears
443​ Layout.maximumHeight: defaultActionButton.implicitHeight
444​ Layout.maximumWidth: Layout.maximumHeight
445​ }
446​
447​ // Expand/collapse button
448​ PlasmaComponents3.Button {
449​ visible: listItem.containsMouse
450​
451​ // TODO: "collapse-all" and "expand-all" would be more
452​ // semantically appropriate, but they have an extra horizontal
453​ // line and don't look right here
454​ icon.name: expandedView.visible? "go-up" : "go-down"
455​ icon.width: units.iconSizes.smallMedium
456​ icon.height: units.iconSizes.smallMedium
457​
458​ onClicked: listItem.toggleExpanded()
459​ }
460​ }
461​
462​
463​ // Expanded view, by default showing the actions list
464​ Loader {
465​ id: expandedView
466​
467​ visible: false
468​ opacity: visible ? 1.0 : 0
469​
470​ active: customExpandedViewContent != undefined
471​ sourceComponent: customExpandedViewContent
472​
473​ Layout.fillWidth: true
474​ Layout.margins: units.smallSpacing
475​
476​ Behavior on opacity {
477​ NumberAnimation {
478​ duration: units.veryLongDuration
479​ easing.type: Easing.InOutCubic
480​ }
481​ }
482​ }
483​ }
484​
485​ // Default expanded view content: contextual actions list
486​ Component {
487​ id: actionsListComponent
488​
489​ // Container for actions list, so that we can add left and right margins to it
490​ Item {
491​ height: actionsList.contentHeight
492​ width: mainRowLayout.width
davidedmundsonUnsubmitted
Done

not contentHeight?

davidedmundson: not contentHeight?
493​
494​ // TODO: Implement keyboard focus
495​ // TODO: Don't highlight the first item by default, unless it has focus
496​ // TODO: Animate the highlight moving, as in the printers applet
497​ ListView {
498​ id: actionsList
499​
500​ anchors.top: parent.top
501​ anchors.left: parent.left
502​ anchors.right: parent.right
503​ anchors.leftMargin: listItemIcon.width + units.smallSpacing
504​ anchors.rightMargin: listItemIcon.width + units.smallSpacing * 2
505​
506​ height: (units.iconSizes.smallMedium + units.smallSpacing * 2) * actionsList.count
507​
508​ focus: true
509​ clip: true
510​
511​ model: listItem.contextualActionsModel
512​
513​ highlight: PlasmaComponents.Highlight {}
514​
515​ delegate: MouseArea {
516​ id: actionItem
517​
518​ enabled: model.enabled
519​
520​ width: actionsList.width
521​ height: actionItemLayout.height + units.smallSpacing * 2
522​
523​ hoverEnabled: true
524​
525​ onContainsMouseChanged: actionItem.ListView.view.currentIndex = (containsMouse ? index : -1)
526​
527​ onClicked: {
528​ modelData.trigger()
529​ collapse()
530​ }
531​
532​ RowLayout {
533​ id: actionItemLayout
534​
535​ enabled: model.enabled
536​
537​ anchors.left: parent.left
538​ anchors.leftMargin: units.smallSpacing
539​ anchors.right: parent.right
540​ anchors.rightMargin: units.smallSpacing
541​ anchors.verticalCenter: parent.verticalCenter
542​
543​ PlasmaCore.IconItem {
544​ implicitWidth: units.iconSizes.smallMedium
545​ implicitHeight: units.iconSizes.smallMedium
546​
547​ source: model.icon.name
548​ }
549​
550​ PlasmaExtras.Heading {
551​ Layout.fillWidth: true
552​
553​ level: 5
554​
555​ text: model.text
556​ textFormat: listItem.allowStyledText ? Text.StyledText : Text.PlainText
557​ elide: Text.ElideRight
558​ maximumLineCount: 1
559​ }
560​ }
561​ }
562​ }
563​ }
564​ }
565​}