Kirigami2

TitleSubtitle.qml
1/*
2 * SPDX-FileCopyrightText: 2010 Marco Martin <notmart@gmail.com>
3 * SPDX-FileCopyrightText: 2022 ivan tkachenko <me@ratijas.tk>
4 * SPDX-FileCopyrightText: 2023 Arjen Hiemstra <ahiemstra@heimr.nl>
5 *
6 * SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8
9import QtQuick
10import org.kde.kirigami as Kirigami
11
12/**
13 * A simple item containing a title and subtitle label.
14 *
15 * This is mainly intended as a replacement for a list delegate content item,
16 * but can be used as a replacement for other content items as well.
17 *
18 * When using it as a contentItem, make sure to bind the appropriate properties
19 * to those of the Control. Prefer binding to the Control's properties over
20 * setting the properties directly, as the Control's properties may affect other
21 * things like setting accessible names.
22 *
23 * Example usage as contentItem of an ItemDelegate:
24 *
25 * ```qml
26 * ItemDelegate {
27 * id: delegate
28 *
29 * text: "Example"
30 *
31 * contentItem: Kirigami.TitleSubtitle {
32 * title: delegate.text
33 * subtitle: "This is an example."
34 * font: delegate.font
35 * selected: delegate.highlighted || delegate.down
36 * }
37 * }
38 * ```
39 *
40 * \sa Kirigami::Delegates::IconTitleSubtitle
41 * \sa Kirigami::Delegates::ItemDelegate
42 */
43Item {
44 id: root
45
46 /**
47 * The title to display.
48 */
49 required property string title
50 /**
51 * The subtitle to display.
52 */
53 property string subtitle
54 /**
55 * The color to use for the title.
56 *
57 * By default this is `Kirigami.Theme.textColor` unless `selected` is true
58 * in which case this is `Kirigami.Theme.highlightedTextColor`.
59 */
60 property color color: selected ? Kirigami.Theme.highlightedTextColor : Kirigami.Theme.textColor
61 /**
62 * The color to use for the subtitle.
63 *
64 * By default this is `color` mixed with the background color.
65 */
66 property color subtitleColor: selected
67 ? Kirigami.Theme.highlightedTextColor
68 : Kirigami.ColorUtils.linearInterpolation(color, Kirigami.Theme.backgroundColor, 0.3)
69 /**
70 * The font used to display the title.
71 */
72 property font font: Kirigami.Theme.defaultFont
73 /**
74 * The font used to display the subtitle.
75 */
76 property font subtitleFont: Kirigami.Theme.smallFont
77 /**
78 * The text elision mode used for both the title and subtitle.
79 */
80 property int elide: Text.ElideRight
81 /**
82 * The text wrap mode used for both the title and subtitle.
83 */
84 property int wrapMode: Text.NoWrap
85 /**
86 * Make the implicit height use the subtitle's height even if no subtitle is set.
87 */
88 property bool reserveSpaceForSubtitle: false
89 /**
90 * Should this item be displayed in a selected style?
91 */
92 property bool selected: false
93 /**
94 * Is the subtitle visible?
95 */
96 // Note: Don't rely on subtitleItem.visible because visibility is an
97 // implicitly propagated property, and we don't wanna re-layout on
98 // hide/show events. Copy-paste its bound expression instead.
99 readonly property bool subtitleVisible: subtitle.length > 0 || reserveSpaceForSubtitle
100 /**
101 * Is the title or subtitle truncated?
102 */
103 readonly property bool truncated: labelItem.truncated || subtitleItem.truncated
104
105 implicitWidth: Math.max(labelItem.implicitWidth, subtitleItem.implicitWidth)
106 implicitHeight: labelItem.implicitHeight + (subtitleVisible ? subtitleItem.implicitHeight : 0)
107
108 Text {
109 id: labelItem
110
111 anchors {
112 left: parent.left
113 right: parent.right
114 verticalCenter: parent.verticalCenter
115 }
116
117 text: root.title
118 color: root.color
119 font: root.font
120 elide: root.elide
121 wrapMode: root.wrapMode
122
123 // Work around Qt bug where left aligned text is not right aligned
124 // in RTL mode unless horizontalAlignment is explicitly set.
125 // https://bugreports.qt.io/browse/QTBUG-95873
126 horizontalAlignment: Text.AlignLeft
127
128 renderType: Text.NativeRendering
129
130 // Note: Can't do this through ordinary bindings as the order between
131 // binding evaluation is not defined which leads to incorrect sizing or
132 // the QML engine complaining about not being able to anchor to null items.
133 states: State {
134 // Note: Same thing about visibility as in subtitleVisible above.
135 when: root.subtitle.length > 0
136 AnchorChanges {
137 target: labelItem
138 anchors.verticalCenter: undefined
139 anchors.bottom: subtitleItem.top
140 }
141 }
142 }
143
144 Text {
145 id: subtitleItem
146
147 anchors {
148 left: parent.left
149 right: parent.right
150 bottom: parent.bottom
151 }
152
153 text: root.subtitle
154 color: root.subtitleColor
155 font: root.subtitleFont
156 elide: root.elide
157 wrapMode: root.wrapMode
158
159 visible: text.length > 0
160
161 // Work around Qt bug where left aligned text is not right aligned
162 // in RTL mode unless horizontalAlignment is explicitly set.
163 // https://bugreports.qt.io/browse/QTBUG-95873
164 horizontalAlignment: Text.AlignLeft
165
166 renderType: Text.NativeRendering
167 }
168}
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:18:46 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.