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