1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1998 Kurt Granroth (granroth@kde.org) |
3 | 2000 Carsten Pfeiffer <pfeiffer@kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License version 2 as published by the Free Software Foundation. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KCURSOR_H |
21 | #define KCURSOR_H |
22 | |
23 | #include <kdeui_export.h> |
24 | #include <QtGui/QCursor> |
25 | |
26 | class QEvent; |
27 | class QWidget; |
28 | |
29 | /** |
30 | * The KCursor class extends QCursor with the ability to create an arbitrary |
31 | * named cursor from the cursor theme, and provides a set of static |
32 | * convenience methods for auto-hiding cursors on widgets. |
33 | * |
34 | * @author Kurt Granroth <granroth@kde.org> |
35 | */ |
36 | class KDEUI_EXPORT KCursor : public QCursor |
37 | { |
38 | public: |
39 | /** |
40 | * Attempts to load the requested @p name cursor from the current theme. |
41 | * |
42 | * This allows one to access cursors that may be in a theme but not in |
43 | * the Qt::CursorShape enum. |
44 | * |
45 | * If the specified cursor doesn't exist in the theme, or if KDE was |
46 | * built without Xcursor support, the cursor will be loaded from the X11 |
47 | * cursor font instead. If the cursor doesn't exist in the cursor font, |
48 | * it falls back to the Qt::CursorShape provided as the second parameter. |
49 | * |
50 | * On platforms other than X11, the fallback shape is always used. |
51 | * |
52 | * @param name the name of the cursor to try and load |
53 | * @param fallback the cursor to load if @p name cursor can not be loaded |
54 | */ |
55 | explicit KCursor( const QString & name, Qt::CursorShape fallback = Qt::ArrowCursor ); |
56 | |
57 | /** |
58 | * Creates a copy of @p cursor. |
59 | */ |
60 | KCursor( const QCursor & cursor ); |
61 | |
62 | /** |
63 | * Assigns @p cursor to this cursor, and returns a reference to this |
64 | * cursor. |
65 | */ |
66 | KCursor & operator = ( const KCursor & cursor ); |
67 | |
68 | /** |
69 | * Sets auto-hiding the cursor for widget @p w. Enabling it will result in |
70 | * the cursor being hidden when |
71 | * @li a key-event happens |
72 | * @li there are no key-events for a configured time-frame (see |
73 | * setHideCursorDelay()) |
74 | * |
75 | * The cursor will be shown again when the focus is lost or a mouse-event |
76 | * happens. |
77 | * |
78 | * Side effect: when enabling auto-hide, mouseTracking is enabled for the |
79 | * specified widget, because it's needed to get mouse-move-events. So |
80 | * don't disable mouseTracking for a widget while using auto-hide for it. |
81 | * |
82 | * When disabling auto-hide, mouseTracking will be disabled, so if you need |
83 | * mouseTracking after disabling auto-hide, you have to reenable |
84 | * mouseTracking. |
85 | * |
86 | * If you want to use auto-hiding for widgets that don't take focus, e.g. |
87 | * a QCanvasView, then you have to pass all key-events that should trigger |
88 | * auto-hiding to autoHideEventFilter(). |
89 | */ |
90 | static void setAutoHideCursor( QWidget *w, bool enable, |
91 | bool customEventFilter = false ); |
92 | |
93 | /** |
94 | * Sets the delay time in milliseconds for auto-hiding. When no keyboard |
95 | * events arrive for that time-frame, the cursor will be hidden. |
96 | * |
97 | * Default is 5000, i.e. 5 seconds. |
98 | */ |
99 | static void setHideCursorDelay( int ms ); |
100 | |
101 | /** |
102 | * @returns the current auto-hide delay time. |
103 | * |
104 | * Default is 5000, i.e. 5 seconds. |
105 | */ |
106 | static int hideCursorDelay(); |
107 | |
108 | /** |
109 | * KCursor has to install an eventFilter over the widget you want to |
110 | * auto-hide. If you have an own eventFilter() on that widget and stop |
111 | * some events by returning true, you might break auto-hiding, because |
112 | * KCursor doesn't get those events. |
113 | * |
114 | * In this case, you need to call setAutoHideCursor( widget, true, true ); |
115 | * to tell KCursor not to install an eventFilter. Then you call this method |
116 | * from the beginning of your eventFilter, for example: |
117 | * \code |
118 | * edit = new KEdit( this, "some edit widget" ); |
119 | * edit->installEventFilter( this ); |
120 | * KCursor::setAutoHideCursor( edit, true, true ); |
121 | * |
122 | * [...] |
123 | * |
124 | * bool YourClass::eventFilter( QObject *o, QEvent *e ) |
125 | * { |
126 | * if ( o == edit ) // only that widget where you enabled auto-hide! |
127 | * KCursor::autoHideEventFilter( o, e ); |
128 | * |
129 | * // now you can do your own event-processing |
130 | * [...] |
131 | * } |
132 | * \endcode |
133 | * |
134 | * Note that you must not call KCursor::autoHideEventFilter() when you |
135 | * didn't enable or after disabling auto-hiding. |
136 | */ |
137 | static void autoHideEventFilter( QObject *, QEvent * ); |
138 | |
139 | private: |
140 | class Private; |
141 | Private* const d; |
142 | }; |
143 | |
144 | |
145 | #endif // _KCURSOR_H |
146 | |