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