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