1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Lars Knoll (knoll@kde.org)
3
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.
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., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19#ifndef KCHARSETS_H
20#define KCHARSETS_H
21
22#include <kdemacros.h>
23#include <kdecore_export.h>
24#include <QtCore/QList>
25
26class KCharsets;
27class KCharsetsPrivate;
28
29class QChar;
30class QString;
31class QStringList;
32class QTextCodec;
33
34namespace KGlobal
35{
36 KDECORE_EXPORT KCharsets *charsets();
37}
38
39/**
40 * Charset font and encoder/decoder handling.
41 *
42 * This is needed, because Qt's encoding name matching in
43 * QTextCodec::codecForName matches only closely-related encoded names
44 * but not alternate names, e.g. found in the reality of the Internet.
45 */
46class KDECORE_EXPORT KCharsets
47{
48 friend KCharsets *KGlobal::charsets();
49
50protected:
51 /** Protected constructor. If you need the kcharsets object, use
52 KGlobal::charsets() instead.
53 */
54 KCharsets();
55
56public:
57
58 /**
59 * Destructor.
60 */
61 virtual ~KCharsets();
62
63 /**
64 * Provided for compatibility.
65 * @param name the name of the codec
66 * @return the QTextCodec. If the desired codec could not be found,
67 * it returns a default (ISO 8859-1) codec
68 */
69 QTextCodec *codecForName(const QString &name) const;
70
71 /**
72 * Tries to find a QTextCodec to convert the given encoding from and to
73 * Unicode.
74 *
75 * If no codec could be found, the ISO 8859-1 codec will be returned an
76 * and @p ok will be set to false.
77 *
78 * @param n the name of the codec
79 * @param ok true if a matching codec has been found, false if not
80 * @return the QTextCodec. If the desired codec could not be found,
81 * it returns a default (ISO 8859-1) codec
82 */
83 QTextCodec *codecForName(const QString &n, bool &ok) const;
84
85 /**
86 * @brief Converts an entity to a character.
87 *
88 * The string must contain only the
89 * entity without the trailing ';'.
90 * @param str the entity
91 * @return QChar::Null if the entity could not be decoded.
92 */
93 static QChar fromEntity(const QString &str);
94
95 /**
96 * Overloaded member function. Tries to find an entity in the
97 * QString str.
98 * @param str the string containing entified
99 * @param len is a return value, that gives the length of the decoded
100 * entity.
101 * @return a decoded entity if one could be found, QChar::null
102 * otherwise
103 */
104 static QChar fromEntity(const QString &str, int &len);
105
106 /**
107 * Converts a QChar to an entity. The returned string does already
108 * contain the leading '&' and the trailing ';'.
109 * @param ch the char to convert
110 * @return the entity
111 */
112 static QString toEntity(const QChar &ch);
113
114 /**
115 * Scans the given string for entities (like &amp;amp;) and resolves them
116 * using fromEntity.
117 * @param text the string containing the entities
118 * @return the clean string
119 */
120 static QString resolveEntities( const QString &text );
121
122 /**
123 * Lists all available encodings as names.
124 * @return the list of all encodings
125 */
126 QStringList availableEncodingNames() const;
127
128 /**
129 * Lists the available encoding names together with a more descriptive language.
130 * @return the list of descriptive encoding names
131 */
132 QStringList descriptiveEncodingNames() const;
133
134 /**
135 * Lists the available encoding names grouped by script (or language that uses them).
136 * @returns the list of lists consisting of description followed by encoding names (i.e. encodingsByScript().at(i).at(0) is a description for encodingsByScript().at(i).at(k), k>0)
137 */
138 QList<QStringList> encodingsByScript() const;
139
140 /**
141 * Returns the language the encoding is used for.
142 * @param encoding the encoding for the language
143 * @return the language of the encoding
144 * @deprecated Please use descriptionForEncoding instead.
145 * This function will be removed before KDE4 is released.
146 */
147#ifndef KDE_NO_DEPRECATED
148 KDE_DEPRECATED QString languageForEncoding( const QString &encoding ) const;
149#endif
150
151 /**
152 * @brief Returns a long description for an encoding name.
153 * @param encoding the encoding for the language
154 * @return the long description for the encoding
155 */
156 QString descriptionForEncoding( const QString& encoding ) const;
157
158 /**
159 * Returns the encoding for a string obtained with descriptiveEncodingNames().
160 * @param descriptiveName the descriptive name for the encoding
161 * @return the name of the encoding
162 */
163 QString encodingForName( const QString &descriptiveName ) const;
164
165private:
166 KCharsetsPrivate* const d;
167
168 /**
169 * @brief Get the QTextCodec for the name or return NULL
170 *
171 * This function is similar to KCharsets::codecForName except that it
172 * can return a NULL value when the name was not found.
173 *
174 * @param n name of the text codec
175 * @return pointer to the QTextCodec or NULL
176 * @todo Make this function public when it is clear what API is needed.
177 */
178 QTextCodec *codecForNameOrNull( const QByteArray& n ) const;
179};
180
181#endif
182