File indexing completed on 2025-02-02 14:20:00
0001 /* 0002 SPDX-FileCopyrightText: 2004 Bram Schoenmakers <bramschoenmakers@kde.nl> 0003 SPDX-License-Identifier: LGPL-2.0-or-later 0004 */ 0005 0006 #ifndef KDATEPICKERPOPUP_H 0007 #define KDATEPICKERPOPUP_H 0008 0009 #include <kwidgetsaddons_export.h> 0010 0011 #include <QDate> 0012 #include <QMenu> 0013 0014 #include <memory> 0015 0016 class KDatePicker; 0017 class KDatePickerPopupPrivate; 0018 0019 /** 0020 * @short This menu helps the user to select a date quickly. 0021 * 0022 * This menu helps the user to select a date quickly. It offers various 0023 * modes of selecting, e.g. with a KDatePicker or with words like "Tomorrow". 0024 * 0025 * The available modes are: 0026 * 0027 * @li NoDate: A menu-item with "No Date". If chosen, the datepicker will emit 0028 * a null QDate. 0029 * @li DatePicker: Shows a KDatePicker-widget. 0030 * @li Words: Shows items like "Today", "Tomorrow" or "Next Week". 0031 * 0032 * @author Bram Schoenmakers <bram_s@softhome.net> 0033 * 0034 * @since 5.94 0035 */ 0036 class KWIDGETSADDONS_EXPORT KDatePickerPopup : public QMenu 0037 { 0038 Q_OBJECT 0039 Q_PROPERTY(Modes modes READ modes WRITE setModes) 0040 0041 public: 0042 /** 0043 * Describes the available selection modes. 0044 */ 0045 enum Mode { 0046 NoDate = 1, ///< A menu-item with "No Date". Will always return an invalid date. 0047 DatePicker = 2, ///< A menu-item with a KDatePicker. 0048 Words = 4 ///< A menu-item with list of words that describe a date. 0049 }; 0050 0051 /** 0052 * Describes a set of combined modes. 0053 */ 0054 Q_DECLARE_FLAGS(Modes, Mode) 0055 0056 /** 0057 * Creates a new date picker popup. 0058 * 0059 * @param modes The selection modes that shall be offered 0060 * @param date The initial date of date picker widget. 0061 * @param parent The parent object. 0062 */ 0063 explicit KDatePickerPopup(Modes modes = DatePicker, QDate date = QDate::currentDate(), QWidget *parent = nullptr); 0064 0065 /** 0066 * Destroys the date picker popup. 0067 */ 0068 ~KDatePickerPopup() override; 0069 0070 /** 0071 * Returns the currently used selection modes. 0072 */ 0073 Modes modes() const; 0074 0075 /** 0076 * Set the selection modes to use. 0077 */ 0078 void setModes(Modes modes); 0079 0080 /** 0081 * Sets the range of dates that can be accepted. 0082 * 0083 * Invalid dates can be used to define open-ended ranges. 0084 * If both values are valid, the minimum date must be less than 0085 * or equal to the maximum date, otherwise the date range will 0086 * not be set. 0087 * 0088 * @param minDate the minimum date 0089 * @param maxDate the maximum date 0090 */ 0091 void setDateRange(const QDate &minDate, const QDate &maxDate); 0092 0093 /** 0094 * Return the map of dates listed in the drop-down and their displayed 0095 * string forms. 0096 * 0097 * @return the select date map 0098 * 0099 * @see setDateMap() 0100 */ 0101 QMap<QDate, QString> dateMap() const; 0102 0103 /** 0104 * Sets the list of dates in the drop-down menu that the user can select from 0105 * and the text string to display for each date, e.g. "2010-01-01" and "Yesterday". 0106 * 0107 * The list of date/string pairs is used as-is (invalid or duplicate dates aren't removed), 0108 * and the order will not be changed (the map is sorted by key); also and the minimum and 0109 * maximum dates will not be affected. 0110 * 0111 * The @p dateMap is keyed by the date to be listed and the value is the 0112 * string to be displayed. If you want the date to be displayed in the 0113 * default date format then the string should be null. If you want a 0114 * separator to be displayed then set the string to "separator". 0115 * 0116 * @param dateMap the map of dates the user can select from 0117 * 0118 * @see dateMap() 0119 */ 0120 void setDateMap(const QMap<QDate, QString> &dateMap); 0121 0122 /** 0123 * Returns the used KDatePicker object. 0124 */ 0125 Q_REQUIRED_RESULT KDatePicker *datePicker() const; 0126 0127 public Q_SLOTS: 0128 /** 0129 * Sets the current @p date. 0130 */ 0131 void setDate(QDate date); 0132 0133 Q_SIGNALS: 0134 /** 0135 * This signal is emitted whenever the user has selected a new date. 0136 * 0137 * @param date The new date. 0138 */ 0139 void dateChanged(const QDate &date); 0140 0141 private: 0142 //@cond PRIVATE 0143 std::unique_ptr<KDatePickerPopupPrivate> const d; 0144 //@endcond 0145 }; 0146 0147 Q_DECLARE_OPERATORS_FOR_FLAGS(KDatePickerPopup::Modes) 0148 0149 #endif