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.platform as Platform
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 ? Platform.Theme.highlightedTextColor : Platform.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 ? Platform.Theme.highlightedTextColor
68 : Platform.ColorUtils.linearInterpolation(color, Platform.Theme.backgroundColor, 0.3)
69 /**
70 * The font used to display the title.
71 */
72 property font font: Platform.Theme.defaultFont
73 /**
74 * The font used to display the subtitle.
75 */
76 property font subtitleFont: Platform.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
105 /**
106 * @brief Emitted when the user clicks on a link embedded in the text of the title or subtitle.
107 */
108 signal linkActivated(string link)
109
110 /**
111 * @brief Emitted when the user hovers on a link embedded in the text of the title or subtitle.
112 */
113 signal linkHovered(string link)
114
115 implicitWidth: Math.max(labelItem.implicitWidth, subtitleItem.implicitWidth)
116 implicitHeight: labelItem.implicitHeight + (subtitleVisible ? subtitleItem.implicitHeight : 0)
117
118 Text {
119 id: labelItem
120
121 anchors {
122 left: parent.left
123 right: parent.right
124 verticalCenter: parent.verticalCenter
125 }
126
127 // Switch off here as this is expected to be set in the base component.
128 Accessible.ignored: true
129
130 text: root.title
131 color: root.color
132 font: root.font
133 elide: root.elide
134 wrapMode: root.wrapMode
135
136 onLinkActivated: link => root.linkActivated(link)
137 onLinkHovered: link => root.linkHovered(link)
138
139 // Work around Qt bug where left aligned text is not right aligned
140 // in RTL mode unless horizontalAlignment is explicitly set.
141 // https://bugreports.qt.io/browse/QTBUG-95873
142 horizontalAlignment: Text.AlignLeft
143
144 renderType: Text.NativeRendering
145
146 // Note: Can't do this through ordinary bindings as the order between
147 // binding evaluation is not defined which leads to incorrect sizing or
148 // the QML engine complaining about not being able to anchor to null items.
149 states: State {
150 // Note: Same thing about visibility as in subtitleVisible above.
151 when: root.subtitle.length > 0
152 AnchorChanges {
153 target: labelItem
154 anchors.verticalCenter: undefined
155 anchors.bottom: subtitleItem.top
156 }
157 }
158 }
159
160 Text {
161 id: subtitleItem
162
163 anchors {
164 left: parent.left
165 right: parent.right
166 bottom: parent.bottom
167 }
168
169 text: root.subtitle
170 color: root.subtitleColor
171 font: root.subtitleFont
172 elide: root.elide
173 wrapMode: root.wrapMode
174
175 visible: text.length > 0
176
177 onLinkActivated: link => root.linkActivated(link)
178 onLinkHovered: link => root.linkHovered(link)
179
180 // Work around Qt bug where left aligned text is not right aligned
181 // in RTL mode unless horizontalAlignment is explicitly set.
182 // https://bugreports.qt.io/browse/QTBUG-95873
183 horizontalAlignment: Text.AlignLeft
184
185 renderType: Text.NativeRendering
186 }
187}
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 12:00:02 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.