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 KDATECOMBOBOX_H
21#define KDATECOMBOBOX_H
22
23#include <kdeui_export.h>
24
25#include <QtGui/QWidget>
26
27#include "kcombobox.h"
28#include "klocale.h"
29#include "kdatetime.h"
30
31class KDateComboBoxPrivate;
32class KCalendarSystem;
33
34class KDEUI_EXPORT KDateComboBox : public KComboBox
35{
36 Q_OBJECT
37
38 Q_PROPERTY(QDate date READ date WRITE setDate NOTIFY dateChanged USER true)
39 Q_PROPERTY(QDate minimumDate READ minimumDate WRITE setMinimumDate RESET resetMinimumDate)
40 Q_PROPERTY(QDate maximumDate READ maximumDate WRITE setMaximumDate RESET resetMaximumDate)
41 Q_PROPERTY(Options options READ options WRITE setOptions)
42 Q_FLAGS(Options)
43
44public:
45
46 /**
47 * Options provided by the widget
48 * @see options()
49 * @see setOptions()
50 */
51 enum Option {
52 EditDate = 0x0001, /**< Allow the user to manually edit the date in the combo line edit */
53 SelectDate = 0x0002, /**< Allow the user to select the date from a drop-down menu */
54 DatePicker = 0x0004, /**< Show a date picker in the drop-down */
55 DateKeywords = 0x0008, /**< Show date keywords in the drop-down */
56 WarnOnInvalid = 0x0010 /**< Show a warning on focus out if the date is invalid */
57 };
58 Q_DECLARE_FLAGS(Options, Option)
59
60 /**
61 * Create a new KDateComboBox widget
62 *
63 * By default the EditDate, SelectDate, DatePicker and DateKeywords options
64 * are enabled, the ShortDate format is used and the date is set to the
65 * current date.
66 */
67 explicit KDateComboBox(QWidget *parent = 0);
68
69 /**
70 * Destroy the widget
71 */
72 virtual ~KDateComboBox();
73
74 /**
75 * Return the currently selected date
76 *
77 * @return the currently selected date
78 */
79 QDate date() const;
80
81 /**
82 * Returns the Calendar System type used by the widget
83 *
84 * @see KLocale::CalendarSystem
85 * @see setCalendarSystem()
86 * @return the Calendar System currently used
87 */
88 KLocale::CalendarSystem calendarSystem() const;
89
90 /**
91 * Returns a pointer to the Calendar System object used by this widget
92 *
93 * Usually this will be the Global Calendar System using the Global Locale,
94 * but this may have been changed to a custom Calendar System possibly
95 * using a custom Locale.
96 *
97 * Normally you will not need to access this object.
98 *
99 * @see KCalendarSystem
100 * @see setCalendar
101 * @return the current calendar system instance
102 */
103 const KCalendarSystem *calendar() const;
104
105 /**
106 * Return if the current user input is valid
107 *
108 * If the user input is null then it is not valid
109 *
110 * @see isNull()
111 * @return if the current user input is valid
112 */
113 bool isValid() const;
114
115 /**
116 * Return if the current user input is null
117 *
118 * @see isValid()
119 * @return if the current user input is null
120 */
121 bool isNull() const;
122
123 /**
124 * Return the currently set widget options
125 *
126 * @return the currently set widget options
127 */
128 Options options() const;
129
130 /**
131 * Return the currently set date display format
132 *
133 * By default this is the Short Date
134 *
135 * @return the currently set date format
136 */
137 KLocale::DateFormat displayFormat() const;
138
139 /**
140 * Return the current minimum date
141 *
142 * @return the current minimum date
143 */
144 QDate minimumDate() const;
145
146 /**
147 * Return the current maximum date
148 *
149 * @return the current maximum date
150 */
151 QDate maximumDate() const;
152
153 /**
154 * Return the map of dates listed in the drop-down and their displayed
155 * string forms.
156 *
157 * @see setDateMap()
158 * @return the select date map
159 */
160 QMap<QDate, QString> dateMap() const;
161
162Q_SIGNALS:
163
164 /**
165 * Signal if the date has been manually entered or selected by the user.
166 *
167 * The returned date may be invalid.
168 *
169 * @param date the new date
170 */
171 void dateEntered(const QDate &date);
172
173 /**
174 * Signal if the date has been changed either manually by the user
175 * or programatically.
176 *
177 * The returned date may be invalid.
178 *
179 * @param date the new date
180 */
181 void dateChanged(const QDate &date);
182
183 /**
184 * Signal if the date is being manually edited by the user.
185 *
186 * The returned date may be invalid.
187 *
188 * @param date the new date
189 */
190 void dateEdited(const QDate &date);
191
192public Q_SLOTS:
193
194 /**
195 * Set the currently selected date
196 *
197 * You can set an invalid date or a date outside the valid range, validity
198 * checking is only done via isValid().
199 *
200 * @param date the new date
201 */
202 void setDate(const QDate &date);
203
204 /**
205 * Set the Calendar System used for this widget. Uses the global locale.
206 *
207 * @see KLocale::CalendarSystem
208 * @see calendarSystem()
209 * @param calendarSystem the Calendar System to use
210 */
211 void setCalendarSystem(KLocale::CalendarSystem calendarSystem);
212
213 /**
214 * Changes the calendar system to use. Can use its own local locale if set.
215 *
216 * You retain ownership of the calendar object, it will not be destroyed with the widget.
217 *
218 * @param calendar the calendar system object to use, defaults to global
219 */
220 void setCalendar(KCalendarSystem *calendar = 0);
221
222 /**
223 * Set the new widget options
224 *
225 * @param options the new widget options
226 */
227 void setOptions(Options options);
228
229 /**
230 * Sets the date format to display.
231 *
232 * By default is the Short Date format.
233 *
234 * @param format the date format to use
235 */
236 void setDisplayFormat(KLocale::DateFormat format);
237
238 /**
239 * Set the valid date range to be applied by isValid().
240 *
241 * Both dates must be valid and the minimum date must be less than or equal
242 * to the maximum date, otherwise the date range will not be set.
243 *
244 * @param minDate the minimum date
245 * @param maxDate the maximum date
246 * @param minWarnMsg the minimum warning message
247 * @param maxWarnMsg the maximum warning message
248 */
249 void setDateRange(const QDate &minDate,
250 const QDate &maxDate,
251 const QString &minWarnMsg = QString(),
252 const QString &maxWarnMsg = QString());
253
254 /**
255 * Reset the minimum and maximum date to the default values.
256 * @see setDateRange()
257 */
258 void resetDateRange();
259
260 /**
261 * Set the minimum allowed date.
262 *
263 * If the date is invalid, or greater than current maximum,
264 * then the minimum will not be set.
265 *
266 * @see minimumDate()
267 * @see maximumDate()
268 * @see setMaximumDate()
269 * @see setDateRange()
270 * @param minDate the minimum date
271 * @param minWarnMsg the minimum warning message
272 */
273 void setMinimumDate(const QDate &minTime, const QString &minWarnMsg = QString());
274
275 /**
276 * Reset the minimum date to the default
277 */
278 void resetMinimumDate();
279
280 /**
281 * Set the maximum allowed date.
282 *
283 * If the date is invalid, or less than current minimum,
284 * then the maximum will not be set.
285 *
286 * @see minimumDate()
287 * @see maximumDate()
288 * @see setMaximumDate()
289 * @see setDateRange()
290 * @param maxDate the maximum date
291 * @param maxWarnMsg the maximum warning message
292 */
293 void setMaximumDate(const QDate &maxDate, const QString &maxWarnMsg = QString());
294
295 /**
296 * Reset the maximum date to the default
297 */
298 void resetMaximumDate();
299
300 /**
301 * Set the list of dates able to be selected from the drop-down and the
302 * string form to display for those dates, e.g. "2010-01-01" and "Yesterday".
303 *
304 * Any invalid or duplicate dates will be used, the list will NOT be
305 * sorted, and the minimum and maximum date will not be affected.
306 *
307 * The @p dateMap is keyed by the date to be listed and the value is the
308 * string to be displayed. If you want the date to be displayed in the
309 * default date format then the string should be null. If you want a
310 * separator to be displayed then set the string to "seperator".
311 *
312 * @see dateMap()
313 * @param dateMap the map of dates able to be selected
314 */
315 void setDateMap(QMap<QDate, QString> dateMap);
316
317protected:
318
319 virtual bool eventFilter(QObject *object, QEvent *event);
320 virtual void showPopup();
321 virtual void hidePopup();
322 virtual void mousePressEvent(QMouseEvent *event);
323 virtual void wheelEvent(QWheelEvent *event);
324 virtual void keyPressEvent(QKeyEvent *event);
325 virtual void focusInEvent(QFocusEvent *event);
326 virtual void focusOutEvent(QFocusEvent *event);
327 virtual void resizeEvent(QResizeEvent *event);
328
329 /**
330 * Assign the date for the widget.
331 *
332 * Virtual to allow sub-classes to apply extra validation rules.
333 *
334 * @param date the new date
335 */
336 virtual void assignDate(const QDate &date);
337
338 /**
339 * Assign the calendar system for the widget.
340 *
341 * Virtual to allow sub-classes to apply extra validation rules.
342 *
343 * @param time the new time
344 */
345 virtual void assignCalendarSystem(KLocale::CalendarSystem calendarSystem);
346
347private:
348
349 friend class KDateComboBoxPrivate;
350 KDateComboBoxPrivate *const d;
351
352 Q_PRIVATE_SLOT(d, void clickDate())
353 Q_PRIVATE_SLOT(d, void selectDate(QAction*))
354 Q_PRIVATE_SLOT(d, void editDate(const QString&))
355 Q_PRIVATE_SLOT(d, void enterDate(const QDate&))
356 Q_PRIVATE_SLOT(d, void parseDate())
357
358};
359
360Q_DECLARE_OPERATORS_FOR_FLAGS(KDateComboBox::Options)
361
362#endif // KDATECOMBOBOX_H
363