summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopetepicture.h
blob: 5631afc14f5bdbaed3677b406c083b237ef2fdd3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
/*
    kopetepicture.h - Kopete Picture

    Copyright (c) 2005      by Michaël Larouche       <michael.larouche@kdemail.net>

    Kopete    (c) 2002-2005 by the Kopete developers  <kopete-devel@kde.org>

    *************************************************************************
    *                                                                       *
    * This library is free software; you can redistribute it and/or         *
    * modify it under the terms of the GNU Lesser General Public            *
    * License as published by the Free Software Foundation; either          *
    * version 2 of the License, or (at your option) any later version.      *
    *                                                                       *
    *************************************************************************
*/
#ifndef KOPETEPICTURE_H
#define KOPETEPICTURE_H

#include <kdemacros.h>
#include <ksharedptr.h>
#include "kopete_export.h"

#include <qimage.h>

namespace KABC
{
	class Picture;
}

namespace Kopete
{
/**
 * @brief Represent a picture in Kopete context
 *
 * It kept a cache of a QImage object, a base64 string and
 * a path to a image file. It ensure that all source are synced.
 * Interally, the image is stored in PNG format when possible.
 * It can happen that the image path do not return a PNG file.
 *
 * You can only use an QImage and a image path to create/update
 * the picture.
 * If the picture doesn't exist as a file, it generate a local
 * copy into ~/.kde/share/apps/kopete/metacontactpicturecache
 *
 * This class is implicitly shared, so don't use it as a pointer.
 *
 * How to use this class:
 * @code
 * Kopete::Picture picture;
 * picture.setPicture(QImage());
 * picture.setPicture(QString("/tmp/image.png"));
 * 
 * QString base64 = picture.base64();
 * QString path = picture.path();
 * QImage image = picture.image();
 * @endcode
 *
 * @author Michaël Larouche <michael.larouche@kdemail.net>
 */
class KOPETE_EXPORT Picture	
{
public:
	/**
	 * Create a empty Kopete::Picture
	 */
	Picture();
	/**
	 * Create a picture from a local path.
	 */
	Picture(const QString &path);
	/**
	 * Create a picture from a QImage.
	 */
	Picture(const QImage &image);
	/**
	 * Create a picture from a KABC::Picture.
	 */
	Picture(const KABC::Picture &picture);
	/**
	 * Copy a picture. It doesn't create a full copy, it just make a reference.
	 */
	Picture(const Picture &other);
	/**
	 * Delete the Kopete::Picture
	 */
	~Picture();
	/**
	 * Assignment operator.
	 * Like the copy constructor, it just make a reference.
	 */
	Picture &operator=(const Picture &other);

	/**
	 * Return the current picture as QImage.
	 * QImage can used to draw the image on a context.
	 * 
	 * @return the QImage cache of current picture.
	 */
	QImage image();
	/**
	 * Return the current picture as a base64 string.
	 * The base64 is used to include the picture into a XML/XHTML context.
	 */
	QString base64();
	/**
	 * Return the local path of the current picture.
	 */
	QString path();

	/**
	 * Check if the picture is null.
 	 */
	bool isNull();
	/**
	 * Reset the picture.
	 */
	void clear();

	/**
	 * Set the picture content.
	 * @param image the picture as a QImage.
	 */
	void setPicture(const QImage &image);
	/**
	 * Set the picture content.
	 * @param path the path to the picture.
	 */
	void setPicture(const QString &path);
	/**
	 * Set the picture content.
	 * @param picture a KABC Picture.
	 */
	void setPicture(const KABC::Picture &picture);
	
private:
	/**
	 * Kopete::Picture is implicitly shared.
	 * Detach the instance when modifying data.
	 */
	void detach();

	class Private;
	KSharedPtr<Private> d;
};

}//END namespace Kopete

#endif