Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

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
+