1/*
2 Copyright (c) 2002 Dave Corrie <kde@davecorrie.com>
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/**
20 @file
21 This file is part of the KDEPIM Utilities library and provides the
22 LinkLocator class.
23
24 @brief
25 Identifies URLs and email addresses embedded in plaintext.
26
27 @author Dave Corrie \<kde@davecorrie.com\>
28*/
29#ifndef KPIMUTILS_LINKLOCATOR_H
30#define KPIMUTILS_LINKLOCATOR_H
31
32#include "kpimutils_export.h"
33
34#include <QtCore/QString>
35
36namespace KPIMUtils {
37
38/**
39 LinkLocator assists in identifying sections of text that can usefully
40 be converted in hyperlinks in HTML. It is intended to be used in two ways:
41 either by calling convertToHtml() to convert a plaintext string into HTML,
42 or to be derived from where more control is needed.
43
44 please note that you are responsible for handling the links. That means you
45 should not execute the link directly but instead open it for example. See
46 the KRun documentation about this parameter if applicable.
47*/
48class KPIMUTILS_EXPORT LinkLocator
49{
50 public:
51 /**
52 Constructs a LinkLocator that will search a plaintext string
53 from a given starting point.
54
55 @param text The string in which to search.
56 @param pos An index into 'text' from where the search should begin.
57 */
58 explicit LinkLocator( const QString &text, int pos = 0 );
59
60 /**
61 * Destructor.
62 */
63 ~LinkLocator();
64
65 /**
66 Sets the maximum length of URLs that will be matched by getUrl().
67 By default, this is set to 4096 characters. The reason for this limit
68 is that there may be possible security implications in handling URLs of
69 unlimited length.
70 @see maxUrlLen()
71
72 @param length A new maximum length of URLs that will be matched by getUrl().
73 */
74 void setMaxUrlLen( int length );
75
76 /**
77 Returns the current limit on the maximum length of a URL.
78
79 @see setMaxUrlLen().
80 */
81 int maxUrlLen() const;
82
83 /**
84 Sets the maximum length of email addresses that will be matched by
85 getEmailAddress(). By default, this is set to 255 characters. The
86 reason for this limit is that there may be possible security implications
87 in handling addresses of unlimited length.
88 @see maxAddressLen().
89
90 @param length The new maximum length of email addresses that will be
91 matched by getEmailAddress().
92 */
93 void setMaxAddressLen( int length );
94
95 /**
96 Returns the current limit on the maximum length of an email address.
97 @see setMaxAddressLen().
98 */
99 int maxAddressLen() const;
100
101 /**
102 Attempts to grab a URL starting at the current scan position.
103 If there is no URL at the current scan position, then an empty
104 string is returned. If a URL is found, the current scan position
105 is set to the index of the last character in the URL.
106
107 @return The URL at the current scan position, or an empty string.
108 */
109 QString getUrl();
110
111 /**
112 Attempts to grab an email address. If there is an @ symbol at the
113 current scan position, then the text will be searched both backwards
114 and forwards to find the email address. If there is no @ symbol at
115 the current scan position, an empty string is returned. If an address
116 is found, then the current scan position is set to the index of the
117 last character in the address.
118
119 @return The email address at the current scan position, or an empty string.
120 */
121 QString getEmailAddress();
122
123 /**
124 Converts plaintext into html. The following characters are converted
125 to HTML entities: & " < >. Newlines are also preserved.
126
127 @param plainText The text to be converted into HTML.
128 @param flags The flags to consider when processing plainText.
129 Currently supported flags are:
130 - PreserveSpaces, preserves the appearance of sequences
131 of space and tab characters in the resulting HTML.
132 - ReplaceSmileys, replace text smileys with
133 emoticon images.
134 - IgnoreUrls, doesn't parse any URLs.
135 - HighlightText, interprets text highlighting
136 markup like *bold*, _underlined_ and /italic/.
137 @param maxUrlLen The maximum length of permitted URLs. (@see maxUrlLen().)
138 @param maxAddressLen The maximum length of permitted email addresses.
139 (@see maxAddressLen().)
140 @return An HTML version of the text supplied in the 'plainText'
141 parameter, suitable for inclusion in the BODY of an HTML document.
142 */
143 static QString convertToHtml( const QString &plainText, int flags = 0,
144 int maxUrlLen = 4096, int maxAddressLen = 255 );
145
146 static const int PreserveSpaces = 0x01;
147 static const int ReplaceSmileys = 0x02;
148 static const int IgnoreUrls = 0x04;
149 static const int HighlightText = 0x08;
150
151 /**
152 Embeds the given PNG image into a data URL.
153 @param iconPath path to the PNG image
154 @return A data URL, QString() if the image could not be read.
155 */
156 static QString pngToDataUrl( const QString & iconPath );
157
158 protected:
159 /**
160 The plaintext string being scanned for URLs and email addresses.
161 */
162 QString mText;
163
164 /**
165 The current scan position.
166 */
167 int mPos;
168
169 bool atUrl() const;
170 bool isEmptyUrl( const QString &url ) const;
171
172 /**
173 Highlight text according to *bold*, /italic/ and _underlined_ markup.
174 @return A HTML string.
175 */
176 QString highlightedText();
177
178 private:
179 private:
180 //@cond PRIVATE
181 class Private;
182 Private *const d;
183 //@endcond
184
185};
186
187}
188
189#endif
190