File indexing completed on 2024-05-12 05:35:39
0001 /* 0002 Copyright (C) 2005, S.R.Haque <srhaque@iee.org>. 0003 This file is part of the KDE project 0004 0005 This library is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Library General Public 0007 License version 2, as published by the Free Software Foundation. 0008 0009 This library is distributed in the hope that it will be useful, 0010 but WITHOUT ANY WARRANTY; without even the implied warranty of 0011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0012 Library General Public License for more details. 0013 0014 You should have received a copy of the GNU Library General Public License 0015 along with this library; see the file COPYING.LIB. If not, write to 0016 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0017 Boston, MA 02110-1301, USA. 0018 */ 0019 0020 #ifndef KTIMEZONEWIDGET_H 0021 #define KTIMEZONEWIDGET_H 0022 0023 #include <QTreeWidget> 0024 0025 class KTimeZones; 0026 0027 /** 0028 * @brief A time zone selection widget. 0029 * 0030 * \b Detail: 0031 * 0032 * This class provides for selection of one or more time zones. 0033 * 0034 * \b Example: 0035 * 0036 * To use the class to implement a system timezone selection feature: 0037 * \code 0038 * 0039 * // This adds a time zone widget to a dialog. 0040 * m_timezones = new K4TimeZoneWidget(this); 0041 * ... 0042 * \endcode 0043 * 0044 * To use the class to implement a multiple-choice custom time zone selector: 0045 * \code 0046 * 0047 * m_timezones = new K4TimeZoneWidget( this, "Time zones", vcalendarTimezones ); 0048 * m_timezones->setSelectionMode( QTreeView::MultiSelection ); 0049 * ... 0050 * \endcode 0051 * 0052 * \image html ktimezonewidget.png "KDE Time Zone Widget" 0053 * 0054 * @author S.R.Haque <srhaque@iee.org> 0055 */ 0056 0057 class K4TimeZoneWidget : public QTreeWidget 0058 { 0059 Q_OBJECT 0060 Q_PROPERTY(bool itemsCheckable READ itemsCheckable WRITE setItemsCheckable) 0061 Q_PROPERTY(QAbstractItemView::SelectionMode selectionMode READ selectionMode WRITE setSelectionMode) 0062 0063 public: 0064 /** 0065 * Constructs a time zone selection widget. 0066 * 0067 * @param parent The parent widget. 0068 * @param timeZones The time zone database to use. If 0, the system time zone 0069 * database is used. 0070 */ 0071 explicit K4TimeZoneWidget(QWidget *parent = nullptr); 0072 0073 /** 0074 * Destroys the time zone selection widget. 0075 */ 0076 ~K4TimeZoneWidget() override; 0077 0078 /** 0079 * Makes all items show a checkbox, so that the user can select multiple 0080 * timezones by means of checking checkboxes, rather than via multi-selection. 0081 * 0082 * In "items checkable" mode, the selection(), setSelected() and clearSelection() 0083 * methods work on the check states rather than on selecting/unselecting. 0084 * 0085 * @since 4.4 0086 */ 0087 void setItemsCheckable(bool enable); 0088 /** 0089 * @return true if setItemsCheckable(true) was called. 0090 * @since 4.4 0091 */ 0092 bool itemsCheckable() const; 0093 0094 /** 0095 * Allows to select multiple timezones. This is the same as 0096 * setSelectionMode(K4TimeZoneWidget::MultiSelection) normally, 0097 * but in "items checkable" mode, this is rather about allowing to 0098 * check multiple items. In that case, the actual QTreeWidget selection 0099 * mode remains unchanged. 0100 * @since 4.4 0101 */ 0102 void setSelectionMode(QAbstractItemView::SelectionMode mode); 0103 0104 /** 0105 * @return the selection mode set by setSelectionMode(). 0106 * @since 4.4 0107 */ 0108 QAbstractItemView::SelectionMode selectionMode() const; 0109 0110 /** 0111 * Returns the currently selected time zones. See QTreeView::selectionChanged(). 0112 * 0113 * @return a list of time zone names, in the format used by the database 0114 * supplied to the {@link K4TimeZoneWidget() } constructor. 0115 */ 0116 QStringList selection() const; 0117 0118 /** 0119 * Select/deselect the named time zone. 0120 * 0121 * @param zone The time zone name to be selected. Ignored if not recognized! 0122 * @param selected The new selection state. 0123 */ 0124 void setSelected(const QString &zone, bool selected); 0125 0126 /** 0127 * Unselect all timezones. 0128 * This is the same as QTreeWidget::clearSelection, except in checkable items mode, 0129 * where items are all unchecked. 0130 * The overload is @since 4.4. 0131 */ 0132 void clearSelection(); 0133 0134 private: 0135 class Private; 0136 Private *const d; 0137 }; 0138 0139 #endif