File indexing completed on 2024-05-12 05:09:48
0001 /* -*- c++ -*- 0002 0003 kwidgetlister.h 0004 0005 This file is part of libkdepim 0006 Copyright (c) 2001 Marc Mutz <mutz@kde.org> 0007 0008 This library is free software; you can redistribute it and/or 0009 modify it under the terms of the GNU General Public License, 0010 version 2, as published by the Free Software Foundation. 0011 0012 This library is distributed in the hope that it will be useful, 0013 but WITHOUT ANY WARRANTY; without even the implied warranty of 0014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0015 General Public License for more details. 0016 0017 You should have received a copy of the GNU General Public License 0018 along with this library; if not, write to the Free Software 0019 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 0020 0021 In addition, as a special exception, the copyright holders give 0022 permission to link the code of this library with any edition of 0023 the Qt library by Trolltech AS, Norway (or with modified versions 0024 of Qt that use the same license as Qt), and distribute linked 0025 combinations including the two. You must obey the GNU General 0026 Public License in all respects for all of the code used other than 0027 Qt. If you modify this file, you may extend this exception to 0028 your version of the file, but you are not obligated to do so. If 0029 you do not wish to do so, delete this exception statement from 0030 your version. 0031 */ 0032 0033 #ifndef KDEPIM_KWIDGETLISTER_H 0034 #define KDEPIM_KWIDGETLISTER_H 0035 0036 #include <QWidget> 0037 0038 class QPushButton; 0039 class QVBoxLayout; 0040 0041 /** 0042 @short Widget that manages a list of other widgets (incl. 'more', 'fewer' and 'clear' buttons). 0043 0044 Simple widget that nonetheless does a lot of the dirty work for 0045 the filter edit widgets (KMSearchPatternEdit and 0046 KMFilterActionEdit). It provides a growable and shrinkable area 0047 where widget may be displayed in rows. Widgets can be added by 0048 hitting the provided 'More' button, removed by the 'Fewer' button 0049 and cleared (e.g. reset, if an derived class implements that and 0050 removed for all but @ref mMinWidgets). 0051 0052 To use this widget, derive from it with the template changed to 0053 the type of widgets this class should list. Then reimplement @ref 0054 addWidgetAtEnd, @ref removeLastWidget, calling the original 0055 implementation as necessary. Instantiate an object of the class and 0056 put it in your dialog. 0057 0058 @author Marc Mutz <Marc@Mutz.com> 0059 @see KMSearchPatternEdit::WidgetLister KMFilterActionEdit::WidgetLister 0060 0061 */ 0062 0063 class KWidgetLister : public QWidget 0064 { 0065 Q_OBJECT 0066 public: 0067 explicit KWidgetLister( int minWidgets=1, int maxWidgets=8, 0068 QWidget *parent=nullptr, const char *name=nullptr ); 0069 virtual ~KWidgetLister(); 0070 0071 protected Q_SLOTS: 0072 /** Called whenever the user clicks on the 'more' button. 0073 Reimplementations should call this method, because this 0074 implementation does all the dirty work with adding the widgets 0075 to the layout (through @ref addWidgetAtEnd) and enabling/disabling 0076 the control buttons. */ 0077 virtual void slotMore(); 0078 0079 /** Called whenever the user clicks on the 'fewer' button. 0080 Reimplementations should call this method, because this 0081 implementation does all the dirty work with removing the widgets 0082 from the layout (through @ref removeLastWidget) and 0083 enabling/disabling the control buttons. */ 0084 virtual void slotFewer(); 0085 0086 /** Called whenever the user clicks on the 'clear' button. 0087 Reimplementations should call this method, because this 0088 implementation does all the dirty work with removing all but 0089 @ref mMinWidgets widgets from the layout and enabling/disabling 0090 the control buttons. */ 0091 virtual void slotClear(); 0092 0093 protected: 0094 /** Adds a single widget. Doesn't care if there are already @ref 0095 mMaxWidgets on screen and whether it should enable/disable any 0096 controls. It simply does what it is asked to do. You want to 0097 reimplement this method if you want to initialize the widget 0098 when showing it on screen. Make sure you call this 0099 implementaion, though, since you cannot put the widget on screen 0100 from derived classes (@p mLayout is private). 0101 Make sure the parent of the QWidget to add is this KWidgetLister. */ 0102 virtual void addWidgetAtEnd( QWidget *w=nullptr ); 0103 0104 /** Removes a single (always the last) widget. Doesn't care if there 0105 are still only @ref mMinWidgets left on screen and whether it 0106 should enable/disable any controls. It simply does what it is 0107 asked to do. You want to reimplement this method if you want to 0108 save the widget's state before removing it from screen. Make 0109 sure you call this implementaion, though, since you should not 0110 remove the widget from screen from derived classes. */ 0111 virtual void removeLastWidget(); 0112 0113 /** Called to clear a given widget. The default implementation does 0114 nothing. */ 0115 virtual void clearWidget( QWidget *w ); 0116 0117 /** Because QT does not support signals/slots in template 0118 classes, we are forced to emulate this by forcing the 0119 implementers of subclasses of KWidgetLister to reimplement this 0120 function which replaces the "@p new @p T" call. */ 0121 virtual QWidget *createWidget( QWidget *parent ); 0122 0123 /** Sets the number of widgets on scrren to exactly @p aNum. Doesn't 0124 check if @p aNum is inside the range @p 0125 [mMinWidgets,mMaxWidgets]. */ 0126 virtual void setNumberOfShownWidgetsTo( int aNum ); 0127 0128 /** The list of widgets. Note that this list is set to auto-delete, 0129 meaning that widgets that are removed from the screen by either 0130 @ref slotFewer or @ref slotClear will be destroyed! */ 0131 QList<QWidget*> mWidgetList; 0132 0133 /** The minimum number of widgets that are to stay on screen. */ 0134 int mMinWidgets; 0135 0136 /** The maximum number of widgets that are to be shown on screen. */ 0137 int mMaxWidgets; 0138 0139 Q_SIGNALS: 0140 /** This signal is emitted whenever a widget was added */ 0141 void widgetAdded(QWidget *); 0142 /** This signal is emitted whenever a widget was removed */ 0143 void widgetRemoved(); 0144 /** This signal is emitted whenever the clear button is clicked */ 0145 void clearWidgets(); 0146 0147 private: 0148 void enableControls(); 0149 0150 QPushButton *mBtnMore, *mBtnFewer, *mBtnClear; 0151 QVBoxLayout *mLayout; 0152 QWidget *mButtonBox; 0153 }; 0154 0155 #endif /* _KWIDGETLISTER_H_ */