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

source code of kwidgetsaddons/src/ktimecombobox.h