Libkdepim

kwidgetlister.h
1 /* -*- c++ -*-
2 
3  kwidgetlister.h
4 
5  This file is part of libkdepim
6  SPDX-FileCopyrightText: 2001 Marc Mutz <[email protected]>
7 
8  SPDX-License-Identifier: GPL-2.0-or-later
9 */
10 
11 #pragma once
12 
13 #include "kdepim_export.h"
14 #include <QWidget>
15 
16 namespace KPIM
17 {
18 /**
19  @short Widget that manages a list of other widgets (incl. 'more', 'fewer' and 'clear' buttons).
20 
21  Simple widget that nonetheless does a lot of the dirty work for
22  the filter edit widgets (KMSearchPatternEdit and
23  KMFilterActionEdit). It provides a growable and shrinkable area
24  where widget may be displayed in rows. Widgets can be added by
25  hitting the provided 'More' button, removed by the 'Fewer' button
26  and cleared (e.g. reset, if an derived class implements that and
27  removed for all but @ref mMinWidgets).
28 
29  To use this widget, derive from it with the template changed to
30  the type of widgets this class should list. Then reimplement @ref
31  addWidgetAtEnd, @ref removeLastWidget, calling the original
32  implementation as necessary. Instantiate an object of the class and
33  put it in your dialog.
34 
35  @author Marc Mutz <[email protected]>
36  @see KMSearchPatternEdit::WidgetLister KMFilterActionEdit::WidgetLister
37 
38 */
39 
40 class KDEPIM_EXPORT KWidgetLister : public QWidget
41 {
42  Q_OBJECT
43 
44 public:
45  /**
46  * Creates a new widget lister.
47  * @param fewerMoreButton Add or Not fewerMoreButton
48  * @param minWidgets The minimum number of widgets to stay on the screen.
49  * @param maxWidgets The maximum number of widgets to stay on the screen.
50  * @param parent The parent widget.
51  */
52  explicit KWidgetLister(bool fewerMoreButton, int minWidgets = 1, int maxWidgets = 8, QWidget *parent = nullptr);
53 
54  /**
55  * Destroys the widget lister.
56  */
57  ~KWidgetLister() override;
58 
59 protected Q_SLOTS:
60  /**
61  * Called whenever the user clicks on the 'more' button.
62  * Reimplementations should call this method, because this
63  * implementation does all the dirty work with adding the widgets
64  * to the layout (through @ref addWidgetAtEnd) and enabling/disabling
65  * the control buttons.
66  */
67  virtual void slotMore();
68 
69  /**
70  * Called whenever the user clicks on the 'fewer' button.
71  * Reimplementations should call this method, because this
72  * implementation does all the dirty work with removing the widgets
73  * from the layout (through @ref removeLastWidget) and
74  * enabling/disabling the control buttons.
75  */
76  virtual void slotFewer();
77 
78  /**
79  * Called whenever the user clicks on the 'clear' button.
80  * Reimplementations should call this method, because this
81  * implementation does all the dirty work with removing all but
82  * @ref mMinWidgets widgets from the layout and enabling/disabling
83  * the control buttons.
84  */
85  virtual void slotClear();
86 
87 protected:
88  /**
89  * Adds a single widget. Doesn't care if there are already @ref
90  * mMaxWidgets on screen and whether it should enable/disable any
91  * controls. It simply does what it is asked to do. You want to
92  * reimplement this method if you want to initialize the widget
93  * when showing it on screen. Make sure you call this
94  * implementation, though, since you cannot put the widget on screen
95  * from derived classes (@p mLayout is private).
96  * Make sure the parent of the QWidget to add is this KWidgetLister.
97  */
98  virtual void addWidgetAtEnd(QWidget *widget = nullptr);
99 
100  /**
101  * Removes a single (always the last) widget. Doesn't care if there
102  * are still only @ref mMinWidgets left on screen and whether it
103  * should enable/disable any controls. It simply does what it is
104  * asked to do. You want to reimplement this method if you want to
105  * save the widget's state before removing it from screen. Make
106  * sure you call this implementation, though, since you should not
107  * remove the widget from screen from derived classes.
108  */
109  virtual void removeLastWidget();
110 
111  /**
112  * Called to clear a given widget. The default implementation does
113  * nothing.
114  */
115  virtual void clearWidget(QWidget *w);
116 
117  /**
118  * Returns a new widget that shall be added to the lister.
119  *
120  * @param parent The parent widget of the new widget.
121  */
122  virtual QWidget *createWidget(QWidget *parent);
123 
124  /**
125  * Sets the number of widgets on screen to exactly @p count. Doesn't
126  * check if @p count is inside the range @p [mMinWidgets,mMaxWidgets].
127  */
128  virtual void setNumberOfShownWidgetsTo(int count);
129 
130  /**
131  * Returns the list of widgets.
132  */
133  QList<QWidget *> widgets() const;
134 
135  /**
136  * The minimum number of widgets that are to stay on screen.
137  */
138  int widgetsMinimum() const;
139 
140  /**
141  * The maximum number of widgets that are to be shown on screen.
142  */
143  int widgetsMaximum() const;
144 
145  /**
146  * Remove specific widget
147  */
148  virtual void removeWidget(QWidget *widget);
149  /**
150  * Add widget after specific widget
151  */
152  virtual void addWidgetAfterThisWidget(QWidget *currentWidget, QWidget *widget = nullptr);
153 
154 private:
155  KDEPIM_NO_EXPORT void init(bool fewerMoreButton = true);
156 
157 Q_SIGNALS:
158  /**
159  * This signal is emitted whenever a widget was added.
160  */
161  void widgetAdded();
162 
163  /**
164  * This signal is emitted whenever a widget was added.
165  *
166  * @param widget The added widget.
167  */
168  void widgetAdded(QWidget *widget);
169 
170  /**
171  * This signal is emitted whenever a widget was removed.
172  */
173  void widgetRemoved();
174 
175  /**
176  * This signal is emitted whenever a widget was removed.
177  */
178  void widgetRemoved(QWidget *widget);
179 
180  /**
181  * This signal is emitted whenever the clear button is clicked.
182  */
183  void clearWidgets();
184 
185 private:
186  //@cond PRIVATE
187  class KWidgetListerPrivate;
188  std::unique_ptr<KWidgetListerPrivate> const d;
189  //@endcond
190 };
191 }
Widget that manages a list of other widgets (incl.
Definition: kwidgetlister.h:40
Class KCheckComboBox::KCheckComboBoxPrivate.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Nov 29 2023 04:01:25 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.