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 | |
30 | class KTimeComboBoxPrivate; |
31 | |
32 | class 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 | |
43 | public: |
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 | |
173 | Q_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 | |
203 | public 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 | |
303 | protected: |
304 | |
305 | virtual bool eventFilter(QObject *object, QEvent *event); |
306 | virtual void (); |
307 | virtual void (); |
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 | |
324 | private: |
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 | |
336 | Q_DECLARE_OPERATORS_FOR_FLAGS(KTimeComboBox::Options) |
337 | |
338 | #endif // KTIMECOMBOBOX_H |
339 | |