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 | |
31 | class KDateComboBoxPrivate; |
32 | class KCalendarSystem; |
33 | |
34 | class 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 | |
44 | public: |
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 | |
162 | Q_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 | |
192 | public 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 | |
317 | protected: |
318 | |
319 | virtual bool eventFilter(QObject *object, QEvent *event); |
320 | virtual void (); |
321 | virtual void (); |
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 | |
347 | private: |
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 | |
360 | Q_DECLARE_OPERATORS_FOR_FLAGS(KDateComboBox::Options) |
361 | |
362 | #endif // KDATECOMBOBOX_H |
363 | |