File indexing completed on 2024-11-10 03:43:47
0001 /* 0002 This file is part of the syndication library 0003 SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef SYNDICATION_CATEGORY_H 0009 #define SYNDICATION_CATEGORY_H 0010 0011 #include <QSharedPointer> 0012 #include <QString> 0013 0014 #include "syndication_export.h" 0015 0016 namespace Syndication 0017 { 0018 class Category; 0019 typedef QSharedPointer<Category> CategoryPtr; 0020 0021 /** 0022 * A category for categorizing items or whole feeds. 0023 * A category can be an informal string set by the feed author ("General", 0024 * "Stuff I like"), a tag assigned by readers, as known from flickr.com 0025 * or de.licio.us ("KDE", "funny"), or a term from a formally defined ontology. 0026 * 0027 * To represent the category in a user interface, use label() (or term() as 0028 * fallback). To create a key for e.g. storage purposes, use scheme() + term(). 0029 * 0030 * @author Frank Osterfeld 0031 */ 0032 class SYNDICATION_EXPORT Category 0033 { 0034 public: 0035 /** 0036 * destructor 0037 */ 0038 virtual ~Category(); 0039 0040 /** 0041 * returns whether this object is a null category 0042 */ 0043 virtual bool isNull() const = 0; 0044 0045 /** 0046 * A term identifying the category, e.g. "general", "life", "books" 0047 * or "Basketball & other sport I like". 0048 * The term must be unique in its scheme (see scheme()). 0049 * 0050 * In user interfaces, use it only if there is no label() available. 0051 * TODO: specify format (HTML, plain text?) and enforce it in the impl 0052 * @return category term. This string is never empty. 0053 */ 0054 virtual QString term() const = 0; 0055 0056 /** 0057 * An optional scheme the term is part of. This can be some 0058 * vocabulary/ontology such as Dublin Core. 0059 * Think of it as the term's namespace, grouping a set of categories. 0060 * When managing categories, scheme() + term() identifies a category 0061 * unambiguously and can be used as key. 0062 * 0063 * @return the scheme this category is part of, or a null string 0064 * if not specified 0065 */ 0066 virtual QString scheme() const = 0; 0067 0068 /** 0069 * An optional human-readable label of the category. If specified, this 0070 * string should be used to represent this category in a user interface. 0071 * If not specified, use term() instead. 0072 * TODO: specify format (HTML, plain text?) and enforce it in the impl 0073 * @return the label of this category, or a null string if not specified 0074 */ 0075 virtual QString label() const = 0; 0076 0077 /** 0078 * Description of the category for debugging purposes. 0079 * 0080 * @return debug string 0081 */ 0082 virtual QString debugInfo() const; 0083 }; 0084 0085 } // namespace Syndication 0086 0087 #endif // SYNDICATION_CATEGORY_H