libyui  3.3.1
YEventFilter.h
1 /*
2  Copyright (C) 2000-2012 Novell, Inc
3  This library is free software; you can redistribute it and/or modify
4  it under the terms of the GNU Lesser General Public License as
5  published by the Free Software Foundation; either version 2.1 of the
6  License, or (at your option) version 3.0 of the License. This library
7  is distributed in the hope that it will be useful, but WITHOUT ANY
8  WARRANTY; without even the implied warranty of MERCHANTABILITY or
9  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
10  License for more details. You should have received a copy of the GNU
11  Lesser General Public License along with this library; if not, write
12  to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
13  Floor, Boston, MA 02110-1301 USA
14 */
15 
16 
17 /*-/
18 
19  File: YEventFilter.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YEventFilter_h
26 #define YEventFilter_h
27 
28 
29 #include "ImplPtr.h"
30 
31 
32 class YEvent;
33 class YDialog;
34 
36 
37 
38 /**
39  * Abstract base class to filter events.
40  *
41  * This class can be used to examine events just before they are delivered to
42  * the application. This is most useful for higher-level widgets or for
43  * libraries that need to react to certain events and either consume them, have
44  * them delivered unchanged to the application, or exchange an event with
45  * another one.
46  *
47  * A YEventFilter belongs to one specific dialog. Each dialog can have any
48  * number of event filters. Each of those event filters is called (its
49  * YEventFilter::filter() method) for each event inside
50  * YDialog::waitForEvent(). The order in which event filters are called is
51  * undefined.
52  *
53  * YEventFilter objects should be created with 'new' (on the heap). Since an
54  * YEventFilter registers itself with its dialog, the dialog will delete it in
55  * its destructor if it still exists after all child widgets are deleted.
56  *
57  * Thus, it is safe to store a pointer to an YEventFilter until the
58  * corresponding dialog is deleted. After that, the pointer becomes invalid.
59  *
60  * See YHelpButtonHandler in YDialog.cc for an example.
61  **/
63 {
64 protected:
65  /**
66  * Constructor.
67  *
68  * This registers the event filter with the specified dialog. The dialog
69  * assumes ownership of this object and will delete it in its destructor
70  * (unless this object is destroyed before that time).
71  *
72  * If 'dialog' is 0, YDialog::currentDialog() is used (which can throw a
73  * YUINoDialogException if there is no dialog).
74  **/
75  YEventFilter( YDialog * dialog = 0 );
76 
77 public:
78  /**
79  * Destructor.
80  *
81  * This will unregister this object with its dialog.
82  **/
83  virtual ~YEventFilter();
84 
85  /**
86  * The heart of the matter: The event filter function.
87  * Derived classes are required to implement this.
88  *
89  * This method can inspect the event it receives. Hint: event->widget()
90  * is typically the most interesting information.
91  *
92  * This method can react on individual events and
93  *
94  * - consume the event (i.e., return 0)
95  * - pass the event through unchanged (simply return the event)
96  * - create a new event (typically based on data in the received event).
97  *
98  * If 0 or a new event (another value than 'event') is returned, the old
99  * event is deleted. If a value different from 'event' or 0 is returned,
100  * that value is assumed to be a pointer to a newly created event. The
101  * dialog will assume ownership of that event and delete it when
102  * appropriate.
103  *
104  * Note: Never delete 'event' in this method! Return 0 or a new event
105  * instead; the caller will take care of deleting the old event.
106  **/
107  virtual YEvent * filter( YEvent * event ) = 0;
108 
109  /**
110  * Return the dialog this event filter belongs to.
111  **/
112  YDialog * dialog() const;
113 
114 private:
115 
117 };
118 
119 
120 #endif // YEventFilter_h
virtual ~YEventFilter()
Destructor.
Definition: YEventFilter.cc:56
YEventFilter(YDialog *dialog=0)
Constructor.
Definition: YEventFilter.cc:44
Abstract base class to filter events.
Definition: YEventFilter.h:62
Abstract base class for events to be returned upon UI::UserInput() and related functions.
Definition: YEvent.h:43
YDialog * dialog() const
Return the dialog this event filter belongs to.
Definition: YEventFilter.cc:63
virtual YEvent * filter(YEvent *event)=0
The heart of the matter: The event filter function.
A window in the desktop environment.
Definition: YDialog.h:47