← Back to branch summary

~ubuntu-branches/ubuntu/precise/koffice/precise

« back to all changes in this revision

Viewing changes to lib/kofficecore/koFilter.h

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell
  • Date: 2006-04-20 21:38:53 UTC
  • mfrom: (1.1.3 upstream)
  • Revision ID: james.westby@ubuntu.com-20060420213853-j5lxluqvymxt2zny
Tags: 1:1.5.0-0ubuntu2
Ubuntu upload 

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/kofficecore/koFilter.h
1
 
/* This file is part of the KOffice libraries
2
 
   Copyright (C) 2001 Werner Trobin <trobin@kde.org>
3
 
                 2002 Werner Trobin <trobin@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 version 2 as published by the Free Software Foundation.
8
 
 
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.
13
 
 
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., 59 Temple Place - Suite 330,
17
 
   Boston, MA 02111-1307, USA.
18
 
*/
19
 
 
20
 
#ifndef __koffice_filter_h__
21
 
#define __koffice_filter_h__
22
 
 
23
 
#include <qobject.h>
24
 
#include <qmap.h>
25
 
#include <qptrstack.h>
26
 
#include <koffice_export.h>
27
 
class QIODevice;
28
 
class KoFilterChain;
29
 
 
30
 
/**
31
 
 * @brief The base class for import and export filters.
32
 
 *
33
 
 * Derive your filter class from this base class and implement
34
 
 * the @ref convert() method. Don't forget to specify the Q_OBJECT
35
 
 * macro in your class even if you don't use signals or slots.
36
 
 * This is needed as filters are created on the fly.
37
 
 * The m_chain member allows access to the @ref KoFilterChain
38
 
 * which invokes the filter to query for input/output.
39
 
 *
40
 
 * @note Take care: The m_chain pointer is invalid while the constructor
41
 
 * runs due to the implementation -- @em don't use it in the constructor.
42
 
 * After the constructor, when running the @ref convert() method it's
43
 
 * guaranteed to be valid, so no need to check against 0.
44
 
 *
45
 
 * @author Werner Trobin <trobin@kde.org>
46
 
 * @todo the class has no constructor and therefore cannot initialize its private class
47
 
 */
48
 
class KOFFICECORE_EXPORT KoFilter : public QObject
49
 
{
50
 
    Q_OBJECT
51
 
 
52
 
    friend class KoFilterEntry;  // needed for the filter chain pointer :(
53
 
    friend class KoFilterChain;
54
 
 
55
 
public:
56
 
    /**
57
 
     * This enum is used to signal the return state of your filter.
58
 
     * Return OK in @ref convert() in case everything worked as expected.
59
 
     * Feel free to add some more error conditions @em before the last item
60
 
     * if it's needed.
61
 
     */
62
 
    enum ConversionStatus { OK, StupidError, UsageError, CreationError, FileNotFound,
63
 
                            StorageCreationError, BadMimeType, BadConversionGraph,
64
 
                            EmbeddedDocError, WrongFormat, NotImplemented,
65
 
                            ParsingError, InternalError, UnexpectedEOF,
66
 
                            UnexpectedOpcode, UserCancelled, OutOfMemory,
67
 
                            JustInCaseSomeBrokenCompilerUsesLessThanAByte = 255 };
68
 
 
69
 
    virtual ~KoFilter();
70
 
 
71
 
    /**
72
 
     * The filter chain calls this method to perform the actual conversion.
73
 
     * The passed mimetypes should be a pair of those you specified in your
74
 
     * .desktop file.
75
 
     * You @em have to implement this method to make the filter work.
76
 
     *
77
 
     * @param from The mimetype of the source file/document
78
 
     * @param to The mimetype of the destination file/document
79
 
     * @return The error status, see the @ref #ConversionStatus enum.
80
 
     *         KoFilter::OK means that everything is alright.
81
 
     */
82
 
    virtual ConversionStatus convert( const QCString& from, const QCString& to ) = 0;
83
 
 
84
 
signals:
85
 
    /**
86
 
     * Emit this signal with a value in the range of 1...100 to have some
87
 
     * progress feedback for the user in the statusbar of the application.
88
 
     *
89
 
     * @param value The actual progress state. Should always remain in
90
 
     * the range 1..100.
91
 
     */
92
 
    void sigProgress( int value );
93
 
 
94
 
protected:
95
 
    /**
96
 
     * This is the constructor your filter has to call, obviously.
97
 
     */
98
 
    KoFilter();
99
 
 
100
 
    /**
101
 
     * Use this pointer to access all information about input/output
102
 
     * during the conversion. @em Don't use it in the constructor -
103
 
     * it's invalid while constructing the object!
104
 
     */
105
 
    KoFilterChain* m_chain;
106
 
 
107
 
private:
108
 
    KoFilter( const KoFilter& rhs );
109
 
    KoFilter& operator=( const KoFilter& rhs );
110
 
 
111
 
    class Private;
112
 
    Private* d;
113
 
};
114
 
 
115
 
 
116
 
/**
117
 
 * The base class for all @em import filters embedding other filters. Right
118
 
 * now we don't support embedding for export filters, but if there's a
119
 
 * request for that feature please don't hesitate to contact Werner Trobin
120
 
 * <trobin@kde.org>.
121
 
 *
122
 
 * To make use of embedding features you have to know that there are two kinds
123
 
 * of embedding for filters: embedding the output of a different filter (library)
124
 
 * or embedding the output of several internal filters (no separate library).
125
 
 * The first case is the simpler one. You just have to override @ref #savePartContents
126
 
 * and call @ref #embedPart to trigger the embedding process. One example for such
127
 
 * a filter is Kontour's MSOD (MS Office Drawing) filter.
128
 
 *
129
 
 * The more complex case is embedding various streams from within the same filter
130
 
 * library. This is neccesary for OLE like files (at least with the current design
131
 
 * of the OLEFilter). In this case you have to use @ref #startInternalEmbedding and
132
 
 * @ref #endInternalEmbedding accordingly. Try to use the previous method if possible.
133
 
 *
134
 
 * If you're using this class you can also setup a signal/slot communication
135
 
 * between parent and child filter. To make that work you simply have to define
136
 
 * signals and slots along the following rules:
137
 
 * Signals should be named "commSignal\<name\>" where \<name\> is the name of the signal,
138
 
 * slots should be named "commSlot\<name\>". The connection will be done automatically
139
 
 * if names and signatures are matching.
140
 
 *
141
 
 * @author Werner Trobin
142
 
 * @todo the class has no constructor and therefore cannot initialize its private class
143
 
 */
144
 
class KOFFICECORE_EXPORT KoEmbeddingFilter : public KoFilter
145
 
{
146
 
    Q_OBJECT
147
 
 
148
 
    friend class KoFilterChain;
149
 
 
150
 
public:
151
 
    virtual ~KoEmbeddingFilter();
152
 
 
153
 
    /**
154
 
     * @internal
155
 
     * This method returns the last recently used part index at the
156
 
     * current directory level. It can be (and is ;) used to generate
157
 
     * the per-directory-unique address for the next part we have to save.
158
 
     * It will get updated automatically, you most likely don't have to
159
 
     * care about that one at all.
160
 
     */
161
 
    int lruPartIndex() const;
162
 
 
163
 
    /**
164
 
     * A static helper method to determine the mimetype via the
165
 
     * file extension. It allows to go from "wmf" to image/x-wmf
166
 
     * and so on. Note that you should only pass the pure extension
167
 
     * and not a whole pattern like "*.doc" or so.
168
 
     */
169
 
    static QString mimeTypeByExtension( const QString& extension );
170
 
 
171
 
protected:
172
 
    /**
173
 
     * Constructs a filter. Note that the m_chain pointer is 0 inside
174
 
     * the constructor. Most likely your constructor will be empty.
175
 
     */
176
 
    KoEmbeddingFilter();
177
 
 
178
 
    /**
179
 
     * Embed some document using an external filter (i.e. a different
180
 
     * filter library). This method works according to the template method
181
 
     * pattern and calls @ref #savePartContents during execution.
182
 
     * Call this method when you want to convert some data using one or more
183
 
     * KOffice filters selected via the filter manager.
184
 
     * This is the way to go when it comes to embedding unless you have very
185
 
     * special requirements.
186
 
     *
187
 
     * @param from The mimetype of the source data
188
 
     * @param to The mimetype of the destination part. If this field is set
189
 
     *           to "" the filter manager will try to find the best native
190
 
     *           KOffice mimetype. When the method returns this parameter will
191
 
     *           hold the string of the used mimetype.
192
 
     * @param status Returns the error status of the filter
193
 
     * @param key Optional key field to allow custom keys inside the part
194
 
     *        map (see @ref #internalPartReference). If this field is left
195
 
     *        empty we generate a key from the part number (e.g. 1 -> "1")
196
 
     * @return The number of the part (can be used to refer to the part from
197
 
     *         within the embedding filter).
198
 
     */
199
 
    int embedPart( const QCString& from, QCString& to,
200
 
                   KoFilter::ConversionStatus& status,
201
 
                   const QString& key = QString::null );
202
 
 
203
 
    /**
204
 
     * Method to perform "internal" embedding of parts in olefilter-style.
205
 
     * This method can be used to signal the start of a new embedding
206
 
     * level within your filter. Very evil, but what shall I say ;)
207
 
     * Unless you really have to you should always use @ref #embedPart as
208
 
     * it's easier to use and not as hacky.
209
 
     *
210
 
     * @param key The key we use to store reference/mimetype of your new part
211
 
     * @param mimeType The mimetype of the part you're about to embed
212
 
     */
213
 
    void startInternalEmbedding( const QString& key, const QCString& mimeType );
214
 
 
215
 
    /**
216
 
     * This method signals the end of an internal embedding session.
217
 
     * You have to call that exactly as often as you call @ref #startInternalEmbedding
218
 
     * or you'll mess up the internal stack and your file will be invalid.
219
 
     * Again: use @ref #embedPart if you can :-)
220
 
     */
221
 
    void endInternalEmbedding();
222
 
 
223
 
    /**
224
 
     * Query the internal part map for the reference of the part
225
 
     * matching the given key. Note that you can use that plain
226
 
     * simple int to refer to the respective part (when used as string).
227
 
     *
228
 
     * @param key The key you would like to look up
229
 
     * @return The reference or -1 if we didn't find a part with the
230
 
     *         given key
231
 
     */
232
 
    int internalPartReference( const QString& key ) const;
233
 
 
234
 
    /**
235
 
     * Query the internal part map for the mimetype of the part
236
 
     * matching the given key.
237
 
     *
238
 
     * @param key The key you would like to look up
239
 
     * @return The mimetype, might be empty if the part matching
240
 
     *         the given key doesn't exist.
241
 
     */
242
 
    QCString internalPartMimeType( const QString& key ) const;
243
 
 
244
 
private:
245
 
    /**
246
 
     * Holds the directory's number and the mimetype of the part
247
 
     * for internal parts. This is all we need to locate a part.
248
 
     * @internal
249
 
     */
250
 
    struct PartReference
251
 
    {
252
 
        PartReference( int index = -1, const QCString& mimeType = "" );
253
 
        bool isValid() const;
254
 
 
255
 
        int m_index;
256
 
        QCString m_mimeType;
257
 
    };
258
 
 
259
 
    /**
260
 
     * This struct keeps track of the last used index for a
261
 
     * child part and all references to existing children
262
 
     * We use it to build a whole stack, one PartState per
263
 
     * embedding level.
264
 
     * @internal
265
 
     */
266
 
    struct PartState
267
 
    {
268
 
        PartState();
269
 
 
270
 
        int m_lruPartIndex;
271
 
        QMap<QString, PartReference> m_partReferences;
272
 
    };
273
 
 
274
 
    /// Better do not copy the filters
275
 
    KoEmbeddingFilter( const KoEmbeddingFilter& rhs );
276
 
    /// Better do not assign the filters
277
 
    KoEmbeddingFilter& operator=( const KoEmbeddingFilter& rhs );
278
 
 
279
 
    /**
280
 
     * This method will be called by @ref #embedPart as soon as it
281
 
     * needs the data of the part (template method pattern). You
282
 
     * have to override that and simply save the part data to the
283
 
     * (already opened) file.
284
 
     * No need to override that when you're not using @ref #embedPart
285
 
     * (as you should ;)
286
 
     *
287
 
     * @param file An already opened file
288
 
     */
289
 
    virtual void savePartContents( QIODevice* file );
290
 
 
291
 
    /**
292
 
     * Internal methods to support the start/endInternalEmbedding
293
 
     * methods (we have to change directories and stuff).
294
 
     * These methods are declared friends of the KoFilterChain
295
 
     */
296
 
    void filterChainEnterDirectory( const QString& directory ) const;
297
 
    /**
298
 
     * Internal methods to support the start/endInternalEmbedding
299
 
     * methods (we have to change directories and stuff).
300
 
     * These methods are declared friends of the KoFilterChain
301
 
     */
302
 
    void filterChainLeaveDirectory() const;
303
 
 
304
 
    /**
305
 
     * A stack which keeps track of the current part references.
306
 
     * We push one PartState structure for every embedding level.
307
 
     */
308
 
    QPtrStack<PartState> m_partStack;
309
 
 
310
 
    class Private;
311
 
    Private* d;
312
 
};
313
 
 
314
 
#endif