Changeset View
Changeset View
Standalone View
Standalone View
src/acbf/AcbfBookinfo.h
Show All 22 Lines | |||||
23 | #define ACBFBOOKINFO_H | 23 | #define ACBFBOOKINFO_H | ||
24 | 24 | | |||
25 | #include <memory> | 25 | #include <memory> | ||
26 | 26 | | |||
27 | #include "AcbfMetadata.h" | 27 | #include "AcbfMetadata.h" | ||
28 | 28 | | |||
29 | #include <QHash> | 29 | #include <QHash> | ||
30 | 30 | | |||
31 | /** | ||||
32 | * \brief Class for handling the book metadata. | ||||
33 | * | ||||
34 | * ACBF book-info is all the metadata that relates | ||||
35 | * to the story inside. | ||||
36 | * | ||||
37 | * This class holds all the authors, titles, languages, | ||||
38 | * summaries, genres, keywords, hashtags and more. | ||||
39 | * | ||||
40 | * It also handles adding and removing, as well as storing | ||||
41 | * and reading it from the xml. | ||||
42 | * | ||||
43 | * ACBF can hold multiple authors per book. Authors have their own object. | ||||
44 | * | ||||
45 | * ACBF can hold titles, annotations(summaries or descriptions) and | ||||
46 | * a list of comma seperated keywords in several languages. | ||||
47 | * | ||||
48 | * Annotations in particular are a stringlist of paragraphs. | ||||
49 | * | ||||
50 | * ACBF's language support is further detailed in the Language object. | ||||
51 | * | ||||
52 | * ACBF can have multiple genres, but they are limited to a list of keys, given | ||||
53 | * by availableGenres(). | ||||
54 | * Genres can also indicate how much they apply on the given story, using | ||||
55 | * a match percentage. This allows noting that a story is 80% romance, and | ||||
56 | * 20% western for example. | ||||
57 | * | ||||
58 | * ACBF can also hold character names. Character names are a type of tag, and | ||||
59 | * especially relevant with American style multiverses, but also in Creative | ||||
60 | * Commons stories because the permissive licenses allow for easier reusage of | ||||
61 | * existing characters. | ||||
62 | * | ||||
63 | * The coverpage is defined in the book-info as a Page object. | ||||
64 | * | ||||
65 | * Finally, ACBF can hold metadata about database references, sequences and | ||||
66 | * content rating. All these too have their own objects. | ||||
67 | */ | ||||
68 | | ||||
31 | namespace AdvancedComicBookFormat | 69 | namespace AdvancedComicBookFormat | ||
32 | { | 70 | { | ||
33 | class Author; | 71 | class Author; | ||
34 | class Page; | 72 | class Page; | ||
35 | class Language; | 73 | class Language; | ||
36 | class Sequence; | 74 | class Sequence; | ||
37 | class DatabaseRef; | 75 | class DatabaseRef; | ||
38 | class ContentRating; | 76 | class ContentRating; | ||
39 | class ACBF_EXPORT BookInfo : public QObject | 77 | class ACBF_EXPORT BookInfo : public QObject | ||
40 | { | 78 | { | ||
41 | Q_OBJECT | 79 | Q_OBJECT | ||
42 | Q_PROPERTY(QStringList authorNames READ authorNames NOTIFY authorsChanged) | 80 | Q_PROPERTY(QStringList authorNames READ authorNames NOTIFY authorsChanged) | ||
43 | Q_PROPERTY(QStringList titleLanguages READ titleLanguages NOTIFY titleChanged) | 81 | Q_PROPERTY(QStringList titleLanguages READ titleLanguages NOTIFY titleChanged) | ||
44 | Q_PROPERTY(QStringList genres READ genres NOTIFY genresChanged) | 82 | Q_PROPERTY(QStringList genres READ genres NOTIFY genresChanged) | ||
45 | Q_PROPERTY(QStringList characters READ characters NOTIFY charactersChanged) | 83 | Q_PROPERTY(QStringList characters READ characters NOTIFY charactersChanged) | ||
46 | public: | 84 | public: | ||
47 | explicit BookInfo(Metadata* parent = nullptr); | 85 | explicit BookInfo(Metadata* parent = nullptr); | ||
48 | ~BookInfo() override; | 86 | ~BookInfo() override; | ||
49 | 87 | | |||
50 | Metadata* metadata(); | 88 | Metadata* metadata(); | ||
51 | 89 | | |||
90 | /** | ||||
91 | * \brief write the whole book-info section to the XML writer. | ||||
92 | */ | ||||
52 | void toXml(QXmlStreamWriter *writer); | 93 | void toXml(QXmlStreamWriter *writer); | ||
94 | | ||||
95 | /** | ||||
96 | * \brief load the whole book-info section from the xml into this object. | ||||
97 | * @return True if the xmlReader encountered no errors. | ||||
98 | */ | ||||
53 | bool fromXml(QXmlStreamReader *xmlReader); | 99 | bool fromXml(QXmlStreamReader *xmlReader); | ||
54 | 100 | | |||
101 | /** | ||||
102 | * @return The list of authors that worked on this book as author objects. | ||||
103 | */ | ||||
55 | QList<Author*> author(); | 104 | QList<Author*> author(); | ||
105 | | ||||
106 | /** | ||||
107 | * @return The list of authors that worked on this book as | ||||
108 | * a stringlist of names. | ||||
109 | */ | ||||
56 | QStringList authorNames() const; | 110 | QStringList authorNames() const; | ||
111 | | ||||
112 | /** | ||||
113 | * \brief get an author object by index. | ||||
114 | * @param index - the index of the author. | ||||
115 | */ | ||||
57 | Q_INVOKABLE Author* getAuthor(int index) const; | 116 | Q_INVOKABLE Author* getAuthor(int index) const; | ||
117 | | ||||
118 | /** | ||||
119 | * \brief add an author to the list. | ||||
120 | * @param activity - the role this author played. | ||||
121 | * @param language - the language of the author in language code, country | ||||
122 | * code format joined by a dash (not an underscore). | ||||
123 | * @param firstName - the given name of the author. | ||||
124 | * @param middleName - the middle name(s) of the author as a string. | ||||
125 | * @param lastName - the family name of the author. | ||||
126 | * @param nickName - the nickname of the author. | ||||
127 | * @param homePage - a homepage url to associate with this author. | ||||
128 | * @param email - an email adress to associate with this author. | ||||
129 | */ | ||||
58 | Q_INVOKABLE void addAuthor(QString activity, QString language, QString firstName, QString middleName, QString lastName, QString nickName, QString homePage, QString email); | 130 | Q_INVOKABLE void addAuthor(QString activity, QString language, QString firstName, QString middleName, QString lastName, QString nickName, QString homePage, QString email); | ||
131 | /** | ||||
132 | * \brief make changes to an author in the list. | ||||
133 | * @param index - The index of this author in the author list. | ||||
134 | * @param activity - the role this author played. | ||||
135 | * @param language - the language of the author in language code, country | ||||
136 | * code format joined by a dash (not an underscore). | ||||
137 | * @param firstName - the given name of the author. | ||||
138 | * @param middleName - the middle name(s) of the author as a string. | ||||
139 | * @param lastName - the family name of the author. | ||||
140 | * @param nickName - the nickname of the author. | ||||
141 | * @param homePage - a homepage url to associate with this author. | ||||
142 | * @param email - an email adress to associate with this author. | ||||
143 | */ | ||||
59 | Q_INVOKABLE void setAuthor(int index, QString activity, QString language, QString firstName, QString middleName, QString lastName, QString nickName, QString homePage, QString email); | 144 | Q_INVOKABLE void setAuthor(int index, QString activity, QString language, QString firstName, QString middleName, QString lastName, QString nickName, QString homePage, QString email); | ||
145 | /** | ||||
146 | * \brief remove an author in the list. | ||||
147 | * @param index - the index of the author to remove. | ||||
148 | */ | ||||
60 | Q_INVOKABLE void removeAuthor(int index); | 149 | Q_INVOKABLE void removeAuthor(int index); | ||
150 | /** | ||||
151 | * \brief add an author to the list. | ||||
152 | * @param author - the author object to add. | ||||
153 | */ | ||||
61 | void addAuthor(Author* author); | 154 | void addAuthor(Author* author); | ||
155 | /** | ||||
156 | * \brief remove an author to the list. | ||||
157 | * @param author - the author object to remove. | ||||
158 | */ | ||||
62 | void removeAuthor(Author* author); | 159 | void removeAuthor(Author* author); | ||
160 | /** | ||||
161 | * \brief triggers when the authors list changes. | ||||
162 | */ | ||||
63 | Q_SIGNAL void authorsChanged(); | 163 | Q_SIGNAL void authorsChanged(); | ||
64 | 164 | | |||
165 | /** | ||||
166 | * \brief this holds a list of titles regardless of language. | ||||
167 | * @return a stringlist with all the titles. | ||||
168 | */ | ||||
65 | Q_INVOKABLE QStringList titleForAllLanguages(); | 169 | Q_INVOKABLE QStringList titleForAllLanguages(); | ||
170 | /** | ||||
171 | * @return a list of the languages the titles are in. | ||||
172 | */ | ||||
66 | Q_INVOKABLE QStringList titleLanguages(); | 173 | Q_INVOKABLE QStringList titleLanguages(); | ||
174 | /** | ||||
175 | * \brief get the title for the given language. | ||||
176 | * @param language - the language of which to return the title for. | ||||
177 | * @return The title for the given language code. | ||||
178 | * When no language is supplied, returns english title. | ||||
179 | */ | ||||
67 | Q_INVOKABLE QString title(QString language = ""); | 180 | Q_INVOKABLE QString title(QString language = ""); | ||
181 | /** | ||||
182 | * \brief set the title for the given language code. | ||||
183 | * @param title - the title as a QString | ||||
184 | * @param language - the language code in language code, country | ||||
185 | * code format joined by a dash (not an underscore). | ||||
186 | * TODO: title() defaults to English when no language is given, but setTitle() does not... | ||||
187 | */ | ||||
68 | Q_INVOKABLE void setTitle(QString title, QString language = ""); | 188 | Q_INVOKABLE void setTitle(QString title, QString language = ""); | ||
189 | | ||||
190 | /** | ||||
191 | * \brief triggers when a title is set for any language. | ||||
192 | */ | ||||
69 | Q_SIGNAL void titleChanged(); | 193 | Q_SIGNAL void titleChanged(); | ||
70 | 194 | | |||
195 | /** | ||||
196 | * @return returns a hash of genre keys and their match percentage. | ||||
197 | */ | ||||
71 | Q_INVOKABLE QHash<QString, int> genre(); | 198 | Q_INVOKABLE QHash<QString, int> genre(); | ||
199 | /** | ||||
200 | * @return a list of strings for the genres. | ||||
201 | */ | ||||
72 | Q_INVOKABLE QStringList genres() const; | 202 | Q_INVOKABLE QStringList genres() const; | ||
203 | /** | ||||
204 | * @param genre - the genre for which to return the percentage. | ||||
205 | * @return an integer between 0 to 100 representing the match | ||||
206 | * percentage of the given genre. | ||||
207 | */ | ||||
73 | Q_INVOKABLE int genrePercentage(QString genre) const; | 208 | Q_INVOKABLE int genrePercentage(QString genre) const; | ||
209 | /** | ||||
210 | * \brief Set a genre and their match percentage. | ||||
211 | * @param genre - the name of the genre to add. | ||||
212 | * @param matchPercentage - the percentage of how much this genre matches. | ||||
213 | */ | ||||
74 | Q_INVOKABLE void setGenre(QString genre, int matchPercentage = 100); | 214 | Q_INVOKABLE void setGenre(QString genre, int matchPercentage = 100); | ||
215 | /** | ||||
216 | * \brief remove the genre from the hashlist. | ||||
217 | * @param genre - the genre name to remove. | ||||
218 | */ | ||||
75 | Q_INVOKABLE void removeGenre(QString genre); | 219 | Q_INVOKABLE void removeGenre(QString genre); | ||
220 | /** | ||||
221 | * \brief triggers when genres are set or removed. | ||||
222 | */ | ||||
76 | Q_SIGNAL void genresChanged(); | 223 | Q_SIGNAL void genresChanged(); | ||
224 | /** | ||||
225 | * \brief the list of approved genre names. | ||||
226 | */ | ||||
77 | Q_INVOKABLE static QStringList availableGenres(); | 227 | Q_INVOKABLE static QStringList availableGenres(); | ||
78 | 228 | | |||
229 | /** | ||||
230 | * @return character names as a stringlist. | ||||
231 | */ | ||||
79 | Q_INVOKABLE QStringList characters(); | 232 | Q_INVOKABLE QStringList characters(); | ||
233 | /** | ||||
234 | * \brief add a character to the characters list. | ||||
235 | * @param name - the name of the character to add. | ||||
236 | */ | ||||
80 | Q_INVOKABLE void addCharacter(QString name); | 237 | Q_INVOKABLE void addCharacter(QString name); | ||
238 | /** | ||||
239 | * \brief remove a character from the character list. | ||||
240 | * @param name - the name of the character to remove. | ||||
241 | */ | ||||
81 | Q_INVOKABLE void removeCharacter(QString name); | 242 | Q_INVOKABLE void removeCharacter(QString name); | ||
243 | /** | ||||
244 | * \brief this triggers when the character name list is changed. | ||||
245 | */ | ||||
82 | Q_SIGNAL void charactersChanged(); | 246 | Q_SIGNAL void charactersChanged(); | ||
83 | 247 | | |||
248 | /** | ||||
249 | * @return a list of annotations, which in turn are stringlists. | ||||
250 | */ | ||||
84 | Q_INVOKABLE QList<QStringList> annotationsForAllLanguage(); | 251 | Q_INVOKABLE QList<QStringList> annotationsForAllLanguage(); | ||
252 | /** | ||||
253 | * @return a list of languages the annotation is available in. | ||||
254 | */ | ||||
85 | Q_INVOKABLE QStringList annotationLanguages(); | 255 | Q_INVOKABLE QStringList annotationLanguages(); | ||
256 | /** | ||||
257 | * @param language - the language for which to return the annotation. | ||||
258 | * @return the annotation for the given language | ||||
259 | * as a stringlist of paragraphs | ||||
260 | */ | ||||
86 | Q_INVOKABLE QStringList annotation(QString language = ""); // empty string means "default language", as (un)defined by the specification... | 261 | Q_INVOKABLE QStringList annotation(QString language = ""); // empty string means "default language", as (un)defined by the specification... | ||
262 | /** | ||||
263 | * \brief set an annotation for the given language. | ||||
264 | * @param annotation - A stringlist of paragraphs which make | ||||
265 | * up the annotiation. | ||||
266 | * @param language - The language for which to set the annotation in | ||||
267 | * language code, country code format joined by a dash (not an underscore). | ||||
268 | */ | ||||
87 | Q_INVOKABLE void setAnnotation(QStringList annotation, QString language = ""); | 269 | Q_INVOKABLE void setAnnotation(QStringList annotation, QString language = ""); | ||
88 | 270 | | |||
271 | /** | ||||
272 | * @return a hashmap of languages and the keyword stringlists. | ||||
273 | */ | ||||
89 | QHash<QString, QStringList> keywordsForAllLanguage(); | 274 | QHash<QString, QStringList> keywordsForAllLanguage(); | ||
275 | /** | ||||
276 | * @param language - the language for which to return the keywords for. | ||||
277 | * @return a stringlist of keywords in the given language. | ||||
278 | */ | ||||
90 | QStringList keywords(QString language = ""); | 279 | QStringList keywords(QString language = ""); | ||
280 | /** | ||||
281 | * \brief set the list of keywords for the given language. | ||||
282 | * @param annotation - A stringlist of keywords | ||||
283 | * @param language - The language for which to set the annotation in | ||||
284 | * language code, country code format joined by a dash (not an underscore). | ||||
285 | */ | ||||
91 | void setKeywords(QStringList keywords, QString language = ""); | 286 | void setKeywords(QStringList keywords, QString language = ""); | ||
92 | 287 | | |||
288 | /** | ||||
289 | * @return the coverpage as a page object. | ||||
290 | */ | ||||
93 | Page* coverpage(); | 291 | Page* coverpage(); | ||
292 | /** | ||||
293 | * \brief set a cover page. | ||||
294 | * @param newCover | ||||
295 | */ | ||||
94 | void setCoverpage(Page* newCover); | 296 | void setCoverpage(Page* newCover); | ||
95 | 297 | | |||
298 | /** | ||||
299 | * @return a list of language objects for determining translations. | ||||
300 | */ | ||||
96 | QList<Language*> languages(); | 301 | QList<Language*> languages(); | ||
302 | /** | ||||
303 | * \brief add a language to the list of translations. | ||||
304 | * @param language - language object to add. | ||||
305 | */ | ||||
97 | void addLanguage(Language* language); | 306 | void addLanguage(Language* language); | ||
307 | /** | ||||
308 | * \brief remove a language from the translations. | ||||
309 | * @param language - language object to remove. | ||||
310 | */ | ||||
98 | void removeLanguage(Language* language); | 311 | void removeLanguage(Language* language); | ||
99 | 312 | | |||
313 | /** | ||||
314 | * @return a list of sequence objects that describe the series and | ||||
315 | * collections this book is part of. | ||||
316 | */ | ||||
100 | QList<Sequence*> sequence(); | 317 | QList<Sequence*> sequence(); | ||
318 | /** | ||||
319 | * \brief add a sequence object to indicate this book is part of one. | ||||
320 | * @param sequence - the sequence object that describes this book's place in | ||||
321 | * a sequence. | ||||
322 | */ | ||||
101 | void addSequence(Sequence* sequence); | 323 | void addSequence(Sequence* sequence); | ||
324 | /** | ||||
325 | * \brief remove a sequence object from the list of sequences this book is | ||||
326 | * part of. | ||||
327 | * @param sequence - the sequence object that describes this book's place in | ||||
328 | * a sequence. | ||||
329 | */ | ||||
102 | void removeSequence(Sequence* sequence); | 330 | void removeSequence(Sequence* sequence); | ||
103 | 331 | | |||
332 | /** | ||||
333 | * @returns a list of entries that this book has in various databases. | ||||
334 | */ | ||||
104 | QList<DatabaseRef*> databaseRef(); | 335 | QList<DatabaseRef*> databaseRef(); | ||
336 | /** | ||||
337 | * \brief add a database entry that this book has. | ||||
338 | * @param databaseRef - a databaseRef object describing this work's place | ||||
339 | * in a database. | ||||
340 | */ | ||||
105 | void addDatabaseRef(DatabaseRef* databaseRef); | 341 | void addDatabaseRef(DatabaseRef* databaseRef); | ||
342 | /** | ||||
343 | * \brief remove a database entry that this book has. | ||||
344 | * @param databaseRef - a databaseRef object describing this work's place | ||||
345 | * in a database. | ||||
346 | */ | ||||
106 | void removeDatabaseRef(DatabaseRef* databaseRef); | 347 | void removeDatabaseRef(DatabaseRef* databaseRef); | ||
107 | 348 | | |||
349 | /** | ||||
350 | * @returns a list of contentRating objects describing the audience for this | ||||
351 | * book. | ||||
352 | */ | ||||
108 | QList<ContentRating*> contentRating(); | 353 | QList<ContentRating*> contentRating(); | ||
354 | /** | ||||
355 | * \brief add a contentRating object to the contentratings. | ||||
356 | * @param contentRating - a contentRating object describing the label and | ||||
357 | * contentrating system. | ||||
358 | */ | ||||
109 | void addContentRating(ContentRating* contentRating); | 359 | void addContentRating(ContentRating* contentRating); | ||
360 | /** | ||||
361 | * \brief remove a contentRating object from the contentRatings. | ||||
362 | * @param contentRating - a contentRating object describing the label and | ||||
363 | * contentrating system. | ||||
364 | */ | ||||
110 | void removeContentRating(ContentRating* contentRating); | 365 | void removeContentRating(ContentRating* contentRating); | ||
111 | private: | 366 | private: | ||
112 | class Private; | 367 | class Private; | ||
113 | std::unique_ptr<Private> d; | 368 | std::unique_ptr<Private> d; | ||
114 | }; | 369 | }; | ||
115 | } | 370 | } | ||
116 | 371 | | |||
117 | #endif//ACBFBOOKINFO_H | 372 | #endif//ACBFBOOKINFO_H |