1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1998 Kurt Granroth <granroth@kde.org>
4 SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <pfeiffer@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-only
7*/
8
9#ifndef KCURSOR_H
10#define KCURSOR_H
11
12#include <kwidgetsaddons_export.h>
13
14class QEvent;
15class QObject;
16class QWidget;
17
18/*!
19 * \class KCursor
20 * \inmodule KWidgetsAddons
21 *
22 * \brief The KCursor class provides a set of static
23 * convenience methods for auto-hiding cursors on widgets.
24 */
25class KWIDGETSADDONS_EXPORT KCursor
26{
27public:
28 /*!
29 * Sets auto-hiding the cursor for widget \a w. Enabling it will result in
30 * the cursor being hidden when
31 * \list
32 * \li a key-event happens
33 * \li there are no key-events for a configured time-frame (see
34 * setHideCursorDelay())
35 * \endlist
36 *
37 * The cursor will be shown again when the focus is lost or a mouse-event
38 * happens.
39 *
40 * Side effect: when enabling auto-hide, mouseTracking is enabled for the
41 * specified widget, because it's needed to get mouse-move-events. So
42 * don't disable mouseTracking for a widget while using auto-hide for it.
43 *
44 * When disabling auto-hide, mouseTracking will be disabled, so if you need
45 * mouseTracking after disabling auto-hide, you have to re-enable
46 * mouseTracking.
47 *
48 * If you want to use auto-hiding for widgets that don't take focus, e.g.
49 * a QCanvasView, then you have to pass all key-events that should trigger
50 * auto-hiding to autoHideEventFilter().
51 */
52 static void setAutoHideCursor(QWidget *w, bool enable, bool customEventFilter = false);
53
54 /*!
55 * Sets the delay time in milliseconds for auto-hiding. When no keyboard
56 * events arrive for that time-frame, the cursor will be hidden.
57 *
58 * Default is 5000, i.e. 5 seconds.
59 */
60 static void setHideCursorDelay(int ms);
61
62 /*!
63 * Returns the current auto-hide delay time.
64 *
65 * Default is 5000, i.e. 5 seconds.
66 */
67 static int hideCursorDelay();
68
69 /*!
70 * KCursor has to install an eventFilter over the widget you want to
71 * auto-hide. If you have an own eventFilter() on that widget and stop
72 * some events by returning true, you might break auto-hiding, because
73 * KCursor doesn't get those events.
74 *
75 * In this case, you need to call setAutoHideCursor( widget, true, true );
76 * to tell KCursor not to install an eventFilter. Then you call this method
77 * from the beginning of your eventFilter, for example:
78 * \code
79 * edit = new KEdit( this, "some edit widget" );
80 * edit->installEventFilter( this );
81 * KCursor::setAutoHideCursor( edit, true, true );
82 *
83 * [...]
84 *
85 * bool YourClass::eventFilter( QObject *o, QEvent *e )
86 * {
87 * if ( o == edit ) // only that widget where you enabled auto-hide!
88 * KCursor::autoHideEventFilter( o, e );
89 *
90 * // now you can do your own event-processing
91 * [...]
92 * }
93 * \endcode
94 *
95 * Note that you must not call KCursor::autoHideEventFilter() when you
96 * didn't enable or after disabling auto-hiding.
97 */
98 static void autoHideEventFilter(QObject *, QEvent *);
99
100private:
101 KCursor() = delete;
102};
103
104#endif // _KCURSOR_H
105

source code of kwidgetsaddons/src/kcursor.h