1 | /* |
2 | Copyright 2011 John Layt <john@layt.net> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; either |
7 | version 2 of the License, or (at your option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KDATETIMEEDIT_H |
21 | #define KDATETIMEEDIT_H |
22 | |
23 | #include <kdeui_export.h> |
24 | |
25 | #include <QtGui/QWidget> |
26 | |
27 | #include "klocale.h" |
28 | #include "kdatetime.h" |
29 | |
30 | class KDateTimeEditPrivate; |
31 | class KCalendarSystem; |
32 | |
33 | class KDEUI_EXPORT KDateTimeEdit : public QWidget |
34 | { |
35 | Q_OBJECT |
36 | |
37 | Q_PROPERTY(QDate date READ date WRITE setDate NOTIFY dateChanged USER true) |
38 | Q_PROPERTY(QTime time READ time WRITE setTime NOTIFY timeChanged USER true) |
39 | Q_PROPERTY(int timeListInterval READ timeListInterval WRITE setTimeListInterval) |
40 | Q_PROPERTY(Options options READ options WRITE setOptions) |
41 | Q_FLAGS(Options) |
42 | |
43 | public: |
44 | |
45 | /** |
46 | * Options provided by the widget |
47 | * @see options |
48 | * @see setOptions |
49 | */ |
50 | enum Option { |
51 | ShowCalendar = 0x00001, /**< If the Calendar System edit is displayed */ |
52 | ShowDate = 0x00002, /**< If the Date is displayed */ |
53 | ShowTime = 0x00004, /**< If the Time is displayed */ |
54 | ShowTimeSpec = 0x00008, /**< If the Time Spec is displayed */ |
55 | //EditCalendar = 0x00010, /**< Allow the user to manually edit the calendar */ |
56 | EditDate = 0x00020, /**< Allow the user to manually edit the date */ |
57 | EditTime = 0x00040, /**< Allow the user to manually edit the time */ |
58 | //EditTimeSpec = 0x00080, /**< Allow the user to manually edit the time spec */ |
59 | SelectCalendar = 0x00100, /**< Allow the user to select a calendar */ |
60 | SelectDate = 0x00200, /**< Allow the user to select a date */ |
61 | SelectTime = 0x00400, /**< Allow the user to select a time */ |
62 | SelectTimeSpec = 0x00800, /**< Allow the user to select a time spec */ |
63 | DatePicker = 0x01000, /**< Show a date picker */ |
64 | DateKeywords = 0x02000, /**< Show date keywords */ |
65 | ForceTime = 0x04000, /**< The entered time can only be a selected time */ |
66 | WarnOnInvalid = 0x08000 /**< Show a warning on focus out if the date or time is invalid */ |
67 | }; |
68 | Q_DECLARE_FLAGS(Options, Option) |
69 | |
70 | /** |
71 | * Create a new KDateTimeEdit widget |
72 | */ |
73 | explicit KDateTimeEdit(QWidget *parent = 0); |
74 | |
75 | /** |
76 | * Destroy the widget |
77 | */ |
78 | virtual ~KDateTimeEdit(); |
79 | |
80 | /** |
81 | * Return the currently set widget options |
82 | * |
83 | * @return the currently set widget options |
84 | */ |
85 | Options options() const; |
86 | |
87 | /** |
88 | * Return the currently selected date, time and time spec |
89 | * |
90 | * @return the currently selected date, time and time spec |
91 | */ |
92 | KDateTime dateTime() const; |
93 | |
94 | /** |
95 | * Returns the Calendar System type used by the widget |
96 | * |
97 | * @see KLocale::CalendarSystem |
98 | * @see setCalendarSystem() |
99 | * @return the Calendar System currently used |
100 | */ |
101 | KLocale::CalendarSystem calendarSystem() const; |
102 | |
103 | /** |
104 | * Returns a pointer to the Calendar System object used by this widget |
105 | * |
106 | * Usually this will be the Global Calendar System using the Global Locale, |
107 | * but this may have been changed to a custom Calendar System possibly |
108 | * using a custom Locale. |
109 | * |
110 | * Normally you will not need to access this object. |
111 | * |
112 | * @see KCalendarSystem |
113 | * @see setCalendar |
114 | * @return the current calendar system instance |
115 | */ |
116 | const KCalendarSystem *calendar() const; |
117 | |
118 | /** |
119 | * Return the currently selected date |
120 | * |
121 | * @return the currently selected date |
122 | */ |
123 | QDate date() const; |
124 | |
125 | /** |
126 | * Return the currently selected time |
127 | * |
128 | * @return the currently selected time |
129 | */ |
130 | QTime time() const; |
131 | |
132 | /** |
133 | * Return the currently selected time spec |
134 | * |
135 | * @return the currently selected time spec |
136 | */ |
137 | KDateTime::Spec timeSpec() const; |
138 | |
139 | /** |
140 | * Returns the list of Calendar Systems displayed. |
141 | * |
142 | * @param calendars the list of calendar systems to display |
143 | */ |
144 | QList<KLocale::CalendarSystem> calendarSystemsList() const; |
145 | |
146 | /** |
147 | * Return the current minimum date and time |
148 | * |
149 | * @return the current minimum date and time |
150 | */ |
151 | KDateTime minimumDateTime() const; |
152 | |
153 | /** |
154 | * Return the current maximum date and time |
155 | * |
156 | * @return the current maximum date and time |
157 | */ |
158 | KDateTime maximumDateTime() const; |
159 | |
160 | /** |
161 | * Return the currently set date display format |
162 | * |
163 | * By default this is the Short Date |
164 | * |
165 | * @return the currently set date format |
166 | */ |
167 | KLocale::DateFormat dateDisplayFormat() const; |
168 | |
169 | /** |
170 | * Return the map of dates listed in the drop-down and their displayed |
171 | * string forms. |
172 | * |
173 | * @see setDateMap() |
174 | * @return the select date map |
175 | */ |
176 | QMap<QDate, QString> dateMap() const; |
177 | |
178 | /** |
179 | * Return the currently set time format |
180 | * |
181 | * By default this is the Short Time |
182 | * |
183 | * @return the currently set time format |
184 | */ |
185 | KLocale::TimeFormatOptions timeDisplayFormat() const; |
186 | |
187 | /** |
188 | * Return the time list interval able to be selected |
189 | * |
190 | * @return the select time intervals in minutes |
191 | */ |
192 | int timeListInterval() const; |
193 | |
194 | /** |
195 | * Return the list of times able to be selected in the drop-down. |
196 | * |
197 | * @see setTimeList() |
198 | * @see timeListInterval() |
199 | * @see setTimeListInterval() |
200 | * @return the select time list |
201 | */ |
202 | QList<QTime> timeList() const; |
203 | |
204 | /** |
205 | * Return the list of time zones able to be selected |
206 | * |
207 | * @param zones the time zones to display |
208 | */ |
209 | KTimeZones::ZoneMap timeZones() const; |
210 | |
211 | /** |
212 | * Return if the current user input is valid |
213 | * |
214 | * If the user input is null then it is not valid |
215 | * |
216 | * @see isNull() |
217 | * @return if the current user input is valid |
218 | */ |
219 | bool isValid() const; |
220 | |
221 | /** |
222 | * Return if the current user input is null |
223 | * |
224 | * @see isValid() |
225 | * @return if the current user input is null |
226 | */ |
227 | bool isNull() const; |
228 | |
229 | /** |
230 | * Return if the current user input date is valid |
231 | * |
232 | * If the user input date is null then it is not valid |
233 | * |
234 | * @see isNullDate() |
235 | * @return if the current user input date is valid |
236 | */ |
237 | bool isValidDate() const; |
238 | |
239 | /** |
240 | * Return if the current user input date is null |
241 | * |
242 | * @see isValidDate() |
243 | * @return if the current user input date is null |
244 | */ |
245 | bool isNullDate() const; |
246 | /** |
247 | * Return if the current user input time is valid |
248 | * |
249 | * If the user input time is null then it is not valid |
250 | * |
251 | * @see isNullTime() |
252 | * @return if the current user input time is valid |
253 | */ |
254 | bool isValidTime() const; |
255 | |
256 | /** |
257 | * Return if the current user input time is null |
258 | * |
259 | * @see isValidTime() |
260 | * @return if the current user input time is null |
261 | */ |
262 | bool isNullTime() const; |
263 | |
264 | Q_SIGNALS: |
265 | |
266 | /** |
267 | * Signal if the date or time has been manually entered by the user. |
268 | * |
269 | * The returned date and time may be invalid. |
270 | * |
271 | * @param dateTime the new date, time and time spec |
272 | */ |
273 | void dateTimeEntered(const KDateTime &dateTime); |
274 | |
275 | /** |
276 | * Signal if the date or time has been changed either manually by the user |
277 | * or programatically. |
278 | * |
279 | * The returned date and time may be invalid. |
280 | * |
281 | * @param dateTime the new date, time and time spec |
282 | */ |
283 | void dateTimeChanged(const KDateTime &dateTime); |
284 | |
285 | /** |
286 | * Signal if the date or time is being manually edited by the user. |
287 | * |
288 | * The returned date and time may be invalid. |
289 | * |
290 | * @param dateTime the new date, time and time spec |
291 | */ |
292 | void dateTimeEdited(const KDateTime &dateTime); |
293 | |
294 | /** |
295 | * Signal if the Calendar System has been manually entered by the user. |
296 | * |
297 | * @param calendarSystem the new calendar system |
298 | */ |
299 | void calendarEntered(KLocale::CalendarSystem calendarSystem); |
300 | |
301 | /** |
302 | * Signal if the Calendar System has been changed either manually by the user |
303 | * or programatically. |
304 | * |
305 | * @param calendarSystem the new calendar system |
306 | */ |
307 | void calendarChanged(KLocale::CalendarSystem calendarSystem); |
308 | |
309 | /** |
310 | * Signal if the date has been manually entered by the user. |
311 | * |
312 | * The returned date may be invalid. |
313 | * |
314 | * @param date the new date |
315 | */ |
316 | void dateEntered(const QDate &date); |
317 | |
318 | /** |
319 | * Signal if the date has been changed either manually by the user |
320 | * or programatically. |
321 | * |
322 | * The returned date may be invalid. |
323 | * |
324 | * @param date the new date |
325 | */ |
326 | void dateChanged(const QDate &date); |
327 | |
328 | /** |
329 | * Signal if the date is being manually edited by the user. |
330 | * |
331 | * The returned date may be invalid. |
332 | * |
333 | * @param date the new date |
334 | */ |
335 | void dateEdited(const QDate &date); |
336 | |
337 | /** |
338 | * Signal if the time has been manually entered by the user. |
339 | * |
340 | * The returned time may be invalid. |
341 | * |
342 | * @param time the new time |
343 | */ |
344 | void timeEntered(const QTime &time); |
345 | |
346 | /** |
347 | * Signal if the time has been changed either manually by the user |
348 | * or programatically. |
349 | * |
350 | * The returned time may be invalid. |
351 | * |
352 | * @param time the new time |
353 | */ |
354 | void timeChanged(const QTime &time); |
355 | |
356 | /** |
357 | * Signal if the time is being manually edited by the user. |
358 | * |
359 | * The returned time may be invalid. |
360 | * |
361 | * @param time the new time |
362 | */ |
363 | void timeEdited(const QTime &time); |
364 | |
365 | /** |
366 | * Signal if the time spec has been changed manually by the user. |
367 | * |
368 | * @param timeSpec the new time spec |
369 | */ |
370 | void timeSpecEntered(const KDateTime::Spec &spec); |
371 | |
372 | /** |
373 | * Signal if the time spec has been changed either manually by the user |
374 | * or programatically. |
375 | * |
376 | * @param timeSpec the new time spec |
377 | */ |
378 | void timeSpecChanged(const KDateTime::Spec &spec); |
379 | |
380 | public Q_SLOTS: |
381 | |
382 | /** |
383 | * Set the new widget options |
384 | * |
385 | * @param options the new widget options |
386 | */ |
387 | void setOptions(Options options); |
388 | |
389 | /** |
390 | * Set the currently selected date, time and time spec |
391 | * |
392 | * @param dateTime the new date, time and time spec |
393 | */ |
394 | void setDateTime(const KDateTime &dateTime); |
395 | |
396 | /** |
397 | * Set the Calendar System used for this widget. Uses the global locale. |
398 | * |
399 | * @see KLocale::CalendarSystem |
400 | * @see calendarSystem() |
401 | * @param calendarSystem the Calendar System to use |
402 | */ |
403 | void setCalendarSystem(KLocale::CalendarSystem calendarSystem); |
404 | |
405 | /** |
406 | * Changes the calendar system to use. Can use its own local locale if set. |
407 | * |
408 | * You retain ownership of the calendar object, it will not be destroyed with the widget. |
409 | * |
410 | * @param calendar the calendar system object to use, defaults to global |
411 | */ |
412 | void setCalendar(KCalendarSystem *calendar = 0); |
413 | |
414 | /** |
415 | * Set the currently selected date |
416 | * |
417 | * @param date the new date |
418 | */ |
419 | void setDate(const QDate &date); |
420 | |
421 | /** |
422 | * Set the currently selected time |
423 | * |
424 | * @param time the new time |
425 | */ |
426 | void setTime(const QTime &time); |
427 | |
428 | /** |
429 | * Set the current time spec |
430 | * |
431 | * @param spec the new spec |
432 | */ |
433 | void setTimeSpec(const KDateTime::Spec &spec); |
434 | |
435 | /** |
436 | * Set the minimum and maximum date and time range |
437 | * |
438 | * To enable range checking provide two valid dates. |
439 | * To disable range checking provide two invalid dates, or call |
440 | * clearDateRange; |
441 | * |
442 | * @param minDateTime the minimum date and time |
443 | * @param maxDateTime the maximum date and time |
444 | * @param minWarnMsg the minimum warning message |
445 | * @param maxWarnMsg the maximum warning message |
446 | */ |
447 | void setDateTimeRange(const KDateTime &minDateTime, |
448 | const KDateTime &maxDateTime, |
449 | const QString &minWarnMsg = QString(), |
450 | const QString &maxWarnMsg = QString()); |
451 | |
452 | /** |
453 | * Reset the minimum and maximum date and time to the default |
454 | */ |
455 | void resetDateTimeRange(); |
456 | |
457 | /** |
458 | * Set the minimum allowed date. |
459 | * |
460 | * If the date is invalid, or more than current maximum, |
461 | * then the minimum will not be set. |
462 | * |
463 | * @see setMaximumDateTime() |
464 | * @see setDateRange() |
465 | * @param maxDate the minimum date |
466 | * @param maxWarnMsg the minimum warning message |
467 | */ |
468 | void setMinimumDateTime(const KDateTime &minDateTime, const QString &minWarnMsg = QString()); |
469 | |
470 | /** |
471 | * Reset the minimum date and time to the default |
472 | */ |
473 | void resetMinimumDateTime(); |
474 | |
475 | /** |
476 | * Set the maximum allowed date. |
477 | * |
478 | * If the date is invalid, or less than current minimum, |
479 | * then the maximum will not be set. |
480 | * |
481 | * @see setMinimumDateTime() |
482 | * @see setDateRange() |
483 | * @param maxDate the maximum date |
484 | * @param maxWarnMsg the maximum warning message |
485 | */ |
486 | void setMaximumDateTime(const KDateTime &maxDateTime, const QString &maxWarnMsg = QString()); |
487 | |
488 | /** |
489 | * Reset the minimum date and time to the default |
490 | */ |
491 | void resetMaximumDateTime(); |
492 | |
493 | /** |
494 | * Sets the date format to display. |
495 | * |
496 | * By default is the Short Date format. |
497 | * |
498 | * @param format the date format to use |
499 | */ |
500 | void setDateDisplayFormat(KLocale::DateFormat format); |
501 | |
502 | /** |
503 | * Set the list of Calendar Systems to display. |
504 | * |
505 | * @param calendars the list of calendar systems to display |
506 | */ |
507 | void setCalendarSystemsList(QList<KLocale::CalendarSystem> calendars); |
508 | |
509 | /** |
510 | * Set the list of dates able to be selected from the drop-down and the |
511 | * string form to display for those dates, e.g. "2010-01-01" and "Yesterday". |
512 | * |
513 | * Any invalid or duplicate dates will be used, the list will NOT be |
514 | * sorted, and the minimum and maximum date will not be affected. |
515 | * |
516 | * The @p dateMap is keyed by the date to be listed and the value is the |
517 | * string to be displayed. If you want the date to be displayed in the |
518 | * default date format then the string should be null. If you want a |
519 | * separator to be displayed then set the string to "seperator". |
520 | * |
521 | * @see dateMap() |
522 | * @param dateMap the map of dates able to be selected |
523 | */ |
524 | void setDateMap(QMap<QDate, QString> dateMap); |
525 | |
526 | /** |
527 | * Sets the time format to display. |
528 | * |
529 | * By default is the Short Time format. |
530 | * |
531 | * @param format the time format to use |
532 | */ |
533 | void setTimeDisplayFormat(KLocale::TimeFormatOptions formatOptions); |
534 | |
535 | /** |
536 | * Set the interval between times able to be selected from the drop-down. |
537 | * |
538 | * The combo drop-down will be populated with times every @param minutes |
539 | * apart, starting from the minimumTime() and ending at maximumTime(). |
540 | * |
541 | * If the ForceInterval option is set then any time manually typed into the |
542 | * combo line edit will be forced to the nearest interval. |
543 | * |
544 | * This interval must be an exact divisor of the valid time range hours. |
545 | * For example with the default 24 hour range @p interval must divide 1440 |
546 | * minutes exactly, meaning 1, 6 and 90 are valid but 7, 31 and 91 are not. |
547 | * |
548 | * Setting the time list interval will override any time list previously set |
549 | * via setTimeList(). |
550 | * |
551 | * @see timeListInterval() |
552 | * @param minutes the time list interval to display |
553 | */ |
554 | void setTimeListInterval(int minutes); |
555 | |
556 | /** |
557 | * Set the list of times able to be selected from the drop-down. |
558 | * |
559 | * Setting the time list will override any time interval previously set via |
560 | * setTimeListInterval(). |
561 | * |
562 | * Any invalid or duplicate times will be ignored, and the list will be |
563 | * sorted. |
564 | * |
565 | * The minimum and maximum time will automatically be set to the earliest |
566 | * and latest value in the list. |
567 | * |
568 | * @see timeList() |
569 | * @param timeList the list of times able to be selected |
570 | * @param minWarnMsg the minimum warning message |
571 | * @param maxWarnMsg the maximum warning message |
572 | */ |
573 | void setTimeList(QList<QTime> timeList, |
574 | const QString &minWarnMsg = QString(), |
575 | const QString &maxWarnMsg = QString()); |
576 | |
577 | /** |
578 | * Set the time zones able to be selected |
579 | * |
580 | * @param zones the time zones to display |
581 | */ |
582 | void setTimeZones(const KTimeZones::ZoneMap &zones); |
583 | |
584 | protected: |
585 | |
586 | virtual bool eventFilter(QObject *object, QEvent *event); |
587 | virtual void focusInEvent(QFocusEvent *event); |
588 | virtual void focusOutEvent(QFocusEvent *event); |
589 | virtual void resizeEvent(QResizeEvent *event); |
590 | |
591 | /** |
592 | * Assign the date, time and time spec for the widget. |
593 | * |
594 | * Virtual to allow sub-classes to apply extra validation rules, |
595 | * but reimplementations must call the parent method at the end. |
596 | * |
597 | * @param datetime the new date and time |
598 | */ |
599 | virtual void assignDateTime(const KDateTime &dateTime); |
600 | |
601 | /** |
602 | * Assign the date for the widget. |
603 | * |
604 | * Virtual to allow sub-classes to apply extra validation rules, |
605 | * but reimplementations must call the parent method at the end. |
606 | * |
607 | * @param date the new date |
608 | */ |
609 | virtual void assignDate(const QDate &date); |
610 | |
611 | /** |
612 | * Assign the calendar system for the widget. |
613 | * |
614 | * Virtual to allow sub-classes to apply extra validation rules, |
615 | * but reimplementations must call the parent method at the end. |
616 | * |
617 | * @param calendarSystem the new calendar system |
618 | */ |
619 | void assignCalendarSystem(KLocale::CalendarSystem calendarSystem); |
620 | |
621 | /** |
622 | * Assign the time for the widget. |
623 | * |
624 | * Virtual to allow sub-classes to apply extra validation rules, |
625 | * but reimplementations must call the parent method at the end. |
626 | * |
627 | * @param time the new time |
628 | */ |
629 | virtual void assignTime(const QTime &time); |
630 | |
631 | /** |
632 | * Assign the time spec for the widget. |
633 | * |
634 | * Virtual to allow sub-classes to apply extra validation rules, |
635 | * but reimplementations must call the parent method at the end. |
636 | * |
637 | * @param spec the new time spec |
638 | */ |
639 | void assignTimeSpec(const KDateTime::Spec &spec); |
640 | |
641 | private: |
642 | |
643 | friend class KDateTimeEditPrivate; |
644 | KDateTimeEditPrivate *const d; |
645 | |
646 | Q_PRIVATE_SLOT(d, void selectCalendar(int)) |
647 | Q_PRIVATE_SLOT(d, void enterCalendar(KLocale::CalendarSystem)) |
648 | Q_PRIVATE_SLOT(d, void selectTimeZone(int)) |
649 | Q_PRIVATE_SLOT(d, void enterTimeZone(const QString&)) |
650 | }; |
651 | |
652 | Q_DECLARE_OPERATORS_FOR_FLAGS(KDateTimeEdit::Options) |
653 | |
654 | #endif // KDATETIMEEDIT_H |
655 | |