1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
/*
* linklocator.h
*
* Copyright (c) 2002 Dave Corrie <kde@davecorrie.com>
*
* This file is part of KMail.
*
* KMail is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#ifndef LINKLOCATOR_H_INCLUDED
#define LINKLOCATOR_H_INCLUDED
#include <qstring.h>
#include <qmap.h>
#include <kdepimmacros.h>
/**
* LinkLocator assists in identifying sections of text that can
* usefully be converted in hyperlinks in html. It is intended
* to be used in two ways: either by calling @ref convertToHtml()
* to convert a plaintext string into html, or to be derived from
* where more control is needed.
*
* @short Identifies URLs and email addresses embedded in plaintext.
* @author Dave Corrie <kde@davecorrie.com>
*/
class KDE_EXPORT LinkLocator
{
public:
/**
* Constructs a LinkLocator that will search a plaintext string
* from a given starting point.
*
* @param text The string in which to search.
* @param pos An index into 'text' from where the search
* should begin.
*/
LinkLocator(const QString& text, int pos = 0);
/**
* Sets the maximum length of URLs that will be matched by
* @ref getUrl(). By default, this is set to 4096
* characters. The reason for this limit is that there may
* be possible security implications in handling URLs of
* unlimited length.
*
* @param length The new maximum length of URLs that will be
* matched by @ref getUrl().
*/
void setMaxUrlLen(int length);
/**
* @return The current limit on the maximum length of a URL.
*
* @see setMaxUrlLen().
*/
int maxUrlLen() const;
/**
* Sets the maximum length of email addresses that will be
* matched by @ref getEmailAddress(). By default, this is
* set to 255 characters. The reason for this limit is that
* there may be possible security implications in handling
* addresses of unlimited length.
*
* @param length The new maximum length of email addresses
* that will be matched by @ref getEmailAddress().
*/
void setMaxAddressLen(int length);
/**
* @return The current limit on the maximum length of an email
* address.
*
* @see setMaxAddressLen().
*/
int maxAddressLen() const;
/**
* Attempts to grab a URL starting at the current scan position.
* If there is no URL at the current scan position, then an empty
* string is returned. If a URL is found, the current scan position
* is set to the index of the last character in the URL.
*
* @return The URL at the current scan position, or an empty string.
*/
QString getUrl();
/**
* Attempts to grab an email address. If there is an @ symbol at the
* current scan position, then the text will be searched both backwards
* and forwards to find the email address. If there is no @ symbol at
* the current scan position, an empty string is returned. If an address
* is found, then the current scan position is set to the index of the
* last character in the address.
*
* @return The email address at the current scan position, or an empty
* string.
*/
QString getEmailAddress();
/**
* Converts plaintext into html. The following characters are converted to HTML
* entities: & " < >. Newlines are also preserved.
*
* @param plainText The text to be converted into HTML.
* @param flags The flags to consider when processing plainText.
* Currently supported flags are:
* - PreserveSpaces, preserves the appearance of
* sequences of space and tab
* characters in the resulting HTML.
* - ReplaceSmileys, replace text smileys with
* emoticon images.
* - IgnoreUrls, doesn't parse any URLs.
* - HighlightText, interprets text highlighting markup
* like *bold*, _underlined_ and
* /italic/.
* @param maxUrlLen The maximum length of permitted URLs. (See
* @ref maxUrlLen().)
* @param maxAddressLen The maximum length of permitted email addresses.
* (See @ref maxAddressLen().)
* @return An HTML version of the text supplied in the 'plainText' parameter,
* suitable for inclusion in the BODY of an HTML document.
*/
static QString convertToHtml(const QString& plainText, int flags = 0,
int maxUrlLen = 4096, int maxAddressLen = 255);
static const int PreserveSpaces = 0x01;
static const int ReplaceSmileys = 0x02;
static const int IgnoreUrls = 0x04;
static const int HighlightText = 0x08;
/** Embed the given PNG image into a data URL.
* @param iconPath path to the PNG image
* @return A data URL, QString::null if the image could not be read.
*/
static QString pngToDataUrl( const QString & iconPath );
protected:
/**
* The plaintext string being scanned for URLs and email addresses.
*/
QString mText;
/**
* The current scan position.
*/
int mPos;
private:
bool atUrl() const;
bool isEmptyUrl(const QString& url);
/**
* Replaces smiley text with an <img> tag containing the relevant image.
* For an emoticon text to be recognised it has to match
* "(^|\s+)text(\s+|$)"
* @return An HTML String with <img> for an emoticon
*/
QString getEmoticon();
/**
* Highlight text according to *bold*, /italic/ and _underlined_ markup.
* @return A HTML string.
*/
QString highlightedText();
int mMaxUrlLen;
int mMaxAddressLen;
// maps the smiley text to the corresponding emoticon name
static QMap<QString, QString> *s_smileyEmoticonNameMap;
// cache for the HTML representation of a smiley
static QMap<QString, QString> *s_smileyEmoticonHTMLCache;
};
#endif // LINKLOCATOR_H_INCLUDED
|
