1/*
2 This file is part of libkabc.
3 Copyright (c) 2002 Tobias Koenig <tokoe@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 as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_FORMATFACTORY_H
22#define KABC_FORMATFACTORY_H
23
24#include <QtCore/QHash>
25#include <QtCore/QString>
26
27#include <kconfig.h>
28
29#include "format.h"
30
31namespace KABC {
32
33/**
34 * Dataype to hold information on format plugins.
35 *
36 * @see FormatFactory::info()
37 */
38struct FormatInfo
39{
40 /**
41 * Returns whether this info object is null.
42 *
43 * An info object is considered null, when its #library string is empty.
44 */
45 bool isNull() const { return library.isEmpty(); }
46
47 /**
48 * Name of a KDE plugin library, e.g.
49 * \code
50 * "kabcformat_vcard"
51 * \endcode
52 *
53 * Maps to the @c X-KDE-Library field of the format plugin's .desktop file
54 */
55 QString library;
56
57 /**
58 * Localized string used as format's name, e.g.
59 * \code
60 * i18n( "vCard" )
61 * \endcode
62 *
63 * Maps to the @c Name field of the format plugin's .desktop file
64 */
65 QString nameLabel;
66
67 /**
68 * Localized string to describe the format, e.g.
69 * \code
70 * i18n( "vCard format" )
71 * \endcode
72 *
73 * Maps to the @c Comment field of the format plugin's .desktop file
74 */
75 QString descriptionLabel;
76};
77
78/**
79 * Class for loading format plugins.
80 *
81 * Example:
82 *
83 * \code
84 * KABC::FormatFactory *factory = KABC::FormatFactory::self();
85 *
86 * QStringList list = factory->formats();
87 * QStringList::Iterator it;
88 * for ( it = list.begin(); it != list.end(); ++it ) {
89 * KABC::Format *format = factory->format( (*it) );
90 * // do something with format
91 * }
92 * \endcode
93 */
94class KABC_DEPRECATED_EXPORT FormatFactory
95{
96 public:
97 /**
98 Destructor.
99 */
100 ~FormatFactory();
101
102 /**
103 * Returns the global format factory.
104 */
105 static FormatFactory *self();
106
107 /**
108 * Returns a pointer to a format object or a null pointer
109 * if format type doesn't exist.
110 *
111 * @param type The type of the format, returned by formats()
112 *
113 * @see info()
114 */
115 Format *format( const QString &type );
116
117 /**
118 * Returns a list of all available format types.
119 */
120 QStringList formats();
121
122 /**
123 * Returns the info structure for a special type.
124 *
125 * @param type The type of the format, returned by formats()
126 *
127 * @see format()
128 */
129 FormatInfo info( const QString &type ) const;
130
131 protected:
132 FormatFactory();
133
134 private:
135 class Private;
136 Private *const d;
137};
138
139}
140#endif
141