kdeui/kurllabel.h

   1 /* This file is part of the KDE libraries
   2    Copyright (C) 1998 Kurt Granroth <granroth@kde.org>
   3    Copyright (C) 2000 Peter Putzer <putzer@kde.org>
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Library General Public
   7    License version 2 as published by the Free Software Foundation.
   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 Steet, Fifth Floor,
  17    Boston, MA 02110-1301, USA.
  18 */
  19
  20 #ifndef KURLLABEL_H
  21 #define KURLLABEL_H
  22
  23 #include <qlabel.h>
  24
  25 #include <kdelibs_export.h>
  26
  27 class QColor;
  28 class QCursor;
  29 class QPixmap;
  30
  31 /**
  32  * @short A drop-in replacement for QLabel that displays hyperlinks.
  33  *
  34  * KURLLabel is a drop-in replacement for QLabel that handles text
  35  * in a fashion similar to how an HTML widget handles hyperlinks.  The
  36  * text can be underlined (or not) and set to different colors.  It
  37  * can also "glow" (cycle colors) when the mouse passes over it.
  38  *
  39  * KURLLabel also provides signals for several events, including
  40  * the mouse leaving and entering the text area and all forms of
  41  * mouse clicking.
  42  *
  43  * A typical usage would be something like so:
  44  *
  45  * \code
  46  * KURLLabel *address = new KURLLabel(this);
  47  * address->setText("My homepage");
  48  * address->setURL("http://www.home.com/~me");
  49  * connect(address, SIGNAL(leftClickedURL(const QString&)),
  50  *                  SLOT(processMyURL(const QString&)));
  51  * \endcode
  52  *
  53  * In this example, the text "My homepage" would be displayed
  54  * as blue, underlined text.  When the mouse passed over it,
  55  * it would "glow" red.  When the user clicks on the text, the
  56  * signal leftClickedURL() would be emitted with "http://www.home.com/~me"
  57  * as its argument.
  58  *
  59  * \image html kurllabel.png "KDE URL Label"
  60  *
  61  * @author Kurt Granroth <granroth@kde.org> (Interface)
  62  * @author Peter Putzer <putzer@kde.org> (Rewrite)
  63  * @version $Id$
  64  *
  65  */
  66 class KDEUI_EXPORT KURLLabel : public QLabel
  67 {
  68   Q_OBJECT
  69   Q_PROPERTY (QString url READ url WRITE setURL)
  70   Q_PROPERTY (QString tipText READ tipText WRITE setTipText )
  71   Q_PROPERTY (QPixmap altPixmap READ altPixmap WRITE setAltPixmap)
  72   Q_PROPERTY (bool glowEnabled READ isGlowEnabled WRITE setGlow )
  73   Q_PROPERTY (bool floatEnabled READ isFloatEnabled WRITE setFloat )
  74   Q_PROPERTY (bool useTips READ useTips WRITE setUseTips )
  75   Q_PROPERTY (bool useCursor READ useCursor WRITE setUseCursor )
  76
  77 public:
  78   /**
  79    * Default constructor.
  80    *
  81    * Use setURL() and setText() or QListView::setPixmap()
  82    * to set the resp. properties.
  83    */
  84   KURLLabel (QWidget* parent = 0L, const char* name = 0L);
  85
  86   /**
  87    * Convenience constructor.
  88    *
  89    * @param url is the URL emitted when the label is clicked.
  90    * @param text is the displayed string. If it's equal to QString::null
  91    * the @p url will be used instead.
  92    * @param parent Passed to lower level constructor
  93    * @param name Passed to lower level constructor
  94    *
  95    * @p parent and @p name are passed to QLabel, which in turn passes
  96    * them further down
  97    */
  98   KURLLabel (const QString& url, const QString& text = QString::null,
  99               QWidget* parent = 0L, const char* name = 0L);
 100
 101   /**
 102    * Destructs the label.
 103    */
 104   virtual ~KURLLabel ();
 105
 106   /**
 107    * Returns the URL.
 108    */
 109   const QString& url () const;
 110
 111   /**
 112    * Returns the current tooltip text.
 113    */
 114   const QString& tipText () const;
 115
 116   /**
 117    * @return true if a tooltip will be displayed.
 118    *
 119    * @see setTipText()
 120    */
 121   bool useTips () const;
 122
 123   /**
 124    * @return true if the cursor will change while over the URL.
 125    *
 126    * @see setUseCursor ()
 127    */
 128   bool useCursor () const;
 129
 130   /**
 131    * When this is on, the text will switch to the selected
 132    * color whenever the mouse passes over it.
 133    */
 134   bool isGlowEnabled () const;
 135
 136   /**
 137    * This feature is very similar to the "glow" feature in that the color of the
 138    * label switches to the selected color when the cursor passes
 139    * over it. In addition, underlining is turned on for as
 140    * long as the mouse is overhead. Note that if "glow" and
 141    * underlining are both already turned on, this feature
 142    * will have no visible effect.
 143    */
 144   bool isFloatEnabled () const;
 145
 146   /**
 147    * @return the alternate pixmap (may be 0L if none was set).
 148    */
 149   const QPixmap* altPixmap () const;
 150
 151 public slots:
 152   /**
 153    * Turns on or off the underlining.
 154    *
 155    *  When this is on, the
 156    * text will be underlined.  By default, it is @p true.
 157    */
 158   void setUnderline (bool on = true);
 159
 160   /**
 161    * Sets the URL for this label to @p url.
 162    *
 163    * @see url
 164    */
 165   void setURL (const QString& url);
 166
 167   /**
 168    * Overridden for internal reasons; the API remains unaffected.
 169    */
 170   virtual void setFont (const QFont&);
 171
 172   /**
 173    * Turns on or off the tool tip feature.
 174    *
 175    * When this is on, the URL will be displayed as a
 176    * tooltip whenever the mouse passes passes over it.
 177    * By default, it is @p false.
 178    */
 179   void setUseTips (bool on = true);
 180
 181   /**
 182    * Specifies what text to display when tooltips are turned on.
 183    *
 184    * If this is not used, the tip will default to the URL.
 185    *
 186    * @see setUseTips()
 187    */
 188   void setTipText (const QString& tip);
 189
 190   /**
 191    * Sets the highlight color.
 192    *
 193    * This is the default foreground
 194    * color (non-selected).  By default, it is @p blue.
 195    */
 196   void setHighlightedColor(const QColor& highcolor);
 197
 198   /**
 199    * This is an overloaded version for convenience.
 200    *
 201    * @see setHighlightedColor()
 202    */
 203   void setHighlightedColor(const QString& highcolor);
 204
 205   /**
 206    * Sets the selected color.
 207    *
 208    * This is the color the text will change
 209    * to when either a mouse passes over it and "glow" mode is on or
 210    * when it is selected (clicked).  By default, it is @p red.
 211    */
 212   void setSelectedColor(const QColor& selcolor);
 213
 214   /**
 215    * This is an overloaded version for convenience.
 216    *
 217    * @see setSelectedColor()
 218    */
 219   void setSelectedColor(const QString& selcolor);
 220
 221   /**
 222    * Turns the custom cursor feature on or off.
 223    *
 224    * When this is on, the cursor will change to a custom cursor
 225    * (default is a "pointing hand") whenever the cursor passes
 226    * over the label. By default, it is on.
 227    *
 228    * @param on whether a custom cursor should be displayed.
 229    * @param cursor is the custom cursor. @p 0L indicates the default "hand cursor".
 230    */
 231   void setUseCursor (bool on, QCursor* cursor = 0L);
 232
 233   /**
 234    * Turns on or off the "glow" feature.
 235    *
 236    * When this is on, the text will switch to the
 237    * selected color whenever the mouse
 238    * passes over it. By default, it is @p true.
 239    */
 240   void setGlow (bool glow = true);
 241
 242   /**
 243    * Turns on or off the "float" feature.
 244    *
 245    * This feature is very similar to the "glow" feature in
 246    * that the color of the label switches to the selected
 247    * color when the cursor passes over it. In addition,
 248    * underlining is turned on for as long as the mouse is overhead.
 249    * Note that if "glow" and underlining are both already turned
 250    * on, this feature will have no visible effect.
 251    * By default, it is @p false.
 252    */
 253   void setFloat (bool do_float = true);
 254
 255   /**
 256    * Sets the "alt" pixmap.
 257    *
 258    * This pixmap will be displayed when the
 259    * cursor passes over the label.  The effect is similar to the
 260    * trick done with 'onMouseOver' in javascript.
 261    *
 262    * @see altPixmap()
 263    */
 264   void setAltPixmap (const QPixmap& altPix);
 265
 266 signals:
 267
 268   /**
 269    * Emitted when the mouse has passed over the label.
 270    *
 271    * @param url The URL for this label.
 272    */
 273   void enteredURL (const QString& url);
 274
 275   /**
 276    * Emitted when the mouse has passed over the label.
 277    */
 278   void enteredURL ();
 279
 280   /**
 281    * Emitted when the mouse is no longer over the label.
 282    *
 283    * @param url The URL for this label.
 284    */
 285   void leftURL (const QString& url);
 286
 287   /**
 288    * Emitted when the mouse is no longer over the label.
 289    */
 290   void leftURL ();
 291
 292   /**
 293    * Emitted when the user clicked the left mouse button on this label.
 294    *
 295    * @param url The URL for this label.
 296    */
 297   void leftClickedURL(const QString& url);
 298
 299   /**
 300    * Emitted when the user clicked the left mouse button on this label.
 301    */
 302   void leftClickedURL();
 303
 304   /**
 305    * Emitted when the user clicked the right mouse button on this label.
 306    *
 307    * @param url The URL for this label.
 308    */
 309   void rightClickedURL(const QString& url);
 310
 311   /**
 312    * Emitted when the user clicked the right mouse button on this label.
 313    */
 314   void rightClickedURL();
 315
 316   /**
 317    * Emitted when the user clicked the middle mouse button on this label.
 318    *
 319    * @param url The URL for this label.
 320    */
 321   void middleClickedURL(const QString& url);
 322
 323   /**
 324    * Emitted when the user clicked the left mouse button on this label.
 325    */
 326   void middleClickedURL();
 327
 328 protected:
 329
 330   /**
 331    * Overridden for internal reasons; the API remains unaffected.
 332    */
 333   virtual void mouseReleaseEvent (QMouseEvent*);
 334
 335   /**
 336    * Overridden for internal reasons; the API remains unaffected.
 337    */
 338   virtual void enterEvent (QEvent*);
 339
 340   /**
 341    * Overridden for internal reasons; the API remains unaffected.
 342    */
 343   virtual void leaveEvent (QEvent*);
 344
 345   /**
 346    * Catch parent palette changes
 347    */
 348   virtual bool event (QEvent *e);
 349
 350
 351 private slots:
 352   /**
 353    * @internal
 354    * Slot used to reset the link-color to normal (timer-driven).
 355    */
 356   void updateColor ();
 357
 358 private:
 359   /**
 360    * @internal
 361    * A private helper function to set the link-color to @p col.
 362    */
 363   void setLinkColor (const QColor& col);
 364
 365 protected:
 366   virtual void virtual_hook( int id, void* data );
 367 private:
 368   class Private;
 369   Private* d;
 370 };
 371
 372 #endif // KURLLABEL_H