Syndication

category.h
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 * 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 */
32class SYNDICATION_EXPORT Category
33{
34public:
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
A category for categorizing items or whole feeds.
Definition category.h:33
virtual bool isNull() const =0
returns whether this object is a null category
virtual QString label() const =0
An optional human-readable label of the category.
virtual QString scheme() const =0
An optional scheme the term is part of.
virtual QString term() const =0
A term identifying the category, e.g.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:56:56 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.