1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1998 Kurt Granroth <granroth@kde.org>
4 SPDX-FileCopyrightText: 2000 Peter Putzer <putzer@kde.org>
5 SPDX-FileCopyrightText: 2005 Jarosław Staniek <staniek@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-only
8*/
9
10#ifndef KURLLABEL_H
11#define KURLLABEL_H
12
13#include <kwidgetsaddons_export.h>
14
15#include <QColor>
16#include <QLabel>
17#include <QPixmap>
18#include <memory>
19
20class QCursor;
21
22/**
23 * @class KUrlLabel kurllabel.h KUrlLabel
24 *
25 * @short A drop-in replacement for QLabel that displays hyperlinks.
26 *
27 * KUrlLabel is a drop-in replacement for QLabel that handles text
28 * in a fashion similar to how an HTML widget handles hyperlinks. The
29 * text can be underlined (or not) and set to different colors. It
30 * can also "glow" (cycle colors) when the mouse passes over it.
31 *
32 * KUrlLabel also provides signals for several events, including
33 * the mouse leaving and entering the text area and all forms of
34 * mouse clicking.
35 *
36 * By default KUrlLabel accepts focus. When focused, standard
37 * focus rectangle is displayed as in HTML widget.
38 * Pressing Enter key accepts the focused label.
39 *
40 * A typical usage would be something like so:
41 *
42 * \code
43 * KUrlLabel *address = new KUrlLabel(this);
44 * address->setText("My homepage");
45 * address->setUrl("http://www.home.com/~me");
46 * connect(address, &KUrlLabel::leftClickedUrl, this, [this](cont QString &url) { processMyUrl(url); };
47 * \endcode
48 *
49 * In this example, the text "My homepage" would be displayed
50 * as blue, underlined text. When the mouse passed over it,
51 * it would "glow" red. When the user clicks on the text, the
52 * signal leftClickedUrl() would be emitted with "http://www.home.com/~me"
53 * as its argument.
54 *
55 * \image html kurllabel.png "KUrlLabel Widget"
56 *
57 * @author Kurt Granroth <granroth@kde.org> (Interface)
58 * @author Peter Putzer <putzer@kde.org> (Rewrite)
59 */
60class KWIDGETSADDONS_EXPORT KUrlLabel : public QLabel
61{
62 Q_OBJECT
63 Q_PROPERTY(QString url READ url WRITE setUrl)
64 Q_PROPERTY(QString tipText READ tipText WRITE setTipText)
65 Q_PROPERTY(QPixmap alternatePixmap READ alternatePixmap WRITE setAlternatePixmap)
66 Q_PROPERTY(bool glowEnabled READ isGlowEnabled WRITE setGlowEnabled)
67 Q_PROPERTY(bool floatEnabled READ isFloatEnabled WRITE setFloatEnabled)
68 Q_PROPERTY(bool useTips READ useTips WRITE setUseTips)
69 Q_PROPERTY(bool useCursor READ useCursor WRITE setUseCursor)
70
71public:
72 /**
73 * Default constructor.
74 *
75 * Use setUrl() and setText() or QListView::setPixmap()
76 * to set the resp. properties.
77 */
78 explicit KUrlLabel(QWidget *parent = nullptr);
79
80 /**
81 * Convenience constructor.
82 *
83 * @param url is the URL emitted when the label is clicked.
84 * @param text is the displayed string. If it's equal to QString()
85 * the @p url will be used instead.
86 * @param parent Passed to lower level constructor
87 *
88 * @p parent and @p name are passed to QLabel, which in turn passes
89 * them further down
90 */
91 explicit KUrlLabel(const QString &url, const QString &text = QString(), QWidget *parent = nullptr);
92
93 /**
94 * Destructs the label.
95 */
96 ~KUrlLabel() override;
97
98 /**
99 * Returns the URL.
100 */
101 QString url() const;
102
103 /**
104 * Returns the current tooltip text.
105 */
106 QString tipText() const;
107
108 /**
109 * @return true if a tooltip will be displayed.
110 *
111 * @see setTipText()
112 */
113 bool useTips() const;
114
115 /**
116 * @return true if the cursor will change while over the URL.
117 *
118 * @see setUseCursor ()
119 */
120 bool useCursor() const;
121
122 /**
123 * When this is on, the text will switch to the selected
124 * color whenever the mouse passes over it.
125 */
126 bool isGlowEnabled() const;
127
128 /**
129 * This feature is very similar to the "glow" feature in that the color of the
130 * label switches to the selected color when the cursor passes
131 * over it. In addition, underlining is turned on for as
132 * long as the mouse is overhead. Note that if "glow" and
133 * underlining are both already turned on, this feature
134 * will have no visible effect.
135 */
136 bool isFloatEnabled() const;
137
138 /**
139 * @return the alternate pixmap (may be a null pointer if none was set)
140 */
141 const QPixmap *alternatePixmap() const;
142
143public Q_SLOTS:
144 /**
145 * Turns on or off the underlining.
146 *
147 * When this is on, the
148 * text will be underlined. By default, it is @p true.
149 */
150 void setUnderline(bool on = true);
151
152 /**
153 * Sets the URL for this label to @p url.
154 *
155 * @see url
156 */
157 void setUrl(const QString &url);
158
159 /**
160 * Overridden for internal reasons; the API remains unaffected.
161 */
162 virtual void setFont(const QFont &font);
163
164 /**
165 * Turns on or off the tool tip feature.
166 *
167 * When this is on, the URL will be displayed as a
168 * tooltip whenever the mouse passes passes over it.
169 * By default, it is @p false.
170 */
171 void setUseTips(bool on = true);
172
173 /**
174 * Specifies what text to display when tooltips are turned on.
175 *
176 * If this is not used, the tip will default to the URL.
177 *
178 * @see setUseTips()
179 */
180 void setTipText(const QString &tip);
181
182 /**
183 * Sets the highlight color.
184 *
185 * This is the default foreground
186 * color (non-selected). By default, it is @p blue.
187 */
188 void setHighlightedColor(const QColor &highcolor);
189
190 /**
191 * This is an overloaded version for convenience.
192 *
193 * @see setHighlightedColor()
194 */
195 void setHighlightedColor(const QString &highcolor);
196
197 /**
198 * Sets the selected color.
199 *
200 * This is the color the text will change
201 * to when either a mouse passes over it and "glow" mode is on or
202 * when it is selected (clicked). By default, it is @p red.
203 */
204 void setSelectedColor(const QColor &color);
205
206 /**
207 * This is an overloaded version for convenience.
208 *
209 * @see setSelectedColor()
210 */
211 void setSelectedColor(const QString &color);
212
213 /**
214 * Turns the custom cursor feature on or off.
215 *
216 * When this is on, the cursor will change to a custom cursor
217 * (default is a "pointing hand") whenever the cursor passes
218 * over the label. By default, it is on.
219 *
220 * @param on whether a custom cursor should be displayed.
221 * @param cursor the custom cursor. A null pointer indicates the default "hand cursor".
222 */
223 void setUseCursor(bool on, QCursor *cursor = nullptr);
224
225 /**
226 * Turns on or off the "glow" feature.
227 *
228 * When this is on, the text will switch to the
229 * selected color whenever the mouse
230 * passes over it. By default, it is @p true.
231 */
232 void setGlowEnabled(bool glow = true);
233
234 /**
235 * Turns on or off the "float" feature.
236 *
237 * This feature is very similar to the "glow" feature in
238 * that the color of the label switches to the selected
239 * color when the cursor passes over it. In addition,
240 * underlining is turned on for as long as the mouse is overhead.
241 * Note that if "glow" and underlining are both already turned
242 * on, this feature will have no visible effect.
243 * By default, it is @p false.
244 */
245 void setFloatEnabled(bool do_float = true);
246
247 /**
248 * Sets the "alt" pixmap.
249 *
250 * This pixmap will be displayed when the
251 * cursor passes over the label. The effect is similar to the
252 * trick done with 'onMouseOver' in javascript.
253 *
254 * @see alternatePixmap()
255 */
256 void setAlternatePixmap(const QPixmap &pixmap);
257
258Q_SIGNALS:
259
260 /**
261 * Emitted when the mouse has passed over the label.
262 */
263 void enteredUrl();
264
265 /**
266 * Emitted when the mouse is no longer over the label.
267 */
268 void leftUrl();
269
270 /**
271 * Emitted when the user clicked the left mouse button on this label.
272 */
273 void leftClickedUrl();
274
275 /**
276 * Emitted when the user clicked the right mouse button on this label.
277 */
278 void rightClickedUrl();
279
280 /**
281 * Emitted when the user clicked the left mouse button on this label.
282 */
283 void middleClickedUrl();
284
285protected:
286 /**
287 * Overridden for internal reasons; the API remains unaffected.
288 */
289 void mouseReleaseEvent(QMouseEvent *) override;
290
291 /**
292 * Overridden for internal reasons; the API remains unaffected.
293 */
294 void enterEvent(QEnterEvent *event) override;
295
296 /**
297 * Overridden for internal reasons; the API remains unaffected.
298 */
299 void leaveEvent(QEvent *) override;
300
301 /**
302 * Catch parent palette changes
303 */
304 bool event(QEvent *) override;
305
306private:
307 std::unique_ptr<class KUrlLabelPrivate> const d;
308};
309
310#endif
311

source code of kwidgetsaddons/src/kurllabel.h