1
/* This file is part of the KDE project
2
Copyright (C) 2005 Jarosław Staniek <staniek@kde.org>
4
This library is free software; you can redistribute it and/or
5
modify it under the terms of the GNU Library General Public
6
License as published by the Free Software Foundation; either
7
version 2 of the License, or (at your option) any later version.
9
This library is distributed in the hope that it will be useful,
10
but WITHOUT ANY WARRANTY; without even the implied warranty of
11
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12
Library General Public License for more details.
14
You should have received a copy of the GNU Library General Public License
15
along with this library; see the file COPYING.LIB. If not, write to
16
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17
* Boston, MA 02110-1301, USA.
20
#ifndef KEXIBLOBBUFFER_H
21
#define KEXIBLOBBUFFER_H
27
#include "kexicore_export.h"
31
//! Application-wide buffer for local BLOB data like pixmaps.
32
/*! For now only pixmaps are supported
33
@todo support any KPart-compatible objects and more...
35
Use this class by acessing to its singleton: KexiBLOBBuffer::self().
37
This class is used for buffering BLOB data,
38
to avoid duplicating object's data in memory and a need for loading (decoding)
39
the same object many times.
40
The data is always local, what means database storage is not employed here.
42
Each BLOB instance is identified by an unsigned integer number (Id_t type),
43
uniquely generated on BLOB loading. Each BLOB can have assigned source url
44
it has been loaded from (the url can be empty though, e.g. for data coming from clipboard).
46
References to KexiBLOBBuffer are counted, so when last reference is lost, data is freed
47
and the integer identifier is no longer pointing any valid data.
48
KexiBLOBBuffer::Handle is value-based class that describes handle based in an identifier.
49
Objects of this class are obtained e.g. from insertPixmap() method.
51
There are two kinds of identifiers:
52
- integers assigned for BLOBs already saved to a db backend,
53
when KexiBLOBBuffer::Handle::stored() is true
54
- temporary integers assigned for new BLOBs not yet saved to a db backend,
55
when KexiBLOBBuffer::Handle::stored() is false
56
KexiBLOBBuffer::Handle::setStoredWidthID() can be used to switch from unstored to stored state.
57
Among others, the state has effect on saving forms: only unstored BLOBs will be saved back
58
to the database; when a BLOB needs to be removed, only it will be physically removed only if it was stored.
60
KexiBLOBBuffer is also useful for two more reasons:
61
- Property editor's item for "image" property displays a preview of pixmap contents.
62
Without buffering, it would be needed to load pixmap data again: what if the file
63
it is loaded from is located remote and connection is slow? Memory would be also unnecessary doubled.
64
- Undo/Redo framework requires to store previous property values. Having a reference defined
65
by a single interger, memory can be handled more effectively.
68
A large pixmap file "abc.jpg" is loaded as QByteArray <b>once</b> and buffered:
69
integer identifier is returned.
70
Then, multiple image widgets are using "abc.jpg" for displaying.
71
Duplicating an image widget means only duplicating it's properties
72
like position and BLOB's id: BLOB itself (data of "abc.jpg") is not duplicated.
73
Creating a new image widget and assiging the same "abc.jpg" pixmap, means only
74
referencing KexiBLOBBuffer using the same identifier.
76
class KEXICORE_EXPORT KexiBLOBBuffer : public QObject
83
//! long integer for unique identifying blobs
84
//! @todo Qt4: will be changed
87
//! Access to KexiBLOBBuffer singleton
88
static KexiBLOBBuffer* self();
90
static void setConnection(KDbConnection *conn);
92
//! Object handle used by KexiBLOBBuffer
93
class KEXICORE_EXPORT Handle
96
//! Constructs a null handle.
97
//! Null handles have empty pixap and data members, id == 0 and cast to boolean false.
100
//! Constructs a copy of \a handle.
101
Handle(const Handle& handle);
106
return m_item ? m_item->id : 0;
109
/*! \return true if this BLOB data pointed by this handle is stored at the db backend
110
or false if it is kept in memory. Null handles return false. */
111
bool stored() const {
112
return m_item ? m_item->stored : false;
115
//! \return true if this is null handle (i.e. one not pointing to any data)
116
operator bool() const {
120
Handle& operator=(const Handle& handle);
122
QByteArray data() const {
123
return m_item ? m_item->data() : QByteArray();
126
QPixmap pixmap() const {
127
return m_item ? m_item->pixmap() : QPixmap();
130
/*! Sets "stored" flag to true by setting non-temporary identifier.
131
Only call this method for unstored (in memory) BLOBs */
132
void setStoredWidthID(Id_t id);
134
QString originalFileName() const {
135
return m_item ? m_item->name : QString();
138
QString mimeType() const {
139
return m_item ? m_item->mimeType : QString();
142
Id_t folderId() const {
143
return m_item ? m_item->folderId : 0;
147
//! Constructs a handle based on \a item. Null handle is constructed for null \a item.
148
explicit Handle(Item* item);
151
friend class KexiBLOBBuffer;
159
/*! Inserts a new pixmap loaded from a file at \a url.
160
If the same file has already been loaded before, it can be found in cache
161
and returned instantly. It is assumed that the BLOB is unstored, because it is loaded from
162
external source, so stored() will be equal to false for returned handle.
163
\return handle to the pixmap data or a null handle if such pixmap could not be loaded. */
164
Handle insertPixmap(const QUrl &url);
166
/*! Inserts a new BLOB data.
167
@param data The data for BLOB object.
168
@param name The name for the object, usually a file name or empty
169
@param caption The more friendly than name, can be based on file name or empty or
170
defined by a user (this case is not yet used)
171
@param mimeType The mimeType for the object for easier and mor accurate decoding.
172
@param identifier Object's identifier. If positive, the "stored" flag for the data
173
will be set to true with \a identifer, otherwise (the default) the BLOB data will
174
have "stored" flag set to false, and a new temporary identifier will be assigned. */
175
Handle insertObject(const QByteArray& data, const QString& name,
176
const QString& caption, const QString& mimeType, Id_t identifier = 0);
178
/*! Inserts a new pixmap available in memory, e.g. coming from clipboard. */
179
Handle insertPixmap(const QPixmap& pixmap);
181
/*! \return an object for a given \a id. If \a stored is true, stored BLOBs buffer
182
is browsed, otherwise unstored (in memory) BLOBs buffer is browsed.
183
If no object is cached for this id, null handle is returned. */
184
Handle objectForId(Id_t id, bool stored);
186
/*! \return an object for a given \a id. First, unstored object is checked, then unstored,
187
if stored was not found. */
188
Handle objectForId(Id_t id);
191
/*! Removes an object for a given \a id. If \a stored is true, stored BLOB is removed,
192
otherwise unstored (in memory) BLOB is removed. */
193
void removeItem(Id_t id, bool stored);
195
/*! Takes an object for a \a item out of the buffer. */
196
void takeItem(Item* item);
198
/*! Inserts an object for a given \a id into the buffer. */
199
void insertItem(Item* item);
202
class KEXICORE_EXPORT Item
205
Item(const QByteArray& data, Id_t ident,
207
const QString& name = QString(),
208
const QString& caption = QString(),
209
const QString& mimeType = QString(),
211
const QPixmap& pixmap = QPixmap());
213
QPixmap pixmap() const;
214
QByteArray data() const;
216
QString caption; //!< @todo for future use within image gallery
222
QString prettyURL; //!< helper
226
bool *m_pixmapLoaded; //!< *m_pixmapLoaded will be set in Info::pixmap(),
227
//!< to avoid multiple pixmap decoding when it previously failed
228
friend class KexiBLOBBuffer;
added
removed
src/core/kexiblobbuffer.h
