File indexing completed on 2024-04-21 14:55:49
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 <kdelibs4support_export.h> 0024 0025 #include <QTreeWidget> 0026 0027 class KTimeZone; 0028 class KTimeZones; 0029 0030 /** 0031 * @brief A time zone selection widget. 0032 * 0033 * \b Detail: 0034 * 0035 * This class provides for selection of one or more time zones. 0036 * 0037 * \b Example: 0038 * 0039 * To use the class to implement a system timezone selection feature: 0040 * \code 0041 * 0042 * // This adds a time zone widget to a dialog. 0043 * m_timezones = new K4TimeZoneWidget(this); 0044 * ... 0045 * \endcode 0046 * 0047 * To use the class to implement a multiple-choice custom time zone selector: 0048 * \code 0049 * 0050 * m_timezones = new K4TimeZoneWidget( this, "Time zones", vcalendarTimezones ); 0051 * m_timezones->setSelectionMode( QTreeView::MultiSelection ); 0052 * ... 0053 * \endcode 0054 * 0055 * \image html ktimezonewidget.png "KDE Time Zone Widget" 0056 * 0057 * @author S.R.Haque <srhaque@iee.org> 0058 */ 0059 class KDELIBS4SUPPORT_EXPORT K4TimeZoneWidget : public QTreeWidget 0060 { 0061 Q_OBJECT 0062 Q_PROPERTY(bool itemsCheckable READ itemsCheckable WRITE setItemsCheckable) 0063 Q_PROPERTY(QAbstractItemView::SelectionMode selectionMode READ selectionMode WRITE setSelectionMode) 0064 0065 public: 0066 /** 0067 * Constructs a time zone selection widget. 0068 * 0069 * @param parent The parent widget. 0070 * @param timeZones The time zone database to use. If 0, the system time zone 0071 * database is used. 0072 */ 0073 KDELIBS4SUPPORT_DEPRECATED explicit K4TimeZoneWidget(QWidget *parent = nullptr, KTimeZones *timeZones = nullptr); 0074 0075 /** 0076 * Destroys the time zone selection widget. 0077 */ 0078 ~K4TimeZoneWidget() override; 0079 0080 /** 0081 * Makes all items show a checkbox, so that the user can select multiple 0082 * timezones by means of checking checkboxes, rather than via multi-selection. 0083 * 0084 * In "items checkable" mode, the selection(), setSelected() and clearSelection() 0085 * methods work on the check states rather than on selecting/unselecting. 0086 * 0087 * @since 4.4 0088 */ 0089 void setItemsCheckable(bool enable); 0090 /** 0091 * @return true if setItemsCheckable(true) was called. 0092 * @since 4.4 0093 */ 0094 bool itemsCheckable() const; 0095 0096 /** 0097 * Allows to select multiple timezones. This is the same as 0098 * setSelectionMode(K4TimeZoneWidget::MultiSelection) normally, 0099 * but in "items checkable" mode, this is rather about allowing to 0100 * check multiple items. In that case, the actual QTreeWidget selection 0101 * mode remains unchanged. 0102 * @since 4.4 0103 */ 0104 void setSelectionMode(QAbstractItemView::SelectionMode mode); 0105 0106 /** 0107 * @return the selection mode set by setSelectionMode(). 0108 * @since 4.4 0109 */ 0110 QAbstractItemView::SelectionMode selectionMode() const; 0111 0112 /** 0113 * Returns the currently selected time zones. See QTreeView::selectionChanged(). 0114 * 0115 * @return a list of time zone names, in the format used by the database 0116 * supplied to the {@link K4TimeZoneWidget() } constructor. 0117 */ 0118 QStringList selection() const; 0119 0120 /** 0121 * Select/deselect the named time zone. 0122 * 0123 * @param zone The time zone name to be selected. Ignored if not recognized! 0124 * @param selected The new selection state. 0125 */ 0126 void setSelected(const QString &zone, bool selected); 0127 0128 /** 0129 * Unselect all timezones. 0130 * This is the same as QTreeWidget::clearSelection, except in checkable items mode, 0131 * where items are all unchecked. 0132 * The overload is @since 4.4. 0133 */ 0134 void clearSelection(); 0135 0136 /** 0137 * Format a time zone name in a standardised manner. 0138 * 0139 * @return formatted time zone name. 0140 */ 0141 static QString displayName(const KTimeZone &zone); 0142 0143 private: 0144 class Private; 0145 Private *const d; 0146 }; 0147 0148 #endif