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

source code of kwidgetsaddons/src/ktimecombobox.h