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 | |
29 | class QString; |
30 | class QStringList; |
31 | |
32 | namespace KHolidays { |
33 | |
34 | class HolidayRegion; |
35 | |
36 | class 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 | |
325 | Q_DECLARE_OPERATORS_FOR_FLAGS( KHolidays::HolidayRegionSelector::RegionUseFlags ) |
326 | |
327 | #endif // KHOLIDAYS_HOLIDAYREGIONSELECTOR_H |
328 | |