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 A class to store a picture of an addressee. It can store the data directly or
24 an url reference to a picture.
25*/
26class KCONTACTS_EXPORT Picture
27{
28 friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Picture &);
29 friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Picture &);
30
31 Q_GADGET
32 Q_PROPERTY(QImage data READ data WRITE setData)
33 Q_PROPERTY(QString url READ url WRITE setUrl)
34 Q_PROPERTY(bool isIntern READ isIntern)
35 Q_PROPERTY(bool isEmpty READ isEmpty)
36
37public:
38 /**
39 * Creates an empty picture.
40 */
41 Picture();
42
43 /**
44 * Creates a picture which points to the given url.
45 *
46 * @param url A URL that describes the location of the picture file.
47 */
48 Picture(const QString &url);
49
50 /**
51 * Creates a picture with the given data.
52 *
53 * @param data The raw data of the picture.
54 */
55 Picture(const QImage &data);
56
57 /**
58 * Copy constructor.
59 *
60 * Fast operation, Picture's data is implicitly shared.
61 *
62 * @param picture The Picture instance to copy from
63 */
64 Picture(const Picture &picture);
65
66 /**
67 * Destructor.
68 */
69 ~Picture();
70
71 typedef QList<Picture> List;
72 /**
73 * Assignment operator
74 *
75 * Fast operation, Picture's data is implicitly shared.
76 *
77 * @param other The Picture instance to assign to @c this
78 */
79 Picture &operator=(const Picture &other);
80
81 /**
82 * Equality operator.
83 */
84 Q_REQUIRED_RESULT bool operator==(const Picture &other) const;
85
86 /**
87 * Not-Equal operator.
88 */
89 Q_REQUIRED_RESULT bool operator!=(const Picture &other) const;
90
91 /**
92 * Returns true, if the picture is empty.
93 */
94 Q_REQUIRED_RESULT bool isEmpty() const;
95
96 /**
97 * Sets a URL for the location of the picture file. When using this
98 * function, isIntern() will return 'false' until you use
99 * setData().
100 * This also clears the type, as it is unknown.
101 *
102 * @param url The location URL of the picture file.
103 */
104 void setUrl(const QString &url);
105
106 /**
107 * Sets a URL for the location of the picture file. When using this
108 * function, isIntern() will return 'false' until you use
109 * setData().
110 *
111 * @param url The location URL of the picture file.
112 * @param type The encoding format of the image, e.g. jpeg or png
113 * @since 4.10
114 */
115 void setUrl(const QString &url, const QString &type);
116
117 /**
118 * Sets the image data of the picture. When using this function,
119 * isIntern() will return 'true' until you use setUrl().
120 * This also sets type to "png" or "jpeg" depending
121 * on whether the image has an alpha channel or not.
122 *
123 * @param data The image data of the picture.
124 */
125 void setData(const QImage &data);
126
127 /**
128 * Sets the raw data of the picture. When using this function,
129 * isIntern() will return 'true' until you use setUrl().
130 *
131 * @param rawData The raw data of the picture.
132 * @param type The encoding format of the image, e.g. jpeg or png
133 * @since 4.10
134 */
135 void setRawData(const QByteArray &rawData, const QString &type);
136
137 /**
138 * Returns whether the picture is described by a URL (extern) or
139 * by the raw data (intern).
140 * When this method returns 'true' you can use data() to
141 * get the raw data. Otherwise you can request the URL of this
142 * picture by url() and load the raw data from that location.
143 */
144 Q_REQUIRED_RESULT bool isIntern() const;
145
146 /**
147 * Returns the location URL of this picture.
148 */
149 Q_REQUIRED_RESULT QString url() const;
150
151 /**
152 * Returns the image data of this picture.
153 */
154 Q_REQUIRED_RESULT QImage data() const;
155
156 /**
157 * Returns the raw data of this picture.
158 *
159 * @since 4.10
160 */
161 Q_REQUIRED_RESULT QByteArray rawData() const;
162
163 /**
164 * Returns the type of this picture.
165 */
166 Q_REQUIRED_RESULT QString type() const;
167
168 /**
169 * Returns string representation of the picture.
170 */
171 Q_REQUIRED_RESULT QString toString() const;
172
173private:
174 QSharedDataPointer<PicturePrivate> d;
175};
176
177/**
178 * Serializes the @p picture object into the @p stream.
179 */
180KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Picture &picture);
181
182/**
183 * Initializes the @p picture object from the @p stream.
184 */
185KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Picture &picture);
186}
187Q_DECLARE_TYPEINFO(KContacts::Picture, Q_RELOCATABLE_TYPE);
188#endif
189

source code of kcontacts/src/picture.h