File indexing completed on 2025-02-02 14:20:13
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 1998 Kurt Granroth <granroth@kde.org> 0004 SPDX-FileCopyrightText: 2000 Peter Putzer <putzer@kde.org> 0005 SPDX-FileCopyrightText: 2005 Jarosław Staniek <staniek@kde.org> 0006 0007 SPDX-License-Identifier: LGPL-2.0-only 0008 */ 0009 0010 #ifndef KURLLABEL_H 0011 #define KURLLABEL_H 0012 0013 #include <kwidgetsaddons_export.h> 0014 0015 #include <QColor> 0016 #include <QLabel> 0017 #include <QPixmap> 0018 #include <memory> 0019 0020 class QCursor; 0021 0022 /** 0023 * @class KUrlLabel kurllabel.h KUrlLabel 0024 * 0025 * @short A drop-in replacement for QLabel that displays hyperlinks. 0026 * 0027 * KUrlLabel is a drop-in replacement for QLabel that handles text 0028 * in a fashion similar to how an HTML widget handles hyperlinks. The 0029 * text can be underlined (or not) and set to different colors. It 0030 * can also "glow" (cycle colors) when the mouse passes over it. 0031 * 0032 * KUrlLabel also provides signals for several events, including 0033 * the mouse leaving and entering the text area and all forms of 0034 * mouse clicking. 0035 * 0036 * By default KUrlLabel accepts focus. When focused, standard 0037 * focus rectangle is displayed as in HTML widget. 0038 * Pressing Enter key accepts the focused label. 0039 * 0040 * A typical usage would be something like so: 0041 * 0042 * \code 0043 * KUrlLabel *address = new KUrlLabel(this); 0044 * address->setText("My homepage"); 0045 * address->setUrl("http://www.home.com/~me"); 0046 * connect(address, &KUrlLabel::leftClickedUrl, this, [this](cont QString &url) { processMyUrl(url); }; 0047 * \endcode 0048 * 0049 * In this example, the text "My homepage" would be displayed 0050 * as blue, underlined text. When the mouse passed over it, 0051 * it would "glow" red. When the user clicks on the text, the 0052 * signal leftClickedUrl() would be emitted with "http://www.home.com/~me" 0053 * as its argument. 0054 * 0055 * \image html kurllabel.png "KUrlLabel Widget" 0056 * 0057 * @author Kurt Granroth <granroth@kde.org> (Interface) 0058 * @author Peter Putzer <putzer@kde.org> (Rewrite) 0059 */ 0060 class KWIDGETSADDONS_EXPORT KUrlLabel : public QLabel 0061 { 0062 Q_OBJECT 0063 Q_PROPERTY(QString url READ url WRITE setUrl) 0064 Q_PROPERTY(QString tipText READ tipText WRITE setTipText) 0065 Q_PROPERTY(QPixmap alternatePixmap READ alternatePixmap WRITE setAlternatePixmap) 0066 Q_PROPERTY(bool glowEnabled READ isGlowEnabled WRITE setGlowEnabled) 0067 Q_PROPERTY(bool floatEnabled READ isFloatEnabled WRITE setFloatEnabled) 0068 Q_PROPERTY(bool useTips READ useTips WRITE setUseTips) 0069 Q_PROPERTY(bool useCursor READ useCursor WRITE setUseCursor) 0070 0071 public: 0072 /** 0073 * Default constructor. 0074 * 0075 * Use setUrl() and setText() or QListView::setPixmap() 0076 * to set the resp. properties. 0077 */ 0078 explicit KUrlLabel(QWidget *parent = nullptr); 0079 0080 /** 0081 * Convenience constructor. 0082 * 0083 * @param url is the URL emitted when the label is clicked. 0084 * @param text is the displayed string. If it's equal to QString() 0085 * the @p url will be used instead. 0086 * @param parent Passed to lower level constructor 0087 * 0088 * @p parent and @p name are passed to QLabel, which in turn passes 0089 * them further down 0090 */ 0091 explicit KUrlLabel(const QString &url, const QString &text = QString(), QWidget *parent = nullptr); 0092 0093 /** 0094 * Destructs the label. 0095 */ 0096 ~KUrlLabel() override; 0097 0098 /** 0099 * Returns the URL. 0100 */ 0101 QString url() const; 0102 0103 /** 0104 * Returns the current tooltip text. 0105 */ 0106 QString tipText() const; 0107 0108 /** 0109 * @return true if a tooltip will be displayed. 0110 * 0111 * @see setTipText() 0112 */ 0113 bool useTips() const; 0114 0115 /** 0116 * @return true if the cursor will change while over the URL. 0117 * 0118 * @see setUseCursor () 0119 */ 0120 bool useCursor() const; 0121 0122 /** 0123 * When this is on, the text will switch to the selected 0124 * color whenever the mouse passes over it. 0125 */ 0126 bool isGlowEnabled() const; 0127 0128 /** 0129 * This feature is very similar to the "glow" feature in that the color of the 0130 * label switches to the selected color when the cursor passes 0131 * over it. In addition, underlining is turned on for as 0132 * long as the mouse is overhead. Note that if "glow" and 0133 * underlining are both already turned on, this feature 0134 * will have no visible effect. 0135 */ 0136 bool isFloatEnabled() const; 0137 0138 /** 0139 * @return the alternate pixmap (may be a null pointer if none was set) 0140 */ 0141 const QPixmap *alternatePixmap() const; 0142 0143 public Q_SLOTS: 0144 /** 0145 * Turns on or off the underlining. 0146 * 0147 * When this is on, the 0148 * text will be underlined. By default, it is @p true. 0149 */ 0150 void setUnderline(bool on = true); 0151 0152 /** 0153 * Sets the URL for this label to @p url. 0154 * 0155 * @see url 0156 */ 0157 void setUrl(const QString &url); 0158 0159 /** 0160 * Overridden for internal reasons; the API remains unaffected. 0161 */ 0162 virtual void setFont(const QFont &font); 0163 0164 /** 0165 * Turns on or off the tool tip feature. 0166 * 0167 * When this is on, the URL will be displayed as a 0168 * tooltip whenever the mouse passes passes over it. 0169 * By default, it is @p false. 0170 */ 0171 void setUseTips(bool on = true); 0172 0173 /** 0174 * Specifies what text to display when tooltips are turned on. 0175 * 0176 * If this is not used, the tip will default to the URL. 0177 * 0178 * @see setUseTips() 0179 */ 0180 void setTipText(const QString &tip); 0181 0182 /** 0183 * Sets the highlight color. 0184 * 0185 * This is the default foreground 0186 * color (non-selected). By default, it is @p blue. 0187 */ 0188 void setHighlightedColor(const QColor &highcolor); 0189 0190 /** 0191 * This is an overloaded version for convenience. 0192 * 0193 * @see setHighlightedColor() 0194 */ 0195 void setHighlightedColor(const QString &highcolor); 0196 0197 /** 0198 * Sets the selected color. 0199 * 0200 * This is the color the text will change 0201 * to when either a mouse passes over it and "glow" mode is on or 0202 * when it is selected (clicked). By default, it is @p red. 0203 */ 0204 void setSelectedColor(const QColor &color); 0205 0206 /** 0207 * This is an overloaded version for convenience. 0208 * 0209 * @see setSelectedColor() 0210 */ 0211 void setSelectedColor(const QString &color); 0212 0213 /** 0214 * Turns the custom cursor feature on or off. 0215 * 0216 * When this is on, the cursor will change to a custom cursor 0217 * (default is a "pointing hand") whenever the cursor passes 0218 * over the label. By default, it is on. 0219 * 0220 * @param on whether a custom cursor should be displayed. 0221 * @param cursor the custom cursor. A null pointer indicates the default "hand cursor". 0222 */ 0223 void setUseCursor(bool on, QCursor *cursor = nullptr); 0224 0225 /** 0226 * Turns on or off the "glow" feature. 0227 * 0228 * When this is on, the text will switch to the 0229 * selected color whenever the mouse 0230 * passes over it. By default, it is @p true. 0231 */ 0232 void setGlowEnabled(bool glow = true); 0233 0234 /** 0235 * Turns on or off the "float" feature. 0236 * 0237 * This feature is very similar to the "glow" feature in 0238 * that the color of the label switches to the selected 0239 * color when the cursor passes over it. In addition, 0240 * underlining is turned on for as long as the mouse is overhead. 0241 * Note that if "glow" and underlining are both already turned 0242 * on, this feature will have no visible effect. 0243 * By default, it is @p false. 0244 */ 0245 void setFloatEnabled(bool do_float = true); 0246 0247 /** 0248 * Sets the "alt" pixmap. 0249 * 0250 * This pixmap will be displayed when the 0251 * cursor passes over the label. The effect is similar to the 0252 * trick done with 'onMouseOver' in javascript. 0253 * 0254 * @see alternatePixmap() 0255 */ 0256 void setAlternatePixmap(const QPixmap &pixmap); 0257 0258 Q_SIGNALS: 0259 0260 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 65) 0261 /** 0262 * Emitted when the mouse has passed over the label. 0263 * 0264 * @param url The URL for this label. 0265 * @deprecated Since 5.65, use enteredUrl(); 0266 */ 0267 KWIDGETSADDONS_DEPRECATED_VERSION(5, 65, "Use KUrlLabel::enteredUrl()") 0268 void enteredUrl(const QString &url); // clazy:exclude=overloaded-signal 0269 #endif 0270 /** 0271 * Emitted when the mouse has passed over the label. 0272 */ 0273 void enteredUrl(); // clazy:exclude=overloaded-signal 0274 0275 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 65) 0276 /** 0277 * Emitted when the mouse is no longer over the label. 0278 * 0279 * @deprecated Since 5.65, use leftUrl(); 0280 * @param url The URL for this label. 0281 */ 0282 KWIDGETSADDONS_DEPRECATED_VERSION(5, 65, "Use KUrlLabel::leftUrl()") 0283 void leftUrl(const QString &url); // clazy:exclude=overloaded-signal 0284 #endif 0285 0286 /** 0287 * Emitted when the mouse is no longer over the label. 0288 */ 0289 void leftUrl(); // clazy:exclude=overloaded-signal 0290 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 65) 0291 /** 0292 * Emitted when the user clicked the left mouse button on this label. 0293 * 0294 * @param url The URL for this label. 0295 * @deprecated Since 5.65, use leftClickedUrl(); 0296 */ 0297 KWIDGETSADDONS_DEPRECATED_VERSION(5, 65, "Use KUrlLabel::leftClickedUrl()") 0298 void leftClickedUrl(const QString &url); // clazy:exclude=overloaded-signal 0299 #endif 0300 /** 0301 * Emitted when the user clicked the left mouse button on this label. 0302 */ 0303 void leftClickedUrl(); // clazy:exclude=overloaded-signal 0304 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 65) 0305 /** 0306 * Emitted when the user clicked the right mouse button on this label. 0307 * 0308 * @param url The URL for this label. 0309 * @deprecated Since 5.65, use rightClickedUrl(); 0310 */ 0311 KWIDGETSADDONS_DEPRECATED_VERSION(5, 65, "Use KUrlLabel::rightClickedUrl()") 0312 void rightClickedUrl(const QString &url); // clazy:exclude=overloaded-signal 0313 #endif 0314 /** 0315 * Emitted when the user clicked the right mouse button on this label. 0316 */ 0317 void rightClickedUrl(); // clazy:exclude=overloaded-signal 0318 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 65) 0319 /** 0320 * Emitted when the user clicked the middle mouse button on this label. 0321 * 0322 * @param url The URL for this label. 0323 * @deprecated Since 5.65, use middleClickedUrl(); 0324 */ 0325 KWIDGETSADDONS_DEPRECATED_VERSION(5, 65, "Use KUrlLabel::middleClickedUrl()") 0326 void middleClickedUrl(const QString &url); // clazy:exclude=overloaded-signal 0327 #endif 0328 /** 0329 * Emitted when the user clicked the left mouse button on this label. 0330 */ 0331 void middleClickedUrl(); // clazy:exclude=overloaded-signal 0332 0333 protected: 0334 /** 0335 * Overridden for internal reasons; the API remains unaffected. 0336 */ 0337 void mouseReleaseEvent(QMouseEvent *) override; 0338 0339 /** 0340 * Overridden for internal reasons; the API remains unaffected. 0341 */ 0342 void enterEvent(QEvent *event) override; 0343 0344 /** 0345 * Overridden for internal reasons; the API remains unaffected. 0346 */ 0347 void leaveEvent(QEvent *) override; 0348 0349 /** 0350 * Catch parent palette changes 0351 */ 0352 bool event(QEvent *) override; 0353 0354 private: 0355 std::unique_ptr<class KUrlLabelPrivate> const d; 0356 }; 0357 0358 #endif