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

not contentHeight?

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