diff options
Diffstat (limited to 'tdeui/kurllabel.h')
| -rw-r--r-- | tdeui/kurllabel.h | 411 |
1 files changed, 411 insertions, 0 deletions
diff --git a/tdeui/kurllabel.h b/tdeui/kurllabel.h new file mode 100644 index 000000000..5563f77ba --- /dev/null +++ b/tdeui/kurllabel.h @@ -0,0 +1,411 @@ +/* This file is part of the KDE libraries + Copyright (C) 1998 Kurt Granroth <granroth@kde.org> + Copyright (C) 2000 Peter Putzer <putzer@kde.org> + Copyright (C) 2005 Jaroslaw Staniek <js@iidea.pl> + + 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., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +#ifndef KURLLABEL_H +#define KURLLABEL_H + +#include <tqlabel.h> + +#include <kdelibs_export.h> + +class TQColor; +class TQCursor; +class TQPixmap; + +/** + * @short A drop-in replacement for TQLabel that displays hyperlinks. + * + * KURLLabel is a drop-in replacement for TQLabel 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. + * + * By default KURLLabel accepts focus. When focused, standard + * focus rectangle is displayed as in HTML widget. + * Pressing Enter key accepts the focused label. + * + * A typical usage would be something like so: + * + * \code + * KURLLabel *address = new KURLLabel(this); + * address->setText("My homepage"); + * address->setURL("http://www.home.com/~me"); + * connect(address, TQT_SIGNAL(leftClickedURL(const TQString&)), + * TQT_SLOT(processMyURL(const TQString&))); + * \endcode + * + * 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 leftClickedURL() would be emitted with "http://www.home.com/~me" + * as its argument. + * + * \image html kurllabel.png "KDE URL Label" + * + * @author Kurt Granroth <granroth@kde.org> (Interface) + * @author Peter Putzer <putzer@kde.org> (Rewrite) + * @version $Id$ + * + */ +class KDEUI_EXPORT KURLLabel : public TQLabel +{ + Q_OBJECT + Q_PROPERTY (TQString url READ url WRITE setURL) + Q_PROPERTY (TQString tipText READ tipText WRITE setTipText ) + Q_PROPERTY (TQPixmap altPixmap READ altPixmap WRITE setAltPixmap) + Q_PROPERTY (bool glowEnabled READ isGlowEnabled WRITE setGlow ) + Q_PROPERTY (bool floatEnabled READ isFloatEnabled WRITE setFloat ) + Q_PROPERTY (bool useTips READ useTips WRITE setUseTips ) + Q_PROPERTY (bool useCursor READ useCursor WRITE setUseCursor ) + +public: + /** + * Default constructor. + * + * Use setURL() and setText() or TQListView::setPixmap() + * to set the resp. properties. + */ + KURLLabel (TQWidget* parent = 0L, const char* name = 0L); + + /** + * Convenience constructor. + * + * @param url is the URL emitted when the label is clicked. + * @param text is the displayed string. If it's equal to TQString::null + * the @p url will be used instead. + * @param parent Passed to lower level constructor + * @param name Passed to lower level constructor + * + * @p parent and @p name are passed to TQLabel, which in turn passes + * them further down + */ + KURLLabel (const TQString& url, const TQString& text = TQString::null, + TQWidget* parent = 0L, const char* name = 0L); + + /** + * Destructs the label. + */ + virtual ~KURLLabel (); + + /** + * Returns the URL. + */ + const TQString& url () const; + + /** + * Returns the current tooltip text. + */ + const TQString& tipText () const; + + /** + * @return true if a tooltip will be displayed. + * + * @see setTipText() + */ + bool useTips () const; + + /** + * @return true if the cursor will change while over the URL. + * + * @see setUseCursor () + */ + bool useCursor () const; + + /** + * When this is on, the text will switch to the selected + * color whenever the mouse passes over it. + */ + bool isGlowEnabled () const; + + /** + * 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. + */ + bool isFloatEnabled () const; + + /** + * @return the alternate pixmap (may be 0L if none was set). + */ + const TQPixmap* altPixmap () const; + + /** + * Reimplemented for internal reasons, the API is not affected. + */ + virtual void setMargin ( int margin ); + + /** + * Reimplemented for internal reasons, the API is not affected. + */ +#ifdef qdoc +#else + virtual void setFocusPolicy ( TQ_FocusPolicy policy ); +#endif + + /** + * Reimplemented for internal reasons, the API is not affected. + */ + virtual void tqsetSizePolicy ( TQSizePolicy ); + +public slots: + /** + * Turns on or off the underlining. + * + * When this is on, the + * text will be underlined. By default, it is @p true. + */ + void setUnderline (bool on = true); + + /** + * Sets the URL for this label to @p url. + * + * @see url + */ + void setURL (const TQString& url); + + /** + * Overridden for internal reasons; the API remains unaffected. + */ + virtual void setFont (const TQFont&); + + /** + * Turns 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 @p false. + */ + void setUseTips (bool on = 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 TQString& tip); + + /** + * Sets the highlight color. + * + * This is the default foreground + * color (non-selected). By default, it is @p blue. + */ + void setHighlightedColor(const TQColor& highcolor); + + /** + * This is an overloaded version for convenience. + * + * @see setHighlightedColor() + */ + void setHighlightedColor(const TQString& highcolor); + + /** + * Sets 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 @p red. + */ + void setSelectedColor(const TQColor& selcolor); + + /** + * This is an overloaded version for convenience. + * + * @see setSelectedColor() + */ + void setSelectedColor(const TQString& selcolor); + + /** + * Overridden for internal reasons; the API remains unaffected. + */ + virtual void setCursor ( const TQCursor& cursor ); + + /** + * Overridden for internal reasons; the API remains unaffected. + */ + virtual void unsetCursor (); + + /** + * Turns the custom cursor feature on or off. + * + * 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 on. + * + * @param on whether a custom cursor should be displayed. + * @param cursor is the custom cursor. @p 0L indicates the default "hand cursor". + */ + void setUseCursor (bool on, TQCursor* cursor = 0L); + + /** + * Turns 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 @p true. + */ + void setGlow (bool glow = true); + + /** + * Turns 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 @p false. + */ + void setFloat (bool do_float = true); + + /** + * Sets 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 TQPixmap& altPix); + +signals: + + /** + * Emitted when the mouse has passed over the label. + * + * @param url The URL for this label. + */ + void enteredURL (const TQString& url); + + /** + * Emitted when the mouse has passed over the label. + */ + void enteredURL (); + + /** + * Emitted when the mouse is no longer over the label. + * + * @param url The URL for this label. + */ + void leftURL (const TQString& url); + + /** + * Emitted when the mouse is no longer over the label. + */ + void leftURL (); + + /** + * Emitted when the user clicked the left mouse button on this label. + * + * @param url The URL for this label. + */ + void leftClickedURL(const TQString& url); + + /** + * Emitted when the user clicked the left mouse button on this label. + */ + void leftClickedURL(); + + /** + * Emitted when the user clicked the right mouse button on this label. + * + * @param url The URL for this label. + */ + void rightClickedURL(const TQString& url); + + /** + * Emitted when the user clicked the right mouse button on this label. + */ + void rightClickedURL(); + + /** + * Emitted when the user clicked the middle mouse button on this label. + * + * @param url The URL for this label. + */ + void middleClickedURL(const TQString& url); + + /** + * Emitted when the user clicked the left mouse button on this label. + */ + void middleClickedURL(); + +protected: + + /** + * Overridden for internal reasons; the API remains unaffected. + */ + virtual void mouseReleaseEvent ( TQMouseEvent * e ); + + /** + * Overridden for internal reasons; the API remains unaffected. + */ + virtual void enterEvent (TQEvent*); + + /** + * Overridden for internal reasons; the API remains unaffected. + */ + virtual void leaveEvent (TQEvent*); + + /** + * Catch parent palette changes + */ + virtual bool event (TQEvent *e); + + /** + * + */ + TQRect activeRect() const; + + +private slots: + /** + * @internal + * Slot used to reset the link-color to normal (timer-driven). + */ + void updateColor (); + +private: + /** + * @internal + * A private helper function to set the link-color to @p col. + */ + void setLinkColor (const TQColor& col); + +protected: + virtual void virtual_hook( int id, void* data ); +private: + class Private; + Private* d; +}; + +#endif // KURLLABEL_H + |