KWidgetsAddons

kurllabel.h
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
259
260 /**
261 * Emitted when the mouse has passed over the label.
262 */
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 */
274
275 /**
276 * Emitted when the user clicked the right mouse button on this label.
277 */
279
280 /**
281 * Emitted when the user clicked the left mouse button on this label.
282 */
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
A drop-in replacement for QLabel that displays hyperlinks.
Definition kurllabel.h:61
void rightClickedUrl()
Emitted when the user clicked the right mouse button on this label.
void enteredUrl()
Emitted when the mouse has passed over the label.
~KUrlLabel() override
Destructs the label.
void middleClickedUrl()
Emitted when the user clicked the left mouse button on this label.
void leftClickedUrl()
Emitted when the user clicked the left mouse button on this label.
void leftUrl()
Emitted when the mouse is no longer over the label.
virtual bool event(QEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *ev) override
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
virtual void enterEvent(QEnterEvent *event)
void setFont(const QFont &)
virtual void leaveEvent(QEvent *event)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 4 2024 12:05:10 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.