File indexing completed on 2025-02-16 13:11:41
0001 /* 0002 SPDX-FileCopyrightText: 2011 John Layt <john@layt.net> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef KDATETIMEEDIT_H 0008 #define KDATETIMEEDIT_H 0009 0010 #include <kwidgetsaddons_export.h> 0011 0012 #include <QLocale> 0013 #include <QTimeZone> 0014 #include <QWidget> 0015 #include <memory> 0016 0017 /** 0018 * @class KDateTimeEdit kdatetimeedit.h KDateTimeEdit 0019 * 0020 * @short A widget for editing date and time. 0021 */ 0022 class KWIDGETSADDONS_EXPORT KDateTimeEdit : public QWidget 0023 { 0024 Q_OBJECT 0025 0026 Q_PROPERTY(QDate date READ date WRITE setDate NOTIFY dateChanged USER true) 0027 Q_PROPERTY(QTime time READ time WRITE setTime NOTIFY timeChanged USER true) 0028 Q_PROPERTY(int timeListInterval READ timeListInterval WRITE setTimeListInterval) 0029 Q_PROPERTY(Options options READ options WRITE setOptions) 0030 0031 public: 0032 /** 0033 * Options provided by the widget 0034 * @see options 0035 * @see setOptions 0036 * @see Options 0037 */ 0038 enum Option { 0039 ShowCalendar = 0x00001, /**< If the Calendar System edit is displayed */ 0040 ShowDate = 0x00002, /**< If the Date is displayed */ 0041 ShowTime = 0x00004, /**< If the Time is displayed */ 0042 ShowTimeZone = 0x00008, /**< If the Time Zone is displayed */ 0043 // EditCalendar = 0x00010, /**< Allow the user to manually edit the calendar */ 0044 EditDate = 0x00020, /**< Allow the user to manually edit the date */ 0045 EditTime = 0x00040, /**< Allow the user to manually edit the time */ 0046 // EditTimeZone = 0x00080, /**< Allow the user to manually edit the time zone */ 0047 SelectCalendar = 0x00100, /**< Allow the user to select a calendar */ 0048 SelectDate = 0x00200, /**< Allow the user to select a date */ 0049 SelectTime = 0x00400, /**< Allow the user to select a time */ 0050 SelectTimeZone = 0x00800, /**< Allow the user to select a time zone */ 0051 DatePicker = 0x01000, /**< Show a date picker */ 0052 DateKeywords = 0x02000, /**< Show date keywords */ 0053 ForceTime = 0x04000, /**< The entered time can only be a selected time */ 0054 WarnOnInvalid = 0x08000, /**< Show a warning on focus out if the date or time is invalid */ 0055 }; 0056 /** 0057 * Stores a combination of #Option values. 0058 */ 0059 Q_DECLARE_FLAGS(Options, Option) 0060 Q_FLAG(Options) 0061 0062 /** 0063 * Create a new KDateTimeEdit widget 0064 */ 0065 explicit KDateTimeEdit(QWidget *parent = nullptr); 0066 0067 /** 0068 * Destroy the widget 0069 */ 0070 ~KDateTimeEdit() override; 0071 0072 /** 0073 * Return the currently set widget options 0074 * 0075 * @return the currently set widget options 0076 */ 0077 Options options() const; 0078 0079 /** 0080 * Return the currently selected date, time and time zone 0081 * 0082 * @return the currently selected date, time and time zone 0083 */ 0084 QDateTime dateTime() const; 0085 0086 /** 0087 * Return the currently selected date 0088 * 0089 * @return the currently selected date 0090 */ 0091 QDate date() const; 0092 0093 /** 0094 * Return the currently selected time 0095 * 0096 * @return the currently selected time 0097 */ 0098 QTime time() const; 0099 0100 /** 0101 * Return the currently selected time zone 0102 * 0103 * @return the currently selected time zone 0104 */ 0105 QTimeZone timeZone() const; 0106 0107 /** 0108 * Returns the list of Calendar Locales displayed. 0109 * 0110 * @return the list of calendar locales displayed 0111 */ 0112 QList<QLocale> calendarLocalesList() const; 0113 0114 /** 0115 * Return the current minimum date and time 0116 * 0117 * @return the current minimum date and time 0118 */ 0119 QDateTime minimumDateTime() const; 0120 0121 /** 0122 * Return the current maximum date and time 0123 * 0124 * @return the current maximum date and time 0125 */ 0126 QDateTime maximumDateTime() const; 0127 0128 /** 0129 * Return the currently set date display format 0130 * 0131 * By default this is the Short Format 0132 * 0133 * @return the currently set date format 0134 */ 0135 QLocale::FormatType dateDisplayFormat() const; 0136 0137 /** 0138 * Return the map of dates listed in the drop-down and their displayed 0139 * string forms. 0140 * 0141 * @return the select date map 0142 * 0143 * @see setDateMap() 0144 */ 0145 QMap<QDate, QString> dateMap() const; 0146 0147 /** 0148 * Return the currently set time format 0149 * 0150 * By default this is the Short Format 0151 * 0152 * @return the currently set time format 0153 */ 0154 QLocale::FormatType timeDisplayFormat() const; 0155 0156 /** 0157 * Return the time list interval able to be selected 0158 * 0159 * @return the select time intervals in minutes 0160 */ 0161 int timeListInterval() const; 0162 0163 /** 0164 * Return the list of times able to be selected in the drop-down. 0165 * 0166 * @return the select time list 0167 * 0168 * @see setTimeList() 0169 * @see timeListInterval() 0170 * @see setTimeListInterval() 0171 */ 0172 QList<QTime> timeList() const; 0173 0174 /** 0175 * Return the list of time zones able to be selected 0176 * 0177 * @return the list of time zones displayed 0178 */ 0179 QList<QTimeZone> timeZones() const; 0180 0181 /** 0182 * Return if the current user input is valid 0183 * 0184 * If the user input is null then it is not valid 0185 * 0186 * @return if the current user input is valid 0187 * 0188 * @see isNull() 0189 */ 0190 bool isValid() const; 0191 0192 /** 0193 * Return if the current user input is null 0194 * 0195 * @return if the current user input is null 0196 * 0197 * @see isValid() 0198 */ 0199 bool isNull() const; 0200 0201 /** 0202 * Return if the current user input date is valid 0203 * 0204 * If the user input date is null then it is not valid 0205 * 0206 * @return if the current user input date is valid 0207 * 0208 * @see isNullDate() 0209 */ 0210 bool isValidDate() const; 0211 0212 /** 0213 * Return if the current user input date is null 0214 * 0215 * @return if the current user input date is null 0216 * 0217 * @see isValidDate() 0218 */ 0219 bool isNullDate() const; 0220 /** 0221 * Return if the current user input time is valid 0222 * 0223 * If the user input time is null then it is not valid 0224 * 0225 * @return if the current user input time is valid 0226 * 0227 * @see isNullTime() 0228 */ 0229 bool isValidTime() const; 0230 0231 /** 0232 * Return if the current user input time is null 0233 * 0234 * @return if the current user input time is null 0235 * 0236 * @see isValidTime() 0237 */ 0238 bool isNullTime() const; 0239 0240 Q_SIGNALS: 0241 0242 /** 0243 * Signal if the date or time has been manually entered by the user. 0244 * 0245 * The returned date and time may be invalid. 0246 * 0247 * @param dateTime the new date, time and time zone 0248 */ 0249 void dateTimeEntered(const QDateTime &dateTime); 0250 0251 /** 0252 * Signal if the date or time has been changed either manually by the user 0253 * or programmatically. 0254 * 0255 * The returned date and time may be invalid. 0256 * 0257 * @param dateTime the new date, time and time zone 0258 */ 0259 void dateTimeChanged(const QDateTime &dateTime); 0260 0261 /** 0262 * Signal if the date or time is being manually edited by the user. 0263 * 0264 * The returned date and time may be invalid. 0265 * 0266 * @param dateTime the new date, time and time zone 0267 */ 0268 void dateTimeEdited(const QDateTime &dateTime); 0269 0270 /** 0271 * Signal if the Calendar Locale has been manually entered by the user. 0272 * 0273 * @param calendarLocale the new calendar locale 0274 */ 0275 void calendarEntered(const QLocale &calendarLocale); 0276 0277 /** 0278 * Signal if the Calendar Locale has been changed either manually by the user 0279 * or programmatically. 0280 * 0281 * @param calendarLocale the new calendar locale 0282 */ 0283 void calendarChanged(const QLocale &calendarLocale); 0284 0285 /** 0286 * Signal if the date has been manually entered by the user. 0287 * 0288 * The returned date may be invalid. 0289 * 0290 * @param date the new date 0291 */ 0292 void dateEntered(const QDate &date); 0293 0294 /** 0295 * Signal if the date has been changed either manually by the user 0296 * or programmatically. 0297 * 0298 * The returned date may be invalid. 0299 * 0300 * @param date the new date 0301 */ 0302 void dateChanged(const QDate &date); 0303 0304 /** 0305 * Signal if the date is being manually edited by the user. 0306 * 0307 * The returned date may be invalid. 0308 * 0309 * @param date the new date 0310 */ 0311 void dateEdited(const QDate &date); 0312 0313 /** 0314 * Signal if the time has been manually entered by the user. 0315 * 0316 * The returned time may be invalid. 0317 * 0318 * @param time the new time 0319 */ 0320 void timeEntered(const QTime &time); 0321 0322 /** 0323 * Signal if the time has been changed either manually by the user 0324 * or programmatically. 0325 * 0326 * The returned time may be invalid. 0327 * 0328 * @param time the new time 0329 */ 0330 void timeChanged(const QTime &time); 0331 0332 /** 0333 * Signal if the time is being manually edited by the user. 0334 * 0335 * The returned time may be invalid. 0336 * 0337 * @param time the new time 0338 */ 0339 void timeEdited(const QTime &time); 0340 0341 /** 0342 * Signal if the time zone has been changed manually by the user. 0343 * 0344 * @param zone the new time zone 0345 */ 0346 void timeZoneEntered(const QTimeZone &zone); 0347 0348 /** 0349 * Signal if the time zone has been changed either manually by the user 0350 * or programmatically. 0351 * 0352 * @param zone the new time zone 0353 */ 0354 void timeZoneChanged(const QTimeZone &zone); 0355 0356 public Q_SLOTS: 0357 0358 /** 0359 * Set the new widget options 0360 * 0361 * @param options the new widget options 0362 */ 0363 void setOptions(Options options); 0364 0365 /** 0366 * Set the currently selected date, time and time zone 0367 * 0368 * @param dateTime the new date, time and time zone 0369 */ 0370 void setDateTime(const QDateTime &dateTime); 0371 0372 /** 0373 * Set the currently selected date 0374 * 0375 * @param date the new date 0376 */ 0377 void setDate(const QDate &date); 0378 0379 /** 0380 * Set the currently selected time 0381 * 0382 * @param time the new time 0383 */ 0384 void setTime(const QTime &time); 0385 0386 /** 0387 * Set the current time zone 0388 * 0389 * @param zone the new zone 0390 */ 0391 void setTimeZone(const QTimeZone &zone); 0392 0393 /** 0394 * Set the minimum and maximum date and time range 0395 * 0396 * To enable range checking provide two valid dates. 0397 * To disable range checking provide two invalid dates, or call 0398 * clearDateRange; 0399 * 0400 * @param minDateTime the minimum date and time 0401 * @param maxDateTime the maximum date and time 0402 * @param minWarnMsg the minimum warning message 0403 * @param maxWarnMsg the maximum warning message 0404 */ 0405 void 0406 setDateTimeRange(const QDateTime &minDateTime, const QDateTime &maxDateTime, const QString &minWarnMsg = QString(), const QString &maxWarnMsg = QString()); 0407 0408 /** 0409 * Reset the minimum and maximum date and time to the default 0410 */ 0411 void resetDateTimeRange(); 0412 0413 /** 0414 * Set the minimum allowed date. 0415 * 0416 * If the date is invalid, or more than current maximum, 0417 * then the minimum will not be set. 0418 * 0419 * @param minDateTime the minimum date 0420 * @param minWarnMsg the minimum warning message 0421 * 0422 * @see setMaximumDateTime() 0423 * @see setDateRange() 0424 */ 0425 void setMinimumDateTime(const QDateTime &minDateTime, const QString &minWarnMsg = QString()); 0426 0427 /** 0428 * Reset the minimum date and time to the default 0429 */ 0430 void resetMinimumDateTime(); 0431 0432 /** 0433 * Set the maximum allowed date. 0434 * 0435 * If the date is invalid, or less than current minimum, 0436 * then the maximum will not be set. 0437 * 0438 * @param maxDateTime the maximum date 0439 * @param maxWarnMsg the maximum warning message 0440 * 0441 * @see setMinimumDateTime() 0442 * @see setDateRange() 0443 */ 0444 void setMaximumDateTime(const QDateTime &maxDateTime, const QString &maxWarnMsg = QString()); 0445 0446 /** 0447 * Reset the minimum date and time to the default 0448 */ 0449 void resetMaximumDateTime(); 0450 0451 /** 0452 * Sets the date format to display. 0453 * 0454 * By default is the Short Format. 0455 * 0456 * @param format the date format to use 0457 */ 0458 void setDateDisplayFormat(QLocale::FormatType format); 0459 0460 /** 0461 * Set the list of Calendar Locales to display. 0462 * 0463 * @param calendarLocales the list of calendar locales to display 0464 */ 0465 void setCalendarLocalesList(const QList<QLocale> &calendarLocales); 0466 0467 /** 0468 * Set the list of dates able to be selected from the drop-down and the 0469 * string form to display for those dates, e.g. "2010-01-01" and "Yesterday". 0470 * 0471 * Any invalid or duplicate dates will be used, the list will NOT be 0472 * sorted, and the minimum and maximum date will not be affected. 0473 * 0474 * The @p dateMap is keyed by the date to be listed and the value is the 0475 * string to be displayed. If you want the date to be displayed in the 0476 * default date format then the string should be null. If you want a 0477 * separator to be displayed then set the string to "separator". 0478 * 0479 * @param dateMap the map of dates able to be selected 0480 * 0481 * @see dateMap() 0482 */ 0483 void setDateMap(QMap<QDate, QString> dateMap); 0484 0485 /** 0486 * Sets the time format to display. 0487 * 0488 * By default is the Short Format. 0489 * 0490 * @param format the time format to use 0491 */ 0492 void setTimeDisplayFormat(QLocale::FormatType format); 0493 0494 /** 0495 * Set the interval between times able to be selected from the drop-down. 0496 * 0497 * The combo drop-down will be populated with times every @p minutes 0498 * apart, starting from the minimumTime() and ending at maximumTime(). 0499 * 0500 * If the ForceInterval option is set then any time manually typed into the 0501 * combo line edit will be forced to the nearest interval. 0502 * 0503 * This interval must be an exact divisor of the valid time range hours. 0504 * For example with the default 24 hour range @p interval must divide 1440 0505 * minutes exactly, meaning 1, 6 and 90 are valid but 7, 31 and 91 are not. 0506 * 0507 * Setting the time list interval will override any time list previously set 0508 * via setTimeList(). 0509 * 0510 * @param minutes the time list interval to display 0511 * 0512 * @see timeListInterval() 0513 */ 0514 void setTimeListInterval(int minutes); 0515 0516 /** 0517 * Set the list of times able to be selected from the drop-down. 0518 * 0519 * Setting the time list will override any time interval previously set via 0520 * setTimeListInterval(). 0521 * 0522 * Any invalid or duplicate times will be ignored, and the list will be 0523 * sorted. 0524 * 0525 * The minimum and maximum time will automatically be set to the earliest 0526 * and latest value in the list. 0527 * 0528 * @param timeList the list of times able to be selected 0529 * @param minWarnMsg the minimum warning message 0530 * @param maxWarnMsg the maximum warning message 0531 * 0532 * @see timeList() 0533 */ 0534 void setTimeList(QList<QTime> timeList, const QString &minWarnMsg = QString(), const QString &maxWarnMsg = QString()); 0535 0536 /** 0537 * Set the time zones able to be selected 0538 * 0539 * @param zones the time zones to display 0540 */ 0541 void setTimeZones(const QList<QTimeZone> &zones); 0542 0543 protected: 0544 bool eventFilter(QObject *object, QEvent *event) override; 0545 void focusInEvent(QFocusEvent *event) override; 0546 void focusOutEvent(QFocusEvent *event) override; 0547 void resizeEvent(QResizeEvent *event) override; 0548 0549 /** 0550 * Assign the date, time and time zone for the widget. 0551 * 0552 * Virtual to allow sub-classes to apply extra validation rules, 0553 * but reimplementations must call the parent method at the end. 0554 * 0555 * @param dateTime the new date and time 0556 */ 0557 virtual void assignDateTime(const QDateTime &dateTime); 0558 0559 /** 0560 * Assign the date for the widget. 0561 * 0562 * Virtual to allow sub-classes to apply extra validation rules, 0563 * but reimplementations must call the parent method at the end. 0564 * 0565 * @param date the new date 0566 */ 0567 virtual void assignDate(const QDate &date); 0568 0569 /** 0570 * Assign the time for the widget. 0571 * 0572 * Virtual to allow sub-classes to apply extra validation rules, 0573 * but reimplementations must call the parent method at the end. 0574 * 0575 * @param time the new time 0576 */ 0577 virtual void assignTime(const QTime &time); 0578 0579 /** 0580 * Assign the time zone for the widget. 0581 * 0582 * Virtual to allow sub-classes to apply extra validation rules, 0583 * but reimplementations must call the parent method at the end. 0584 * 0585 * @param zone the new time zone 0586 */ 0587 void assignTimeZone(const QTimeZone &zone); 0588 0589 private: 0590 friend class KDateTimeEditPrivate; 0591 std::unique_ptr<class KDateTimeEditPrivate> const d; 0592 }; 0593 0594 Q_DECLARE_OPERATORS_FOR_FLAGS(KDateTimeEdit::Options) 0595 0596 #endif // KDATETIMEEDIT_H