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 | |
36 | namespace 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 | */ |
48 | class 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 | |