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
16namespace Syndication
17{
18class Category;
19typedef QSharedPointer<Category> CategoryPtr;
20
21/*!
22 * \class Syndication::Category
23 * \inmodule Syndication
24 * \inheaderfile Syndication/Category
25 *
26 * \brief A category for categorizing items or whole feeds.
27 *
28 * A category can be an informal string set by the feed author ("General",
29 * "Stuff I like"), a tag assigned by readers, as known from flickr.com
30 * or de.licio.us ("KDE", "funny"), or a term from a formally defined ontology.
31 *
32 * To represent the category in a user interface, use label() (or term() as
33 * fallback). To create a key for e.g. storage purposes, use scheme() + term().
34 */
35class SYNDICATION_EXPORT Category
36{
37public:
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 *
53 * Returns category term. This string is never empty.
54 */
55 virtual QString term() const = 0;
56
57 /*!
58 * An optional scheme the term is part of. This can be some
59 * vocabulary/ontology such as Dublin Core.
60 * Think of it as the term's namespace, grouping a set of categories.
61 * When managing categories, scheme() + term() identifies a category
62 * unambiguously and can be used as key.
63 *
64 * Returns the scheme this category is part of, or a null string
65 * if not specified
66 */
67 virtual QString scheme() const = 0;
68
69 /*!
70 * An optional human-readable label of the category.
71 *
72 * If specified, this
73 * string should be used to represent this category in a user interface.
74 * If not specified, use term() instead.
75 *
76 * TODO: specify format (HTML, plain text?) and enforce it in the impl
77 *
78 * Returns the label of this category, or a null string if not specified
79 */
80 virtual QString label() const = 0;
81
82 /*!
83 * Description of the category for debugging purposes.
84 *
85 * Returns debug string
86 */
87 virtual QString debugInfo() const;
88};
89
90} // namespace Syndication
91
92#endif // SYNDICATION_CATEGORY_H
93

source code of syndication/src/category.h