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 KTIMECOMBOBOX_H
21#define KTIMECOMBOBOX_H
22
23#include <kdeui_export.h>
24
25#include <QtGui/QWidget>
26
27#include "kcombobox.h"
28#include "klocale.h"
29
30class KTimeComboBoxPrivate;
31
32class KDEUI_EXPORT KTimeComboBox : public KComboBox
33{
34 Q_OBJECT
35
36 Q_PROPERTY(QTime time READ time WRITE setTime NOTIFY timeChanged USER true)
37 Q_PROPERTY(QTime minimumTime READ minimumTime WRITE setMinimumTime RESET resetMinimumTime)
38 Q_PROPERTY(QTime maximumTime READ maximumTime WRITE setMaximumTime RESET resetMaximumTime)
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 EditTime = 0x0001, /**< Allow the user to manually edit the time in the combo line edit */
52 SelectTime = 0x0002, /**< Allow the user to select the time from a drop-down menu */
53 ForceTime = 0x0004, /**< Any set or entered time will be forced to one of the drop-down times */
54 WarnOnInvalid = 0x0008 /**< Show a warning box on focus out if the user enters an invalid time */
55 };
56 Q_DECLARE_FLAGS(Options, Option)
57
58 /**
59 * Create a new KTimeComboBox widget
60 */
61 explicit KTimeComboBox(QWidget *parent = 0);
62
63 /**
64 * Destroy the widget
65 */
66 virtual ~KTimeComboBox();
67
68 /**
69 * Return the currently selected time
70 *
71 * @return the currently selected time
72 */
73 QTime time() const;
74
75 /**
76 * Return if the current user input is valid
77 *
78 * If the user input is null then it is not valid
79 *
80 * @see isNull()
81 * @return if the current user input is valid
82 */
83 bool isValid() const;
84
85 /**
86 * Return if the current user input is null
87 *
88 * @see isValid()
89 * @return if the current user input is null
90 */
91 bool isNull() const;
92
93 /**
94 * Return the currently set widget options
95 *
96 * @return the currently set widget options
97 */
98 Options options() const;
99
100 /**
101 * Return the currently set time format
102 *
103 * By default this is the Short Time
104 *
105 * @return the currently set time format
106 */
107 KLocale::TimeFormatOptions displayFormat() const;
108
109 /**
110 * Return the current minimum time
111 *
112 * @return the current minimum time
113 */
114 QTime minimumTime() const;
115
116 /**
117 * Reset the minimum time to the default of 00:00:00.000
118 */
119 void resetMinimumTime();
120
121 /**
122 * Return the current maximum time
123 *
124 * @return the current maximum time
125 */
126 QTime maximumTime() const;
127
128 /**
129 * Reset the maximum time to the default of 23:59:59.999
130 */
131 void resetMaximumTime();
132
133 /**
134 * Set the minimum and maximum time range.
135 *
136 * If either time is invalid, or min > max then the range will not be set.
137 *
138 * @param minTime the minimum time
139 * @param maxTime the maximum time
140 * @param minWarnMsg the minimum warning message
141 * @param maxWarnMsg the maximum warning message
142 */
143 void setTimeRange(const QTime &minTime,
144 const QTime &maxTime,
145 const QString &minWarnMsg = QString(),
146 const QString &maxWarnMsg = QString());
147
148 /**
149 * Reset the minimum and maximum time to the default values.
150 */
151 void resetTimeRange();
152
153 /**
154 * Return the interval between select time list entries if set by setTimeListInterval().
155 *
156 * Returns -1 if not set.
157 *
158 * @see setTimeListInterval()
159 * @return the select time list interval in minutes
160 */
161 int timeListInterval() const;
162
163 /**
164 * Return the list of times able to be selected in the drop-down.
165 *
166 * @see setTimeList()
167 * @see timeListInterval()
168 * @see setTimeListInterval()
169 * @return the select time list
170 */
171 QList<QTime> timeList() const;
172
173Q_SIGNALS:
174
175 /**
176 * Signal if the time has been manually entered or selected by the user.
177 *
178 * The returned time may be invalid.
179 *
180 * @param time the new time
181 */
182 void timeEntered(const QTime &time);
183
184 /**
185 * Signal if the time has been changed either manually by the user
186 * or programatically.
187 *
188 * The returned time may be invalid.
189 *
190 * @param time the new time
191 */
192 void timeChanged(const QTime &time);
193
194 /**
195 * Signal if the time is being manually edited by the user.
196 *
197 * The returned time may be invalid.
198 *
199 * @param time the new time
200 */
201 void timeEdited(const QTime &time);
202
203public Q_SLOTS:
204
205 /**
206 * Set the currently selected time
207 *
208 * You can set an invalid time or a time outside the valid range, validity
209 * checking is only done via isValid().
210 *
211 * @param time the new time
212 */
213 void setTime(const QTime &time);
214
215 /**
216 * Set the new widget options
217 *
218 * @param options the new widget options
219 */
220 void setOptions(Options options);
221
222 /**
223 * Sets the time format to display.
224 *
225 * By default is the Short Time format.
226 *
227 * @param format the time format to use
228 */
229 void setDisplayFormat(KLocale::TimeFormatOptions formatOptions);
230
231 /**
232 * Set the minimum allowed time.
233 *
234 * If the time is invalid, or greater than current maximum,
235 * then the minimum will not be set.
236 *
237 * @see minimumTime()
238 * @see maximumTime()
239 * @see setMaximumTime()
240 * @see setTimeRange()
241 * @param minTime the minimum time
242 * @param minWarnMsg the minimum warning message
243 */
244 void setMinimumTime(const QTime &minTime, const QString &minWarnMsg = QString());
245
246 /**
247 * Set the maximum allowed time.
248 *
249 * If the time is invalid, or less than current minimum,
250 * then the maximum will not be set.
251 *
252 * @see minimumTime()
253 * @see maximumTime()
254 * @see setMaximumTime()
255 * @see setTimeRange()
256 * @param maxTime the maximum time
257 * @param maxWarnMsg the maximum warning message
258 */
259 void setMaximumTime(const QTime &maxTime, const QString &maxWarnMsg = QString());
260
261 /**
262 * Set the interval between times able to be selected from the drop-down.
263 *
264 * The combo drop-down will be populated with times every @param minutes
265 * apart, starting from the minimumTime() and ending at maximumTime().
266 *
267 * If the ForceInterval option is set then any time manually typed into the
268 * combo line edit will be forced to the nearest interval.
269 *
270 * This interval must be an exact divisor of the valid time range hours.
271 * For example with the default 24 hour range @p interval must divide 1440
272 * minutes exactly, meaning 1, 6 and 90 are valid but 7, 31 and 91 are not.
273 *
274 * Setting the time list interval will override any time list previously set
275 * via setTimeList().
276 *
277 * @see timeListInterval()
278 * @param minutes the time list interval to display
279 */
280 void setTimeListInterval(int minutes);
281
282 /**
283 * Set the list of times able to be selected from the drop-down.
284 *
285 * Setting the time list will override any time interval previously set via
286 * setTimeListInterval().
287 *
288 * Any invalid or duplicate times will be ignored, and the list will be
289 * sorted.
290 *
291 * The minimum and maximum time will automatically be set to the earliest
292 * and latest value in the list.
293 *
294 * @see timeList()
295 * @param timeList the list of times able to be selected
296 * @param minWarnMsg the minimum warning message
297 * @param maxWarnMsg the maximum warning message
298 */
299 void setTimeList(QList<QTime> timeList,
300 const QString &minWarnMsg = QString(),
301 const QString &maxWarnMsg = QString());
302
303protected:
304
305 virtual bool eventFilter(QObject *object, QEvent *event);
306 virtual void showPopup();
307 virtual void hidePopup();
308 virtual void mousePressEvent(QMouseEvent *event);
309 virtual void wheelEvent(QWheelEvent *event);
310 virtual void keyPressEvent(QKeyEvent *event);
311 virtual void focusInEvent(QFocusEvent *event);
312 virtual void focusOutEvent(QFocusEvent *event);
313 virtual void resizeEvent(QResizeEvent *event);
314
315 /**
316 * Assign the time for the widget.
317 *
318 * Virtual to allow sub-classes to apply extra validation rules.
319 *
320 * @param time the new time
321 */
322 virtual void assignTime(const QTime &time);
323
324private:
325
326 friend class KTimeComboBoxPrivate;
327 KTimeComboBoxPrivate *const d;
328
329 Q_PRIVATE_SLOT(d, void selectTime(int index))
330 Q_PRIVATE_SLOT(d, void editTime(const QString&))
331 Q_PRIVATE_SLOT(d, void enterTime(const QTime&))
332 Q_PRIVATE_SLOT(d, void parseTime())
333
334};
335
336Q_DECLARE_OPERATORS_FOR_FLAGS(KTimeComboBox::Options)
337
338#endif // KTIMECOMBOBOX_H
339