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 | |
30 | class 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 | */ |
69 | class 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 | |