1/*
2 This file is part of the KContacts framework.
3 SPDX-FileCopyrightText: 2002 Tobias Koenig <tokoe@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCONTACTS_PICTURE_H
9#define KCONTACTS_PICTURE_H
10
11#include "kcontacts_export.h"
12
13#include <QDataStream>
14#include <QImage>
15#include <QSharedDataPointer>
16#include <QString>
17
18namespace KContacts
19{
20class PicturePrivate;
21
22/*!
23 * \qmlvaluetype picture
24 * \inqmlmodule org.kde.contacts
25 * \nativetype KContacts::Picture
26 *
27 * \brief A class to store a picture of an addressee.
28 *
29 * It can store the data directly or
30 * an url reference to a picture.
31 */
32
33/*!
34 * \class KContacts::Picture
35 * \inheaderfile KContacts/Picture
36 * \inmodule KContacts
37 *
38 * \brief A class to store a picture of an addressee.
39 *
40 * It can store the data directly or
41 * an url reference to a picture.
42 */
43class KCONTACTS_EXPORT Picture
44{
45 friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Picture &);
46 friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Picture &);
47
48 Q_GADGET
49
50 /*!
51 * \qmlproperty image picture::data
52 */
53
54 /*!
55 * \property KContacts::Picture::data
56 */
57 Q_PROPERTY(QImage data READ data WRITE setData)
58
59 /*!
60 * \qmlproperty string picture::url
61 */
62
63 /*!
64 * \property KContacts::Picture::url
65 */
66 Q_PROPERTY(QString url READ url WRITE setUrl)
67
68 /*!
69 * \qmlproperty bool picture::isIntern
70 */
71
72 /*!
73 * \property KContacts::Picture::isIntern
74 */
75 Q_PROPERTY(bool isIntern READ isIntern)
76
77 /*!
78 * \qmlproperty bool picture::isEmpty
79 */
80
81 /*!
82 * \property KContacts::Picture::isEmpty
83 */
84 Q_PROPERTY(bool isEmpty READ isEmpty)
85
86public:
87 /*!
88 * Creates an empty picture.
89 */
90 Picture();
91
92 /*!
93 * Creates a picture which points to the given url.
94 *
95 * \a url A URL that describes the location of the picture file.
96 */
97 Picture(const QString &url);
98
99 /*!
100 * Creates a picture with the given data.
101 *
102 * \a data The raw data of the picture.
103 */
104 Picture(const QImage &data);
105
106 /*!
107 * Copy constructor.
108 *
109 * Fast operation, Picture's data is implicitly shared.
110 *
111 * \a picture The Picture instance to copy from
112 */
113 Picture(const Picture &picture);
114
115 ~Picture();
116
117 /*!
118 */
119 typedef QList<Picture> List;
120
121 /*!
122 * Assignment operator
123 *
124 * Fast operation, Picture's data is implicitly shared.
125 *
126 * \a other The Picture instance to assign to \c this
127 */
128 Picture &operator=(const Picture &other);
129
130 /*!
131 * Equality operator.
132 */
133 Q_REQUIRED_RESULT bool operator==(const Picture &other) const;
134
135 /*!
136 * Not-Equal operator.
137 */
138 Q_REQUIRED_RESULT bool operator!=(const Picture &other) const;
139
140 /*!
141 * Returns true, if the picture is empty.
142 */
143 Q_REQUIRED_RESULT bool isEmpty() const;
144
145 /*!
146 * Sets a URL for the location of the picture file. When using this
147 * function, isIntern() will return 'false' until you use
148 * setData().
149 * This also clears the type, as it is unknown.
150 *
151 * \a url The location URL of the picture file.
152 */
153 void setUrl(const QString &url);
154
155 /*!
156 * Sets a URL for the location of the picture file. When using this
157 * function, isIntern() will return 'false' until you use
158 * setData().
159 *
160 * \a url The location URL of the picture file.
161 *
162 * \a type The encoding format of the image, e.g. jpeg or png
163 *
164 * \since 4.10
165 */
166 void setUrl(const QString &url, const QString &type);
167
168 /*!
169 * Sets the image data of the picture. When using this function,
170 * isIntern() will return 'true' until you use setUrl().
171 * This also sets type to "png" or "jpeg" depending
172 * on whether the image has an alpha channel or not.
173 *
174 * \a data The image data of the picture.
175 */
176 void setData(const QImage &data);
177
178 /*!
179 * Sets the raw data of the picture. When using this function,
180 * isIntern() will return 'true' until you use setUrl().
181 *
182 * \a rawData The raw data of the picture.
183 *
184 * \a type The encoding format of the image, e.g. jpeg or png
185 *
186 * \since 4.10
187 */
188 void setRawData(const QByteArray &rawData, const QString &type);
189
190 /*!
191 * Returns whether the picture is described by a URL (extern) or
192 * by the raw data (intern).
193 *
194 * When this method returns 'true' you can use data() to
195 * get the raw data. Otherwise you can request the URL of this
196 * picture by url() and load the raw data from that location.
197 */
198 Q_REQUIRED_RESULT bool isIntern() const;
199
200 /*!
201 * Returns the location URL of this picture.
202 */
203 Q_REQUIRED_RESULT QString url() const;
204
205 /*!
206 * Returns the image data of this picture.
207 */
208 Q_REQUIRED_RESULT QImage data() const;
209
210 /*!
211 * Returns the raw data of this picture.
212 *
213 * \since 4.10
214 */
215 Q_REQUIRED_RESULT QByteArray rawData() const;
216
217 /*!
218 * Returns the type of this picture.
219 */
220 Q_REQUIRED_RESULT QString type() const;
221
222 /*!
223 * Returns string representation of the picture.
224 */
225 Q_REQUIRED_RESULT QString toString() const;
226
227private:
228 QSharedDataPointer<PicturePrivate> d;
229};
230
231/*!
232 * \relates KContacts::Picture
233 *
234 * Serializes the \a picture object into the \a stream.
235 */
236KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Picture &picture);
237
238/*!
239 * \relates KContacts::Picture
240 *
241 * Initializes the \a picture object from the \a stream.
242 */
243KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Picture &picture);
244}
245Q_DECLARE_TYPEINFO(KContacts::Picture, Q_RELOCATABLE_TYPE);
246#endif
247

source code of kcontacts/src/picture.h