1/*
2 SPDX-FileCopyrightText: 2011 John Layt <john@layt.net>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KDATECOMBOBOX_H
8#define KDATECOMBOBOX_H
9
10#include <kwidgetsaddons_export.h>
11
12#include <QComboBox>
13#include <QLocale>
14#include <memory>
15
16/*!
17 * \class KDateComboBox
18 * \inmodule KWidgetsAddons
19 *
20 * \brief A combobox for dates.
21 */
22class KWIDGETSADDONS_EXPORT KDateComboBox : public QComboBox
23{
24 Q_OBJECT
25
26 /*!
27 * \property KDateComboBox::date
28 */
29 Q_PROPERTY(QDate date READ date WRITE setDate NOTIFY dateChanged USER true)
30
31 /*!
32 * \property KDateComboBox::minimumDate
33 */
34 Q_PROPERTY(QDate minimumDate READ minimumDate WRITE setMinimumDate RESET resetMinimumDate)
35
36 /*!
37 * \property KDateComboBox::maximumDate
38 */
39 Q_PROPERTY(QDate maximumDate READ maximumDate WRITE setMaximumDate RESET resetMaximumDate)
40
41 /*!
42 * \property KDateComboBox::options
43 */
44 Q_PROPERTY(Options options READ options WRITE setOptions)
45
46public:
47 /*!
48 * Options provided by the widget
49 * \sa options()
50 * \sa setOptions()
51 *
52 * \value EditDate Allow the user to manually edit the date in the combo line edit
53 * \value SelectDate Allow the user to select the date from a drop-down menu
54 * \value DatePicker Show a date picker in the drop-down
55 * \value DateKeywords Show date keywords in the drop-down
56 * \value WarnOnInvalid Show a warning on focus out if the date is invalid
57 */
58 enum Option {
59 EditDate = 0x0001,
60 SelectDate = 0x0002,
61 DatePicker = 0x0004,
62 DateKeywords = 0x0008,
63 WarnOnInvalid = 0x0010,
64 };
65 Q_DECLARE_FLAGS(Options, Option)
66 Q_FLAG(Options)
67
68 /*!
69 * Create a new KDateComboBox widget
70 *
71 * By default the EditDate, SelectDate, DatePicker and DateKeywords options
72 * are enabled, the ShortDate format is used and the date is set to the
73 * current date.
74 */
75 explicit KDateComboBox(QWidget *parent = nullptr);
76
77 ~KDateComboBox() override;
78
79 /*!
80 * Return the currently selected date
81 */
82 QDate date() const;
83
84 /*!
85 * Return if the current user input is valid
86 *
87 * If the user input is null then it is not valid
88 *
89 * \sa isNull()
90 */
91 bool isValid() const;
92
93 /*!
94 * Return if the current user input is null
95 *
96 * \sa isValid()
97 */
98 bool isNull() const;
99
100 /*!
101 * Return the currently set widget options
102 */
103 Options options() const;
104
105 /*!
106 * Return the currently set date display format
107 *
108 * By default this is the Short Format
109 */
110 QLocale::FormatType displayFormat() const;
111
112 /*!
113 * Return the current minimum date
114 */
115 QDate minimumDate() const;
116
117 /*!
118 * Return the current maximum date
119 */
120 QDate maximumDate() const;
121
122 /*!
123 * Return the map of dates listed in the drop-down and their displayed
124 * string forms.
125 *
126 * \sa setDateMap()
127 */
128 QMap<QDate, QString> dateMap() const;
129
130Q_SIGNALS:
131
132 /*!
133 * Signal if the date has been manually entered (by typing a date and losing focus, or pressing Enter)
134 * or selected by the user (using the popup selector, or up, down, page up, page down keys, or the mouse wheel).
135 *
136 * The emitted date may be invalid.
137 *
138 * \a date the new date
139 */
140 void dateEntered(const QDate &date);
141
142 /*!
143 * Signal if the date has been changed either manually by the user
144 * or programmatically.
145 *
146 * The emitted date may be invalid.
147 *
148 * \a date the new date
149 */
150 void dateChanged(const QDate &date);
151
152 /*!
153 * Signal if the date is being manually edited by the user.
154 *
155 * The emitted date may be invalid, or may not yet be what the user intends as the final date.
156 *
157 * \a date the new date
158 */
159 void dateEdited(const QDate &date);
160
161public Q_SLOTS:
162
163 /*!
164 * Set the currently selected date
165 *
166 * You can set an invalid date or a date outside the valid range, validity
167 * checking is only done via isValid().
168 *
169 * \a date the new date
170 */
171 void setDate(const QDate &date);
172
173 /*!
174 * Set the new widget options
175 *
176 * \a options the new widget options
177 */
178 void setOptions(Options options);
179
180 /*!
181 * Sets the date format to display.
182 *
183 * By default is the Short Format.
184 *
185 * \a format the date format to use
186 */
187 void setDisplayFormat(QLocale::FormatType format);
188
189 /*!
190 * Set the valid date range to be applied by isValid().
191 *
192 * Both dates must be valid and the minimum date must be less than or equal
193 * to the maximum date, otherwise the date range will not be set.
194 *
195 * \a minDate the minimum date
196 *
197 * \a maxDate the maximum date
198 *
199 * \a minWarnMsg the minimum warning message
200 *
201 * \a maxWarnMsg the maximum warning message
202 */
203 void setDateRange(const QDate &minDate, const QDate &maxDate, const QString &minWarnMsg = QString(), const QString &maxWarnMsg = QString());
204
205 /*!
206 * Reset the minimum and maximum date to the default values.
207 * \sa setDateRange()
208 */
209 void resetDateRange();
210
211 /*!
212 * Set the minimum allowed date.
213 *
214 * If the date is invalid, or greater than current maximum,
215 * then the minimum will not be set.
216 *
217 * \a minDate the minimum date
218 *
219 * \a minWarnMsg the minimum warning message
220 *
221 * \sa minimumDate()
222 * \sa maximumDate()
223 * \sa setMaximumDate()
224 * \sa setDateRange()
225 */
226 void setMinimumDate(const QDate &minDate, const QString &minWarnMsg = QString());
227
228 /*!
229 * Reset the minimum date to the default.
230 *
231 * The default is to have no minimum date.
232 */
233 void resetMinimumDate();
234
235 /*!
236 * Set the maximum allowed date.
237 *
238 * If the date is invalid, or less than current minimum,
239 * then the maximum will not be set.
240 *
241 * \a maxDate the maximum date
242 *
243 * \a maxWarnMsg the maximum warning message
244 *
245 * \sa minimumDate()
246 * \sa maximumDate()
247 * \sa setMaximumDate()
248 * \sa setDateRange()
249 */
250 void setMaximumDate(const QDate &maxDate, const QString &maxWarnMsg = QString());
251
252 /*!
253 * Reset the maximum date to the default
254 *
255 * The default is to have no maximum date.
256 */
257 void resetMaximumDate();
258
259 /*!
260 * Set the list of dates able to be selected from the drop-down and the
261 * string form to display for those dates, e.g. "2010-01-01" and "Yesterday".
262 *
263 * Any invalid or duplicate dates will be used, the list will NOT be
264 * sorted, and the minimum and maximum date will not be affected.
265 *
266 * The \a dateMap is keyed by the date to be listed and the value is the
267 * string to be displayed. If you want the date to be displayed in the
268 * default date format then the string should be null. If you want a
269 * separator to be displayed then set the string to "separator".
270 *
271 * \a dateMap the map of dates able to be selected
272 *
273 * \sa dateMap()
274 */
275 void setDateMap(QMap<QDate, QString> dateMap);
276
277protected:
278 bool eventFilter(QObject *object, QEvent *event) override;
279 void showPopup() override;
280 void hidePopup() override;
281 void mousePressEvent(QMouseEvent *event) override;
282 void wheelEvent(QWheelEvent *event) override;
283 void keyPressEvent(QKeyEvent *event) override;
284 void focusInEvent(QFocusEvent *event) override;
285 void focusOutEvent(QFocusEvent *event) override;
286 void resizeEvent(QResizeEvent *event) override;
287
288 /*!
289 * Assign the date for the widget.
290 *
291 * Virtual to allow sub-classes to apply extra validation rules.
292 *
293 * \a date the new date
294 */
295 virtual void assignDate(const QDate &date);
296
297private:
298 friend class KDateComboBoxPrivate;
299 std::unique_ptr<class KDateComboBoxPrivate> const d;
300};
301
302Q_DECLARE_OPERATORS_FOR_FLAGS(KDateComboBox::Options)
303
304#endif // KDATECOMBOBOX_H
305

source code of kwidgetsaddons/src/kdatecombobox.h