libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YEventFilter.h
00001 /*
00002   Copyright (C) 2000-2012 Novell, Inc
00003   This library is free software; you can redistribute it and/or modify
00004   it under the terms of the GNU Lesser General Public License as
00005   published by the Free Software Foundation; either version 2.1 of the
00006   License, or (at your option) version 3.0 of the License. This library
00007   is distributed in the hope that it will be useful, but WITHOUT ANY
00008   WARRANTY; without even the implied warranty of MERCHANTABILITY or 
00009   FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
00010   License for more details. You should have received a copy of the GNU
00011   Lesser General Public License along with this library; if not, write
00012   to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
00013   Floor, Boston, MA 02110-1301 USA
00014 */
00015 
00016 
00017 /*-/
00018 
00019   File:         YEventFilter.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YEventFilter_h
00026 #define YEventFilter_h
00027 
00028 
00029 #include "ImplPtr.h"
00030 
00031 
00032 class YEvent;
00033 class YDialog;
00034 
00035 class YEventFilterPrivate;
00036 
00037 
00038 /**
00039  * Abstract base class to filter events.
00040  *
00041  * This class can be used to examine events just before they are delivered to
00042  * the application. This is most useful for higher-level widgets or for
00043  * libraries that need to react to certain events and either consume them, have
00044  * them delivered unchanged to the application, or exchange an event with
00045  * another one.
00046  *
00047  * A YEventFilter belongs to one specific dialog. Each dialog can have any
00048  * number of event filters. Each of those event filters is called (its
00049  * YEventFilter::filter() method) for each event inside
00050  * YDialog::waitForEvent(). The order in which event filters are called is
00051  * undefined.
00052  *
00053  * YEventFilter objects should be created with 'new' (on the heap). Since an
00054  * YEventFilter registers itself with its dialog, the dialog will delete it in
00055  * its destructor if it still exists after all child widgets are deleted.
00056  *
00057  * Thus, it is safe to store a pointer to an YEventFilter until the
00058  * corresponding dialog is deleted. After that, the pointer becomes invalid.
00059  *
00060  * See YHelpButtonHandler in YDialog.cc for an example.
00061  **/
00062 class YEventFilter
00063 {
00064 protected:
00065     /**
00066      * Constructor.
00067      *
00068      * This registers the event filter with the specified dialog. The dialog
00069      * assumes ownership of this object and will delete it in its destructor
00070      * (unless this object is destroyed before that time).
00071      *
00072      * If 'dialog' is 0, YDialog::currentDialog() is used (which can throw a
00073      * YUINoDialogException if there is no dialog).
00074      **/
00075     YEventFilter( YDialog * dialog = 0 );
00076 
00077 public:
00078     /**
00079      * Destructor.
00080      *
00081      * This will unregister this object with its dialog.
00082      **/
00083     virtual ~YEventFilter();
00084 
00085     /**
00086      * The heart of the matter: The event filter function.
00087      * Derived classes are required to implement this.
00088      *
00089      * This method can inspect the event it receives.  Hint: event->widget()
00090      * is typically the most interesting information.
00091      *
00092      * This method can react on individual events and
00093      *
00094      *   - consume the event (i.e., return 0)
00095      *   - pass the event through unchanged (simply return the event)
00096      *   - create a new event (typically based on data in the received event).
00097      *
00098      * If 0 or a new event (another value than 'event') is returned, the old
00099      * event is deleted. If a value different from 'event' or 0 is returned,
00100      * that value is assumed to be a pointer to a newly created event. The
00101      * dialog will assume ownership of that event and delete it when
00102      * appropriate.
00103      *
00104      * Note: Never delete 'event' in this method! Return 0 or a new event
00105      * instead; the caller will take care of deleting the old event.
00106      **/
00107     virtual YEvent * filter( YEvent * event ) = 0;
00108 
00109     /**
00110      * Return the dialog this event filter belongs to.
00111      **/
00112     YDialog * dialog() const;
00113 
00114 private:
00115 
00116     ImplPtr<YEventFilterPrivate> priv;
00117 };
00118 
00119 
00120 #endif // YEventFilter_h
 All Classes Functions Variables Enumerations Friends