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
24 *
25 * \brief 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 kurllabel.png "KUrlLabel Widget"
56 */
57class KWIDGETSADDONS_EXPORT KUrlLabel : public QLabel
58{
59 Q_OBJECT
60
61 /*!
62 * \property KUrlLabel::url
63 */
64 Q_PROPERTY(QString url READ url WRITE setUrl)
65
66 /*!
67 * \property KUrlLabel::tipText
68 */
69 Q_PROPERTY(QString tipText READ tipText WRITE setTipText)
70
71 /*!
72 * \property KUrlLabel::alternatePixmap
73 */
74 Q_PROPERTY(QPixmap alternatePixmap READ alternatePixmap WRITE setAlternatePixmap)
75
76 /*!
77 * \property KUrlLabel::glowEnabled
78 */
79 Q_PROPERTY(bool glowEnabled READ isGlowEnabled WRITE setGlowEnabled)
80
81 /*!
82 * \property KUrlLabel::floatEnabled
83 */
84 Q_PROPERTY(bool floatEnabled READ isFloatEnabled WRITE setFloatEnabled)
85
86 /*!
87 * \property KUrlLabel::useTips
88 */
89 Q_PROPERTY(bool useTips READ useTips WRITE setUseTips)
90
91 /*!
92 * \property KUrlLabel::useCursor
93 */
94 Q_PROPERTY(bool useCursor READ useCursor WRITE setUseCursor)
95
96public:
97 /*!
98 * Default constructor.
99 *
100 * Use setUrl() and setText() or QListView::setPixmap()
101 * to set the resp. properties.
102 */
103 explicit KUrlLabel(QWidget *parent = nullptr);
104
105 /*!
106 * Convenience constructor.
107 *
108 * \a url is the URL emitted when the label is clicked.
109 *
110 * \a text is the displayed string. If it's equal to QString()
111 * the \a url will be used instead.
112 *
113 * \a parent Passed to lower level constructor
114 *
115 * @p parent and @p name are passed to QLabel, which in turn passes
116 * them further down
117 */
118 explicit KUrlLabel(const QString &url, const QString &text = QString(), QWidget *parent = nullptr);
119
120 ~KUrlLabel() override;
121
122 /*!
123 * Returns the URL.
124 */
125 QString url() const;
126
127 /*!
128 * Returns the current tooltip text.
129 */
130 QString tipText() const;
131
132 /*!
133 * Returns \c true if a tooltip will be displayed.
134 *
135 * \sa setTipText()
136 */
137 bool useTips() const;
138
139 /*!
140 * Returns \c true if the cursor will change while over the URL.
141 *
142 * \sa setUseCursor()
143 */
144 bool useCursor() const;
145
146 /*!
147 * When this is on, the text will switch to the selected
148 * color whenever the mouse passes over it.
149 */
150 bool isGlowEnabled() const;
151
152 /*!
153 * This feature is very similar to the "glow" feature in that the color of the
154 * label switches to the selected color when the cursor passes
155 * over it. In addition, underlining is turned on for as
156 * long as the mouse is overhead. Note that if "glow" and
157 * underlining are both already turned on, this feature
158 * will have no visible effect.
159 */
160 bool isFloatEnabled() const;
161
162 /*!
163 * Returns the alternate pixmap (may be a null pointer if none was set)
164 */
165 const QPixmap *alternatePixmap() const;
166
167public Q_SLOTS:
168 /*!
169 * Turns on or off the underlining.
170 *
171 * When this is on, the
172 * text will be underlined. By default, it is \a true.
173 */
174 void setUnderline(bool on = true);
175
176 /*!
177 * Sets the URL for this label to \a url.
178 *
179 * \sa url
180 */
181 void setUrl(const QString &url);
182
183 virtual void setFont(const QFont &font);
184
185 /*!
186 * Turns on or off the tool tip feature.
187 *
188 * When this is on, the URL will be displayed as a
189 * tooltip whenever the mouse passes passes over it.
190 * By default, it is \a false.
191 */
192 void setUseTips(bool on = true);
193
194 /*!
195 * Specifies what text to display when tooltips are turned on.
196 *
197 * If this is not used, the tip will default to the URL.
198 *
199 * \sa setUseTips()
200 */
201 void setTipText(const QString &tip);
202
203 /*!
204 * Sets the highlight color.
205 *
206 * This is the default foreground
207 * color (non-selected). By default, it is \a blue.
208 */
209 void setHighlightedColor(const QColor &highcolor);
210
211 /*!
212 * This is an overloaded version for convenience.
213 *
214 * \sa setHighlightedColor()
215 */
216 void setHighlightedColor(const QString &highcolor);
217
218 /*!
219 * Sets the selected color.
220 *
221 * This is the color the text will change
222 * to when either a mouse passes over it and "glow" mode is on or
223 * when it is selected (clicked). By default, it is \a red.
224 */
225 void setSelectedColor(const QColor &color);
226
227 /*!
228 * This is an overloaded version for convenience.
229 *
230 * \sa setSelectedColor()
231 */
232 void setSelectedColor(const QString &color);
233
234 /*!
235 * Turns the custom cursor feature on or off.
236 *
237 * When this is on, the cursor will change to a custom cursor
238 * (default is a "pointing hand") whenever the cursor passes
239 * over the label. By default, it is on.
240 *
241 * \a on whether a custom cursor should be displayed.
242 *
243 * \a cursor the custom cursor. A null pointer indicates the default "hand cursor".
244 */
245 void setUseCursor(bool on, QCursor *cursor = nullptr);
246
247 /*!
248 * Turns on or off the "glow" feature.
249 *
250 * When this is on, the text will switch to the
251 * selected color whenever the mouse
252 * passes over it. By default, it is \a true.
253 */
254 void setGlowEnabled(bool glow = true);
255
256 /*!
257 * Turns on or off the "float" feature.
258 *
259 * This feature is very similar to the "glow" feature in
260 * that the color of the label switches to the selected
261 * color when the cursor passes over it. In addition,
262 * underlining is turned on for as long as the mouse is overhead.
263 * Note that if "glow" and underlining are both already turned
264 * on, this feature will have no visible effect.
265 * By default, it is \a false.
266 */
267 void setFloatEnabled(bool do_float = true);
268
269 /*!
270 * Sets the "alt" pixmap.
271 *
272 * This pixmap will be displayed when the
273 * cursor passes over the label. The effect is similar to the
274 * trick done with 'onMouseOver' in javascript.
275 *
276 * \sa alternatePixmap()
277 */
278 void setAlternatePixmap(const QPixmap &pixmap);
279
280Q_SIGNALS:
281
282 /*!
283 * Emitted when the mouse has passed over the label.
284 */
285 void enteredUrl();
286
287 /*!
288 * Emitted when the mouse is no longer over the label.
289 */
290 void leftUrl();
291
292 /*!
293 * Emitted when the user clicked the left mouse button on this label.
294 */
295 void leftClickedUrl();
296
297 /*!
298 * Emitted when the user clicked the right mouse button on this label.
299 */
300 void rightClickedUrl();
301
302 /*!
303 * Emitted when the user clicked the left mouse button on this label.
304 */
305 void middleClickedUrl();
306
307protected:
308 void mouseReleaseEvent(QMouseEvent *) override;
309
310 void enterEvent(QEnterEvent *event) override;
311
312 void leaveEvent(QEvent *) override;
313
314 bool event(QEvent *) override;
315
316private:
317 std::unique_ptr<class KUrlLabelPrivate> const d;
318};
319
320#endif
321

source code of kwidgetsaddons/src/kurllabel.h