Syndication

category.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2006 Frank Osterfeld <[email protected]>
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
A category for categorizing items or whole feeds.
Definition: category.h:32
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Oct 3 2023 03:49:16 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.