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
30class KDateTimeEditPrivate;
31class KCalendarSystem;
32
33class 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
43public:
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
264Q_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
380public 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
584protected:
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
641private:
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
652Q_DECLARE_OPERATORS_FOR_FLAGS(KDateTimeEdit::Options)
653
654#endif // KDATETIMEEDIT_H
655