1 | /* |
2 | * This file is part of the syndication library |
3 | * |
4 | * Copyright (C) 2006 Frank Osterfeld <osterfeld@kde.org> |
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 GNU |
14 | * 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 |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | * |
21 | */ |
22 | |
23 | #ifndef SYNDICATION_CATEGORY_H |
24 | #define SYNDICATION_CATEGORY_H |
25 | |
26 | #include <QtCore/QString> |
27 | #include <boost/shared_ptr.hpp> |
28 | |
29 | #include "ksyndication_export.h" |
30 | |
31 | namespace Syndication { |
32 | |
33 | class Category; |
34 | typedef boost::shared_ptr<Category> CategoryPtr; |
35 | |
36 | /** |
37 | * A category for categorizing items or whole feeds. |
38 | * A category can be an informal string set by the feed author ("General", |
39 | * "Stuff I like"), a tag assigned by readers, as known from flickr.com |
40 | * or de.licio.us ("KDE", "funny"), or a term from a formally defined ontology. |
41 | * |
42 | * To represent the category in a user interface, use label() (or term() as |
43 | * fallback). To create a key for e.g. storage purposes, use scheme() + term(). |
44 | * |
45 | * @author Frank Osterfeld |
46 | */ |
47 | class SYNDICATION_EXPORT Category |
48 | { |
49 | public: |
50 | |
51 | /** |
52 | * destructor |
53 | */ |
54 | virtual ~Category(); |
55 | |
56 | /** |
57 | * returns whether this object is a null category |
58 | */ |
59 | virtual bool isNull() const = 0; |
60 | |
61 | |
62 | /** |
63 | * A term identifying the category, e.g. "general", "life", "books" |
64 | * or "Basketball & other sport I like". |
65 | * The term must be unique in its scheme (see scheme()). |
66 | * |
67 | * In user interfaces, use it only if there is no label() available. |
68 | * TODO: specify format (HTML, plain text?) and enforce it in the impl |
69 | * @return category term. This string is never empty. |
70 | */ |
71 | virtual QString term() const = 0; |
72 | |
73 | /** |
74 | * An optional scheme the term is part of. This can be some |
75 | * vocabulary/ontology such as Dublin Core. |
76 | * Think of it as the term's namespace, grouping a set of categories. |
77 | * When managing categories, scheme() + term() identifies a category |
78 | * unambigously and can be used as key. |
79 | * |
80 | * @return the scheme this category is part of, or a null string |
81 | * if not specified |
82 | */ |
83 | virtual QString scheme() const = 0; |
84 | |
85 | /** |
86 | * An optional human-readable label of the category. If specified, this |
87 | * string should be used to represent this category in a user interface. |
88 | * If not specified, use term() instead. |
89 | * TODO: specify format (HTML, plain text?) and enforce it in the impl |
90 | * @return the label of this category, or a null string if not specified |
91 | */ |
92 | virtual QString label() const = 0; |
93 | |
94 | /** |
95 | * Description of the category for debugging purposes. |
96 | * |
97 | * @return debug string |
98 | */ |
99 | virtual QString debugInfo() const; |
100 | }; |
101 | |
102 | } // namespace Syndication |
103 | |
104 | #endif // SYNDICATION_CATEGORY_H |
105 | |