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