1/*
2 This file is part of libkabc.
3 Copyright (c) 2002 Tobias Koenig <tokoe@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_PICTURE_H
22#define KABC_PICTURE_H
23
24#include "kabc_export.h"
25
26#include <QtCore/QDataStream>
27#include <QtCore/QString>
28#include <QtCore/QSharedDataPointer>
29#include <QImage>
30
31namespace KABC {
32
33class PicturePrivate;
34
35/**
36 A class to store a picture of an addressee. It can store the data directly or
37 an url reference to a picture.
38*/
39class KABC_EXPORT Picture
40{
41 friend KABC_EXPORT QDataStream &operator<<( QDataStream &, const Picture & );
42 friend KABC_EXPORT QDataStream &operator>>( QDataStream &, Picture & );
43
44 public:
45 /**
46 * Creates an empty picture.
47 */
48 Picture();
49
50 /**
51 * Creates a picture which points to the given url.
52 *
53 * @param url A URL that describes the location of the picture file.
54 */
55 Picture( const QString &url );
56
57 /**
58 * Creates a picture with the given data.
59 *
60 * @param data The raw data of the picture.
61 */
62 Picture( const QImage &data );
63
64 /**
65 * Copy constructor.
66 *
67 * Fast operation, Picture's data is implicitly shared.
68 *
69 * @param picture The Picture instance to copy from
70 */
71 Picture( const Picture &picture );
72
73 /**
74 * Destructor.
75 */
76 ~Picture();
77
78 /**
79 * Assignment operator
80 *
81 * Fast operation, Picture's data is implicitly shared.
82 *
83 * @param other The Picture instance to assign to @c this
84 */
85 Picture &operator=( const Picture &other );
86
87 /**
88 * Equality operator.
89 */
90 bool operator==( const Picture & ) const;
91
92 /**
93 * Not-Equal operator.
94 */
95 bool operator!=( const Picture & ) const;
96
97 /**
98 * Returns true, if the picture is empty.
99 */
100 bool isEmpty() const;
101
102 /**
103 * Sets a URL for the location of the picture file. When using this
104 * function, isIntern() will return 'false' until you use
105 * setData().
106 * This also clears the type, as it is unknown.
107 *
108 * @param url The location URL of the picture file.
109 */
110 void setUrl( const QString &url );
111
112 /**
113 * Sets a URL for the location of the picture file. When using this
114 * function, isIntern() will return 'false' until you use
115 * setData().
116 *
117 * @param url The location URL of the picture file.
118 * @param type The encoding format of the image, e.g. jpeg or png
119 * @since 4.10
120 */
121 void setUrl( const QString &url, const QString &type );
122
123 /**
124 * Sets the image data of the picture. When using this function,
125 * isIntern() will return 'true' until you use setUrl().
126 * This also sets type to "png" or "jpeg" depending
127 * on whether the image has an alpha channel or not.
128 *
129 * @param data The image data of the picture.
130 */
131 void setData( const QImage &data );
132
133 /**
134 * Sets the raw data of the picture. When using this function,
135 * isIntern() will return 'true' until you use setUrl().
136 *
137 * @param rawData The raw data of the picture.
138 * @param type The encoding format of the image, e.g. jpeg or png
139 * @since 4.10
140 */
141 void setRawData( const QByteArray &rawData, const QString &type );
142
143 /**
144 * Sets the type of the picture.
145 * @param type the picture's data type
146 * @deprecated type should only be set along with setRawData()
147 */
148 void KABC_DEPRECATED setType( const QString &type );
149
150 /**
151 * Returns whether the picture is described by a URL (extern) or
152 * by the raw data (intern).
153 * When this method returns 'true' you can use data() to
154 * get the raw data. Otherwise you can request the URL of this
155 * picture by url() and load the raw data from that location.
156 */
157 bool isIntern() const;
158
159 /**
160 * Returns the location URL of this picture.
161 */
162 QString url() const;
163
164 /**
165 * Returns the image data of this picture.
166 */
167 QImage data() const;
168
169 /**
170 * Returns the raw data of this picture.
171 *
172 * @since 4.10
173 */
174 QByteArray rawData() const;
175
176 /**
177 * Returns the type of this picture.
178 */
179 QString type() const;
180
181 /**
182 * Returns string representation of the picture.
183 */
184 QString toString() const;
185
186 private:
187 QSharedDataPointer<PicturePrivate> d;
188};
189
190/**
191 * Serializes the @p picture object into the @p stream.
192 */
193KABC_EXPORT QDataStream &operator<<( QDataStream &stream, const Picture &picture );
194
195/**
196 * Initializes the @p picture object from the @p stream.
197 */
198KABC_EXPORT QDataStream &operator>>( QDataStream &stream, Picture &picture );
199
200}
201
202#endif
203