1/*
2 SPDX-FileCopyrightText: 2011 John Layt <john@layt.net>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KDATETIMEEDIT_H
8#define KDATETIMEEDIT_H
9
10#include <kwidgetsaddons_export.h>
11
12#include <QLocale>
13#include <QTimeZone>
14#include <QWidget>
15#include <memory>
16
17/*!
18 * \class KDateTimeEdit
19 * \inmodule KWidgetsAddons
20 *
21 * \brief A widget for editing date and time.
22 */
23class KWIDGETSADDONS_EXPORT KDateTimeEdit : public QWidget
24{
25 Q_OBJECT
26
27 /*!
28 * \property KDateTimeEdit::date
29 */
30 Q_PROPERTY(QDate date READ date WRITE setDate NOTIFY dateChanged USER true)
31
32 /*!
33 * \property KDateTimeEdit::time
34 */
35 Q_PROPERTY(QTime time READ time WRITE setTime NOTIFY timeChanged USER true)
36
37 /*!
38 * \property KDateTimeEdit::timeListInterval
39 */
40 Q_PROPERTY(int timeListInterval READ timeListInterval WRITE setTimeListInterval)
41
42 /*!
43 * \property KDateTimeEdit::options
44 */
45 Q_PROPERTY(Options options READ options WRITE setOptions)
46
47public:
48 /*!
49 * Options provided by the widget
50 * \sa options
51 * \sa setOptions
52 * \sa Options
53 *
54 * \value ShowCalendar If the Calendar System edit is displayed
55 * \value ShowDate If the Date is displayed
56 * \value ShowTime If the Time is displayed
57 * \value ShowTimeZone If the Time Zone is displayed
58 * \value EditDate Allow the user to manually edit the date
59 * \value EditTime Allow the user to manually edit the time
60 * \value SelectCalendar Allow the user to select a calendar
61 * \value SelectDate Allow the user to select a date
62 * \value SelectTime Allow the user to select a time
63 * \value SelectTimeZone Allow the user to select a time zone
64 * \value DatePicker Show a date picker
65 * \value DateKeywords Show date keywords
66 * \value ForceTime The entered time can only be a selected time
67 * \value WarnOnInvalid Show a warning on focus out if the date or time is invalid
68 */
69 enum Option {
70 ShowCalendar = 0x00001,
71 ShowDate = 0x00002,
72 ShowTime = 0x00004,
73 ShowTimeZone = 0x00008,
74 // EditCalendar = 0x00010
75 EditDate = 0x00020,
76 EditTime = 0x00040,
77 // EditTimeZone = 0x00080
78 SelectCalendar = 0x00100,
79 SelectDate = 0x00200,
80 SelectTime = 0x00400,
81 SelectTimeZone = 0x00800,
82 DatePicker = 0x01000,
83 DateKeywords = 0x02000,
84 ForceTime = 0x04000,
85 WarnOnInvalid = 0x08000,
86 };
87 Q_DECLARE_FLAGS(Options, Option)
88 Q_FLAG(Options)
89
90 /*!
91 * Create a new KDateTimeEdit widget
92 */
93 explicit KDateTimeEdit(QWidget *parent = nullptr);
94
95 ~KDateTimeEdit() override;
96
97 /*!
98 * Return the currently set widget options
99 */
100 Options options() const;
101
102 /*!
103 * Return the currently selected date, time and time zone
104 */
105 QDateTime dateTime() const;
106
107 /*!
108 * Return the currently selected date
109 */
110 QDate date() const;
111
112 /*!
113 * Return the currently selected time
114 */
115 QTime time() const;
116
117 /*!
118 * Return the currently selected time zone
119 */
120 QTimeZone timeZone() const;
121
122 /*!
123 * Returns the list of Calendar Locales displayed.
124 */
125 QList<QLocale> calendarLocalesList() const;
126
127 /*!
128 * Return the current minimum date and time
129 */
130 QDateTime minimumDateTime() const;
131
132 /*!
133 * Return the current maximum date and time
134 */
135 QDateTime maximumDateTime() const;
136
137 /*!
138 * Return the currently set date display format
139 *
140 * By default this is the Short Format
141 */
142 QLocale::FormatType dateDisplayFormat() const;
143
144 /*!
145 * Return the map of dates listed in the drop-down and their displayed
146 * string forms.
147 *
148 * \sa setDateMap()
149 */
150 QMap<QDate, QString> dateMap() const;
151
152 /*!
153 * Return the currently set time format
154 *
155 * By default this is the Short Format
156 */
157 QLocale::FormatType timeDisplayFormat() const;
158
159 /*!
160 * Return the time list interval able to be selected
161 */
162 int timeListInterval() const;
163
164 /*!
165 * Return the list of times able to be selected in the drop-down.
166 *
167 * \sa setTimeList()
168 * \sa timeListInterval()
169 * \sa setTimeListInterval()
170 */
171 QList<QTime> timeList() const;
172
173 /*!
174 * Return the list of time zones able to be selected
175 */
176 QList<QTimeZone> timeZones() const;
177
178 /*!
179 * Return if the current user input is valid
180 *
181 * If the user input is null then it is not valid
182 *
183 * \sa isNull()
184 */
185 bool isValid() const;
186
187 /*!
188 * Return if the current user input is null
189 *
190 * \sa isValid()
191 */
192 bool isNull() const;
193
194 /*!
195 * Return if the current user input date is valid
196 *
197 * If the user input date is null then it is not valid
198 *
199 * \sa isNullDate()
200 */
201 bool isValidDate() const;
202
203 /*!
204 * Return if the current user input date is null
205 *
206 * \sa isValidDate()
207 */
208 bool isNullDate() const;
209 /*!
210 * Return if the current user input time is valid
211 *
212 * If the user input time is null then it is not valid
213 *
214 * \sa isNullTime()
215 */
216 bool isValidTime() const;
217
218 /*!
219 * Return if the current user input time is null
220 *
221 * \sa isValidTime()
222 */
223 bool isNullTime() const;
224
225Q_SIGNALS:
226
227 /*!
228 * Signal if the date or time has been manually entered by the user.
229 *
230 * The returned date and time may be invalid.
231 *
232 * \a dateTime the new date, time and time zone
233 */
234 void dateTimeEntered(const QDateTime &dateTime);
235
236 /*!
237 * Signal if the date or time has been changed either manually by the user
238 * or programmatically.
239 *
240 * The returned date and time may be invalid.
241 *
242 * \a dateTime the new date, time and time zone
243 */
244 void dateTimeChanged(const QDateTime &dateTime);
245
246 /*!
247 * Signal if the date or time is being manually edited by the user.
248 *
249 * The returned date and time may be invalid.
250 *
251 * \a dateTime the new date, time and time zone
252 */
253 void dateTimeEdited(const QDateTime &dateTime);
254
255 /*!
256 * Signal if the Calendar Locale has been manually entered by the user.
257 *
258 * \a calendarLocale the new calendar locale
259 */
260 void calendarEntered(const QLocale &calendarLocale);
261
262 /*!
263 * Signal if the Calendar Locale has been changed either manually by the user
264 * or programmatically.
265 *
266 * \a calendarLocale the new calendar locale
267 */
268 void calendarChanged(const QLocale &calendarLocale);
269
270 /*!
271 * Signal if the date has been manually entered by the user.
272 *
273 * The returned date may be invalid.
274 *
275 * \a date the new date
276 */
277 void dateEntered(const QDate &date);
278
279 /*!
280 * Signal if the date has been changed either manually by the user
281 * or programmatically.
282 *
283 * The returned date may be invalid.
284 *
285 * \a date the new date
286 */
287 void dateChanged(const QDate &date);
288
289 /*!
290 * Signal if the date is being manually edited by the user.
291 *
292 * The returned date may be invalid.
293 *
294 * \a date the new date
295 */
296 void dateEdited(const QDate &date);
297
298 /*!
299 * Signal if the time has been manually entered by the user.
300 *
301 * The returned time may be invalid.
302 *
303 * \a time the new time
304 */
305 void timeEntered(const QTime &time);
306
307 /*!
308 * Signal if the time has been changed either manually by the user
309 * or programmatically.
310 *
311 * The returned time may be invalid.
312 *
313 * \a time the new time
314 */
315 void timeChanged(const QTime &time);
316
317 /*!
318 * Signal if the time is being manually edited by the user.
319 *
320 * The returned time may be invalid.
321 *
322 * \a time the new time
323 */
324 void timeEdited(const QTime &time);
325
326 /*!
327 * Signal if the time zone has been changed manually by the user.
328 *
329 * \a zone the new time zone
330 */
331 void timeZoneEntered(const QTimeZone &zone);
332
333 /*!
334 * Signal if the time zone has been changed either manually by the user
335 * or programmatically.
336 *
337 * \a zone the new time zone
338 */
339 void timeZoneChanged(const QTimeZone &zone);
340
341public Q_SLOTS:
342
343 /*!
344 * Set the new widget options
345 *
346 * \a options the new widget options
347 */
348 void setOptions(Options options);
349
350 /*!
351 * Set the currently selected date, time and time zone
352 *
353 * \a dateTime the new date, time and time zone
354 */
355 void setDateTime(const QDateTime &dateTime);
356
357 /*!
358 * Set the currently selected date
359 *
360 * \a date the new date
361 */
362 void setDate(const QDate &date);
363
364 /*!
365 * Set the currently selected time
366 *
367 * \a time the new time
368 */
369 void setTime(const QTime &time);
370
371 /*!
372 * Set the current time zone
373 *
374 * \a zone the new zone
375 */
376 void setTimeZone(const QTimeZone &zone);
377
378 /*!
379 * Set the minimum and maximum date and time range
380 *
381 * To enable range checking provide two valid dates.
382 * To disable range checking provide two invalid dates, or call
383 * clearDateRange;
384 *
385 * \a minDateTime the minimum date and time
386 *
387 * \a maxDateTime the maximum date and time
388 *
389 * \a minWarnMsg the minimum warning message
390 *
391 * \a maxWarnMsg the maximum warning message
392 */
393 void
394 setDateTimeRange(const QDateTime &minDateTime, const QDateTime &maxDateTime, const QString &minWarnMsg = QString(), const QString &maxWarnMsg = QString());
395
396 /*!
397 * Reset the minimum and maximum date and time to the default
398 */
399 void resetDateTimeRange();
400
401 /*!
402 * Set the minimum allowed date.
403 *
404 * If the date is invalid, or more than current maximum,
405 * then the minimum will not be set.
406 *
407 * \a minDateTime the minimum date
408 *
409 * \a minWarnMsg the minimum warning message
410 *
411 * \sa setMaximumDateTime()
412 * \sa setDateRange()
413 */
414 void setMinimumDateTime(const QDateTime &minDateTime, const QString &minWarnMsg = QString());
415
416 /*!
417 * Reset the minimum date and time to the default
418 */
419 void resetMinimumDateTime();
420
421 /*!
422 * Set the maximum allowed date.
423 *
424 * If the date is invalid, or less than current minimum,
425 * then the maximum will not be set.
426 *
427 * \a maxDateTime the maximum date
428 *
429 * \a maxWarnMsg the maximum warning message
430 *
431 * \sa setMinimumDateTime()
432 * \sa setDateRange()
433 */
434 void setMaximumDateTime(const QDateTime &maxDateTime, const QString &maxWarnMsg = QString());
435
436 /*!
437 * Reset the minimum date and time to the default
438 */
439 void resetMaximumDateTime();
440
441 /*!
442 * Sets the date format to display.
443 *
444 * By default is the Short Format.
445 *
446 * \a format the date format to use
447 */
448 void setDateDisplayFormat(QLocale::FormatType format);
449
450 /*!
451 * Set the list of Calendar Locales to display.
452 *
453 * \a calendarLocales the list of calendar locales to display
454 */
455 void setCalendarLocalesList(const QList<QLocale> &calendarLocales);
456
457 /*!
458 * Set the list of dates able to be selected from the drop-down and the
459 * string form to display for those dates, e.g. "2010-01-01" and "Yesterday".
460 *
461 * Any invalid or duplicate dates will be used, the list will NOT be
462 * sorted, and the minimum and maximum date will not be affected.
463 *
464 * The \a dateMap is keyed by the date to be listed and the value is the
465 * string to be displayed. If you want the date to be displayed in the
466 * default date format then the string should be null. If you want a
467 * separator to be displayed then set the string to "separator".
468 *
469 * \a dateMap the map of dates able to be selected
470 *
471 * \sa dateMap()
472 */
473 void setDateMap(QMap<QDate, QString> dateMap);
474
475 /*!
476 * Sets the time format to display.
477 *
478 * By default is the Short Format.
479 *
480 * \a format the time format to use
481 */
482 void setTimeDisplayFormat(QLocale::FormatType format);
483
484 /*!
485 * Set the interval between times able to be selected from the drop-down.
486 *
487 * The combo drop-down will be populated with times every \a minutes
488 * apart, starting from the minimumTime() and ending at maximumTime().
489 *
490 * If the ForceInterval option is set then any time manually typed into the
491 * combo line edit will be forced to the nearest interval.
492 *
493 * This interval must be an exact divisor of the valid time range hours.
494 * For example with the default 24 hour range \a interval must divide 1440
495 * minutes exactly, meaning 1, 6 and 90 are valid but 7, 31 and 91 are not.
496 *
497 * Setting the time list interval will override any time list previously set
498 * via setTimeList().
499 *
500 * \a minutes the time list interval to display
501 *
502 * \sa timeListInterval()
503 */
504 void setTimeListInterval(int minutes);
505
506 /*!
507 * Set the list of times able to be selected from the drop-down.
508 *
509 * Setting the time list will override any time interval previously set via
510 * setTimeListInterval().
511 *
512 * Any invalid or duplicate times will be ignored, and the list will be
513 * sorted.
514 *
515 * The minimum and maximum time will automatically be set to the earliest
516 * and latest value in the list.
517 *
518 * \a timeList the list of times able to be selected
519 *
520 * \a minWarnMsg the minimum warning message
521 *
522 * \a maxWarnMsg the maximum warning message
523 *
524 * \sa timeList()
525 */
526 void setTimeList(QList<QTime> timeList, const QString &minWarnMsg = QString(), const QString &maxWarnMsg = QString());
527
528 /*!
529 * Set the time zones able to be selected
530 *
531 * \a zones the time zones to display
532 */
533 void setTimeZones(const QList<QTimeZone> &zones);
534
535protected:
536 bool eventFilter(QObject *object, QEvent *event) override;
537 void focusInEvent(QFocusEvent *event) override;
538 void focusOutEvent(QFocusEvent *event) override;
539 void resizeEvent(QResizeEvent *event) override;
540
541 /*!
542 * Assign the date, time and time zone for the widget.
543 *
544 * Virtual to allow sub-classes to apply extra validation rules,
545 * but reimplementations must call the parent method at the end.
546 *
547 * \a dateTime the new date and time
548 */
549 virtual void assignDateTime(const QDateTime &dateTime);
550
551 /*!
552 * Assign the date for the widget.
553 *
554 * Virtual to allow sub-classes to apply extra validation rules,
555 * but reimplementations must call the parent method at the end.
556 *
557 * \a date the new date
558 */
559 virtual void assignDate(const QDate &date);
560
561 /*!
562 * Assign the time for the widget.
563 *
564 * Virtual to allow sub-classes to apply extra validation rules,
565 * but reimplementations must call the parent method at the end.
566 *
567 * \a time the new time
568 */
569 virtual void assignTime(const QTime &time);
570
571 /*!
572 * Assign the time zone for the widget.
573 *
574 * Virtual to allow sub-classes to apply extra validation rules,
575 * but reimplementations must call the parent method at the end.
576 *
577 * \a zone the new time zone
578 */
579 void assignTimeZone(const QTimeZone &zone);
580
581private:
582 friend class KDateTimeEditPrivate;
583 std::unique_ptr<class KDateTimeEditPrivate> const d;
584};
585
586Q_DECLARE_OPERATORS_FOR_FLAGS(KDateTimeEdit::Options)
587
588#endif // KDATETIMEEDIT_H
589

source code of kwidgetsaddons/src/kdatetimeedit.h