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 | |
26 | class KCharsets; |
27 | class KCharsetsPrivate; |
28 | |
29 | class QChar; |
30 | class QString; |
31 | class QStringList; |
32 | class QTextCodec; |
33 | |
34 | namespace 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 | */ |
46 | class KDECORE_EXPORT KCharsets |
47 | { |
48 | friend KCharsets *KGlobal::charsets(); |
49 | |
50 | protected: |
51 | /** Protected constructor. If you need the kcharsets object, use |
52 | KGlobal::charsets() instead. |
53 | */ |
54 | KCharsets(); |
55 | |
56 | public: |
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;) 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 | |
165 | private: |
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 | |