KWidgetsAddons

kdatecombobox.h
1/*
2 SPDX-FileCopyrightText: 2011 John Layt <john@layt.net>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KDATECOMBOBOX_H
8#define KDATECOMBOBOX_H
9
10#include <kwidgetsaddons_export.h>
11
12#include <QComboBox>
13#include <QLocale>
14#include <memory>
15
16/**
17 * @class KDateComboBox kdatecombobox.h KDateComboBox
18 *
19 * @short A combobox for dates.
20 */
21class KWIDGETSADDONS_EXPORT KDateComboBox : public QComboBox
22{
23 Q_OBJECT
24
25 Q_PROPERTY(QDate date READ date WRITE setDate NOTIFY dateChanged USER true)
26 Q_PROPERTY(QDate minimumDate READ minimumDate WRITE setMinimumDate RESET resetMinimumDate)
27 Q_PROPERTY(QDate maximumDate READ maximumDate WRITE setMaximumDate RESET resetMaximumDate)
28 Q_PROPERTY(Options options READ options WRITE setOptions)
29
30public:
31 /**
32 * Options provided by the widget
33 * @see options()
34 * @see setOptions()
35 * @see Options
36 */
37 enum Option {
38 EditDate = 0x0001, /**< Allow the user to manually edit the date in the combo line edit */
39 SelectDate = 0x0002, /**< Allow the user to select the date from a drop-down menu */
40 DatePicker = 0x0004, /**< Show a date picker in the drop-down */
41 DateKeywords = 0x0008, /**< Show date keywords in the drop-down */
42 WarnOnInvalid = 0x0010, /**< Show a warning on focus out if the date is invalid */
43 };
44 /**
45 * Stores a combination of #Option values.
46 */
47 Q_DECLARE_FLAGS(Options, Option)
49
50 /**
51 * Create a new KDateComboBox widget
52 *
53 * By default the EditDate, SelectDate, DatePicker and DateKeywords options
54 * are enabled, the ShortDate format is used and the date is set to the
55 * current date.
56 */
57 explicit KDateComboBox(QWidget *parent = nullptr);
58
59 /**
60 * Destroy the widget
61 */
62 ~KDateComboBox() override;
63
64 /**
65 * Return the currently selected date
66 *
67 * @return the currently selected date
68 */
69 QDate date() const;
70
71 /**
72 * Return if the current user input is valid
73 *
74 * If the user input is null then it is not valid
75 *
76 * @return if the current user input is valid
77 *
78 * @see isNull()
79 */
80 bool isValid() const;
81
82 /**
83 * Return if the current user input is null
84 *
85 * @return if the current user input is null
86 *
87 * @see isValid()
88 */
89 bool isNull() const;
90
91 /**
92 * Return the currently set widget options
93 *
94 * @return the currently set widget options
95 */
96 Options options() const;
97
98 /**
99 * Return the currently set date display format
100 *
101 * By default this is the Short Format
102 *
103 * @return the currently set date format
104 */
105 QLocale::FormatType displayFormat() const;
106
107 /**
108 * Return the current minimum date
109 *
110 * @return the current minimum date
111 */
112 QDate minimumDate() const;
113
114 /**
115 * Return the current maximum date
116 *
117 * @return the current maximum date
118 */
119 QDate maximumDate() const;
120
121 /**
122 * Return the map of dates listed in the drop-down and their displayed
123 * string forms.
124 *
125 * @return the select date map
126 *
127 * @see setDateMap()
128 */
129 QMap<QDate, QString> dateMap() const;
130
132
133 /**
134 * Signal if the date has been manually entered (by typing a date and losing focus, or pressing Enter)
135 * or selected by the user (using the popup selector, or up, down, page up, page down keys, or the mouse wheel).
136 *
137 * The emitted date may be invalid.
138 *
139 * @param date the new date
140 */
141 void dateEntered(const QDate &date);
142
143 /**
144 * Signal if the date has been changed either manually by the user
145 * or programmatically.
146 *
147 * The emitted date may be invalid.
148 *
149 * @param date the new date
150 */
151 void dateChanged(const QDate &date);
152
153 /**
154 * Signal if the date is being manually edited by the user.
155 *
156 * The emitted date may be invalid, or may not yet be what the user intends as the final date.
157 *
158 * @param date the new date
159 */
160 void dateEdited(const QDate &date);
161
162public Q_SLOTS:
163
164 /**
165 * Set the currently selected date
166 *
167 * You can set an invalid date or a date outside the valid range, validity
168 * checking is only done via isValid().
169 *
170 * @param date the new date
171 */
172 void setDate(const QDate &date);
173
174 /**
175 * Set the new widget options
176 *
177 * @param options the new widget options
178 */
179 void setOptions(Options options);
180
181 /**
182 * Sets the date format to display.
183 *
184 * By default is the Short Format.
185 *
186 * @param format the date format to use
187 */
188 void setDisplayFormat(QLocale::FormatType format);
189
190 /**
191 * Set the valid date range to be applied by isValid().
192 *
193 * Both dates must be valid and the minimum date must be less than or equal
194 * to the maximum date, otherwise the date range will not be set.
195 *
196 * @param minDate the minimum date
197 * @param maxDate the maximum date
198 * @param minWarnMsg the minimum warning message
199 * @param maxWarnMsg the maximum warning message
200 */
201 void setDateRange(const QDate &minDate, const QDate &maxDate, const QString &minWarnMsg = QString(), const QString &maxWarnMsg = QString());
202
203 /**
204 * Reset the minimum and maximum date to the default values.
205 * @see setDateRange()
206 */
207 void resetDateRange();
208
209 /**
210 * Set the minimum allowed date.
211 *
212 * If the date is invalid, or greater than current maximum,
213 * then the minimum will not be set.
214 *
215 * @param minDate the minimum date
216 * @param minWarnMsg the minimum warning message
217 *
218 * @see minimumDate()
219 * @see maximumDate()
220 * @see setMaximumDate()
221 * @see setDateRange()
222 */
223 void setMinimumDate(const QDate &minDate, const QString &minWarnMsg = QString());
224
225 /**
226 * Reset the minimum date to the default.
227 *
228 * The default is to have no minimum date.
229 */
230 void resetMinimumDate();
231
232 /**
233 * Set the maximum allowed date.
234 *
235 * If the date is invalid, or less than current minimum,
236 * then the maximum will not be set.
237 *
238 * @param maxDate the maximum date
239 * @param maxWarnMsg the maximum warning message
240 *
241 * @see minimumDate()
242 * @see maximumDate()
243 * @see setMaximumDate()
244 * @see setDateRange()
245 */
246 void setMaximumDate(const QDate &maxDate, const QString &maxWarnMsg = QString());
247
248 /**
249 * Reset the maximum date to the default
250 *
251 * The default is to have no maximum date.
252 */
253 void resetMaximumDate();
254
255 /**
256 * Set the list of dates able to be selected from the drop-down and the
257 * string form to display for those dates, e.g. "2010-01-01" and "Yesterday".
258 *
259 * Any invalid or duplicate dates will be used, the list will NOT be
260 * sorted, and the minimum and maximum date will not be affected.
261 *
262 * The @p dateMap is keyed by the date to be listed and the value is the
263 * string to be displayed. If you want the date to be displayed in the
264 * default date format then the string should be null. If you want a
265 * separator to be displayed then set the string to "separator".
266 *
267 * @param dateMap the map of dates able to be selected
268 *
269 * @see dateMap()
270 */
271 void setDateMap(QMap<QDate, QString> dateMap);
272
273protected:
274 bool eventFilter(QObject *object, QEvent *event) override;
275 void showPopup() override;
276 void hidePopup() override;
277 void mousePressEvent(QMouseEvent *event) override;
278 void wheelEvent(QWheelEvent *event) override;
279 void keyPressEvent(QKeyEvent *event) override;
280 void focusInEvent(QFocusEvent *event) override;
281 void focusOutEvent(QFocusEvent *event) override;
282 void resizeEvent(QResizeEvent *event) override;
283
284 /**
285 * Assign the date for the widget.
286 *
287 * Virtual to allow sub-classes to apply extra validation rules.
288 *
289 * @param date the new date
290 */
291 virtual void assignDate(const QDate &date);
292
293private:
294 friend class KDateComboBoxPrivate;
295 std::unique_ptr<class KDateComboBoxPrivate> const d;
296};
297
298Q_DECLARE_OPERATORS_FOR_FLAGS(KDateComboBox::Options)
299
300#endif // KDATECOMBOBOX_H
A combobox for dates.
void dateEdited(const QDate &date)
Signal if the date is being manually edited by the user.
Option
Options provided by the widget.
void dateChanged(const QDate &date)
Signal if the date has been changed either manually by the user or programmatically.
void dateEntered(const QDate &date)
Signal if the date has been manually entered (by typing a date and losing focus, or pressing Enter) o...
~KDateComboBox() override
Destroy the widget.
virtual void focusInEvent(QFocusEvent *e) override
virtual void focusOutEvent(QFocusEvent *e) override
virtual void hidePopup()
virtual void keyPressEvent(QKeyEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void resizeEvent(QResizeEvent *e) override
virtual void showPopup()
virtual void wheelEvent(QWheelEvent *e) override
Q_FLAG(...)
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
virtual bool eventFilter(QObject *watched, QEvent *event)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:14:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.