Differential D28033 Diff 78177 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​ * Required.
124​ */
125​ property alias title: listItemTitle.text
126​
127​ /*
128​ * subtitle: string
129​ * The subtitle for this list item, displayed under the title.
130​ *
131​ * Optional; if not defined, there will be no subtitle and the title will be
132​ * vertically centered in the list item.
133​ */
134​ property alias subtitle: listItemSubtitle.text
135​
136​ /*
137​ * subtitleCanWrap: bool
138​ * Whether to allow the subtitle to become a multi-line string instead of
139​ * eliding when the text is very long.
140​ *
141​ * Optional, defaults to false.
142​ */
143​ property bool subtitleCanWrap: false
144​
145​ /*
146​ * allowStyledText: bool
147​ * Whether to allow the title and subtitle to contain styled text. For
148​ * performance and security reasons, keep this off unless absolutely needed.
149​ *
150​ * Optional, defaults to false.
151​ */
152​ property bool allowStyledText: false
153​
154​ /*
155​ * defaultActionButtonAction: Action
156​ * The Action to execute when the default button is clicked.
157​ *
158​ * Optional; if not defined, no default action button will be displayed.
159​ */
160​ property alias defaultActionButtonAction: defaultActionButton.action
161​
162​ /*
163​ * contextualActionsModel: list<QtObject>
164​ * A list of Action objects that describes additional actions that can be
165​ * performed on this list item. The actions should define appropriate
166​ * "text:", icon.name:", and "onTriggered:" properties. For example:
167​ *
168​ * @code
169​ * contextualActionsModel: [
170​ * Action {
171​ * text: i18n("Do something")
172​ * icon.name: "document-edit"
173​ * onTriggered: doSomething()
174​ * }
175​ * Action {
176​ * text: i18n("Do something else")
177​ * icon.name: "draw-polygon"
178​ * onTriggered: doSomethingElse()
179​ * }
180​ * Action {
181​ * text: i18n("Do something completely different")
182​ * icon.name: "games-highscores"
183​ * onTriggered: doSomethingCompletelyDifferent()
184​ * }
185​ * ]
186​ * @endcode
187​ *
188​ * Optional; if not defined, no contextual actions will be displayed and
189​ * you should instead assign a custom view to customExpandedViewContent,
190​ * which will be shown when the user expands the list item.
191​ */
192​ property list<QtObject> contextualActionsModel
193​
194​ /*
195​ * menu: PlasmaComponents.Menu
196​ * The context menu to show when the user right-clicks on this list item.
197​ * For example:
198​ *
199​ * @code
200​ * contextMenu: PlasmaComponents.Menu {
201​ * PlasmaComponents.MenuItem {
202​ * text: i18n("Do something")
203​ * icon: "document-edit"
204​ * onClicked: doSomething()
205​ * }
206​ * PlasmaComponents.MenuItem {
207​ * text: i18n("Do something else")
208​ * icon: "draw-polygon"
209​ * onClicked: doSomethingElse()
210​ * }
211​ * PlasmaComponents.MenuItem {
212​ * text: i18n("Do something completely different")
213​ * icon: "games-highscores"
214​ * onClicked: doSomethingCompletelyDifferent()
215​ * }
216​ * }
217​ * @endcode
218​ *
219​ * Optional; if not defined, no context menu will be displayed when the user
220​ * right-clicks on the list item.
221​ */
222​ property var contextMenu
223​
224​ /*
225​ * A custom view to display when the user expands the list item.
226​ *
227​ * This component must define width: and height: values. Width: should be
228​ * equal to the width of the list item itself, while height: will depend
229​ * on the component itself.
230​ *
231​ * Optional; if not defined, the expanded view will show contextual actions
232​ * instead.
233​ */
234​ property var customExpandedViewContent: actionsListComponent
235​
236​ /*
237​ * isBusy: bool
238​ * Whether or not to display a busy indicator on the list item. Set to true
239​ * while the item should be non-interactive because things are processing.
240​ *
241​ * Optional; defaults to false.
242​ */
243​ property bool isBusy: false
244​
245​ /*
246​ * isEnabled: bool
247​ * Whether or not this list item should be enabled and interactive.
248​ *
249​ * Optional; defaults to true.
250​ */
251​ property bool isEnabled: true
252​
253​ /*
254​ * isDefault: bool
255​ * Whether or not this list item should be considered the "default" or
256​ * "Current" item in the list. When set to true, and the list itself has
257​ * more than one item in it, the list item's title and subtitle will be
258​ * drawn in a bold style.
259​ *
260​ * Optional; defaults to false.
261​ */
262​ property bool isDefault: false
263​
264​ /*
265​ * expand()
266​ * Show the expanded view, growing the list item to its taller size.
267​ */
268​ function expand() {
269​ expandedView.visible = true
270​ listItem.itemExpanded(listItem)
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​
273​ /*
274​ * collapse()
275​ * Hide the expanded view and collapse the list item to its shorter size.
276​ */
277​ function collapse() {
278​ expandedView.visible = false
279​ listItem.itemExpanded(null)
280​ }
281​
282​ /*
283​ * toggleExpanded()
284​ * Expand or collapse the list item depending on its current state.
285​ */
286​ function toggleExpanded() {
287​ expandedView.visible ? listItem.collapse() : listItem.expand()
288​ }
289​
290​ signal itemExpanded(variant item)
291​
292​ width: parent.width // Assume that we will be used as a delegate, not placed in a layout
293​ height: mainLayout.height
294​
295​ acceptedButtons: Qt.LeftButton | Qt.RightButton
296​ hoverEnabled: true
297​ cursorShape: Qt.PointingHandCursor // To indicate that the whole thing is clickable
298​
299​ onContainsMouseChanged: listItem.ListView.view.currentIndex = (containsMouse ? index : -1)
300​
301​ onIsEnabledChanged: if (!listItem.isEnabled) { collapse() }
302​
303​ onClicked: {
304​ // Item is disabled: do nothing
305​ if (!listItem.isEnabled) return
306​
307​ // Left click: toggle expanded state
308​ if (mouse.button & Qt.LeftButton) {
309​ listItem.toggleExpanded()
310​ }
311​
312​ // Right-click: show context menu, if defined
313​ if (contextMenu != undefined) {
314​ if (mouse.button & Qt.RightButton) {
315​ contextMenu.visualParent = parent
316​ contextMenu.prepare();
317​ contextMenu.open(mouse.x, mouse.y)
318​ return
319​ }
320​ }
321​ }
322​
323​ ColumnLayout {
324​ id: mainLayout
325​
326​ anchors.top: parent.top
327​ anchors.left: parent.left
328​ anchors.right: parent.right
329​
330​ spacing: 0
331​
332​ RowLayout {
333​ id: mainRowLayout
334​
335​ Layout.fillWidth: true
336​ Layout.margins: units.smallSpacing
337​ // Otherwise it becomes taller when the button appears
338​ Layout.minimumHeight: defaultActionButton.height
339​
340​ // Icon and optional emblem
341​ PlasmaCore.IconItem {
342​ id: listItemIcon
343​
344​ usesPlasmaTheme: listItem.iconUsesPlasmaSVG
345​
346​ implicitWidth: units.iconSizes.medium
347​ implicitHeight: units.iconSizes.medium
348​
349​ PlasmaCore.IconItem {
350​ id: iconEmblem
351​
352​ visible: source != undefined && source.length > 0
353​
354​ anchors.right: parent.right
355​ anchors.bottom: parent.bottom
356​
357​ implicitWidth: units.iconSizes.small
358​ implicitHeight: units.iconSizes.small
359​ }
360​ }
361​
362​ // Title and subtitle
363​ ColumnLayout {
364​ Layout.fillWidth: true
365​ Layout.alignment: Qt.AlignVCenter
366​
367​ spacing: 0
368​
369​ PlasmaExtras.Heading {
370​ id: listItemTitle
371​
372​ Layout.fillWidth: true
373​
374​ level: 5
375​
376​ textFormat: listItem.allowStyledText ? Text.StyledText : Text.PlainText
377​ elide: Text.ElideRight
378​ maximumLineCount: 1
379​
380​ // Even if it's the default item, only make it bold when
381​ // there's more than one item in the list, or else there's
382​ // only one item and it's bold, which is a little bit weird
383​ font.weight: listItem.isDefault && listItem.ListView.count > 1
384​ ? Font.Bold
385​ : Font.Normal
386​ }
387​
388​ PlasmaComponents3.Label {
389​ id: listItemSubtitle
390​
391​ enabled: false
392​ visible: text.length > 0
393​
394​ Layout.fillWidth: true
395​
396​ textFormat: listItem.allowStyledText ? Text.StyledText : Text.PlainText
397​ elide: Text.ElideRight
398​ maximumLineCount: subtitleCanWrap ? 9999 : 1
399​ wrapMode: subtitleCanWrap ? Text.WordWrap : Text.NoWrap
400​ }
401​ }
402​
403​ // Default action button
404​ PlasmaComponents3.Button {
405​ id: defaultActionButton
406​
407​ enabled: listItem.isEnabled
408​ visible: defaultActionButtonAction
409​ && listItem.containsMouse
410​ && !busyIndicator.visible
411​
412​ icon.width: units.iconSizes.smallMedium
413​ icon.height: units.iconSizes.smallMedium
414​ }
415​
416​ PlasmaComponents3.BusyIndicator {
417​ id: busyIndicator
418​
419​ visible: listItem.isBusy
420​
421​ // Otherwise it makes the list item taller when it appears
422​ Layout.maximumHeight: defaultActionButton.implicitHeight
423​ Layout.maximumWidth: Layout.maximumHeight
424​ }
425​
426​ // Expand/collapse button
427​ PlasmaComponents3.Button {
428​ visible: listItem.containsMouse
429​
430​ // TODO: "collapse-all" and "expand-all" would be more
431​ // semantically appropriate, but they have an extra horizontal
432​ // line and don't look right here
433​ icon.name: expandedView.visible? "go-up" : "go-down"
434​ icon.width: units.iconSizes.smallMedium
435​ icon.height: units.iconSizes.smallMedium
436​
437​ onClicked: listItem.toggleExpanded()
438​ }
439​ }
440​
441​
442​ // Expanded view, by default showing the actions list
443​ Loader {
444​ id: expandedView
445​
446​ visible: false
447​ opacity: visible ? 1.0 : 0
448​
449​ active: customExpandedViewContent != undefined
450​ sourceComponent: customExpandedViewContent
451​
452​ Layout.fillWidth: true
453​ Layout.margins: units.smallSpacing
454​
455​ Behavior on opacity {
456​ NumberAnimation {
457​ duration: units.veryLongDuration
458​ easing.type: Easing.InOutCubic
459​ }
460​ }
461​ }
462​ }
463​
464​ // Default expanded view content: contextual actions list
465​ Component {
466​ id: actionsListComponent
467​
468​ // Container for actions list, so that we can add left and right margins to it
469​ Item {
470​ height: actionsList.height
471​ width: mainRowLayout.width
472​
473​ // TODO: Implement keyboard focus
474​ // TODO: Don't highlight the first item by default, unless it has focus
475​ // TODO: Animate the highlight moving, as in the printers applet
476​ ListView {
477​ id: actionsList
478​
479​ anchors.top: parent.top
480​ anchors.left: parent.left
481​ anchors.right: parent.right
482​ anchors.leftMargin: listItemIcon.width + units.smallSpacing
483​ anchors.rightMargin: listItemIcon.width + units.smallSpacing * 2
484​
485​ height: (units.iconSizes.smallMedium + units.smallSpacing * 2) * actionsList.count
486​
487​ focus: true
488​ clip: true
489​
490​ model: listItem.contextualActionsModel
491​
492​ highlight: PlasmaComponents.Highlight {}
davidedmundsonUnsubmitted
Done

not contentHeight?

davidedmundson: not contentHeight?
493​
494​ delegate: MouseArea {
495​ id: actionItem
496​
497​ enabled: model.enabled
498​
499​ width: actionsList.width
500​ height: actionItemLayout.height + units.smallSpacing * 2
501​
502​ hoverEnabled: true
503​
504​ onContainsMouseChanged: actionItem.ListView.view.currentIndex = (containsMouse ? index : -1)
505​
506​ onClicked: {
507​ modelData.trigger()
508​ collapse()
509​ }
510​
511​ RowLayout {
512​ id: actionItemLayout
513​
514​ enabled: model.enabled
515​
516​ anchors.left: parent.left
517​ anchors.leftMargin: units.smallSpacing
518​ anchors.right: parent.right
519​ anchors.rightMargin: units.smallSpacing
520​ anchors.verticalCenter: parent.verticalCenter
521​
522​ PlasmaCore.IconItem {
523​ implicitWidth: units.iconSizes.smallMedium
524​ implicitHeight: units.iconSizes.smallMedium
525​
526​ source: model.icon.name
527​ }
528​
529​ PlasmaExtras.Heading {
530​ Layout.fillWidth: true
531​
532​ level: 5
533​
534​ text: model.text
535​ textFormat: listItem.allowStyledText ? Text.StyledText : Text.PlainText
536​ elide: Text.ElideRight
537​ maximumLineCount: 1
538​ }
539​ }
540​ }
541​ }
542​ }
543​ }
544​}