1/*
2 SPDX-FileCopyrightText: 2004 Bram Schoenmakers <bramschoenmakers@kde.nl>
3 SPDX-License-Identifier: LGPL-2.0-or-later
4*/
5
6#ifndef KDATEPICKERPOPUP_H
7#define KDATEPICKERPOPUP_H
8
9#include <kwidgetsaddons_export.h>
10
11#include <QDate>
12#include <QMenu>
13
14#include <memory>
15
16class KDatePicker;
17class KDatePickerPopupPrivate;
18
19/**
20 * @short This menu helps the user to select a date quickly.
21 *
22 * This menu helps the user to select a date quickly. It offers various
23 * modes of selecting, e.g. with a KDatePicker or with words like "Tomorrow".
24 *
25 * The available modes are:
26 *
27 * @li NoDate: A menu-item with "No Date". If chosen, the datepicker will emit
28 * a null QDate.
29 * @li DatePicker: Shows a KDatePicker-widget.
30 * @li Words: Shows items like "Today", "Tomorrow" or "Next Week".
31 *
32 * @author Bram Schoenmakers <bram_s@softhome.net>
33 *
34 * @since 5.94
35 */
36class KWIDGETSADDONS_EXPORT KDatePickerPopup : public QMenu
37{
38 Q_OBJECT
39 Q_PROPERTY(Modes modes READ modes WRITE setModes)
40
41public:
42 /**
43 * Describes the available selection modes.
44 */
45 enum Mode {
46 NoDate = 1, ///< A menu-item with "No Date". Will always return an invalid date.
47 DatePicker = 2, ///< A menu-item with a KDatePicker.
48 Words = 4 ///< A menu-item with list of words that describe a date.
49 };
50
51 /**
52 * Describes a set of combined modes.
53 */
54 Q_DECLARE_FLAGS(Modes, Mode)
55
56 /**
57 * Creates a new date picker popup.
58 *
59 * @param modes The selection modes that shall be offered
60 * @param date The initial date of date picker widget.
61 * @param parent The parent object.
62 */
63 explicit KDatePickerPopup(Modes modes = DatePicker, QDate date = QDate::currentDate(), QWidget *parent = nullptr);
64
65 /**
66 * Destroys the date picker popup.
67 */
68 ~KDatePickerPopup() override;
69
70 /**
71 * Returns the currently used selection modes.
72 */
73 Modes modes() const;
74
75 /**
76 * Set the selection modes to use.
77 */
78 void setModes(Modes modes);
79
80 /**
81 * Sets the range of dates that can be accepted.
82 *
83 * Invalid dates can be used to define open-ended ranges.
84 * If both values are valid, the minimum date must be less than
85 * or equal to the maximum date, otherwise the date range will
86 * not be set.
87 *
88 * @param minDate the minimum date
89 * @param maxDate the maximum date
90 */
91 void setDateRange(const QDate &minDate, const QDate &maxDate);
92
93 /**
94 * Return the map of dates listed in the drop-down and their displayed
95 * string forms.
96 *
97 * @return the select date map
98 *
99 * @see setDateMap()
100 */
101 QMap<QDate, QString> dateMap() const;
102
103 /**
104 * Sets the list of dates in the drop-down menu that the user can select from
105 * and the text string to display for each date, e.g. "2010-01-01" and "Yesterday".
106 *
107 * The list of date/string pairs is used as-is (invalid or duplicate dates aren't removed),
108 * and the order will not be changed (the map is sorted by key); also and the minimum and
109 * maximum dates will not be affected.
110 *
111 * The @p dateMap is keyed by the date to be listed and the value is the
112 * string to be displayed. If you want the date to be displayed in the
113 * default date format then the string should be null. If you want a
114 * separator to be displayed then set the string to "separator".
115 *
116 * @param dateMap the map of dates the user can select from
117 *
118 * @see dateMap()
119 */
120 void setDateMap(const QMap<QDate, QString> &dateMap);
121
122 /**
123 * Returns the used KDatePicker object.
124 */
125 Q_REQUIRED_RESULT KDatePicker *datePicker() const;
126
127public Q_SLOTS:
128 /**
129 * Sets the current @p date.
130 */
131 void setDate(QDate date);
132
133Q_SIGNALS:
134 /**
135 * This signal is emitted whenever the user has selected a new date.
136 *
137 * @param date The new date.
138 */
139 void dateChanged(const QDate &date);
140
141private:
142 //@cond PRIVATE
143 std::unique_ptr<KDatePickerPopupPrivate> const d;
144 //@endcond
145};
146
147Q_DECLARE_OPERATORS_FOR_FLAGS(KDatePickerPopup::Modes)
148
149#endif
150

source code of kwidgetsaddons/src/kdatepickerpopup.h