1/*
2 This file is part of the kholidays library.
3
4 Copyright 2010 John Layt <john@layt.net>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KHOLIDAYS_HOLIDAYREGIONSELECTOR_H
23#define KHOLIDAYS_HOLIDAYREGIONSELECTOR_H
24
25#include "kholidays_export.h"
26
27#include <QTreeWidget>
28
29class QString;
30class QStringList;
31
32namespace KHolidays {
33
34class HolidayRegion;
35
36class KHOLIDAYS_EXPORT HolidayRegionSelector : public QWidget
37{
38 Q_OBJECT
39 Q_PROPERTY( QAbstractItemView::SelectionMode listSelectionMode
40 READ selectionMode WRITE setSelectionMode )
41
42 Q_PROPERTY( bool enableRegionUseFlags
43 READ regionUseFlagsEnabled WRITE setRegionUseFlagsEnabled )
44
45 Q_PROPERTY( bool hideSearch
46 READ searchHidden WRITE setSearchHidden )
47
48 Q_PROPERTY( bool hideDescription
49 READ descriptionHidden WRITE setDescriptionHidden )
50
51 Q_PROPERTY( bool hideLanguage
52 READ languageHidden WRITE setLanguageHidden )
53
54 Q_PROPERTY( QStringList languageFilter
55 READ languageFilter WRITE setLanguageFilter )
56
57 public:
58 /**
59 * Describes the Selection Status of a Holiday Region.
60 */
61 enum SelectionStatus {
62 RegionHidden, ///< The Holiday Region is not displayed
63 RegionDisabled, ///< The Holiday Region is not available for selection
64 RegionAvailable, ///< The Holiday Region is available for selection
65 RegionSelected ///< The Holiday Region is selected
66 };
67
68 /**
69 * Describes the Usage of a Holiday Region.
70 */
71 enum RegionUseFlag {
72 NotUsed = 0x00, ///< The Holiday Region is not used
73 UseInformationOnly = 0x01, ///< The Holiday Region is used for information only
74 UseDaysOff = 0x02 ///< The Holiday Region is used for Days Off
75 };
76 Q_DECLARE_FLAGS( RegionUseFlags, RegionUseFlag )
77
78 /**
79 * Constructs a default Holiday Region selection widget.
80 *
81 * This widget will automatically be populated with all available Holiday Regions,
82 * will display all available features including a serach bar and various details
83 * columns, and will operate in Multi Selection mode. If you require fewer details
84 * or regions displayed or to operate in single or no selection mode, then you must
85 * configure these after the widget is created.
86 *
87 * By default multiple Region Use selections are available to the user. This is
88 * normally used to set if holidays are to be used for days off or information only.
89 * These Use options can be overridden or disabled, or the text displayed modifed
90 * as required.
91 *
92 * @param parent The parent widget.
93 */
94 explicit HolidayRegionSelector( QWidget *parent = 0 );
95
96 /**
97 * Destructor
98 */
99 virtual ~HolidayRegionSelector();
100
101 /**
102 * Return a list of all Holiday Regions available
103 *
104 * @return List of all Holiday Region Codes
105 */
106 QStringList holidayRegions() const;
107
108 /**
109 * Set what selection mode the Region list uses.
110 *
111 * The Selection Mode determines how many Holiday Regions can be selected in the list:
112 * - If NoSelection mode then the widget is display only and the user cannot select any
113 * Holiday Region.
114 * - If SingleSelection mode then only a single Holiday Region can be chosen.
115 * - If MultiSelection mode then more than one Holiday Regions can be chosen.
116 *
117 * @see selectionMode
118 * @param selectionMode The selection mode to use
119 */
120 void setSelectionMode( QAbstractItemView::SelectionMode selectionMode );
121
122 /**
123 * Return what selection mode the Region list uses.
124 *
125 * @see setSelectionMode
126 * @return The selection mode used
127 */
128 QAbstractItemView::SelectionMode selectionMode() const;
129
130 /**
131 * Set if Region Use Flags are enabled
132 *
133 * If Region Use Flags are disabled then the user can only select a Region
134 * with a binary on/off check box. The selection status is set and returned
135 * using the holidayRegionStatus and setHolidayRegionStatus methods.
136 *
137 * If the Region Use Flags are enabled then the user can select from multiple
138 * options for how a Region can be used via a combo box. The use flags are
139 * set and returned using the setRegionUseFlags and regionUseFlags methods.
140 *
141 * @see setSelectionMode
142 * @param listSelectionMode The list selection mode to use
143 */
144 void setRegionUseFlagsEnabled( bool enableRegionUseFlags );
145
146 /**
147 * Returns if Region Use Flags are enabled.
148 *
149 * @see setRegionUseFlagsEnabled
150 * @return if the Region Use Flags are enabled
151 */
152 bool regionUseFlagsEnabled() const;
153
154 /**
155 * Set the Selection Status for a Holiday Region.
156 *
157 * @see selectionStatus
158 * @param holidayRegionCode The Holiday Region to set the Status for
159 * @param status The Selection Status of the Holiday Region
160 */
161 void setSelectionStatus( const QString &holidayRegionCode,
162 HolidayRegionSelector::SelectionStatus status );
163
164 /**
165 * Returns the current Selection Status for a Holiday Region.
166 *
167 * @see setSelectionStatus
168 * @param holidayRegionCode The Holiday Region required
169 * @return The current Selection Status for the Holiday Region
170 */
171 HolidayRegionSelector::SelectionStatus selectionStatus(
172 const QString &holidayRegionCode ) const;
173
174 /**
175 * Returns the current Selection Status for all Holiday Regions.
176 *
177 * @see setSelectionStatus
178 * @return A QHash of all Holiday Regions and their current Selection Status
179 */
180 QHash<QString, HolidayRegionSelector::SelectionStatus> selectionStatus() const;
181
182 /**
183 * Returns the list of Holiday Regions with a required Selection Status,
184 * defults to returning all selected Regions.
185 *
186 * @see setSelectionStatus
187 * @see selectionStatus
188 * @param selectionStatus The selection status to match, defaults to RegionSelected
189 * @return A list of selected Holiday Regions
190 */
191 QStringList selection( HolidayRegionSelector::SelectionStatus selectionStatus =
192 HolidayRegionSelector::RegionSelected ) const;
193
194 /**
195 * Returns the list of Holiday Regions with a required Region Use Flag.
196 *
197 * @see setRegionUseFlags
198 * @see regionUseFlags
199 * @param regionUseFlags The Region Use flags to match
200 * @return A list of matching Holiday Regions
201 */
202 QStringList selection( HolidayRegionSelector::RegionUseFlags regionUseFlags ) const;
203
204 /**
205 * Clear the current Selection Status of all Holiday Regions including Region Use Flags.
206 *
207 * @see setSelectionStatus
208 * @see selectionStatus
209 * @see selection
210 */
211 void clearSelection();
212
213 /**
214 * Set the Region Use Flags for a Holiday Region.
215 *
216 * @see regionUseFlags
217 * @param holidayRegionCode The Holiday Region to set the Use Flags for
218 * @param regionUseFlags The Use Flags for the Holiday Region
219 */
220 void setRegionUseFlags( const QString &holidayRegionCode,
221 HolidayRegionSelector::RegionUseFlags regionUseFlags );
222
223 /**
224 * Returns the current Region Use Flags for a Holiday Region.
225 *
226 * @see setRegionUseFlags
227 * @param holidayRegionCode The Holiday Region required
228 * @return The current Use Flags for the Holiday Region
229 */
230 HolidayRegionSelector::RegionUseFlags regionUseFlags( const QString &holidayRegionCode ) const;
231
232 /**
233 * Returns the current Region Use Flags for all Holiday Regions.
234 *
235 * @see setRegionUseFlags
236 * @return A QHash of Holiday Regions and their current Region Use Flags
237 */
238 QHash<QString, HolidayRegionSelector::RegionUseFlags> regionUseFlags() const;
239
240 /**
241 * Set a language filter on the Holiday Regions to be displayed.
242 *
243 * Only Holiday Regions in a language included in the filter will be
244 * displayed in the widget, i.e. all other Holiday Regions will have
245 * a SelectionStatus of RegionHidden.
246 *
247 * Setting a null list disables the display filter, i.e. all Holiday
248 * Regions are displayed.
249 *
250 * @see languageFilter
251 * @param languages A list of languages to filter for
252 */
253 void setLanguageFilter( const QStringList &languages );
254
255 /**
256 * Return the current language filter, a null list implies no filter is set.
257 *
258 * @see setLanguageFilter
259 * @return The list of languages currently being displayed
260 */
261 QStringList languageFilter() const;
262
263 /**
264 * Set if the search line to be hidden or displayed.
265 *
266 * @see searchHidden
267 * @param hideSearch If the search is to be hidden
268 */
269 void setSearchHidden( bool hideSearch );
270
271 /**
272 * Return if the search line is currently hidden.
273 *
274 * @see setSearchHidden
275 * @return If the search line is hidden
276 */
277 bool searchHidden() const;
278
279 /**
280 * Set if the Holiday Region Language field is to be hidden or displayed.
281 *
282 * @see languageHidden
283 * @param hideLanguage If the language field is to be hidden
284 */
285 void setLanguageHidden( bool hideLanguage );
286
287 /**
288 * Return if the Holiday Region Language field is currently hidden.
289 *
290 * @see setLanguageHidden
291 * @return If the language field is hidden
292 */
293 bool languageHidden() const;
294
295 /**
296 * Set if the Holiday Region Description field is to be hidden or displayed.
297 *
298 * @see descriptionHidden
299 * @param hideDescription If the description field is to be hidden
300 */
301 void setDescriptionHidden( bool hideDescription );
302
303 /**
304 * Return if the Holiday Region Description field is currently hidden.
305 *
306 * @see setDescriptionHidden
307 * @return If the description field is hidden
308 */
309 bool descriptionHidden() const;
310
311 private Q_SLOTS:
312 void itemChanged( QTreeWidgetItem *item, int column );
313 void itemChanged( int index );
314
315 Q_SIGNALS:
316 void selectionChanged();
317
318 private:
319 class Private;
320 Private *const d;
321};
322
323} // namespace KHolidays
324
325Q_DECLARE_OPERATORS_FOR_FLAGS( KHolidays::HolidayRegionSelector::RegionUseFlags )
326
327#endif // KHOLIDAYS_HOLIDAYREGIONSELECTOR_H
328