KWidgetsAddons

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

KDE's Doxygen guidelines are available online.