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
27class KTimeZone;
28class 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 */
59class 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