File indexing completed on 2024-06-23 05:16:27
0001 /* -*- c++ -*- 0002 0003 kwidgetlister.h 0004 0005 This file is part of libkdepim 0006 SPDX-FileCopyrightText: 2001 Marc Mutz <mutz@kde.org> 0007 0008 SPDX-License-Identifier: GPL-2.0-or-later 0009 */ 0010 0011 #pragma once 0012 0013 #include "kdepim_export.h" 0014 #include <QWidget> 0015 0016 namespace KPIM 0017 { 0018 /** 0019 @short Widget that manages a list of other widgets (incl. 'more', 'fewer' and 'clear' buttons). 0020 0021 Simple widget that nonetheless does a lot of the dirty work for 0022 the filter edit widgets (KMSearchPatternEdit and 0023 KMFilterActionEdit). It provides a growable and shrinkable area 0024 where widget may be displayed in rows. Widgets can be added by 0025 hitting the provided 'More' button, removed by the 'Fewer' button 0026 and cleared (e.g. reset, if an derived class implements that and 0027 removed for all but @ref mMinWidgets). 0028 0029 To use this widget, derive from it with the template changed to 0030 the type of widgets this class should list. Then reimplement @ref 0031 addWidgetAtEnd, @ref removeLastWidget, calling the original 0032 implementation as necessary. Instantiate an object of the class and 0033 put it in your dialog. 0034 0035 @author Marc Mutz <Marc@Mutz.com> 0036 @see KMSearchPatternEdit::WidgetLister KMFilterActionEdit::WidgetLister 0037 0038 */ 0039 0040 class KDEPIM_EXPORT KWidgetLister : public QWidget 0041 { 0042 Q_OBJECT 0043 0044 public: 0045 /** 0046 * Creates a new widget lister. 0047 * @param fewerMoreButton Add or Not fewerMoreButton 0048 * @param minWidgets The minimum number of widgets to stay on the screen. 0049 * @param maxWidgets The maximum number of widgets to stay on the screen. 0050 * @param parent The parent widget. 0051 */ 0052 explicit KWidgetLister(bool fewerMoreButton, int minWidgets = 1, int maxWidgets = 8, QWidget *parent = nullptr); 0053 0054 /** 0055 * Destroys the widget lister. 0056 */ 0057 ~KWidgetLister() override; 0058 0059 protected Q_SLOTS: 0060 /** 0061 * Called whenever the user clicks on the 'more' button. 0062 * Reimplementations should call this method, because this 0063 * implementation does all the dirty work with adding the widgets 0064 * to the layout (through @ref addWidgetAtEnd) and enabling/disabling 0065 * the control buttons. 0066 */ 0067 virtual void slotMore(); 0068 0069 /** 0070 * Called whenever the user clicks on the 'fewer' button. 0071 * Reimplementations should call this method, because this 0072 * implementation does all the dirty work with removing the widgets 0073 * from the layout (through @ref removeLastWidget) and 0074 * enabling/disabling the control buttons. 0075 */ 0076 virtual void slotFewer(); 0077 0078 /** 0079 * Called whenever the user clicks on the 'clear' button. 0080 * Reimplementations should call this method, because this 0081 * implementation does all the dirty work with removing all but 0082 * @ref mMinWidgets widgets from the layout and enabling/disabling 0083 * the control buttons. 0084 */ 0085 virtual void slotClear(); 0086 0087 protected: 0088 /** 0089 * Adds a single widget. Doesn't care if there are already @ref 0090 * mMaxWidgets on screen and whether it should enable/disable any 0091 * controls. It simply does what it is asked to do. You want to 0092 * reimplement this method if you want to initialize the widget 0093 * when showing it on screen. Make sure you call this 0094 * implementation, though, since you cannot put the widget on screen 0095 * from derived classes (@p mLayout is private). 0096 * Make sure the parent of the QWidget to add is this KWidgetLister. 0097 */ 0098 virtual void addWidgetAtEnd(QWidget *widget = nullptr); 0099 0100 /** 0101 * Removes a single (always the last) widget. Doesn't care if there 0102 * are still only @ref mMinWidgets left on screen and whether it 0103 * should enable/disable any controls. It simply does what it is 0104 * asked to do. You want to reimplement this method if you want to 0105 * save the widget's state before removing it from screen. Make 0106 * sure you call this implementation, though, since you should not 0107 * remove the widget from screen from derived classes. 0108 */ 0109 virtual void removeLastWidget(); 0110 0111 /** 0112 * Called to clear a given widget. The default implementation does 0113 * nothing. 0114 */ 0115 virtual void clearWidget(QWidget *w); 0116 0117 /** 0118 * Returns a new widget that shall be added to the lister. 0119 * 0120 * @param parent The parent widget of the new widget. 0121 */ 0122 virtual QWidget *createWidget(QWidget *parent); 0123 0124 /** 0125 * Sets the number of widgets on screen to exactly @p count. Doesn't 0126 * check if @p count is inside the range @p [mMinWidgets,mMaxWidgets]. 0127 */ 0128 virtual void setNumberOfShownWidgetsTo(int count); 0129 0130 /** 0131 * Returns the list of widgets. 0132 */ 0133 QList<QWidget *> widgets() const; 0134 0135 /** 0136 * The minimum number of widgets that are to stay on screen. 0137 */ 0138 int widgetsMinimum() const; 0139 0140 /** 0141 * The maximum number of widgets that are to be shown on screen. 0142 */ 0143 int widgetsMaximum() const; 0144 0145 /** 0146 * Remove specific widget 0147 */ 0148 virtual void removeWidget(QWidget *widget); 0149 /** 0150 * Add widget after specific widget 0151 */ 0152 virtual void addWidgetAfterThisWidget(QWidget *currentWidget, QWidget *widget = nullptr); 0153 0154 private: 0155 KDEPIM_NO_EXPORT void init(bool fewerMoreButton = true); 0156 0157 Q_SIGNALS: 0158 /** 0159 * This signal is emitted whenever a widget was added. 0160 */ 0161 void widgetAdded(); 0162 0163 /** 0164 * This signal is emitted whenever a widget was added. 0165 * 0166 * @param widget The added widget. 0167 */ 0168 void widgetAdded(QWidget *widget); 0169 0170 /** 0171 * This signal is emitted whenever a widget was removed. 0172 */ 0173 void widgetRemoved(); 0174 0175 /** 0176 * This signal is emitted whenever a widget was removed. 0177 */ 0178 void widgetRemoved(QWidget *widget); 0179 0180 /** 0181 * This signal is emitted whenever the clear button is clicked. 0182 */ 0183 void clearWidgets(); 0184 0185 private: 0186 //@cond PRIVATE 0187 class KWidgetListerPrivate; 0188 std::unique_ptr<KWidgetListerPrivate> const d; 0189 //@endcond 0190 }; 0191 }