diff options
Diffstat (limited to 'libkdepim/linklocator.h')
| -rw-r--r-- | libkdepim/linklocator.h | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/libkdepim/linklocator.h b/libkdepim/linklocator.h new file mode 100644 index 000000000..2c7fdbb19 --- /dev/null +++ b/libkdepim/linklocator.h @@ -0,0 +1,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 + |