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
29class QString;
30
31/**
32 * This class contains the emoticons theme
33 */
34class KEMOTICONS_EXPORT KEmoticonsTheme
35{
36public:
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);
210private:
211 class KEmoticonsThemeData;
212 /**
213 * Private class
214 */
215 QSharedDataPointer<KEmoticonsThemeData> d;
216};
217
218Q_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