Libkdepim

kwidgetlister.h
1/* -*- c++ -*-
2
3 kwidgetlister.h
4
5 This file is part of libkdepim
6 SPDX-FileCopyrightText: 2001 Marc Mutz <mutz@kde.org>
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
16namespace 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 <Marc@Mutz.com>
36 @see KMSearchPatternEdit::WidgetLister KMFilterActionEdit::WidgetLister
37
38*/
39
40class KDEPIM_EXPORT KWidgetLister : public QWidget
41{
42 Q_OBJECT
43
44public:
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
59protected 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
87protected:
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
154private:
155 KDEPIM_NO_EXPORT void init(bool fewerMoreButton = true);
156
157Q_SIGNALS:
158 /**
159 * This signal is emitted whenever a widget was added.
160 */
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 */
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 */
184
185private:
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.
void widgetAdded(QWidget *widget)
This signal is emitted whenever a widget was added.
void widgetAdded()
This signal is emitted whenever a widget was added.
void widgetRemoved()
This signal is emitted whenever a widget was removed.
void widgetRemoved(QWidget *widget)
This signal is emitted whenever a widget was removed.
~KWidgetLister() override
Destroys the widget lister.
void clearWidgets()
This signal is emitted whenever the clear button is clicked.
Class KCheckComboBox::KCheckComboBoxPrivate.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 12:03:55 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.