Kirigami-addons

Avatar.qml
1/*
2 * SPDX-FileCopyrightText: 2020 Carson Black <uhhadd@gmail.com>
3 * SPDX-FileCopyrightText: 2023 ivan tkachenko <me@ratijas.tk>
4 *
5 * SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7
8import QtQuick 2.15
9import QtQuick.Window 2.15
10import org.kde.kirigami 2.15 as Kirigami
11import org.kde.kirigamiaddons.components 1.0 as Components
12
13/**
14 * @brief An element that represents a user, either with initials, an icon, or a profile image.
15 * @inherit QtQuick.Item
16 */
17Item {
18 id: root
19
20 enum ImageMode {
21 AlwaysShowImage,
22 AdaptiveImageOrInitals,
23 AlwaysShowInitials
24 }
25
26 enum InitialsMode {
27 UseInitials,
28 UseIcon
29 }
30
31//BEGIN properties
32 /**
33 * @brief This property holds the given name of a user.
34 *
35 * The user's name will be used for generating initials and to provide the
36 * accessible name for assistive technology.
37 */
38 property string name
40 /**
41 * @brief This property holds the source of the user's profile picture; an image.
42 * @see QtQuick.Image::source
43 * @property url source
44 */
45 property alias source: avatarImage.source
46
47 /**
48 * @brief This property holds avatar's icon source.
49 *
50 * This icon is displayed when using an icon with ``Avatar.InitialsMode.UseIcon`` and
51 * ``Avatar.ImageNode.AlwaysShowInitials`` enabled.
52 *
53 * @see org::kde::kirigami::Icon::source
54 * @property var iconSource
55 */
56 property alias iconSource: avatarIcon.source
57
58 /**
59 * @brief This property holds how the button should represent the user when no user-set image is available.
60 *
61 * Possible values are:
62 * * ``Avatar.InitialsMode.UseInitials``: Show the user's initials.
63 * * ``Avatar.InitialsMode.UseIcon``: Show a generic icon.
64 *
65 * @see org::kde::kirigamiaddons::components::Avatar::InitialsMode
66 */
67 property int initialsMode: Avatar.InitialsMode.UseInitials
68
69 /**
70 * @brief This property holds how the avatar should be shown.
71 *
72 * This property holds whether the button should always show the image; show the image if one is
73 * available and show initials when it is not; or always show initials.
74 *
75 * Possible values are:
76 * * ``Avatar.ImageMode.AlwaysShowImage``: Always try to show the image; even if it hasn't loaded yet or is undefined.
77 * * ``Avatar.ImageMode.AdaptiveImageOrInitals``: Show the image if it is valid; or show initials if it is not
78 * * ``Avatar.ImageMode.AlwaysShowInitials``: Always show initials
79 *
80 * @see org::kde::kirigamiaddons::components::Avatar::ImageMode
81 */
82 property int imageMode: Avatar.ImageMode.AdaptiveImageOrInitals
83
84 /**
85 * @brief This property sets whether the provided image should be cached.
86 * @see QtQuick.Image::cache
87 * @property bool cache
88 */
89 property alias cache: avatarImage.cache
90
91 /**
92 * @brief This property holds the source size of the user's profile picture.
93 * @see QtQuick.Image::sourceSize
94 * @property int sourceSize
95 */
96 property alias sourceSize: avatarImage.sourceSize
97
98 /**
99 * @brief This property holds the color to use for this avatar.
100 *
101 * If not explicitly set, this defaults to generating a color from the name.
103 * @property color color
104 */
105 property color color: Components.NameUtils.colorsFromString(name)
106
107 /**
108 * @brief This property holds the color of the avatar's initials.
109 *
110 * If not explicitly set, this defaults to defaultInitialsColor.
112 * @see defaultInitialsColor
113 * @property color initialsColor
114 */
115 property color initialsColor: defaultInitialsColor
116
117 /**
118 * @brief This property holds the default color of the avatar's initials.
120 * It depends on the avatar's color.
121 *
122 * @property color defaultInitialsColor
123 */
124 readonly property alias defaultInitialsColor: root.__textColor
125
126 /**
127 * @brief This item holds the parent item on the clipped circle.
128 *
129 * Implementations may add custom graphics which will be clipped along with
130 * the rest of the avatar content.
131 */
132 readonly property alias clippedContent: clippedContent
133
134 implicitWidth: Kirigami.Units.iconSizes.large
135 implicitHeight: Kirigami.Units.iconSizes.large
136
137 Accessible.role: Accessible.Graphic
138 Accessible.name: name
139
140 readonly property real __diameter: Math.min(root.width, root.height)
141
142 readonly property color __textColor: Kirigami.ColorUtils.brightnessForColor(root.color) === Kirigami.ColorUtils.Light
143 ? "black"
144 : "white"
145
146 readonly property bool __showImage: {
147 switch (root.imageMode) {
148 case Avatar.ImageMode.AlwaysShowImage:
149 return true;
150 case Avatar.ImageMode.AdaptiveImageOrInitals:
151 return avatarImage.status === Image.Ready;
152 case Avatar.ImageMode.AlwaysShowInitials:
153 default:
154 return false;
155 }
156 }
157
158 Item {
159 id: clippedContent
160
161 anchors.centerIn: parent
162
163 width: root.__diameter
164 height: root.__diameter
165
166 Text {
167 anchors.fill: parent
168
169 visible: root.initialsMode === Avatar.InitialsMode.UseInitials &&
170 !root.__showImage &&
171 !Components.NameUtils.isStringUnsuitableForInitials(root.name) &&
172 root.width > Kirigami.Units.gridUnit
173
174 text: Components.NameUtils.initialsFromString(root.name)
175 color: root.color
176
177 font {
178 // this ensures we don't get a both point and pixel size are set warning
179 pointSize: -1
180 pixelSize: Math.round((root.height - Kirigami.Units.largeSpacing) / 2)
181 }
182 fontSizeMode: Text.Fit
183 verticalAlignment: Text.AlignVCenter
184 horizontalAlignment: Text.AlignHCenter
185 }
186
187 Kirigami.Icon {
188 id: avatarIcon
189
190 anchors.fill: parent
191 anchors.margins: Kirigami.Units.largeSpacing
192
193 visible: !root.__showImage
194 && (root.initialsMode === Avatar.InitialsMode.UseIcon
195 || Components.NameUtils.isStringUnsuitableForInitials(root.name))
196
197 color: root.__textColor
198 source: "user"
199 }
200
201 Image {
202 id: avatarImage
203
204 anchors.fill: parent
205
206 visible: root.__showImage
207
208 fillMode: Image.PreserveAspectCrop
209 mipmap: true
210 sourceSize {
211 width: root.__diameter * root.Screen.devicePixelRatio
212 height: root.__diameter * root.Screen.devicePixelRatio
213 }
214 }
215
216 layer {
217 enabled: true
218 effect: Kirigami.ShadowedTexture {
219 radius: root.__diameter
220
221 border {
222 width: root.__showImage ? 0 : 1.25
223 color: root.color
224 }
225
226 color: Kirigami.ColorUtils.tintWithAlpha(Kirigami.Theme.backgroundColor, border.color, 0.07)
227 }
228 }
229 }
230}
An element that represents a user, either with initials, an icon, or a profile image.
Definition Avatar.qml:15
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:05:53 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.