libyui
3.0.10
|
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