1 | /********************************************************************************** |
2 | * Copyright (C) 2008 by Carlo Segato <brandon.ml@gmail.com> * |
3 | * Copyright (c) 2002-2003 by Stefan Gehn <metz@gehn.net> * |
4 | * Kopete (c) 2002-2008 by the Kopete developers <kopete-devel@kde.org> * |
5 | * Copyright (c) 2005 by Engin AYDOGAN <engin@bzzzt.biz> * |
6 | * * |
7 | * This library is free software; you can redistribute it and/or * |
8 | * modify it under the terms of the GNU Lesser General Public * |
9 | * License as published by the Free Software Foundation; either * |
10 | * version 2.1 of the License, or (at your option) any later version. * |
11 | * * |
12 | * This library is distributed in the hope that it will be useful, * |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of * |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * |
15 | * Lesser General Public License for more details. * |
16 | * * |
17 | * You should have received a copy of the GNU Lesser General Public * |
18 | * License along with this library. If not, see <http://www.gnu.org/licenses/>.* |
19 | * * |
20 | **********************************************************************************/ |
21 | |
22 | #ifndef KEMOTICONS_THEME_H |
23 | #define KEMOTICONS_THEME_H |
24 | |
25 | #include "kemoticonsprovider.h" |
26 | |
27 | #include <QtCore/QSharedDataPointer> |
28 | |
29 | class QString; |
30 | |
31 | /** |
32 | * This class contains the emoticons theme |
33 | */ |
34 | class KEMOTICONS_EXPORT KEmoticonsTheme |
35 | { |
36 | public: |
37 | |
38 | /** |
39 | * The possible parse modes |
40 | */ |
41 | enum ParseModeEnum { |
42 | DefaultParse = 0x0, /**< Use strict or relaxed according to the config */ |
43 | StrictParse = 0x1, /**< Strict parsing requires a space between each emoticon */ |
44 | RelaxedParse = 0x2, /**< Parse mode where all possible emoticon matches are allowed */ |
45 | SkipHTML = 0x4 /**< Skip emoticons within HTML */ |
46 | }; |
47 | |
48 | Q_DECLARE_FLAGS(ParseMode, ParseModeEnum) |
49 | |
50 | /** |
51 | * TokenType, a token might be an image ( emoticon ) or text. |
52 | */ |
53 | enum TokenType { |
54 | Undefined, /**< Undefined, for completeness only */ |
55 | Image, /**< Token contains a path to an image */ |
56 | Text /**< Token contains text */ |
57 | }; |
58 | |
59 | /** |
60 | * A token consists of a QString text which is either a regular text |
61 | * or a path to image depending on the type. |
62 | * If type is Image the text refers to an image path. |
63 | * If type is Text the text refers to a regular text. |
64 | */ |
65 | struct Token { |
66 | Token() : type(Undefined) {} |
67 | /** |
68 | * Create a Token of type @p t, and text @p m |
69 | */ |
70 | Token(TokenType t, const QString &m) : type(t), text(m) {} |
71 | /** |
72 | * Create a Token of type @p t, text @p m, image path @p p and html code @p html |
73 | */ |
74 | Token(TokenType t, const QString &m, const QString &p, const QString &html) |
75 | : type(t), text(m), picPath(p), picHTMLCode(html) {} |
76 | TokenType type; /**< type */ |
77 | QString text; /**< text */ |
78 | QString picPath; /**< path to the image */ |
79 | QString picHTMLCode; /**< \<img> html code */ |
80 | }; |
81 | |
82 | /** |
83 | * Default constructor, it creates a null emoticons theme |
84 | * you should probably never use this, instead use KEmoticons::theme() |
85 | */ |
86 | KEmoticonsTheme(); |
87 | |
88 | /** |
89 | * Copy constructor |
90 | */ |
91 | KEmoticonsTheme(const KEmoticonsTheme &ket); |
92 | |
93 | /** |
94 | * Another constructor where you set the KEmoticonsProvider @p p |
95 | * you should probably never use this, instead use KEmoticons::theme() |
96 | */ |
97 | KEmoticonsTheme(KEmoticonsProvider *p); |
98 | |
99 | /** |
100 | * Destructor |
101 | */ |
102 | ~KEmoticonsTheme(); |
103 | |
104 | /** |
105 | * Parse emoticons in text @p text with ParseMode @p mode and optionally excluding emoticons from @p exclude |
106 | * @code |
107 | * KEmoticonsTheme theme = KEmoticons().theme(); |
108 | * QString text = ":D hi :)"; |
109 | * QStringList exclude(":)"); |
110 | * QString parsed = theme.parseEmoticons(text, KEmoticonsTheme::DefaultParse, exclude); |
111 | * // parsed will be "<img align="center" title=":D" alt=":D" src="/path/to/:D.png" width="24" height="24" /> hi :)" |
112 | * @endcode |
113 | * @param text the text to parse |
114 | * @param mode how to parse the text |
115 | * @param exclude a list of emoticons to exclude from the parsing |
116 | * @return the text with emoticons replaced by html images |
117 | * @note SkipHTML is forced when using this function |
118 | */ |
119 | QString parseEmoticons(const QString &text, ParseMode mode = DefaultParse, const QStringList &exclude = QStringList()) const; |
120 | |
121 | /** |
122 | * Tokenize the message @p message with ParseMode @p mode |
123 | * @code |
124 | * KEmoticonsTheme theme = KEmoticons().theme(); |
125 | * QString text = "hi :)"; |
126 | * QList<Token> tokens = theme.tokenize(text, KEmoticonsTheme::DefaultParse); |
127 | * // tokens[0].text = "hi " |
128 | * // tokens[1].text = ":)" |
129 | * // tokens[1].picPath = "/path/to/:).png" |
130 | * // tokens[1].picHTMLCode = "<img align="center" title=":)" alt=":)" src="/path/to/:).png" width="24" height="24" />" |
131 | * @endcode |
132 | */ |
133 | QList<Token> tokenize(const QString &message, ParseMode mode = DefaultParse) const; |
134 | |
135 | /** |
136 | * Load the theme inside the directory @p path |
137 | * @param path path to the directory |
138 | */ |
139 | bool loadTheme(const QString &path); |
140 | |
141 | /** |
142 | * Remove the emoticon @p emo, this will not delete the image file too |
143 | * @code |
144 | * KEmoticonsTheme theme = KEmoticons().theme(); |
145 | * theme.removeEmoticon(":)"); |
146 | * @endcode |
147 | * @param emo the emoticon text to remove |
148 | * @return @c true if it can delete the emoticon |
149 | */ |
150 | bool removeEmoticon(const QString &emo); |
151 | |
152 | /** |
153 | * Add the emoticon @p emo with text @p text |
154 | * @code |
155 | * KEmoticonsTheme theme = KEmoticons().theme(); |
156 | * theme.addEmoticon("/path/to/smiley.png", ":) :-)"); |
157 | * @endcode |
158 | * @param emo path to the emoticon image |
159 | * @param text the text of the emoticon separated by space for multiple text |
160 | * @param copy whether or not copy @p emo into the theme directory |
161 | * @return @c true if it can add the emoticon |
162 | */ |
163 | bool addEmoticon(const QString &emo, const QString &text, KEmoticonsProvider::AddEmoticonOption option = KEmoticonsProvider::DoNotCopy); |
164 | |
165 | /** |
166 | * Save the emoticon theme |
167 | */ |
168 | void save(); |
169 | |
170 | /** |
171 | * Returns the theme name |
172 | */ |
173 | QString themeName() const; |
174 | |
175 | /** |
176 | * Set the theme name |
177 | * @param name name of the theme |
178 | */ |
179 | void setThemeName(const QString &name); |
180 | |
181 | /** |
182 | * Returns the theme path |
183 | */ |
184 | QString themePath() const; |
185 | |
186 | /** |
187 | * Returns the file name of the theme |
188 | */ |
189 | QString fileName() const; |
190 | |
191 | /** |
192 | * Returns a QHash that contains the emoticons path as keys and the text as values |
193 | */ |
194 | QHash<QString, QStringList> emoticonsMap() const; |
195 | |
196 | /** |
197 | * Create a new theme |
198 | */ |
199 | void createNew(); |
200 | |
201 | /** |
202 | * Check if the theme has a valid provider and it returns true if it can't find it |
203 | */ |
204 | bool isNull() const; |
205 | |
206 | /** |
207 | * @internal |
208 | */ |
209 | KEmoticonsTheme& operator=(const KEmoticonsTheme &ket); |
210 | private: |
211 | class KEmoticonsThemeData; |
212 | /** |
213 | * Private class |
214 | */ |
215 | QSharedDataPointer<KEmoticonsThemeData> d; |
216 | }; |
217 | |
218 | Q_DECLARE_OPERATORS_FOR_FLAGS(KEmoticonsTheme::ParseMode) |
219 | |
220 | #endif /* KEMOTICONS_THEME_H */ |
221 | |
222 | // kate: space-indent on; indent-width 4; replace-tabs on; |
223 | |