1 | /* |
2 | Copyright (C) 2005, S.R.Haque <srhaque@iee.org>. |
3 | This file is part of the KDE project |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License version 2, as published by the Free Software Foundation. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KTIMEZONEWIDGET_H |
21 | #define KTIMEZONEWIDGET_H |
22 | |
23 | #include <kdeui_export.h> |
24 | |
25 | #include <QtGui/QTreeWidget> |
26 | |
27 | class KTimeZone; |
28 | class KTimeZones; |
29 | |
30 | /** |
31 | * @brief A time zone selection widget. |
32 | * |
33 | * \b Detail: |
34 | * |
35 | * This class provides for selection of one or more time zones. |
36 | * |
37 | * \b Example: |
38 | * |
39 | * To use the class to implement a system timezone selection feature: |
40 | * \code |
41 | * |
42 | * // This adds a time zone widget to a dialog. |
43 | * m_timezones = new KTimeZoneWidget(this); |
44 | * ... |
45 | * \endcode |
46 | * |
47 | * To use the class to implement a multiple-choice custom time zone selector: |
48 | * \code |
49 | * |
50 | * m_timezones = new KTimeZoneWidget( this, "Time zones", vcalendarTimezones ); |
51 | * m_timezones->setSelectionMode( QTreeView::MultiSelection ); |
52 | * ... |
53 | * \endcode |
54 | * |
55 | * \image html ktimezonewidget.png "KDE Time Zone Widget" |
56 | * |
57 | * @author S.R.Haque <srhaque@iee.org> |
58 | */ |
59 | class KDEUI_EXPORT KTimeZoneWidget : public QTreeWidget |
60 | { |
61 | Q_OBJECT |
62 | Q_PROPERTY(bool itemsCheckable READ itemsCheckable WRITE setItemsCheckable) |
63 | Q_PROPERTY(QAbstractItemView::SelectionMode selectionMode READ selectionMode WRITE setSelectionMode) |
64 | |
65 | public: |
66 | /** |
67 | * Constructs a time zone selection widget. |
68 | * |
69 | * @param parent The parent widget. |
70 | * @param timeZones The time zone database to use. If 0, the system time zone |
71 | * database is used. |
72 | */ |
73 | explicit KTimeZoneWidget( QWidget *parent = 0, KTimeZones *timeZones = 0 ); |
74 | |
75 | /** |
76 | * Destroys the time zone selection widget. |
77 | */ |
78 | virtual ~KTimeZoneWidget(); |
79 | |
80 | /** |
81 | * Makes all items show a checkbox, so that the user can select multiple |
82 | * timezones by means of checking checkboxes, rather than via multi-selection. |
83 | * |
84 | * In "items checkable" mode, the selection(), setSelected() and clearSelection() |
85 | * methods work on the check states rather than on selecting/unselecting. |
86 | * |
87 | * @since 4.4 |
88 | */ |
89 | void setItemsCheckable(bool enable); |
90 | /** |
91 | * @return true if setItemsCheckable(true) was called. |
92 | * @since 4.4 |
93 | */ |
94 | bool itemsCheckable() const; |
95 | |
96 | /** |
97 | * Allows to select multiple timezones. This is the same as |
98 | * setSelectionMode(KTimeZoneWidget::MultiSelection) normally, |
99 | * but in "items checkable" mode, this is rather about allowing to |
100 | * check multiple items. In that case, the actual QTreeWidget selection |
101 | * mode remains unchanged. |
102 | * @since 4.4 |
103 | */ |
104 | void setSelectionMode(QAbstractItemView::SelectionMode mode); |
105 | |
106 | /** |
107 | * @return the selection mode set by setSelectionMode(). |
108 | * @since 4.4 |
109 | */ |
110 | QAbstractItemView::SelectionMode selectionMode() const; |
111 | |
112 | /** |
113 | * Returns the currently selected time zones. See QTreeView::selectionChanged(). |
114 | * |
115 | * @return a list of time zone names, in the format used by the database |
116 | * supplied to the {@link KTimeZoneWidget() } constructor. |
117 | */ |
118 | QStringList selection() const; |
119 | |
120 | /** |
121 | * Select/deselect the named time zone. |
122 | * |
123 | * @param zone The time zone name to be selected. Ignored if not recognized! |
124 | * @param selected The new selection state. |
125 | */ |
126 | void setSelected( const QString &zone, bool selected ); |
127 | |
128 | /** |
129 | * Unselect all timezones. |
130 | * This is the same as QTreeWidget::clearSelection, except in checkable items mode, |
131 | * where items are all unchecked. |
132 | * The overload is @since 4.4. |
133 | */ |
134 | void clearSelection(); |
135 | |
136 | /** |
137 | * Format a time zone name in a standardised manner. The returned value is |
138 | * transformed via an i18n lookup, so the caller should previously have |
139 | * set the time zone catalog: |
140 | * \code |
141 | * KGlobal::locale()->insertCatalog( "timezones4" ); |
142 | * \endcode |
143 | * |
144 | * @return formatted time zone name. |
145 | */ |
146 | static QString displayName( const KTimeZone &zone ); |
147 | |
148 | private: |
149 | class Private; |
150 | Private* const d; |
151 | }; |
152 | |
153 | #endif |
154 | |