File indexing completed on 2024-04-14 03:51:27

0001 /*
0002     This file is part of the KContacts framework.
0003     SPDX-FileCopyrightText: 2002 Tobias Koenig <tokoe@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KCONTACTS_PICTURE_H
0009 #define KCONTACTS_PICTURE_H
0010 
0011 #include "kcontacts_export.h"
0012 
0013 #include <QDataStream>
0014 #include <QImage>
0015 #include <QSharedDataPointer>
0016 #include <QString>
0017 
0018 namespace KContacts
0019 {
0020 class PicturePrivate;
0021 
0022 /**
0023   A class to store a picture of an addressee. It can store the data directly or
0024   an url reference to a picture.
0025 */
0026 class KCONTACTS_EXPORT Picture
0027 {
0028     friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Picture &);
0029     friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Picture &);
0030 
0031     Q_GADGET
0032     Q_PROPERTY(QImage data READ data WRITE setData)
0033     Q_PROPERTY(QString url READ url WRITE setUrl)
0034     Q_PROPERTY(bool isIntern READ isIntern)
0035     Q_PROPERTY(bool isEmpty READ isEmpty)
0036 
0037 public:
0038     /**
0039      * Creates an empty picture.
0040      */
0041     Picture();
0042 
0043     /**
0044      * Creates a picture which points to the given url.
0045      *
0046      * @param url A URL that describes the location of the picture file.
0047      */
0048     Picture(const QString &url);
0049 
0050     /**
0051      * Creates a picture with the given data.
0052      *
0053      * @param data The raw data of the picture.
0054      */
0055     Picture(const QImage &data);
0056 
0057     /**
0058      * Copy constructor.
0059      *
0060      * Fast operation, Picture's data is implicitly shared.
0061      *
0062      * @param picture The Picture instance to copy from
0063      */
0064     Picture(const Picture &picture);
0065 
0066     /**
0067      * Destructor.
0068      */
0069     ~Picture();
0070 
0071     typedef QList<Picture> List;
0072     /**
0073      * Assignment operator
0074      *
0075      * Fast operation, Picture's data is implicitly shared.
0076      *
0077      * @param other The Picture instance to assign to @c this
0078      */
0079     Picture &operator=(const Picture &other);
0080 
0081     /**
0082      * Equality operator.
0083      */
0084     Q_REQUIRED_RESULT bool operator==(const Picture &other) const;
0085 
0086     /**
0087      * Not-Equal operator.
0088      */
0089     Q_REQUIRED_RESULT bool operator!=(const Picture &other) const;
0090 
0091     /**
0092      * Returns true, if the picture is empty.
0093      */
0094     Q_REQUIRED_RESULT bool isEmpty() const;
0095 
0096     /**
0097      * Sets a URL for the location of the picture file. When using this
0098      * function, isIntern() will return 'false' until you use
0099      * setData().
0100      * This also clears the type, as it is unknown.
0101      *
0102      * @param url  The location URL of the picture file.
0103      */
0104     void setUrl(const QString &url);
0105 
0106     /**
0107      * Sets a URL for the location of the picture file. When using this
0108      * function, isIntern() will return 'false' until you use
0109      * setData().
0110      *
0111      * @param url  The location URL of the picture file.
0112      * @param type  The encoding format of the image, e.g. jpeg or png
0113      * @since 4.10
0114      */
0115     void setUrl(const QString &url, const QString &type);
0116 
0117     /**
0118      * Sets the image data of the picture. When using this function,
0119      * isIntern() will return 'true' until you use setUrl().
0120      * This also sets type to "png" or "jpeg" depending
0121      * on whether the image has an alpha channel or not.
0122      *
0123      * @param data  The image data of the picture.
0124      */
0125     void setData(const QImage &data);
0126 
0127     /**
0128      * Sets the raw data of the picture. When using this function,
0129      * isIntern() will return 'true' until you use setUrl().
0130      *
0131      * @param rawData  The raw data of the picture.
0132      * @param type  The encoding format of the image, e.g. jpeg or png
0133      * @since 4.10
0134      */
0135     void setRawData(const QByteArray &rawData, const QString &type);
0136 
0137     /**
0138      * Returns whether the picture is described by a URL (extern) or
0139      * by the raw data (intern).
0140      * When this method returns 'true' you can use data() to
0141      * get the raw data. Otherwise you can request the URL of this
0142      * picture by url() and load the raw data from that location.
0143      */
0144     Q_REQUIRED_RESULT bool isIntern() const;
0145 
0146     /**
0147      * Returns the location URL of this picture.
0148      */
0149     Q_REQUIRED_RESULT QString url() const;
0150 
0151     /**
0152      * Returns the image data of this picture.
0153      */
0154     Q_REQUIRED_RESULT QImage data() const;
0155 
0156     /**
0157      * Returns the raw data of this picture.
0158      *
0159      * @since 4.10
0160      */
0161     Q_REQUIRED_RESULT QByteArray rawData() const;
0162 
0163     /**
0164      * Returns the type of this picture.
0165      */
0166     Q_REQUIRED_RESULT QString type() const;
0167 
0168     /**
0169      * Returns string representation of the picture.
0170      */
0171     Q_REQUIRED_RESULT QString toString() const;
0172 
0173 private:
0174     QSharedDataPointer<PicturePrivate> d;
0175 };
0176 
0177 /**
0178  * Serializes the @p picture object into the @p stream.
0179  */
0180 KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Picture &picture);
0181 
0182 /**
0183  * Initializes the @p picture object from the @p stream.
0184  */
0185 KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Picture &picture);
0186 }
0187 Q_DECLARE_TYPEINFO(KContacts::Picture, Q_RELOCATABLE_TYPE);
0188 #endif