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
26class QEvent;
27class 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 */
36class KDEUI_EXPORT KCursor : public QCursor
37{
38public:
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
139private:
140 class Private;
141 Private* const d;
142};
143
144
145#endif // _KCURSOR_H
146