kopete/libkopete/kopetepicture.h

   1 /*
   2     kopetepicture.h - Kopete Picture
   3
   4     Copyright (c) 2005      by Michaël Larouche       <larouche@kde.org>
   5
   6     Kopete    (c) 2002-2005 by the Kopete developers  <kopete-devel@kde.org>
   7
   8     *************************************************************************
   9     *                                                                       *
  10     * This library is free software; you can redistribute it and/or         *
  11     * modify it under the terms of the GNU Lesser General Public            *
  12     * License as published by the Free Software Foundation; either          *
  13     * version 2 of the License, or (at your option) any later version.      *
  14     *                                                                       *
  15     *************************************************************************
  16 */
  17 #ifndef KOPETEPICTURE_H
  18 #define KOPETEPICTURE_H
  19
  20 #include <kdemacros.h>
  21 #include <ksharedptr.h>
  22 #include "kopete_export.h"
  23
  24 #include <QtGui/QImage>
  25
  26 namespace KABC
  27 {
  28         class Picture;
  29 }
  30
  31 namespace Kopete
  32 {
  33 /**
  34  * @brief Represent a picture in Kopete context
  35  *
  36  * It kept a cache of a QImage object, a base64 string and
  37  * a path to a image file. It ensure that all source are synced.
  38  * Interally, the image is stored in PNG format when possible.
  39  * It can happen that the image path do not return a PNG file.
  40  *
  41  * You can only use an QImage and a image path to create/update
  42  * the picture.
  43  * If the picture doesn't exist as a file, it generate a local
  44  * copy into ~/.kde/share/apps/kopete/metacontactpicturecache
  45  *
  46  * This class is implicitly shared, so don't use it as a pointer.
  47  *
  48  * How to use this class:
  49  * @code
  50  * Kopete::Picture picture;
  51  * picture.setPicture(QImage());
  52  * picture.setPicture(QString("/tmp/image.png"));
  53  *
  54  * QString base64 = picture.base64();
  55  * QString path = picture.path();
  56  * QImage image = picture.image();
  57  * @endcode
  58  *
  59  * @author Michaël Larouche <larouche@kde.org>
  60  */
  61 class KOPETE_EXPORT Picture
  62 {
  63 public:
  64         /**
  65          * Create a empty Kopete::Picture
  66          */
  67         Picture();
  68         /**
  69          * Create a picture from a local path.
  70          */
  71         explicit Picture(const QString &path);
  72         /**
  73          * Create a picture from a QImage.
  74          */
  75         explicit Picture(const QImage &image);
  76         /**
  77          * Create a picture from a KABC::Picture.
  78          */
  79         explicit Picture(const KABC::Picture &picture);
  80         /**
  81          * Copy a picture. It doesn't create a full copy, it just make a reference.
  82          */
  83         Picture(const Picture &other);
  84         /**
  85          * Delete the Kopete::Picture
  86          */
  87         ~Picture();
  88         /**
  89          * Assignment operator.
  90          * Like the copy constructor, it just make a reference.
  91          */
  92         Picture &operator=(const Picture &other);
  93
  94         /**
  95          * Return the current picture as QImage.
  96          * QImage can used to draw the image on a context.
  97          *
  98          * @return the QImage cache of current picture.
  99          */
 100         QImage image();
 101         /**
 102          * Return the current picture as a base64 string.
 103          * The base64 is used to include the picture into a XML/XHTML context.
 104          */
 105         QString base64();
 106         /**
 107          * Return the local path of the current picture.
 108          */
 109         QString path();
 110
 111         /**
 112          * Check if the picture is null.
 113          */
 114         bool isNull();
 115         /**
 116          * Reset the picture.
 117          */
 118         void clear();
 119
 120         /**
 121          * Set the picture content.
 122          * @param image the picture as a QImage.
 123          */
 124         void setPicture(const QImage &image);
 125         /**
 126          * Set the picture content.
 127          * @param path the path to the picture.
 128          */
 129         void setPicture(const QString &path);
 130         /**
 131          * Set the picture content.
 132          * @param picture a KABC Picture.
 133          */
 134         void setPicture(const KABC::Picture &picture);
 135
 136 private:
 137         /**
 138          * Kopete::Picture is implicitly shared.
 139          * Detach the instance when modifying data.
 140          */
 141         void detach();
 142
 143         class Private;
 144         KSharedPtr<Private> d;
 145 };
 146
 147 }//END namespace Kopete
 148
 149 #endif