Warning, file /frameworks/kwidgetsaddons/src/ktimecombobox.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
0001 /* 0002 SPDX-FileCopyrightText: 2011 John Layt <john@layt.net> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef KTIMECOMBOBOX_H 0008 #define KTIMECOMBOBOX_H 0009 0010 #include <kwidgetsaddons_export.h> 0011 0012 #include <QComboBox> 0013 #include <QLocale> 0014 #include <memory> 0015 0016 /** 0017 * @class KTimeComboBox ktimecombobox.h KTimeComboBox 0018 * 0019 * @short A combobox for times. 0020 */ 0021 class KWIDGETSADDONS_EXPORT KTimeComboBox : public QComboBox 0022 { 0023 Q_OBJECT 0024 0025 Q_PROPERTY(QTime time READ time WRITE setTime NOTIFY timeChanged USER true) 0026 Q_PROPERTY(QTime minimumTime READ minimumTime WRITE setMinimumTime RESET resetMinimumTime) 0027 Q_PROPERTY(QTime maximumTime READ maximumTime WRITE setMaximumTime RESET resetMaximumTime) 0028 Q_PROPERTY(int timeListInterval READ timeListInterval WRITE setTimeListInterval) 0029 Q_PROPERTY(Options options READ options WRITE setOptions) 0030 0031 public: 0032 /** 0033 * Options provided by the widget 0034 * @see options 0035 * @see setOptions 0036 * @see Options 0037 */ 0038 enum Option { 0039 EditTime = 0x0001, /**< Allow the user to manually edit the time in the combo line edit */ 0040 SelectTime = 0x0002, /**< Allow the user to select the time from a drop-down menu */ 0041 ForceTime = 0x0004, /**< Any set or entered time will be forced to one of the drop-down times */ 0042 WarnOnInvalid = 0x0008, /**< Show a warning box on focus out if the user enters an invalid time */ 0043 }; 0044 /** 0045 * Stores a combination of #Option values. 0046 */ 0047 Q_DECLARE_FLAGS(Options, Option) 0048 Q_FLAG(Options) 0049 0050 /** 0051 * Create a new KTimeComboBox widget 0052 */ 0053 explicit KTimeComboBox(QWidget *parent = nullptr); 0054 0055 /** 0056 * Destroy the widget 0057 */ 0058 ~KTimeComboBox() override; 0059 0060 /** 0061 * Return the currently selected time 0062 * 0063 * @return the currently selected time 0064 */ 0065 QTime time() const; 0066 0067 /** 0068 * Return if the current user input is valid 0069 * 0070 * If the user input is null then it is not valid 0071 * 0072 * @return if the current user input is valid 0073 * 0074 * @see isNull() 0075 */ 0076 bool isValid() const; 0077 0078 /** 0079 * Return if the current user input is null 0080 * 0081 * @return if the current user input is null 0082 * 0083 * @see isValid() 0084 */ 0085 bool isNull() const; 0086 0087 /** 0088 * Return the currently set widget options 0089 * 0090 * @return the currently set widget options 0091 */ 0092 Options options() const; 0093 0094 /** 0095 * Return the currently set time format 0096 * 0097 * By default this is the Short Format 0098 * 0099 * @return the currently set time format 0100 */ 0101 QLocale::FormatType displayFormat() const; 0102 0103 /** 0104 * Return the current minimum time 0105 * 0106 * @return the current minimum time 0107 */ 0108 QTime minimumTime() const; 0109 0110 /** 0111 * Reset the minimum time to the default of 00:00:00.000 0112 */ 0113 void resetMinimumTime(); 0114 0115 /** 0116 * Return the current maximum time 0117 * 0118 * @return the current maximum time 0119 */ 0120 QTime maximumTime() const; 0121 0122 /** 0123 * Reset the maximum time to the default of 23:59:59.999 0124 */ 0125 void resetMaximumTime(); 0126 0127 /** 0128 * Set the minimum and maximum time range. 0129 * 0130 * If either time is invalid, or min > max then the range will not be set. 0131 * 0132 * @param minTime the minimum time 0133 * @param maxTime the maximum time 0134 * @param minWarnMsg the minimum warning message 0135 * @param maxWarnMsg the maximum warning message 0136 */ 0137 void setTimeRange(const QTime &minTime, const QTime &maxTime, const QString &minWarnMsg = QString(), const QString &maxWarnMsg = QString()); 0138 0139 /** 0140 * Reset the minimum and maximum time to the default values. 0141 */ 0142 void resetTimeRange(); 0143 0144 /** 0145 * Return the interval between select time list entries if set by setTimeListInterval(). 0146 * 0147 * Returns -1 if not set. 0148 * 0149 * @return the select time list interval in minutes 0150 * 0151 * @see setTimeListInterval() 0152 */ 0153 int timeListInterval() const; 0154 0155 /** 0156 * Return the list of times able to be selected in the drop-down. 0157 * 0158 * @return the select time list 0159 * 0160 * @see setTimeList() 0161 * @see timeListInterval() 0162 * @see setTimeListInterval() 0163 */ 0164 QList<QTime> timeList() const; 0165 0166 Q_SIGNALS: 0167 0168 /** 0169 * Signal if the time has been manually entered or selected by the user. 0170 * 0171 * The returned time may be invalid. 0172 * 0173 * @param time the new time 0174 */ 0175 void timeEntered(const QTime &time); 0176 0177 /** 0178 * Signal if the time has been changed either manually by the user 0179 * or programmatically. 0180 * 0181 * The returned time may be invalid. 0182 * 0183 * @param time the new time 0184 */ 0185 void timeChanged(const QTime &time); 0186 0187 /** 0188 * Signal if the time is being manually edited by the user. 0189 * 0190 * The returned time may be invalid. 0191 * 0192 * @param time the new time 0193 */ 0194 void timeEdited(const QTime &time); 0195 0196 public Q_SLOTS: 0197 0198 /** 0199 * Set the currently selected time 0200 * 0201 * You can set an invalid time or a time outside the valid range, validity 0202 * checking is only done via isValid(). 0203 * 0204 * @param time the new time 0205 */ 0206 void setTime(const QTime &time); 0207 0208 /** 0209 * Set the new widget options 0210 * 0211 * @param options the new widget options 0212 */ 0213 void setOptions(Options options); 0214 0215 /** 0216 * Sets the time format to display. 0217 * 0218 * By default is the Short Format. 0219 * 0220 * @param format the time format to use 0221 */ 0222 void setDisplayFormat(QLocale::FormatType format); 0223 0224 /** 0225 * Set the minimum allowed time. 0226 * 0227 * If the time is invalid, or greater than current maximum, 0228 * then the minimum will not be set. 0229 * 0230 * @param minTime the minimum time 0231 * @param minWarnMsg the minimum warning message 0232 * 0233 * @see minimumTime() 0234 * @see maximumTime() 0235 * @see setMaximumTime() 0236 * @see setTimeRange() 0237 */ 0238 void setMinimumTime(const QTime &minTime, const QString &minWarnMsg = QString()); 0239 0240 /** 0241 * Set the maximum allowed time. 0242 * 0243 * If the time is invalid, or less than current minimum, 0244 * then the maximum will not be set. 0245 * 0246 * @param maxTime the maximum time 0247 * @param maxWarnMsg the maximum warning message 0248 * 0249 * @see minimumTime() 0250 * @see maximumTime() 0251 * @see setMaximumTime() 0252 * @see setTimeRange() 0253 */ 0254 void setMaximumTime(const QTime &maxTime, const QString &maxWarnMsg = QString()); 0255 0256 /** 0257 * Set the interval between times able to be selected from the drop-down. 0258 * 0259 * The combo drop-down will be populated with times every @p minutes 0260 * apart, starting from the minimumTime() and ending at maximumTime(). 0261 * 0262 * If the ForceInterval option is set then any time manually typed into the 0263 * combo line edit will be forced to the nearest interval. 0264 * 0265 * This interval must be an exact divisor of the valid time range hours. 0266 * For example with the default 24 hour range @p interval must divide 1440 0267 * minutes exactly, meaning 1, 6 and 90 are valid but 7, 31 and 91 are not. 0268 * 0269 * Setting the time list interval will override any time list previously set 0270 * via setTimeList(). 0271 * 0272 * @param minutes the time list interval to display 0273 * 0274 * @see timeListInterval() 0275 */ 0276 void setTimeListInterval(int minutes); 0277 0278 /** 0279 * Set the list of times able to be selected from the drop-down. 0280 * 0281 * Setting the time list will override any time interval previously set via 0282 * setTimeListInterval(). 0283 * 0284 * Any invalid or duplicate times will be ignored, and the list will be 0285 * sorted. 0286 * 0287 * The minimum and maximum time will automatically be set to the earliest 0288 * and latest value in the list. 0289 * 0290 * @param timeList the list of times able to be selected 0291 * @param minWarnMsg the minimum warning message 0292 * @param maxWarnMsg the maximum warning message 0293 * 0294 * @see timeList() 0295 */ 0296 void setTimeList(QList<QTime> timeList, const QString &minWarnMsg = QString(), const QString &maxWarnMsg = QString()); 0297 0298 protected: 0299 bool eventFilter(QObject *object, QEvent *event) override; 0300 void showPopup() override; 0301 void hidePopup() override; 0302 void mousePressEvent(QMouseEvent *event) override; 0303 void wheelEvent(QWheelEvent *event) override; 0304 void keyPressEvent(QKeyEvent *event) override; 0305 void focusInEvent(QFocusEvent *event) override; 0306 void focusOutEvent(QFocusEvent *event) override; 0307 void resizeEvent(QResizeEvent *event) override; 0308 0309 /** 0310 * Assign the time for the widget. 0311 * 0312 * Virtual to allow sub-classes to apply extra validation rules. 0313 * 0314 * @param time the new time 0315 */ 0316 virtual void assignTime(const QTime &time); 0317 0318 private: 0319 friend class KTimeComboBoxPrivate; 0320 std::unique_ptr<class KTimeComboBoxPrivate> const d; 0321 }; 0322 0323 Q_DECLARE_OPERATORS_FOR_FLAGS(KTimeComboBox::Options) 0324 0325 #endif // KTIMECOMBOBOX_H