author | zecke <zecke> | 2002-09-10 12:09:49 (UTC) |
---|---|---|
committer | zecke <zecke> | 2002-09-10 12:09:49 (UTC) |
commit | 6b77a1cdb9536b1c135eb86d53a6b2c22c19b0a4 (patch) (unidiff) | |
tree | 6ebc93c6432f4ed9d00ef1448b6a047ef522a79a /library/backend/categories.cpp | |
parent | d10cddb3c9ce75bc90b14add14bc133737fe35aa (diff) | |
download | opie-6b77a1cdb9536b1c135eb86d53a6b2c22c19b0a4.zip opie-6b77a1cdb9536b1c135eb86d53a6b2c22c19b0a4.tar.gz opie-6b77a1cdb9536b1c135eb86d53a6b2c22c19b0a4.tar.bz2 |
Qtopia1-6 merge
still to test
bic changes to be resolved
more changes to be made?
Diffstat (limited to 'library/backend/categories.cpp') (more/less context) (ignore whitespace changes)
-rw-r--r-- | library/backend/categories.cpp | 327 |
1 files changed, 293 insertions, 34 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,16 +1,15 @@ | |||
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 | ** |
@@ -18,11 +17,11 @@ | |||
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 | ||
@@ -38,6 +37,24 @@ UidGen CategoryGroup::sUidGen( UidGen::PalmtopCenter ); | |||
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") ) |
@@ -58,6 +75,8 @@ void CategoryGroup::insert( int uid, const QString &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") ) |
@@ -73,6 +92,9 @@ bool CategoryGroup::add( int uid, const QString &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 ); |
@@ -85,6 +107,9 @@ bool CategoryGroup::remove( const QString &label ) | |||
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 ); |
@@ -97,6 +122,8 @@ bool CategoryGroup::remove( int uid ) | |||
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") ) |
@@ -113,23 +140,27 @@ bool CategoryGroup::rename( int uid, const QString &newLabel ) | |||
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 | { |
@@ -139,7 +170,7 @@ const QString &CategoryGroup::label(int uid) const | |||
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 ); |
@@ -148,6 +179,7 @@ int CategoryGroup::id(const QString &label) const | |||
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; |
@@ -159,6 +191,7 @@ QStringList CategoryGroup::labels() const | |||
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; |
@@ -177,9 +210,49 @@ QStringList CategoryGroup::labels(const QArray<int> &catids ) const | |||
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 |
182 | */ | 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 | ||
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 ) |
@@ -204,6 +277,11 @@ int Categories::addCategory( const QString &appname, | |||
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 | { |
@@ -229,6 +307,9 @@ int Categories::addCategory( const QString &appname, | |||
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 ); |
@@ -236,6 +317,12 @@ int Categories::addGlobalCategory( const QString &catname, int 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 ); |
@@ -245,10 +332,12 @@ int Categories::addGlobalCategory( const QString &catname ) | |||
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 |
251 | */ | 338 | found in the application group and \a checkGlobal is TRUE, then it |
339 | attempts to remove it from the global list | ||
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 ) |
@@ -268,6 +357,11 @@ bool Categories::removeCategory( const QString &appname, | |||
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 |
@@ -282,6 +376,10 @@ bool Categories::removeCategory( const QString &appname, int uid ) | |||
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 ); |
@@ -292,7 +390,10 @@ bool Categories::removeGlobalCategory( const QString &catname ) | |||
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 ) ) { |
@@ -302,9 +403,10 @@ bool Categories::removeGlobalCategory( int uid ) | |||
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, |
@@ -316,7 +418,7 @@ QStringList Categories::labels( const QString &app, | |||
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 | ||
@@ -338,6 +440,9 @@ QStringList Categories::labels( const QString &app, | |||
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 ) ) |
@@ -349,11 +454,17 @@ QString Categories::label( const QString &app, int id ) const | |||
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 |
356 | */ | 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. | ||
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 |
@@ -380,12 +491,17 @@ QString Categories::displaySingle( const QString &app, | |||
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; |
387 | int i; | 503 | int i; |
388 | 504 | ||
389 | for ( i=0, it=labels.begin(); it!=labels.end(); i++, ++it ) { | 505 | for ( i=0, it=labels.begin(); it!=labels.end(); i++, ++it ) { |
390 | int value = id( app, *it ); | 506 | int value = id( app, *it ); |
391 | if ( value != 0 ) { | 507 | if ( value != 0 ) { |
@@ -397,6 +513,11 @@ QArray<int> Categories::ids( const QString &app, const QStringList &labels) cons | |||
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.)") ) ) |
@@ -408,8 +529,13 @@ int Categories::id( const QString &app, const QString &cat ) const | |||
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, |
@@ -429,6 +555,12 @@ bool Categories::renameCategory( const QString &appname, | |||
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 | { |
@@ -440,6 +572,10 @@ bool Categories::renameGlobalCategory( const QString &oldName, | |||
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 ) |
@@ -458,13 +594,18 @@ void Categories::setGlobal( const QString &appname, | |||
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 | { |
@@ -478,6 +619,10 @@ bool Categories::exists( const QString &catname ) const | |||
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 | { |
@@ -490,7 +635,12 @@ bool Categories::exists( const QString &appname, | |||
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"; |
@@ -534,6 +684,9 @@ bool Categories::save( const QString &fname ) const | |||
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()); |
@@ -544,6 +697,12 @@ bool Categories::save( const QString &fname ) const | |||
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 ); |
@@ -619,12 +778,19 @@ bool Categories::load( const QString &fname ) | |||
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() ); |
@@ -675,3 +841,96 @@ void CheckedListView::setChecked( const QStringList &checked ) | |||
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 | |||