Source: kurllabel.h


Annotated List
Files
Globals
Hierarchy
Index
/* This file is part of the KDE libraries
   Copyright (C) 1998 Kurt Granroth (granroth@kde.org)

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   This library 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
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
   Boston, MA 02111-1307, USA.
*/
/*
 * $Id: kurllabel.h,v 1.9 2000/01/26 22:58:14 granroth Exp $
 *
 */
#ifndef _KURLLABEL_H
#define _KURLLABEL_H

#include <qpalette.h>
#include <qlabel.h>
#include <qstring.h>
#include <qpixmap.h>
#include <qmovie.h>
#include <qpainter.h>
#include <qbitmap.h>

enum TextAlignment
{
	Bottom,
	Left,
	Top,
	Right
};

/**
 * A label class that supports displaying an active hyperlink.
 *
 * KURLLabel is a drop-in replacement for QLabel that handles text
 * in a fashion similar to how an HTML widget handles hyperlinks.  The
 * text can be underlined (or not) and set to different colors.  It
 * can also "glow" (cycle colors) when the mouse passes over it.
 *
 * KURLLabel also provides signals for several events, including
 * the mouse leaving and entering the text area and all forms of
 * mouse clicking.
 *
 * A typical usage would be something like so:
 *
 * <PRE>
 *     KURLLabel *address = new KURLLabel(this);
 *     address->setText("My homepage");
 *     address->setURL("http://www.home.com/~me");
 *     connect(address, SIGNAL(leftClickedURL(const QString&)),
 *                      SLOT(processMyURL(const QString&)));
 * </PRE>
 *
 * In this example, the text "My homepage" would be displayed
 * as blue, underlined text.  When the mouse passed over it, 
 * it would "glow" red.  When the user clicks on the text, the
 * signal @ref leftClickedURL() would be emitted with "http://www.home.com/~me"
 * as its argument.
 *
 * @short A drop-in replacement for QLabel that displays hyperlinks.
 * @author Kurt Granroth <granroth@kde.org>
 * @version 0.5.3
 */
class KURLLabel : public QLabel
{
	Q_OBJECT
public:
	/**
	 * Constructor.
	 *
	 *  Use this exactly like you would QLabel.
	 */
	KURLLabel(QWidget *parent=0, const char *name=0, WFlags f=0);

	/**
	 * Destructor.
	 */
	virtual ~KURLLabel();

	/**
	 * Retreive the URL. 
	 *
	 * This will be the same as @ref text() if 
	 * @ref setURL() is not used.
	 *
	 * @return The URL.
	 */
	const QString url() const;

	/**
	 * Retrieve the current text.
	 *
	 * @see setText()
	 *
	 * @return The current text.
	 */
	const QString text() const;

	/**
	 * Retrieve the current pixmap.
	 *
	 * @see setPixmap()
	 *
	 * @return The current pixmap.
	 */
	const QPixmap* pixmap() const;

	/**
	 * Retrieve the recommended size for this label.
	 */
	QSize sizeHint() const;
  
        /**
	 * Enable or disable "transparent mode".
	 *
	 * If transparent mode 
	 * is enabled, the label copies its own background from its 
	 * parent widget so that it seems to be transparent.
	 * Transparent mode is disabled by default.
	 * Please note that the method does not repaint the widget.
	 * Changes take effect on the next repainting.
	 * Transparent widgets do not (currently) work if there is another 
	 * widget (a frame, for example) layered between this widget and its
	 * parent in Z-order.
	 */
         void setTransparentMode(bool state);
public slots:
	/**
	 * Turn on or off the "glow" feature. 
	 *
	 * When this is on, the
	 * text will switch to the selected color whenever the mouse
	 * passes over it.  By default, it is @bf on.
	 */
	void setGlow(bool glow = true);

	/**
	 * Turn on or off the "float" feature.
	 *
	 *  This feature is very
	 * similar to the "glow" feature in that the color of the
	 * label switches to the selected color when the cursor passes
	 * over it.  In addition, underlining is turned on for as
	 * long as the mouse is overhead.  Note that if "glow" and
	 * underlining are both already turned on, this feature
	 * will have no visible effect.  By default, it is @bf off.
	 */
	void setFloat(bool do_float = true);

	/**
	 * Turn on or off the custom cursor feature.
	 *
	 *  When this is on, the
	 * cursor will change to a custom cursor (default is a "pointing
	 * hand") whenever the cursor passes over the label.  By default,
	 * it is @bf on.
	 */
	void setUseCursor(bool use_cursor, const QCursor* cursor = 0);

	/**
	 * Turn on or off the tool tip feature.
	 *
	 *  When this is on, the
	 * URL will be displayed as a tooltip whenever the mouse passes
	 * passes over it.  By default, it is @bf off.
	 */
	void setUseTips(bool tips = true);

	/**
	 * Specifies what text to display when tooltips are turned on.
	 *
	 * If this is not used, the tip will default to the URL.
	 *
	 * @see setUseTips()
	 */
	void setTipText(const QString& tip);

	/**
	 * Set the text alignment.
	 */
	void setTextAlignment(TextAlignment align);

	/**
	 * Turn on or off the underlining.
	 *
	 *  When this is on, the
	 * text will be underlined.  By default, it is @bf on.
	 */
	void setUnderline(bool underline = true);

	/**
	 * Set the highlight color.
	 *
	 * This is the default foreground
	 * color (non-selected).  By default, it is @bf blue.
	 */
	void setHighlightedColor(const QColor& highcolor);

	/**
	 * This is an overloaded version for convenience.
	 *
	 * @see setHighlightedColor()
	 */
	void setHighlightedColor(const QString& highcolor);
	
	/**
	 * Set the selected color.
	 *
	 * This is the color the text will change
	 * to when either a mouse passes over it and "glow" mode is on or
	 * when it is selected (clicked).  By default, it is @bf red.
	 */
	void setSelectedColor(const QColor& selcolor);

	/**
	 * This is an overloaded versionfor convenience.
	 *
	 * @see setSelectedColor()
	 */
	void setSelectedColor(const QString& selcolor);
	
	/**
	 * Set the background color.
	 *
	 *  By default, it is set to the
	 * KDE background color.
	 */
	void setBackgroundColor(const QColor& bgcolor);

	/**
	 * This is an overloaded version for convenience.
	 *
	 * @see setBackgroundColor()
	 */
	void setBackgroundColor(const QString& bgcolor);

	/**
	 * Set the font for the label.
	 */
	void setFont(const QFont& font);

	/**
	 * Set the label contents to @p text.
	 *
	 * @see text()
	 */
	void setText(const QString& text);

	/**
	 * Set the pixmap.
	 *
	 * Unlike QLabel, this can co-exist with 
	 * @ref setText().  It cannot be used along with @ref setMovie(),
	 * however.
	 *
	 * @see pixmap()
	 */
	void setPixmap(const QPixmap& pixmap);

	/**
	 * Set the "alt" pixmap. 
	 *
	 * This pixmap will be displayed when the
	 * cursor passes over the label.  The effect is similar to the
	 * trick done with 'onMouseOver' in javascript.
	 *
	 * @see altPixmap()
	 */
	void setAltPixmap(const QPixmap& pixmap);

	/**
	 * Set the movie.
	 *
	 *  Cannot be used with @ref setPixmap ()
	 *
	 * @see #movie
	 */
	void setMovie(const QMovie& movie);

	/**
	 * Sets the URL for this label to @p url.
	 *
	 * @see #url
	 */
	void setURL(const QString& url);

signals:
	/**
	 * The mouse has passed over the label.
	 *
	 * @param url The URL for this label.
	 */ 
	void enteredURL(const QString& url);

	/**
	 * The mouse has passed over the label.
	 */ 
	void enteredURL();

	/**
	 * The mouse is no longer over the label.
	 *
	 * @param url The URL for this label.
	 */ 
	void leftURL(const QString& url);

	/**
	 * The mouse is no longer over the label.
	 */ 
	void leftURL();

	/**
	 * The user clicked the left mouse button on this label.
	 *
	 * @param url The URL for this label.
	 */ 
	void leftClickedURL(const QString& url);

	/**
	 * The user clicked the left mouse button on this label.
	 */ 
	void leftClickedURL();

	/**
	 * The user clicked the right mouse button on this label.
	 *
	 * @param url The URL for this label.
	 */ 
	void rightClickedURL(const QString& url);

	/**
	 * The user clicked the left mouse button on this label.
	 */ 
	void rightClickedURL();

	/**
	 * The user clicked the middle mouse button on this label.
	 *
	 * @param url The URL for this label.
	 */ 
	void middleClickedURL(const QString& url);

	/**
	 * The user clicked the left mouse button on this label.
	 */ 
	void middleClickedURL();

protected:			
	/**
	 * Draws the text, pixmap, and/or movie
	 */
	void drawContents(QPainter *);

	/**
	 * Used to "glow" the text when it is selected.
	 */
	void timerEvent(QTimerEvent *);

	/**
	 * <CODE>emit</CODE>s the @ref #enteredURL signal.  If glow is
	 * on, it sets the selected color. 
	 */
	void m_enterEvent();

	/**
	 * <CODE>emit</CODE>s the @ref #leftURL signal.  If glow is
	 * on, it sets the normal color. 
	 */
	void m_leaveEvent();

	/**
	 * Processes "true" leave events since @ref #mouseMoveEvent cannot
	 */
	void leaveEvent(QEvent *event);

	/**
	 * Tracks if the cursor is above the text as well as the mouse state.
	 * It <CODE>emit</CODE>s either the @ref #enteredURL, @ref #leftURL,
	 * @ref #leftClickedURL, @ref #middleClickedURL, or @ref #rightClickedURL
	 * as appropriate.
	 */
	void mouseMoveEvent(QMouseEvent *);

	/**
	 * <CODE>emit</CODE>s either the @ref #leftClickedURL,
	 * @ref #rightClickedURL, or @ref #middleClickedURL signal depending
	 * on which one the user clicked.  Changes the color to selected
	 * to indicate that it was selected.  Starts a timer to deselect
	 * it.
	 */
	void mousePressEvent(QMouseEvent *);

        /**
	 * An overloaded repaint event that handles the background in 
	 * transparent mode. It sets a background pixmap that is obtained 
	 * from the widgets parent and calls the QLabel repaint handler 
	 * after that.
	 */
         void paintEvent(QPaintEvent*);

private:
	QRect m_textRect() const;
	QRect m_pixmapRect() const;
	void  m_resetPalette();

	TextAlignment m_textAlign;

	QString m_url;
	QString m_tipText;

	QPixmap m_altPixmap;
	QPixmap m_origPixmap;
	QPixmap m_unselPixmap;
	QPixmap m_pixmap;

	QString m_text;
	QMovie  m_movie;

	QCursor m_customCursor;

	QColor m_hc;
	QColor m_bc;
	QColor m_sc;
	QPalette m_nsp;
	QPalette m_sp;

	bool m_float;
	bool m_tips;
	bool m_glow;
	bool m_underline;
	bool m_inRegion;
	bool m_haveCursor;
	bool m_transparent; // true when transparent mode is enabled
};

#endif // _KURLLABEL_H

Generated by: root@tantive.terraplex.com on Sun Feb 27 17:39:25 2000, using kdoc 2.0a33.