1/**
2 * Copyright 2009, 2010 Michael Leupold <lemma@confuego.org>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) version 3, or any
8 * later version accepted by the membership of KDE e.V. (or its
9 * successor approved by the membership of KDE e.V.), which shall
10 * act as a proxy defined in Section 6 of version 3 of the license.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library. If not, see <http://www.gnu.org/licenses/>
19 */
20
21#ifndef KSYSTEMEVENTFILTER_H
22#define KSYSTEMEVENTFILTER_H
23
24#include <kdeui_export.h>
25
26class QWidget;
27
28/**
29 * Members of this namespace allow installing and removing global event-filters
30 * that will catch all window system events the application receives.
31 *
32 * @author Michael Leupold <lemma@confuego.org>
33 */
34namespace KSystemEventFilter
35{
36 /**
37 * Installs a widget filter as a global X11 event filter.
38 *
39 * The widget filter receives all events in its standard x11Event(), winEvent(),
40 * qwsEvent() and macEvent() event handler functions. When the filter widget is
41 * destroyed, it is automatically removed from the list of known filters. Each filter
42 * widget can be added (and will be called) only once.
43 * The function doesn't transfer the widget filter's ownership, so the code installing
44 * the event filter is responsible for freeing it if it's no longer needed.
45 *
46 * @param filter the filter widget to install
47 *
48 * @remarks The order in which installed event filters are called is arbitrary.
49 * Processing the events will stop as soon as a filter "consumes" an
50 * event (ie. the *Event() method returns true).
51 * Also note that the result parameter of the widget filter'
52 * winEvent() method will be discarded.
53 *
54 * @warning Only do this when absolutely necessary. An installed event filter
55 * can slow things down.
56 */
57 void KDEUI_EXPORT installEventFilter(QWidget *filter);
58
59 /**
60 * Removes a global widget filter.
61 */
62 void KDEUI_EXPORT removeEventFilter(const QWidget *filter);
63}
64
65#endif
66