Diffstat (limited to 'library/backend/categories.cpp') (more/less context) (show whitespace changes)
-rw-r--r-- | library/backend/categories.cpp | 319 |
1 files changed, 289 insertions, 30 deletions
diff --git a/library/backend/categories.cpp b/library/backend/categories.cpp index 6e011c4..e37b3b9 100644 --- a/library/backend/categories.cpp +++ b/library/backend/categories.cpp | |||
@@ -1,29 +1,28 @@ | |||
1 | /********************************************************************** | 1 | /********************************************************************** |
2 | ** Copyright (C) 2000 Trolltech AS. All rights reserved. | 2 | ** Copyright (C) 2000-2002 Trolltech AS. All rights reserved. |
3 | ** | 3 | ** |
4 | ** This file is part of Qtopia Environment. | 4 | ** This file is part of the Qtopia Environment. |
5 | ** | 5 | ** |
6 | ** This file may be distributed and/or modified under the terms of the | 6 | ** This file may be distributed and/or modified under the terms of the |
7 | ** GNU General Public License version 2 as published by the Free | 7 | ** GNU General Public License version 2 as published by the Free Software |
8 | ** Software Foundation and appearing in the file LICENSE.GPL included | 8 | ** Foundation and appearing in the file LICENSE.GPL included in the |
9 | ** in the packaging of this file. | 9 | ** packaging of this file. |
10 | ** | 10 | ** |
11 | ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING | 11 | ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE |
12 | ** THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A | 12 | ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
13 | ** PARTICULAR PURPOSE. | ||
14 | ** | 13 | ** |
15 | ** See http://www.trolltech.com/gpl/ for GPL licensing information. | 14 | ** See http://www.trolltech.com/gpl/ for GPL licensing information. |
16 | ** | 15 | ** |
17 | ** Contact info@trolltech.com if any conditions of this licensing are | 16 | ** Contact info@trolltech.com if any conditions of this licensing are |
18 | ** not clear to you. | 17 | ** not clear to you. |
19 | ** | 18 | ** |
20 | **********************************************************************/ | 19 | **********************************************************************/ |
21 | #include "categories.h" | 20 | #include <qtopia/categories.h> |
21 | #include <qtopia/stringutil.h> | ||
22 | #include <qfile.h> | 22 | #include <qfile.h> |
23 | #include <qcstring.h> | 23 | #include <qcstring.h> |
24 | #include <qtextstream.h> | 24 | #include <qtextstream.h> |
25 | #include "stringutil.h" | ||
26 | 25 | ||
27 | using namespace Qtopia; | 26 | using namespace Qtopia; |
28 | 27 | ||
29 | /*********************************************************** | 28 | /*********************************************************** |
@@ -37,8 +36,26 @@ UidGen CategoryGroup::sUidGen( UidGen::PalmtopCenter ); | |||
37 | #else | 36 | #else |
38 | UidGen CategoryGroup::sUidGen( UidGen::Qtopia ); | 37 | UidGen CategoryGroup::sUidGen( UidGen::Qtopia ); |
39 | #endif | 38 | #endif |
40 | 39 | ||
40 | /*! \class CategoryGroup categories.h | ||
41 | \brief Helper class that is used by Categories | ||
42 | |||
43 | CategoryGroup is a group of categories that is associated with an | ||
44 | application or global set. Mainly it defines a map of ids to | ||
45 | category labels and category labels to ids. Lookups can be done with | ||
46 | labels or unique idenifiers. | ||
47 | |||
48 | \ingroup qtopiaemb | ||
49 | \ingroup qtopiadesktop | ||
50 | \warning Categories API will likely change between Qtopia 1.5 and Qtopia 3 | ||
51 | \sa Categories::appGroupMap(), Categories::globalGroup() | ||
52 | */ | ||
53 | |||
54 | /*! Add \a label and return the UID. If failure, then 0 is returned. Note | ||
55 | that All and Unfiled are reserved labels. | ||
56 | \internal | ||
57 | */ | ||
41 | int CategoryGroup::add( const QString &label ) | 58 | int CategoryGroup::add( const QString &label ) |
42 | { | 59 | { |
43 | if ( label == QObject::tr("All") || label == QObject::tr("Unfiled") ) | 60 | if ( label == QObject::tr("All") || label == QObject::tr("Unfiled") ) |
44 | return 0; | 61 | return 0; |
@@ -57,8 +74,10 @@ void CategoryGroup::insert( int uid, const QString &label ) | |||
57 | mIdLabelMap[uid] = label; | 74 | mIdLabelMap[uid] = label; |
58 | mLabelIdMap[label] = uid; | 75 | mLabelIdMap[label] = uid; |
59 | } | 76 | } |
60 | 77 | ||
78 | /*! \internal | ||
79 | */ | ||
61 | bool CategoryGroup::add( int uid, const QString &label ) | 80 | bool CategoryGroup::add( int uid, const QString &label ) |
62 | { | 81 | { |
63 | if ( label == QObject::tr("All") || label == QObject::tr("Unfiled") ) | 82 | if ( label == QObject::tr("All") || label == QObject::tr("Unfiled") ) |
64 | return FALSE; | 83 | return FALSE; |
@@ -72,8 +91,11 @@ bool CategoryGroup::add( int uid, const QString &label ) | |||
72 | insert( uid, label ); | 91 | insert( uid, label ); |
73 | return TRUE; | 92 | return TRUE; |
74 | } | 93 | } |
75 | 94 | ||
95 | /*! Returns TRUE if \a label was removed from the group, FALSE if not. | ||
96 | \internal | ||
97 | */ | ||
76 | bool CategoryGroup::remove( const QString &label ) | 98 | bool CategoryGroup::remove( const QString &label ) |
77 | { | 99 | { |
78 | QMap<QString,int>::Iterator findIt = mLabelIdMap.find( label ); | 100 | QMap<QString,int>::Iterator findIt = mLabelIdMap.find( label ); |
79 | if ( findIt == mLabelIdMap.end() ) | 101 | if ( findIt == mLabelIdMap.end() ) |
@@ -84,8 +106,11 @@ bool CategoryGroup::remove( const QString &label ) | |||
84 | 106 | ||
85 | return TRUE; | 107 | return TRUE; |
86 | } | 108 | } |
87 | 109 | ||
110 | /*! Returns TRUE if \a uid was removed from the group, FALSE if not. | ||
111 | \internal | ||
112 | */ | ||
88 | bool CategoryGroup::remove( int uid ) | 113 | bool CategoryGroup::remove( int uid ) |
89 | { | 114 | { |
90 | QMap<int,QString>::Iterator idIt = mIdLabelMap.find( uid ); | 115 | QMap<int,QString>::Iterator idIt = mIdLabelMap.find( uid ); |
91 | if ( idIt == mIdLabelMap.end() ) | 116 | if ( idIt == mIdLabelMap.end() ) |
@@ -96,8 +121,10 @@ bool CategoryGroup::remove( int uid ) | |||
96 | 121 | ||
97 | return TRUE; | 122 | return TRUE; |
98 | } | 123 | } |
99 | 124 | ||
125 | /*! \internal | ||
126 | */ | ||
100 | bool CategoryGroup::rename( int uid, const QString &newLabel ) | 127 | bool CategoryGroup::rename( int uid, const QString &newLabel ) |
101 | { | 128 | { |
102 | if ( newLabel == QObject::tr("All") || newLabel == QObject::tr("Unfiled") ) | 129 | if ( newLabel == QObject::tr("All") || newLabel == QObject::tr("Unfiled") ) |
103 | return FALSE; | 130 | return FALSE; |
@@ -112,25 +139,29 @@ bool CategoryGroup::rename( int uid, const QString &newLabel ) | |||
112 | 139 | ||
113 | return TRUE; | 140 | return TRUE; |
114 | } | 141 | } |
115 | 142 | ||
143 | /*! \internal | ||
144 | */ | ||
116 | bool CategoryGroup::rename( const QString &oldLabel, const QString &newLabel ) | 145 | bool CategoryGroup::rename( const QString &oldLabel, const QString &newLabel ) |
117 | { | 146 | { |
118 | return rename( id(oldLabel), newLabel ); | 147 | return rename( id(oldLabel), newLabel ); |
119 | } | 148 | } |
120 | 149 | ||
150 | /*! Returns TRUE if \a uid is stored in this group, FALSE if not. */ | ||
121 | bool CategoryGroup::contains(int uid) const | 151 | bool CategoryGroup::contains(int uid) const |
122 | { | 152 | { |
123 | return ( mIdLabelMap.find( uid ) != mIdLabelMap.end() ); | 153 | return ( mIdLabelMap.find( uid ) != mIdLabelMap.end() ); |
124 | } | 154 | } |
125 | 155 | ||
156 | /*! Returns TRUE if \a label is stored in this group, FALSE if not. */ | ||
126 | bool CategoryGroup::contains(const QString &label) const | 157 | bool CategoryGroup::contains(const QString &label) const |
127 | { | 158 | { |
128 | return ( mLabelIdMap.find( label ) != mLabelIdMap.end() ); | 159 | return ( mLabelIdMap.find( label ) != mLabelIdMap.end() ); |
129 | } | 160 | } |
130 | 161 | ||
131 | /** Returns label associated with the uid or QString::null if | 162 | /*! Returns label associated with the \a uid or QString::null if |
132 | * not found | 163 | not found |
133 | */ | 164 | */ |
134 | const QString &CategoryGroup::label(int uid) const | 165 | const QString &CategoryGroup::label(int uid) const |
135 | { | 166 | { |
136 | QMap<int,QString>::ConstIterator idIt = mIdLabelMap.find( uid ); | 167 | QMap<int,QString>::ConstIterator idIt = mIdLabelMap.find( uid ); |
@@ -138,17 +169,18 @@ const QString &CategoryGroup::label(int uid) const | |||
138 | return QString::null; | 169 | return QString::null; |
139 | return *idIt; | 170 | return *idIt; |
140 | } | 171 | } |
141 | 172 | ||
142 | /** Returns the uid associated with label or 0 if not found */ | 173 | /*! Returns the uid associated with \a label or 0 if not found */ |
143 | int CategoryGroup::id(const QString &label) const | 174 | int CategoryGroup::id(const QString &label) const |
144 | { | 175 | { |
145 | QMap<QString,int>::ConstIterator labelIt = mLabelIdMap.find( label ); | 176 | QMap<QString,int>::ConstIterator labelIt = mLabelIdMap.find( label ); |
146 | if ( labelIt == mLabelIdMap.end() ) | 177 | if ( labelIt == mLabelIdMap.end() ) |
147 | return 0; | 178 | return 0; |
148 | return *labelIt; | 179 | return *labelIt; |
149 | } | 180 | } |
150 | 181 | ||
182 | /*! Returns a list of all labels stored in this group. */ | ||
151 | QStringList CategoryGroup::labels() const | 183 | QStringList CategoryGroup::labels() const |
152 | { | 184 | { |
153 | QStringList labels; | 185 | QStringList labels; |
154 | for ( QMap<int, QString>::ConstIterator it = mIdLabelMap.begin(); | 186 | for ( QMap<int, QString>::ConstIterator it = mIdLabelMap.begin(); |
@@ -158,8 +190,9 @@ QStringList CategoryGroup::labels() const | |||
158 | // labels.sort(); | 190 | // labels.sort(); |
159 | return labels; | 191 | return labels; |
160 | } | 192 | } |
161 | 193 | ||
194 | /*! Returns a list of all labels associated with the \a catids */ | ||
162 | QStringList CategoryGroup::labels(const QArray<int> &catids ) const | 195 | QStringList CategoryGroup::labels(const QArray<int> &catids ) const |
163 | { | 196 | { |
164 | QStringList labels; | 197 | QStringList labels; |
165 | if ( catids.count() == 0 ) | 198 | if ( catids.count() == 0 ) |
@@ -176,10 +209,50 @@ QStringList CategoryGroup::labels(const QArray<int> &catids ) const | |||
176 | * Categories | 209 | * Categories |
177 | * | 210 | * |
178 | **********************************************************/ | 211 | **********************************************************/ |
179 | 212 | ||
180 | /** Add the category name as long as it doesn't already exist locally | 213 | /*! |
181 | * or globally. Return TRUE if added, FALSE if conflicts. | 214 | \class Categories categories.h |
215 | \brief The Categories class is a database that groups categories and maps ids to names. | ||
216 | |||
217 | The Categories class is the low level Categories accessor class. To | ||
218 | add a category menu and filter for your application, see CategoryMenu. | ||
219 | |||
220 | The Categories class allows the developer to add, remove, and rename | ||
221 | categories. Categories can be created for an individual application | ||
222 | such as Todo List or to be used for all applications. Categories | ||
223 | that can be used by all applications are called global | ||
224 | categories. Each PalmtopRecord subclass stores categories as an | ||
225 | QArray<int> using PalmtopRecord::setCategories() and | ||
226 | PalmtopRecord::categories(). This allows each record to be assigned | ||
227 | to multiple categories. This also allows the user to rename a | ||
228 | category and for it to update automatically in all records. | ||
229 | |||
230 | This class provides several methods to convert between a category id | ||
231 | and it's associated string such as id(), ids(), label() and labels(). A | ||
232 | helper class called CategoryGroup is used to access categories of a | ||
233 | single application group, such as Todo List. Global categories can | ||
234 | also be accessed via CategoryGroup objects. See appGroupMap() and | ||
235 | globalGroup() for the appropriate accessor methods. | ||
236 | |||
237 | Categories are stored in an xml file in the Settings directory | ||
238 | (Categories.xml). A global function called categoryFileName() will | ||
239 | return to appropriate QString file location to be passed to load() | ||
240 | and save() for the master categories database. | ||
241 | |||
242 | \ingroup qtopiaemb | ||
243 | \ingroup qtopiadesktop | ||
244 | \warning Categories API will likely change between Qtopia 1.5 and Qtopia 3 | ||
245 | \sa CategoryGroup, CategoryMenu | ||
246 | */ | ||
247 | |||
248 | |||
249 | /*! | ||
250 | Add the category name as long as it doesn't already exist locally or | ||
251 | globally. The \a uid is assigned to the category if successfully | ||
252 | added. Return \a uid if added, 0 if conflicts (error). | ||
253 | |||
254 | \internal | ||
182 | */ | 255 | */ |
183 | int Categories::addCategory( const QString &appname, | 256 | int Categories::addCategory( const QString &appname, |
184 | const QString &catname, | 257 | const QString &catname, |
185 | int uid ) | 258 | int uid ) |
@@ -203,8 +276,13 @@ int Categories::addCategory( const QString &appname, | |||
203 | emit categoryAdded( *this, appname, uid ); | 276 | emit categoryAdded( *this, appname, uid ); |
204 | return uid; | 277 | return uid; |
205 | } | 278 | } |
206 | 279 | ||
280 | /*! | ||
281 | Add the category name as long as it doesn't already exist locally or | ||
282 | globally. Return UID if added, 0 if conflicts (error). | ||
283 | */ | ||
284 | |||
207 | int Categories::addCategory( const QString &appname, | 285 | int Categories::addCategory( const QString &appname, |
208 | const QString &catname ) | 286 | const QString &catname ) |
209 | { | 287 | { |
210 | if ( mGlobalCats.contains(catname) ) | 288 | if ( mGlobalCats.contains(catname) ) |
@@ -228,15 +306,24 @@ int Categories::addCategory( const QString &appname, | |||
228 | emit categoryAdded( *this, appname, uid ); | 306 | emit categoryAdded( *this, appname, uid ); |
229 | return uid; | 307 | return uid; |
230 | } | 308 | } |
231 | 309 | ||
310 | /*! | ||
311 | \internal | ||
312 | */ | ||
232 | int Categories::addGlobalCategory( const QString &catname, int uid ) | 313 | int Categories::addGlobalCategory( const QString &catname, int uid ) |
233 | { | 314 | { |
234 | mGlobalCats.add( uid, catname ); | 315 | mGlobalCats.add( uid, catname ); |
235 | emit categoryAdded( *this, QString::null, uid ); | 316 | emit categoryAdded( *this, QString::null, uid ); |
236 | return uid; | 317 | return uid; |
237 | } | 318 | } |
238 | 319 | ||
320 | /*! | ||
321 | Add the global category \a catname while checking that it doesn't | ||
322 | already exist globally. Return UID if added, 0 if conflicts. | ||
323 | |||
324 | \sa addCategory() | ||
325 | */ | ||
239 | int Categories::addGlobalCategory( const QString &catname ) | 326 | int Categories::addGlobalCategory( const QString &catname ) |
240 | { | 327 | { |
241 | int uid = mGlobalCats.add( catname ); | 328 | int uid = mGlobalCats.add( catname ); |
242 | if ( !uid ) | 329 | if ( !uid ) |
@@ -244,11 +331,13 @@ int Categories::addGlobalCategory( const QString &catname ) | |||
244 | emit categoryAdded( *this, QString::null, uid ); | 331 | emit categoryAdded( *this, QString::null, uid ); |
245 | return uid; | 332 | return uid; |
246 | } | 333 | } |
247 | 334 | ||
248 | /** Removes the category from the application; if it is not found | 335 | /*! |
249 | * in the application, then it attempts to remove it from | 336 | |
250 | * the global list | 337 | Removes the \a catname from the application group. If it is not |
338 | found in the application group and \a checkGlobal is TRUE, then it | ||
339 | attempts to remove it from the global list | ||
251 | */ | 340 | */ |
252 | bool Categories::removeCategory( const QString &appname, | 341 | bool Categories::removeCategory( const QString &appname, |
253 | const QString &catname, | 342 | const QString &catname, |
254 | bool checkGlobal ) | 343 | bool checkGlobal ) |
@@ -267,8 +356,13 @@ bool Categories::removeCategory( const QString &appname, | |||
267 | return FALSE; | 356 | return FALSE; |
268 | return removeGlobalCategory( catname ); | 357 | return removeGlobalCategory( catname ); |
269 | } | 358 | } |
270 | 359 | ||
360 | |||
361 | /*! | ||
362 | Removes the \a uid from the application group \a appname. Returns TRUE | ||
363 | if success, FALSE if not found. | ||
364 | */ | ||
271 | bool Categories::removeCategory( const QString &appname, int uid ) | 365 | bool Categories::removeCategory( const QString &appname, int uid ) |
272 | { | 366 | { |
273 | QMap< QString, CategoryGroup >::Iterator | 367 | QMap< QString, CategoryGroup >::Iterator |
274 | appIt = mAppCats.find( appname ); | 368 | appIt = mAppCats.find( appname ); |
@@ -281,8 +375,12 @@ bool Categories::removeCategory( const QString &appname, int uid ) | |||
281 | } | 375 | } |
282 | return FALSE; | 376 | return FALSE; |
283 | } | 377 | } |
284 | 378 | ||
379 | /*! | ||
380 | Removes the global category \a catname. Returns TRUE | ||
381 | if success, FALSE if not found. | ||
382 | */ | ||
285 | bool Categories::removeGlobalCategory( const QString &catname ) | 383 | bool Categories::removeGlobalCategory( const QString &catname ) |
286 | { | 384 | { |
287 | int uid = mGlobalCats.id( catname ); | 385 | int uid = mGlobalCats.id( catname ); |
288 | if ( mGlobalCats.remove( uid ) ) { | 386 | if ( mGlobalCats.remove( uid ) ) { |
@@ -291,9 +389,12 @@ bool Categories::removeGlobalCategory( const QString &catname ) | |||
291 | } | 389 | } |
292 | return FALSE; | 390 | return FALSE; |
293 | } | 391 | } |
294 | 392 | ||
295 | 393 | /*! | |
394 | Removes the global category \a uid. Returns TRUE | ||
395 | if success, FALSE if not found. | ||
396 | */ | ||
296 | bool Categories::removeGlobalCategory( int uid ) | 397 | bool Categories::removeGlobalCategory( int uid ) |
297 | { | 398 | { |
298 | if ( mGlobalCats.remove( uid ) ) { | 399 | if ( mGlobalCats.remove( uid ) ) { |
299 | emit categoryRemoved( *this, QString::null, uid ); | 400 | emit categoryRemoved( *this, QString::null, uid ); |
@@ -301,11 +402,12 @@ bool Categories::removeGlobalCategory( int uid ) | |||
301 | } | 402 | } |
302 | return FALSE; | 403 | return FALSE; |
303 | } | 404 | } |
304 | 405 | ||
305 | /** Returns the sorted list of all categories that are associated with | 406 | /*! |
306 | * the app. If includeGlobal parameter is TRUE then the returned | 407 | Returns the sorted list of all categories that are associated with |
307 | * categories will include the global category items. | 408 | the \a app. If \a includeGlobal is TRUE then the returned |
409 | categories will include the global category items. | ||
308 | */ | 410 | */ |
309 | QStringList Categories::labels( const QString &app, | 411 | QStringList Categories::labels( const QString &app, |
310 | bool includeGlobal, | 412 | bool includeGlobal, |
311 | ExtraLabels extra ) const | 413 | ExtraLabels extra ) const |
@@ -315,9 +417,9 @@ QStringList Categories::labels( const QString &app, | |||
315 | QStringList cats; | 417 | QStringList cats; |
316 | 418 | ||
317 | if ( appIt != mAppCats.end() ) | 419 | if ( appIt != mAppCats.end() ) |
318 | cats += (*appIt).labels(); | 420 | cats += (*appIt).labels(); |
319 | else qDebug("Categories::labels didn't find app %s", app.latin1() ); | 421 | //else qDebug("Categories::labels didn't find app %s", app.latin1() ); |
320 | if ( includeGlobal ) | 422 | if ( includeGlobal ) |
321 | cats += mGlobalCats.labels(); | 423 | cats += mGlobalCats.labels(); |
322 | 424 | ||
323 | cats.sort(); | 425 | cats.sort(); |
@@ -337,8 +439,11 @@ QStringList Categories::labels( const QString &app, | |||
337 | 439 | ||
338 | return cats; | 440 | return cats; |
339 | } | 441 | } |
340 | 442 | ||
443 | /*! | ||
444 | Returns the label associated with the id | ||
445 | */ | ||
341 | QString Categories::label( const QString &app, int id ) const | 446 | QString Categories::label( const QString &app, int id ) const |
342 | { | 447 | { |
343 | if ( mGlobalCats.contains( id ) ) | 448 | if ( mGlobalCats.contains( id ) ) |
344 | return mGlobalCats.label( id ); | 449 | return mGlobalCats.label( id ); |
@@ -348,12 +453,18 @@ QString Categories::label( const QString &app, int id ) const | |||
348 | return QString::null; | 453 | return QString::null; |
349 | return (*appIt).label( id ); | 454 | return (*appIt).label( id ); |
350 | } | 455 | } |
351 | 456 | ||
352 | /** Returns a single string associated with the cat ids for display in | 457 | /*! |
353 | * a combobox or any area that requires one string. If catids are empty | 458 | Returns a single string associated with \a catids for display in a |
354 | * then "Unfiled" will be returned. If multiple categories are assigned | 459 | combobox or any area that requires one string. If \a catids are empty |
355 | * the first cat id is shown with " (multi)" appended to the string. | 460 | then "Unfiled" will be returned. If multiple categories are |
461 | assigned then the behavior depends on the DisplaySingle type. | ||
462 | |||
463 | If \a display is set to ShowMulti then " (multi)" appended to the | ||
464 | first string. If \a display is set to ShowAll, then a space | ||
465 | seperated string is returned with all categories. If ShowFirst is | ||
466 | set, the just the first string is returned. | ||
356 | */ | 467 | */ |
357 | QString Categories::displaySingle( const QString &app, | 468 | QString Categories::displaySingle( const QString &app, |
358 | const QArray<int> &catids, | 469 | const QArray<int> &catids, |
359 | DisplaySingle display ) const | 470 | DisplaySingle display ) const |
@@ -379,8 +490,13 @@ QString Categories::displaySingle( const QString &app, | |||
379 | else r = strs.first(); | 490 | else r = strs.first(); |
380 | return r; | 491 | return r; |
381 | } | 492 | } |
382 | 493 | ||
494 | /*! | ||
495 | |||
496 | Returns all ids associated with the application CategoryGroup \a app | ||
497 | and the passed in \a labels in that group. | ||
498 | */ | ||
383 | QArray<int> Categories::ids( const QString &app, const QStringList &labels) const | 499 | QArray<int> Categories::ids( const QString &app, const QStringList &labels) const |
384 | { | 500 | { |
385 | QArray<int> results; | 501 | QArray<int> results; |
386 | QStringList::ConstIterator it; | 502 | QStringList::ConstIterator it; |
@@ -396,8 +512,13 @@ QArray<int> Categories::ids( const QString &app, const QStringList &labels) cons | |||
396 | } | 512 | } |
397 | return results; | 513 | return results; |
398 | } | 514 | } |
399 | 515 | ||
516 | /*! | ||
517 | Returns the id associated with the app. If the id is not found in the | ||
518 | application CategoryGroup, then it searches the global CategoryGroup. | ||
519 | If it is not found it either, 0 is returned. | ||
520 | */ | ||
400 | int Categories::id( const QString &app, const QString &cat ) const | 521 | int Categories::id( const QString &app, const QString &cat ) const |
401 | { | 522 | { |
402 | if ( cat == tr("Unfiled") || cat.contains( tr(" (multi.)") ) ) | 523 | if ( cat == tr("Unfiled") || cat.contains( tr(" (multi.)") ) ) |
403 | return 0; | 524 | return 0; |
@@ -407,10 +528,15 @@ int Categories::id( const QString &app, const QString &cat ) const | |||
407 | return mAppCats[app].id( cat ); | 528 | return mAppCats[app].id( cat ); |
408 | } | 529 | } |
409 | 530 | ||
410 | 531 | ||
411 | /** Return TRUE if renaming succeeded; FALSE if app name not found, | 532 | /*! |
412 | * or if there was a name conflict | 533 | Return TRUE if renaming succeeded; FALSE if \a appname or \a oldName |
534 | is not found, or if \a newName conflicts with an existing category | ||
535 | in the CategoryGroup. | ||
536 | |||
537 | It will first search the CategoryGroup associated with \a appname | ||
538 | and if not found it will try to replace in global CategoryGroup. | ||
413 | */ | 539 | */ |
414 | bool Categories::renameCategory( const QString &appname, | 540 | bool Categories::renameCategory( const QString &appname, |
415 | const QString &oldName, | 541 | const QString &oldName, |
416 | const QString &newName ) | 542 | const QString &newName ) |
@@ -428,8 +554,14 @@ bool Categories::renameCategory( const QString &appname, | |||
428 | } | 554 | } |
429 | return renameGlobalCategory( oldName, newName ); | 555 | return renameGlobalCategory( oldName, newName ); |
430 | } | 556 | } |
431 | 557 | ||
558 | /*! | ||
559 | Return TRUE if renaming succeeded; FALSE if \a appname or \a oldName | ||
560 | is not found, or if \a newName conflicts with an existing category | ||
561 | in the CategoryGroup. This function will only rename categories found | ||
562 | in the global CategoryGroup. | ||
563 | */ | ||
432 | bool Categories::renameGlobalCategory( const QString &oldName, | 564 | bool Categories::renameGlobalCategory( const QString &oldName, |
433 | const QString &newName ) | 565 | const QString &newName ) |
434 | { | 566 | { |
435 | int uid = mGlobalCats.id( oldName ); | 567 | int uid = mGlobalCats.id( oldName ); |
@@ -439,8 +571,12 @@ bool Categories::renameGlobalCategory( const QString &oldName, | |||
439 | } | 571 | } |
440 | return FALSE; | 572 | return FALSE; |
441 | } | 573 | } |
442 | 574 | ||
575 | /*! | ||
576 | Changes the grouping of a category. If a category was global and \a global | ||
577 | is set to TRUE, then the \a catname will be moved to the \a appname group. | ||
578 | */ | ||
443 | void Categories::setGlobal( const QString &appname, | 579 | void Categories::setGlobal( const QString &appname, |
444 | const QString &catname, | 580 | const QString &catname, |
445 | bool global ) | 581 | bool global ) |
446 | { | 582 | { |
@@ -457,15 +593,20 @@ void Categories::setGlobal( const QString &appname, | |||
457 | if ( removeCategory( appname, catname, FALSE ) ) | 593 | if ( removeCategory( appname, catname, FALSE ) ) |
458 | addGlobalCategory( catname ); | 594 | addGlobalCategory( catname ); |
459 | } | 595 | } |
460 | 596 | ||
597 | /*! | ||
598 | Returns TRUE if the \a catname is in the global CategoryGroup, FALSE if not. | ||
599 | */ | ||
461 | bool Categories::isGlobal( const QString &catname ) const | 600 | bool Categories::isGlobal( const QString &catname ) const |
462 | { | 601 | { |
463 | return mGlobalCats.contains( catname ); | 602 | return mGlobalCats.contains( catname ); |
464 | } | 603 | } |
465 | 604 | ||
466 | 605 | ||
467 | /** Returns true if the catname is associated with any application | 606 | /*! |
607 | Returns true if the \a catname is associated with any CategoryGroup, | ||
608 | including global. | ||
468 | */ | 609 | */ |
469 | bool Categories::exists( const QString &catname ) const | 610 | bool Categories::exists( const QString &catname ) const |
470 | { | 611 | { |
471 | if ( isGlobal(catname) ) | 612 | if ( isGlobal(catname) ) |
@@ -477,8 +618,12 @@ bool Categories::exists( const QString &catname ) const | |||
477 | 618 | ||
478 | return FALSE; | 619 | return FALSE; |
479 | } | 620 | } |
480 | 621 | ||
622 | /*! | ||
623 | Returns TRUE if the \a catname is associated with the \a appname | ||
624 | CategoryGroup, FALSE if not found. | ||
625 | */ | ||
481 | bool Categories::exists( const QString &appname, | 626 | bool Categories::exists( const QString &appname, |
482 | const QString &catname) const | 627 | const QString &catname) const |
483 | { | 628 | { |
484 | QMap< QString, CategoryGroup >::ConstIterator | 629 | QMap< QString, CategoryGroup >::ConstIterator |
@@ -489,9 +634,14 @@ bool Categories::exists( const QString &appname, | |||
489 | 634 | ||
490 | return (*appIt).contains( catname ); | 635 | return (*appIt).contains( catname ); |
491 | } | 636 | } |
492 | 637 | ||
638 | /*! | ||
639 | Saves the Categories database to the \a fname. See categoryFileName() | ||
640 | for the default file name string used for the shared category database. | ||
493 | 641 | ||
642 | Returns FALSE if there is error writing the file or TRUE on success. | ||
643 | */ | ||
494 | bool Categories::save( const QString &fname ) const | 644 | bool Categories::save( const QString &fname ) const |
495 | { | 645 | { |
496 | QString strNewFile = fname + ".new"; | 646 | QString strNewFile = fname + ".new"; |
497 | QFile f( strNewFile ); | 647 | QFile f( strNewFile ); |
@@ -533,8 +683,11 @@ bool Categories::save( const QString &fname ) const | |||
533 | return FALSE; | 683 | return FALSE; |
534 | } | 684 | } |
535 | f.close(); | 685 | f.close(); |
536 | 686 | ||
687 | #ifdef Q_OS_WIN32 | ||
688 | QFile::remove( fname ); | ||
689 | #endif | ||
537 | if ( ::rename( strNewFile.latin1(), fname.latin1() ) < 0 ) { | 690 | if ( ::rename( strNewFile.latin1(), fname.latin1() ) < 0 ) { |
538 | qWarning( "problem renaming file %s to %s", | 691 | qWarning( "problem renaming file %s to %s", |
539 | strNewFile.latin1(), fname.latin1()); | 692 | strNewFile.latin1(), fname.latin1()); |
540 | // remove the tmp file... | 693 | // remove the tmp file... |
@@ -543,8 +696,14 @@ bool Categories::save( const QString &fname ) const | |||
543 | 696 | ||
544 | return TRUE; | 697 | return TRUE; |
545 | } | 698 | } |
546 | 699 | ||
700 | /*! | ||
701 | Loads the Categories database using \a fname. See categoryFileName() | ||
702 | for the default file name string used for the shared category database. | ||
703 | |||
704 | Returns FALSE if there is error reading the file or TRUE on success. | ||
705 | */ | ||
547 | bool Categories::load( const QString &fname ) | 706 | bool Categories::load( const QString &fname ) |
548 | { | 707 | { |
549 | QFile file( fname ); | 708 | QFile file( fname ); |
550 | if ( !file.open( IO_ReadOnly ) ) { | 709 | if ( !file.open( IO_ReadOnly ) ) { |
@@ -618,14 +777,21 @@ bool Categories::load( const QString &fname ) | |||
618 | 777 | ||
619 | return TRUE; | 778 | return TRUE; |
620 | } | 779 | } |
621 | 780 | ||
781 | /*! | ||
782 | Clear the categories in memory. Equivelent to creating an empty Categories | ||
783 | object. | ||
784 | */ | ||
622 | void Categories::clear() | 785 | void Categories::clear() |
623 | { | 786 | { |
624 | mGlobalCats.clear(); | 787 | mGlobalCats.clear(); |
625 | mAppCats.clear(); | 788 | mAppCats.clear(); |
626 | } | 789 | } |
627 | 790 | ||
791 | /*! | ||
792 | Dump the contents to standard out. Used for debugging only. | ||
793 | */ | ||
628 | void Categories::dump() const | 794 | void Categories::dump() const |
629 | { | 795 | { |
630 | qDebug("\tglobal categories = %s", mGlobalCats.labels().join(", ").latin1() ); | 796 | qDebug("\tglobal categories = %s", mGlobalCats.labels().join(", ").latin1() ); |
631 | for ( QMap<QString, CategoryGroup>::ConstIterator appsIt = mAppCats.begin(); appsIt != mAppCats.end(); ++appsIt ) { | 797 | for ( QMap<QString, CategoryGroup>::ConstIterator appsIt = mAppCats.begin(); appsIt != mAppCats.end(); ++appsIt ) { |
@@ -674,4 +840,97 @@ void CheckedListView::setChecked( const QStringList &checked ) | |||
674 | } | 840 | } |
675 | else | 841 | else |
676 | i->setOn( FALSE ); | 842 | i->setOn( FALSE ); |
677 | } | 843 | } |
844 | |||
845 | /*! \fn Categories &Categories::operator= ( const Categories &c ) | ||
846 | |||
847 | Performs deep copy. | ||
848 | */ | ||
849 | |||
850 | |||
851 | /*! \fn QStringList Categories::labels( const QString & app, const QArray<int> &catids ) const | ||
852 | |||
853 | Returns list of labels associated with the application and catids | ||
854 | */ | ||
855 | |||
856 | /*! \fn QStringList Categories::globalCategories() const | ||
857 | |||
858 | Returns list of all global category labels | ||
859 | */ | ||
860 | |||
861 | /*! \fn const QMap<QString, CategoryGroup> &Categories::appGroupMap() const | ||
862 | |||
863 | Returns a map of application names to CategoryGroup. The CategoryGroup | ||
864 | class defines a map of ids to category labels and category labels to ids. | ||
865 | */ | ||
866 | |||
867 | /*! \fn const CategoryGroup &Categories::globalGroup() const | ||
868 | |||
869 | Returns the global CategoryGroup. The CategoryGroup | ||
870 | class defines a map of ids to category labels and category labels to ids. | ||
871 | */ | ||
872 | |||
873 | /*! \fn void Categories::categoryAdded( const Categories &cats, const QString &appname, int uid) | ||
874 | |||
875 | Emitted if a category is added. | ||
876 | |||
877 | \a cats is a const reference to this object | ||
878 | \a appname is the CategoryGroup application name that the category was added to or QString::null if it was global | ||
879 | \a uid is the unique identifier associated with the added category | ||
880 | */ | ||
881 | |||
882 | /*! \fn void Categories::categoryRemoved( const Categories &cats, const QString &appname, | ||
883 | int uid) | ||
884 | |||
885 | Emitted if removed category is removed. | ||
886 | |||
887 | \a cats is a const reference to this object | ||
888 | \a appname is the CategoryGroup application name that the category was removed from or QString::null if it was the global CategoryGroup | ||
889 | \a uid is the unique identifier associated with the removed category | ||
890 | */ | ||
891 | |||
892 | |||
893 | /*! \fn void Categories::categoryRenamed( const Categories &cats, const QString &appname, | ||
894 | int uid) | ||
895 | |||
896 | Emitted if \a uid in the \a appname CategoryGroup is renamed in \a cats | ||
897 | object. | ||
898 | |||
899 | \a cats is a const reference to this object | ||
900 | \a appname is the CategoryGroup application name that the category was renamed in or QString::null if it was the global CategoryGroup | ||
901 | \a uid is the unique identifier associated with the renamed category | ||
902 | */ | ||
903 | |||
904 | /*! \fn Categories::Categories( QObject *parent=0, const char *name = 0 ) | ||
905 | |||
906 | Constructor for an empty Categories object. | ||
907 | */ | ||
908 | |||
909 | /*! \fn Categories::Categories( const Categories ©From ) | ||
910 | |||
911 | Deep copy constructor | ||
912 | */ | ||
913 | |||
914 | /*! \fn Categories::~Categories() | ||
915 | |||
916 | Empty destructor. Call save() before destruction if there are changes | ||
917 | that need to be saved. | ||
918 | */ | ||
919 | |||
920 | /*! \fn CategoryGroup::clear() | ||
921 | \internal | ||
922 | */ | ||
923 | |||
924 | /*! \fn const QMap<int, QString> &CategoryGroup::idMap() const | ||
925 | |||
926 | Returns a const reference to the id to label QMap | ||
927 | */ | ||
928 | |||
929 | /*! \fn CategoryGroup::CategoryGroup() | ||
930 | \internal | ||
931 | */ | ||
932 | |||
933 | /*! \fn CategoryGroup::CategoryGroup(const CategoryGroup &c) | ||
934 | \internal | ||
935 | */ | ||
936 | |||