diff --git a/src/acbf/AcbfAuthor.h b/src/acbf/AcbfAuthor.h --- a/src/acbf/AcbfAuthor.h +++ b/src/acbf/AcbfAuthor.h @@ -25,6 +25,39 @@ #include "AcbfMetadata.h" #include +/** + * \brief Class for handling ACBF style authors. + * + * ACBF style authors have their names split up into + * first/middle/last and nickname. This is because + * traditionally archives use a lastname, first name + * format to catalogue the entry, while in the west + * their proper name is firstname/lastname. + * + * Nickname is particularly necessary for comics because + * many artists use a nom de plume of sorts. + * + * activity is similar to EPUB role, but where EPUB uses + * MARC relators, ACBF has its own limited list of activities. + * These are available as a stringlist from + * the available activities function. + * + * Authors also have two contact options + * available(homepage and email), the official xsd + * allows multiple of these. + * + * Authors can also have a language assigned. + * This is relevant for translator in particular, but + * the official xsd does not invalidate any other with + * the attribute. + * + * Authors should, at minimum have a name, which is either + * a nickname, or a first and lastname. + * + * TODO: Authors can have multiple email and homepage entries + * according to the official xsd. + */ + namespace AdvancedComicBookFormat { class ACBF_EXPORT Author : public QObject @@ -35,30 +68,118 @@ explicit Author(Metadata* parent = nullptr); ~Author(); + /** + * Write the data from this author object into the XmlStream. + */ void toXml(QXmlStreamWriter* writer); + + /** + * \brief Load the data from the acbf xml into this author object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * \brief convenience function to put together the different parts + * of the author's name into a single string. + * @return a single string for the author's name. + */ Q_INVOKABLE QString displayName() const; + /** + * @return The activity this author performed on the book. + */ Q_INVOKABLE QString activity() const; + + /** + * \brief Set the activity this author performed on the book. + * @param activity - the activity as a string, should be an entry + * of availableActivities(). + */ Q_INVOKABLE void setActivity(const QString& activity); + + /** + * @return A list of all the approved activities. + */ Q_INVOKABLE static QStringList availableActivities(); - // The language this author worked in for this book. Activity dependent (writer, translator, letterer...) + /** + * \brief The language this author worked in for this book. Activity dependent (writer, translator, letterer...) + * @return The language in xs:language style language-COUNTRY format. + */ Q_INVOKABLE QString language() const; + + /** + * \brief Set the language used by this author, in particular necessary for translator. + * + * @param language should be xs:language, which is BCP 47 minus the script. + */ Q_INVOKABLE void setLanguage(const QString& language = QString()); + /** + * @return the given name of this author as a QString. + */ Q_INVOKABLE QString firstName() const; + + /** + * \brief Set the given name of this author. + * @param name - the given name as a string. + */ Q_INVOKABLE void setFirstName(const QString& name); + + /** + * @return the middles name(s) of this author as a QString. + */ Q_INVOKABLE QString middleName() const; + + /** + * \brief Set the middles name(s) of this author. + * @param name - the middle name(s) as a string. + */ Q_INVOKABLE void setMiddleName(const QString& name); + + /** + * @return the family name of this author as a QString. + */ Q_INVOKABLE QString lastName() const; + + /** + * \brief Set the family name of this author. + * @param name - the family name as a string. + */ Q_INVOKABLE void setLastName(const QString& name); + + /** + * @return the nick name of this author as a QString. + */ Q_INVOKABLE QString nickName() const; + + /** + * \brief set the nick name of this author. + * @param name - the nickname as a string. + */ Q_INVOKABLE void setNickName(const QString& name); + + /** + * @return the homepage associated with this author as a QString. + */ Q_INVOKABLE QString homePage() const; + + /** + * \brief Set the homepage associated with this author. + * @param homepage - the url of the homepage as a string. + */ Q_INVOKABLE void setHomePage(const QString& homepage); + + /** + * @return The email adress associated with this author as a QString. + */ Q_INVOKABLE QString email() const; + + /** + * \brief Set the email adress associated with this author. + * @param email - email as a string. + */ Q_INVOKABLE void setEmail(const QString& email); private: class Private; diff --git a/src/acbf/AcbfBinary.h b/src/acbf/AcbfBinary.h --- a/src/acbf/AcbfBinary.h +++ b/src/acbf/AcbfBinary.h @@ -31,6 +31,23 @@ class QXmlStreamReader; class QXmlStreamWriter; +/** + * \brief Class for handling the embedded data in ACBF + * + * ACBF allows for embedding images and fonts as Base64 bytearrays. + * + * The images are used to allow ACBF to be standalone. + * + * The fonts are used to indicate the appropriate style + * for text areas. + * + * This class holds the bytearray and mimetype, + * handling reading and loading from the xml. + * + * It does not convert the bytearrays + * to the appropriate object. + */ + namespace AdvancedComicBookFormat { class Data; @@ -41,16 +58,53 @@ explicit Binary(Data* parent = nullptr); ~Binary() override; + /** + *\brief Load binary data into xml. + */ void toXml(QXmlStreamWriter *writer); + + /** + * \brief Load binary data from xml. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return The ID of this binary data element as a QString. + * Used to identify it from other parts of the + * ACBF document. + */ QString id() const; + + /** + * \brief Set the ID for this binary element. + * This is used to reference this element from + * other parts of the ACBF document. + * @param newId - The new ID as a string. + */ void setId(const QString& newId); + /** + * @return the mimetype of the binary data as a QString. + */ QString contentType() const; + + /** + * \brief Indicate the mimetype of the binary data. + * @param newContentType - the mimetype in string format. + */ void setContentType(const QString& newContentType); + /** + * @return The binary data as a QByteArray. + */ QByteArray data() const; + + /** + * \brief Set the binary data to store in this element. + * + * @param newData - This should be a QByteArray. + */ void setData(const QByteArray& newData); private: class Private; diff --git a/src/acbf/AcbfBody.h b/src/acbf/AcbfBody.h --- a/src/acbf/AcbfBody.h +++ b/src/acbf/AcbfBody.h @@ -29,7 +29,17 @@ #include class QXmlStreamWriter; class QXmlStreamReader; - +/** + * \brief Class to handle the body section of ACBF. + * + * ACBF's body section holds all the pages. Beyond that, + * it has a bgcolor. The presence of the body section + * is mandatory. + * + * This class can load and save the body section. + * It also holds the page objects and allows + * ordering/adding/removing them. + */ namespace AdvancedComicBookFormat { class Page; @@ -42,19 +52,62 @@ Document* document() const; + /** + * \brief write body data into the XMLWriter. + */ void toXml(QXmlStreamWriter *writer); + + /** + * \brief Load data from the xml into this body object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return the background color as a QString. + * + * It should be an 8bit per channel rgb hexcode. + */ QString bgcolor() const; + + /** + * \brief set the background color. + * + * @param newColor - a String with an 8bit per channel rgb hexcode (#ff00ff, or the like) + */ void setBgcolor(const QString& newColor); + /** + * @return a QList of all the pages stored currently. + */ QList pages() const; + + /** + * @param index - the index of the page. + * @return the page object at the given index. + */ Page* page(int index) const; + + /** + * @param page - The page for which to return the index. + * @return index of the page given, will return -1 if the page isn't in this document. + */ int pageIndex(Page* page) const; // If afterIndex is larger than zero, the insertion will happen at that index void addPage(Page* page, int index = -1); + + /** + * \brief remove the given page object from this body. + * @param page - the page to remove. + */ void removePage(Page* page); + + /** + * \brief Swap two pages in the list. + * @param swapThis - the first page to swap. + * @param withThis - the second page to swap. + */ bool swapPages(Page* swapThis, Page* withThis); private: diff --git a/src/acbf/AcbfBookinfo.h b/src/acbf/AcbfBookinfo.h --- a/src/acbf/AcbfBookinfo.h +++ b/src/acbf/AcbfBookinfo.h @@ -28,6 +28,44 @@ #include +/** + * \brief Class for handling the book metadata. + * + * ACBF book-info is all the metadata that relates + * to the story inside. + * + * This class holds all the authors, titles, languages, + * summaries, genres, keywords, hashtags and more. + * + * It also handles adding and removing, as well as storing + * and reading it from the xml. + * + * ACBF can hold multiple authors per book. Authors have their own object. + * + * ACBF can hold titles, annotations(summaries or descriptions) and + * a list of comma seperated keywords in several languages. + * + * Annotations in particular are a stringlist of paragraphs. + * + * ACBF's language support is further detailed in the Language object. + * + * ACBF can have multiple genres, but they are limited to a list of keys, given + * by availableGenres(). + * Genres can also indicate how much they apply on the given story, using + * a match percentage. This allows noting that a story is 80% romance, and + * 20% western for example. + * + * ACBF can also hold character names. Character names are a type of tag, and + * especially relevant with American style multiverses, but also in Creative + * Commons stories because the permissive licenses allow for easier reusage of + * existing characters. + * + * The coverpage is defined in the book-info as a Page object. + * + * Finally, ACBF can hold metadata about database references, sequences and + * content rating. All these too have their own objects. + */ + namespace AdvancedComicBookFormat { class Author; @@ -49,64 +87,281 @@ Metadata* metadata(); + /** + * \brief write the whole book-info section to the XML writer. + */ void toXml(QXmlStreamWriter *writer); + + /** + * \brief load the whole book-info section from the xml into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return The list of authors that worked on this book as author objects. + */ QList author(); + + /** + * @return The list of authors that worked on this book as + * a stringlist of names. + */ QStringList authorNames() const; + + /** + * \brief get an author object by index. + * @param index - the index of the author. + */ Q_INVOKABLE Author* getAuthor(int index) const; + + /** + * \brief add an author to the list. + * @param activity - the role this author played. + * @param language - the language of the author in language code, country + * code format joined by a dash (not an underscore). + * @param firstName - the given name of the author. + * @param middleName - the middle name(s) of the author as a string. + * @param lastName - the family name of the author. + * @param nickName - the nickname of the author. + * @param homePage - a homepage url to associate with this author. + * @param email - an email adress to associate with this author. + */ Q_INVOKABLE void addAuthor(QString activity, QString language, QString firstName, QString middleName, QString lastName, QString nickName, QString homePage, QString email); + /** + * \brief make changes to an author in the list. + * @param index - The index of this author in the author list. + * @param activity - the role this author played. + * @param language - the language of the author in language code, country + * code format joined by a dash (not an underscore). + * @param firstName - the given name of the author. + * @param middleName - the middle name(s) of the author as a string. + * @param lastName - the family name of the author. + * @param nickName - the nickname of the author. + * @param homePage - a homepage url to associate with this author. + * @param email - an email adress to associate with this author. + */ Q_INVOKABLE void setAuthor(int index, QString activity, QString language, QString firstName, QString middleName, QString lastName, QString nickName, QString homePage, QString email); + /** + * \brief remove an author in the list. + * @param index - the index of the author to remove. + */ Q_INVOKABLE void removeAuthor(int index); + /** + * \brief add an author to the list. + * @param author - the author object to add. + */ void addAuthor(Author* author); + /** + * \brief remove an author to the list. + * @param author - the author object to remove. + */ void removeAuthor(Author* author); + /** + * \brief triggers when the authors list changes. + */ Q_SIGNAL void authorsChanged(); + /** + * \brief this holds a list of titles regardless of language. + * @return a stringlist with all the titles. + */ Q_INVOKABLE QStringList titleForAllLanguages(); + /** + * @return a list of the languages the titles are in. + */ Q_INVOKABLE QStringList titleLanguages(); + /** + * \brief get the title for the given language. + * @param language - the language of which to return the title for. + * @return The title for the given language code. + * When no language is supplied, returns english title. + */ Q_INVOKABLE QString title(QString language = ""); + /** + * \brief set the title for the given language code. + * @param title - the title as a QString + * @param language - the language code in language code, country + * code format joined by a dash (not an underscore). + * TODO: title() defaults to English when no language is given, but setTitle() does not... + */ Q_INVOKABLE void setTitle(QString title, QString language = ""); + + /** + * \brief triggers when a title is set for any language. + */ Q_SIGNAL void titleChanged(); + /** + * @return returns a hash of genre keys and their match percentage. + */ Q_INVOKABLE QHash genre(); + /** + * @return a list of strings for the genres. + */ Q_INVOKABLE QStringList genres() const; + /** + * @param genre - the genre for which to return the percentage. + * @return an integer between 0 to 100 representing the match + * percentage of the given genre. + */ Q_INVOKABLE int genrePercentage(QString genre) const; + /** + * \brief Set a genre and their match percentage. + * @param genre - the name of the genre to add. + * @param matchPercentage - the percentage of how much this genre matches. + */ Q_INVOKABLE void setGenre(QString genre, int matchPercentage = 100); + /** + * \brief remove the genre from the hashlist. + * @param genre - the genre name to remove. + */ Q_INVOKABLE void removeGenre(QString genre); + /** + * \brief triggers when genres are set or removed. + */ Q_SIGNAL void genresChanged(); + /** + * \brief the list of approved genre names. + */ Q_INVOKABLE static QStringList availableGenres(); + /** + * @return character names as a stringlist. + */ Q_INVOKABLE QStringList characters(); + /** + * \brief add a character to the characters list. + * @param name - the name of the character to add. + */ Q_INVOKABLE void addCharacter(QString name); + /** + * \brief remove a character from the character list. + * @param name - the name of the character to remove. + */ Q_INVOKABLE void removeCharacter(QString name); + /** + * \brief this triggers when the character name list is changed. + */ Q_SIGNAL void charactersChanged(); + /** + * @return a list of annotations, which in turn are stringlists. + */ Q_INVOKABLE QList annotationsForAllLanguage(); + /** + * @return a list of languages the annotation is available in. + */ Q_INVOKABLE QStringList annotationLanguages(); + /** + * @param language - the language for which to return the annotation. + * @return the annotation for the given language + * as a stringlist of paragraphs + */ Q_INVOKABLE QStringList annotation(QString language = ""); // empty string means "default language", as (un)defined by the specification... + /** + * \brief set an annotation for the given language. + * @param annotation - A stringlist of paragraphs which make + * up the annotiation. + * @param language - The language for which to set the annotation in + * language code, country code format joined by a dash (not an underscore). + */ Q_INVOKABLE void setAnnotation(QStringList annotation, QString language = ""); + /** + * @return a hashmap of languages and the keyword stringlists. + */ QHash keywordsForAllLanguage(); + /** + * @param language - the language for which to return the keywords for. + * @return a stringlist of keywords in the given language. + */ QStringList keywords(QString language = ""); + /** + * \brief set the list of keywords for the given language. + * @param annotation - A stringlist of keywords + * @param language - The language for which to set the annotation in + * language code, country code format joined by a dash (not an underscore). + */ void setKeywords(QStringList keywords, QString language = ""); + /** + * @return the coverpage as a page object. + */ Page* coverpage(); + /** + * \brief set a cover page. + * @param newCover + */ void setCoverpage(Page* newCover); + /** + * @return a list of language objects for determining translations. + */ QList languages(); + /** + * \brief add a language to the list of translations. + * @param language - language object to add. + */ void addLanguage(Language* language); + /** + * \brief remove a language from the translations. + * @param language - language object to remove. + */ void removeLanguage(Language* language); + /** + * @return a list of sequence objects that describe the series and + * collections this book is part of. + */ QList sequence(); + /** + * \brief add a sequence object to indicate this book is part of one. + * @param sequence - the sequence object that describes this book's place in + * a sequence. + */ void addSequence(Sequence* sequence); + /** + * \brief remove a sequence object from the list of sequences this book is + * part of. + * @param sequence - the sequence object that describes this book's place in + * a sequence. + */ void removeSequence(Sequence* sequence); + /** + * @returns a list of entries that this book has in various databases. + */ QList databaseRef(); + /** + * \brief add a database entry that this book has. + * @param databaseRef - a databaseRef object describing this work's place + * in a database. + */ void addDatabaseRef(DatabaseRef* databaseRef); + /** + * \brief remove a database entry that this book has. + * @param databaseRef - a databaseRef object describing this work's place + * in a database. + */ void removeDatabaseRef(DatabaseRef* databaseRef); + /** + * @returns a list of contentRating objects describing the audience for this + * book. + */ QList contentRating(); + /** + * \brief add a contentRating object to the contentratings. + * @param contentRating - a contentRating object describing the label and + * contentrating system. + */ void addContentRating(ContentRating* contentRating); + /** + * \brief remove a contentRating object from the contentRatings. + * @param contentRating - a contentRating object describing the label and + * contentrating system. + */ void removeContentRating(ContentRating* contentRating); private: class Private; diff --git a/src/acbf/AcbfContentrating.h b/src/acbf/AcbfContentrating.h --- a/src/acbf/AcbfContentrating.h +++ b/src/acbf/AcbfContentrating.h @@ -25,7 +25,15 @@ #include #include "AcbfBookinfo.h" - +/** + * \brief Class to handle the content rating of the work. + * + * Because there are multiple ContentRating systems over various + * countries, ACBF can handle multiple content rating objects, and + * has entries for handling which system said rating is in. + * + * This is used in the BookInfo object. + */ namespace AdvancedComicBookFormat { class ACBF_EXPORT ContentRating : public QObject @@ -35,13 +43,34 @@ explicit ContentRating(BookInfo* parent = nullptr); ~ContentRating() override; + /** + * \brief write this content rating to the xml writer. + */ void toXml(QXmlStreamWriter* writer); + /** + * \brief load a content-rating section from the xml into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return the system that the content rating belongs to. + */ QString type() const; + /** + * \brief set the system that defines this rating. + * @param type - the name of the system. + */ void setType(const QString& type); + /** + * @return the rating label as a string. + */ QString rating() const; + /** + * \brief set the rating. + * @param rating - the name of the rating label as a QString. + */ void setRating(const QString& rating); private: class Private; diff --git a/src/acbf/AcbfData.h b/src/acbf/AcbfData.h --- a/src/acbf/AcbfData.h +++ b/src/acbf/AcbfData.h @@ -29,7 +29,16 @@ #include "AcbfDocument.h" #include "AcbfBinary.h" - +/** + * \brief Class to handle the list of embedded data in an ACBF document. + * + * ACBF allows embedding images and fonts as Base64 bytearrays. + * They are stored in the data section of the file, with a binary + * element each. + * + * This class holds Binary objects which in turn hold the binary data. + * This class cannot yet modify the entries or add and remove entries. + */ namespace AdvancedComicBookFormat { class ACBF_EXPORT Data : public QObject @@ -39,9 +48,20 @@ explicit Data(Document* parent = nullptr); ~Data() override; + /** + * \brief writes the data section and its entries to the file. + */ void toXml(QXmlStreamWriter *writer); + /** + * \brief load the data section from the xml into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @param id - the id that is used to reference to this object. + * @return the binary object referenced by this id. + */ Binary* binary(const QString& id) const; private: class Private; diff --git a/src/acbf/AcbfDatabaseref.h b/src/acbf/AcbfDatabaseref.h --- a/src/acbf/AcbfDatabaseref.h +++ b/src/acbf/AcbfDatabaseref.h @@ -24,7 +24,18 @@ #include #include "AcbfBookinfo.h" - +/** + * \brief Class to handle references to this book in catalogues and databases. + * + * Books can have entries in databases and library catalogues. If such an entry + * exists, the DatabaseRef object can hold it. Such entries are useful to figure + * out if two stories are related, or to retrieve extra information about the book + * such as collections it may be part of. + * + * dbname is the name of the database. + * type is the type of reference it is, such as IssueID, SeriesID, or just plain URL. + * reference is the actual reference. + */ namespace AdvancedComicBookFormat { class ACBF_EXPORT DatabaseRef : public QObject @@ -34,16 +45,44 @@ explicit DatabaseRef(BookInfo* parent = nullptr); ~DatabaseRef() override; + /** + * \brief write the contents of this object into the xmlwriter. + */ void toXml(QXmlStreamWriter* writer); + /** + * \brief load a DatabaseRef section from the xml into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return the name of the database. + */ QString dbname() const; + /** + * \brief set the name of the database for this reference. + * @param dbname - the name of the database. + */ void setDbname(const QString& dbname); + /** + * @returns the type of reference the reference is. + */ QString type() const; + /** + * \brief set which type of reference the reference is. + * @param type - the type of reference. + */ void setType(const QString& type); + /** + * @returns the reference. + */ QString reference() const; + /** + * \brief set the reference as a string. + * @param reference - the reference a QString. + */ void setReference(const QString& reference); private: class Private; diff --git a/src/acbf/AcbfDocument.h b/src/acbf/AcbfDocument.h --- a/src/acbf/AcbfDocument.h +++ b/src/acbf/AcbfDocument.h @@ -26,7 +26,23 @@ #include #include "acbf_export.h" - +/** + * \brief Class that handles all of the ACBF document. + * + * ACBF documents are made up of several subsections: + * + * - Metadata, which in turn holds book, publishing and document info. + * - Body, which holds the pages and their frame and text definitions. + * - Data, which holds embedded data like images and fonts. + * - References, a section which holds notes and references that can be pointed + * at from the text. Not supported currently. + * - Stylesheet, which is a css stylesheet to inform how overlaid translations + * should be rendered. Not supported currently. + * + * Of these, only Body and Metadata are necessary for a proper ACBF file. + * + * TODO: Support references and stylesheets. + */ namespace AdvancedComicBookFormat { class Metadata; @@ -42,14 +58,33 @@ explicit Document(QObject* parent = nullptr); ~Document() override; + /** + * \brief write the whole document to an ACBF xml. + */ QString toXml(); + /** + * \brief load an ACBF file from XML. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QString xmlDocument); + /** + * @returns The metadata object. + */ Metadata* metaData() const; + /** + * \brief triggers when the metadata is changed. + */ Q_SIGNAL void metaDataChanged(); + /** + * @returns the Body object. + */ Body* body() const; // References* references(); + /** + * @returns the Data object. + */ Data* data() const; // Stylesheet* stylesheet(); private: diff --git a/src/acbf/AcbfDocumentinfo.h b/src/acbf/AcbfDocumentinfo.h --- a/src/acbf/AcbfDocumentinfo.h +++ b/src/acbf/AcbfDocumentinfo.h @@ -27,7 +27,16 @@ #include "AcbfMetadata.h" #include - +/** + * \brief Class to handle the DocumentInfo section. + * + * DocumentInfo, in ACBF is the data about the ACBF file itself. + * It contains the ACBF author, creation date, original source, version + * number and a version history. + * + * Sources is a stringlist, which is useful when the ACBF encompasses several + * pages of a webcomic, for example. + */ namespace AdvancedComicBookFormat { class Author; @@ -40,27 +49,86 @@ Metadata* metadata() const; + /** + * \brief write the documentinfo into the XML writer. + */ void toXml(QXmlStreamWriter *writer); + /** + * \brief load the DocumentInfo into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * \brief the list of authors that worked on this specific acbf. + * @return a list of author objects. + */ QList author() const; + /** + * \brief add an Author object to the list of authors. + * @param author - an author object. + */ void addAuthor(Author* author); + /** + * \brief remove an Author object from the list of authors. + * @param author - an author object. + */ void removeAuthor(Author* author); + /** + * @return a QDate with the creation date of this file. + */ QDate creationDate() const; + /** + * \brief set the creation date of this file. + * @param creationDate - a QDate object holding the creation date. + */ void setCreationDate(const QDate& creationDate); + /** + * @return a list of sources that this ACBF is an adaptation of. + */ QStringList source() const; + /** + * \brief set the list of source that this ACBF is an adaptation of. + * @param source - a stringlist of sources. + */ void setSource(const QStringList& source); + /** + * @returns the unique id of this ACBF document, used for cataloguing purposes. + */ QString id() const; + /** + * \brief set the unique ID for this file used for cataloguing purposes. + * @param id - a unique ID. Can be any kind of string, a UUID is recommended as default. + */ void setId(const QString& id); + /** + * @return the version of this document. + */ QString version() const; + /** + * \brief set the version of this document + * @param version - the version as a string. + * TODO: The official XSD requires a floating point number here. + */ void setVersion(const QString& version); + /** + * @return a list of history entries as a stringlist. + */ QStringList history() const; + /** + * \brief set the whole history list as a single stringlist. + * @param history - the whole history of the document as a stringlist. + */ void setHistory(const QStringList& history); + /** + * \brief add a single entry to the document history. + * @param historyLine - a single entry in the document. + */ void addHistoryLine(const QString& historyLine); private: class Private; diff --git a/src/acbf/AcbfLanguage.h b/src/acbf/AcbfLanguage.h --- a/src/acbf/AcbfLanguage.h +++ b/src/acbf/AcbfLanguage.h @@ -25,25 +25,56 @@ #include #include "AcbfBookinfo.h" - +/** + * \brief Class to handle the list of translations in an ACBF document. + * + * Due to an oddity in the naming of certain elements in the ACBF standard, this class + * actually represents a text-layer sub-element in the languages subelement of book-info. + * + * Show determines whether the language in question can be overlaid(true) or is actually the + * language the comic is written in(false). + */ namespace AdvancedComicBookFormat { -// Due to an oddity in the naming of certain elements in the ACBF standard, this class -// actually represents a text-layer sub-element in the languages subelement of book-info + class ACBF_EXPORT Language : public QObject { Q_OBJECT public: explicit Language(BookInfo* parent = nullptr); ~Language() override; + /** + * \brief write the language into the XML writer. + */ void toXml(QXmlStreamWriter* writer); + /** + * \brief load a language element into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * \brief set the language of this language entry. + * @param language - the language of the entry in language code, country + * code format joined by a dash (not an underscore). + */ void setLanguage(const QString& language); + /** + * @returns the language of this language entry. + */ QString language() const; + /** + * \brief set whether the language entry should be overlaid(true) or is the native + * language(false). + * @param show - wether to overlay or not. + */ void setShow(bool show); + /** + * @return whether the language entry should be overlaid(true) or is the native + * language(false). + */ bool show() const; private: class Private; diff --git a/src/acbf/AcbfMetadata.h b/src/acbf/AcbfMetadata.h --- a/src/acbf/AcbfMetadata.h +++ b/src/acbf/AcbfMetadata.h @@ -26,6 +26,17 @@ #include "AcbfDocument.h" +/** + * \brief Class to handle the metadata section of ACBF. + * + * ACBF metadata is split into three sections: + * + * - Book-info, which handles the metadata about the story. + * - Publishing-info, which handles the metadata about the publishing. + * - Document-info, which handles the metadata about this specific ACBF document. + * + * All three are mandatory. + */ class QXmlStreamWriter; class QXmlStreamReader; namespace AdvancedComicBookFormat @@ -42,12 +53,31 @@ Document* document() const; + /** + * \brief Write the metadata into the xml writer. + */ void toXml(QXmlStreamWriter *writer); + /** + * \brief load the metadata element into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return the bookinfo object. + */ BookInfo* bookInfo() const; + /** + * \brief triggers when the bookinfo is changed. + */ Q_SIGNAL void bookInfoChanged(); + /** + * @returns the publishinfo object. + */ PublishInfo* publishInfo() const; + /** + * @returns the documentinfo object. + */ DocumentInfo* documentInfo() const; private: class Private; diff --git a/src/acbf/AcbfPage.h b/src/acbf/AcbfPage.h --- a/src/acbf/AcbfPage.h +++ b/src/acbf/AcbfPage.h @@ -23,7 +23,30 @@ #define ACBFPAGE_H #include "AcbfDocument.h" - +/** + * \brief Class to handle page objects. + * + * A proper ACBF document should have entries for all pages + * and said entries should point at the images that make up + * the comic. + * + * However, ACBF also has room from frame definitions, transcriptions, + * translations, table of contents, jumps and more. + * + * The frame definitions are used to navigate a page and zoom efficiently on a + * small screen. Similarly, transscriptions and translations can be used to show + * text when the image itself is too blurry. + * + * Title is used to generate a table of contents. + * + * Transition is to indicate extra information about how the page should be entered. + * + * bgcolor is used by the reading software to determine what background color to give. + * + * Jumps can be used to move around in the comic. + * + * TODO: Frame and Jump seem to be missing classes despite being used here? + */ class QXmlStreamWriter; class QXmlStreamReader; namespace AdvancedComicBookFormat @@ -39,47 +62,170 @@ explicit Page(Document* parent = nullptr); ~Page() override; + /** + * \brief Write the page into the xml writer. + */ void toXml(QXmlStreamWriter* writer); + /** + * \brief load a page element into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return the background color as a QString. + * + * It should be an 8bit per channel rgb hexcode. + */ QString bgcolor() const; + /** + * \brief set the background color. + * + * @param newColor - a String with an 8bit per channel rgb hexcode (#ff00ff, or the like) + */ void setBgcolor(const QString& newColor = QString()); + /** + * @return transition type as a string. + */ QString transition() const; + /** + * \brief set the transition type. + * @param transition - the transition type, possible entries are in the availableTransitions() stringlist. + */ void setTransition(const QString& transition); + /** + * @returns a list of strings that can be used for the transition. + */ static QStringList availableTransitions(); + /** + * @return all titles for this page in all languages. + */ QStringList titleForAllLanguages() const; + /** + * @param language - the language of the entry in language code, country + * code format joined by a dash (not an underscore). + * @return the title for this language. + */ QString title(const QString& language = QString()) const; + /** + * \brief set the title for this language. + * @param language - the language of the entry in language code, country + * code format joined by a dash (not an underscore). + */ void setTitle(const QString& title, const QString& language = QString()); + /** + * @returns the URI for the image of this page as a QString + */ QString imageHref() const; + /** + * \brief set the URI for the image of this page. + * @param imageHref - the URI to an image. + * + * - A Binary representation will use the ID of that representation. + * - A reference to a file on the internet will start with "http://" or "https://" + * - A reference to a file in a zip will be prefixed with "zip:" + * - Everything else is presumed to be a file on disk. + */ void setImageHref(const QString& imageHref); + /** + * @returns all the textlayers objects. + */ QList textLayersForAllLanguages() const; + /** + * @param language - the language of the entry in language code, country + * code format joined by a dash (not an underscore). + * @returns the TextLayer object for that language. + */ Textlayer* textLayer(const QString& language = QString()) const; - // Setting the textlayer for a language to null removes that language (as with other translated entries, though this one not being text warranted a comment) + /** + * + * @param language - the language of the entry in language code, country + * code format joined by a dash (not an underscore). Setting the textlayer + * for a language to null removes that language (as with other translated + * entries, though this one not being text warranted a comment) + */ void setTextLayer(Textlayer* textlayer, const QString& language = ""); + /** + * @returns a list of frames in this page. + */ QList frames() const; + /** + * @param index - index of the frame. + * @return the frame of that index. + */ Frame* frame(int index) const; + /** + * @param frame - the frame you want to index of. + * @returns the index of the given frame. + */ int frameIndex(Frame* frame) const; - // If afterIndex is larger than zero, the insertion will happen at that index + /** + * \brief add a frame to the list of frames. + * @param frame - the frame to add. + * @param index - the index to add it at. If afterIndex is larger than + * zero, the insertion will happen at that index + */ void addFrame(Frame* frame, int index = -1); + /** + * \brief remove the given frame from the framelist. + * @param frame - the frame to remove. + */ void removeFrame(Frame* frame); + /** + * \brief Swap two frames in the list. + * @param swapThis - the first frame to swap. + * @param withThis - the second frame to swap. + */ bool swapFrames(Frame* swapThis, Frame* withThis); + /** + * @return the list of jump objects for this page. + */ QList jumps() const; + /** + * @param index - the index for which you want the jump object. + * @return a jump object for the given frame. + */ Jump* jump(int index) const; + /** + * @param jump - the jump you want to index of. + * @returns the index of the given jump. + */ int jumpIndex(Jump* jump) const; - // If afterIndex is larger than zero, the insertion will happen at that index + /** + * \brief add a jump to the list of frames. + * @param jump - the jump to add. + * @param index - the index to add it at. If afterIndex is larger than + * zero, the insertion will happen at that index + */ void addJump(Jump* jump, int index = -1); + /** + * \brief remove the given jump from the list of jumps. + * @param jump - the jump to remove. + */ void removeJump(Jump* jump); + /** + * \brief Swap two jumps in the list. + * @param swapThis - the first jumps to swap. + * @param withThis - the second jumps to swap. + */ bool swapJumps(Jump* swapThis, Jump* withThis); + /** + * @returns whether this is the cover page. + */ bool isCoverPage() const; + /** + * \brief toggle whether this is the cover page. + * + */ void setIsCoverPage(bool isCoverPage = false); private: class Private; diff --git a/src/acbf/AcbfPublishinfo.h b/src/acbf/AcbfPublishinfo.h --- a/src/acbf/AcbfPublishinfo.h +++ b/src/acbf/AcbfPublishinfo.h @@ -27,7 +27,13 @@ #include "AcbfMetadata.h" #include - +/** + * \brief Class to handle the publishing info. + * + * The Publishing info in ACBF is about who published the book, + * when, where, the ISBN number, and which license it was published + * under. + */ namespace AdvancedComicBookFormat { class ACBF_EXPORT PublishInfo : public QObject @@ -37,22 +43,63 @@ explicit PublishInfo(Metadata* parent = nullptr); ~PublishInfo() override; + /** + * \brief Write the publishingInfo into the xml writer. + */ void toXml(QXmlStreamWriter *writer); + /** + * \brief load the publishing info into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return the name of the publisher. + */ QString publisher() const; + /** + * \brief set the name of the publisher. + */ void setPublisher(const QString& publisher); + /** + * @return the publishing date as a QDate object. + */ QDate publishDate() const; + /** + * \brief set the publishing date. + * @param publishDate - the publishingdate as a QDate object. + */ void setPublishDate(const QDate& publishDate); + /** + * @return the name of the city the work was published in. + */ QString city() const; + /** + * \brief set the name of the city the work was published in. + * @param city - the name of the city as a QString. + */ void setCity(const QString& city = QString()); + /** + * @return the ISBN number as a QString. + */ QString isbn() const; + /** + * \brief set the ISBN number. + * @param isbn - the ISBN number as a QString. ISBN numbers should be registered. + */ void setIsbn(const QString& isbn = QString()); + /** + * @return the name of the license the comic was published under. + */ QString license() const; + /** + * \brief set the License that the work was published under. + * @param license - the name of the license as a QString. + */ void setLicense(const QString& license = QString()); private: class Private; diff --git a/src/acbf/AcbfSequence.h b/src/acbf/AcbfSequence.h --- a/src/acbf/AcbfSequence.h +++ b/src/acbf/AcbfSequence.h @@ -25,7 +25,13 @@ #include #include "AcbfBookinfo.h" - +/** + * \brief Class to handle the sequence information. + * + * A comic book can be part of several collections or series. + * ACBF can handle multiple sequences, with numbers and volumes. + * + */ namespace AdvancedComicBookFormat { class ACBF_EXPORT Sequence : public QObject @@ -35,17 +41,46 @@ explicit Sequence(BookInfo * parent = nullptr); ~Sequence() override; + /** + * \brief Write the sequence into the xml writer. + */ void toXml(QXmlStreamWriter* writer); + /** + * \brief load the sequence element into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @returns the name of the series or sequence. + */ QString title() const; + /** + * \brief set the name of the sequence. + * @param title - the name of the sequence as a QString. + */ void setTitle(const QString& title); - // Optional attribute - if set to 0, this is not saved + /** + * @returns the volume number. + */ int volume() const; + /** + * \brief set the volume number. + * @param volume - The volume number, this is optional + * if set to 0, this is not saved + */ void setVolume(int volume = 0); + /** + * @return the number that this work takes up in the sequence. + */ int number() const; + /** + * \brief set the number in the sequence. + * @param number - an interger number that indicates where it is + * part of the series. + */ void setNumber(int number); private: class Private; diff --git a/src/acbf/AcbfTextarea.h b/src/acbf/AcbfTextarea.h --- a/src/acbf/AcbfTextarea.h +++ b/src/acbf/AcbfTextarea.h @@ -28,6 +28,13 @@ #include +/** + * \brief Class to handle the text areas in ACBF + * + * ACBF text areas are a collection of points, some text + * and some extra information on how to render that text if necessary. + */ + namespace AdvancedComicBookFormat { class ACBF_EXPORT Textarea : public QObject @@ -37,38 +44,124 @@ explicit Textarea(Textlayer* parent = nullptr); ~Textarea() override; + /** + * @return the types that a text-area can be, like speech or commentary. + */ static QStringList availableTypes(); + /** + * \brief Write the textarea into the xml writer. + */ void toXml(QXmlStreamWriter* writer); + /** + * \brief load a textarea element into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @return a list of points that encompasses the textarea. + */ QList points() const; + /** + * @param index - the index of the desired point. + * @return a point for an index. + */ QPoint point(int index) const; + /** + * @param point - a point from the points list. + * @return the index of the given point. + */ int pointIndex(const QPoint& point) const; - // If afterIndex is larger than zero, the insertion will happen at that index + /** + * \brief add a point to the points list. + * @param point - the point to add. Coordinates should be in pixels. + * @param index - the index to add it at. If afterIndex is larger than zero, + * the insertion will happen at that index + */ void addPoint(const QPoint& point, int index = -1); + /** + * \brief remove a point from the list. + * @param point - point to remove from the list. + */ void removePoint(const QPoint& point); + /** + * \brief Swap two points in the list. + * @param swapThis - the first points to swap. + * @param withThis - the second points to swap. + */ bool swapPoints(const QPoint& swapThis, const QPoint& withThis); + /** + * @return the background color as a QString. + * + * It should be an 8bit per channel rgb hexcode. + */ QString bgcolor() const; + /** + * \brief set the background color. + * + * @param newColor - a String with an 8bit per channel rgb hexcode (#ff00ff, or the like) + */ void setBgcolor(const QString& newColor = QString()); + /** + * @return the text rotation in degrees. + */ int textRotation() const; + /** + * \brief set the text rotation. + * @param rotation - the text rotation in degrees. + */ void setTextRotation(int rotation = 0); + /** + * @return the type of the text area. This determines how it is styled. + */ QString type() const; + /** + * \brief set the type of the text area. + * @param type - this should be an entry from the availableTypes(), + * it will change the way how the text is styled. The default is "speech". + */ void setType(const QString& type = QStringLiteral("speech")); + /** + * @return whether the text should use the 'inverted' colorscheme. + */ bool inverted() const; + /** + * \brief set whether the text should use the inverted colorscheme. + * @param inverted - whether to do so. + */ void setInverted(bool inverted = false); + /** + * @return whether to use the background color when overlaying the text. + */ bool transparent() const; + /** + * \brief set whether to use the background color when overlaying the text. + * @param transparent - false means to use the background color, true means + * to have the textare background transparent. + */ void setTransparent(bool transparent = false); + /** + * @returns a list of paragraphs. + * + * Contains allowed sub-elements: strong, emphasis, strikethrough + * sub, sup, a (with mandatory href attribute only) + * Can also contain deprecated sub-elements (superceded by...): code (type option code), + * inverted (textarea option inverted) + */ QStringList paragraphs() const; - // Allowed sub-elements: strong, emphasis, strikethrough, sub, sup, a (with mandatory href attribute only) - // Deprecated sub-elements (superceded by...): code (type option code), inverted (textarea option inverted) + /** + * \brief set the list of paragraphs for this textarea. + * @param paragraphs - a list of paragraphs. Can contain sub-elements: + * strong, emphasis, strikethrough, sub, sup, a (with mandatory href attribute only) + */ void setParagraphs(const QStringList& paragraphs); private: class Private; diff --git a/src/acbf/AcbfTextlayer.h b/src/acbf/AcbfTextlayer.h --- a/src/acbf/AcbfTextlayer.h +++ b/src/acbf/AcbfTextlayer.h @@ -25,7 +25,14 @@ #include #include "AcbfPage.h" - +/** + * \brief Class to handle the textlayer element. + * + * ACBF textlayers are groupings of textareas + * according to a specific language. + * + * They also have a default textarea background color. + */ namespace AdvancedComicBookFormat { class Textarea; @@ -36,22 +43,72 @@ explicit Textlayer(Page* parent = nullptr); ~Textlayer() override; + /** + * \brief Write the textlayer into the xml writer. + */ void toXml(QXmlStreamWriter* writer); + /** + * \brief load a textlayer element into this object. + * @return True if the xmlReader encountered no errors. + */ bool fromXml(QXmlStreamReader *xmlReader); + /** + * @returns the language for this text-layer. + */ QString language() const; + /** + * \brief set the language for this text-layer. + * @param language - the language of the entry in language code, country + * code format joined by a dash (not an underscore). + */ void setLanguage(const QString& language); + /** + * @return the background color as a QString. + * + * It should be an 8bit per channel rgb hexcode. + */ QString bgcolor() const; + /** + * \brief set the background color. + * + * @param newColor - a String with an 8bit per channel rgb hexcode (#ff00ff, or the like) + */ void setBgcolor(const QString& newColor = QString()); + /** + * @returns a list of textareas in this page. + */ QList textareas() const; + /** + * @param index - index of the textarea. + * @return the textarea of that index. + */ Textarea* textarea(int index) const; + /** + * @param textarea - the textarea you want to index of. + * @returns the index of the given textarea. + */ int textareaIndex(Textarea* textarea) const; - // If afterIndex is larger than zero, the insertion will happen at that index + /** + * \brief add a textarea to the list of frames. + * @param textarea - the frame to add. + * @param index - the index to add it at. If afterIndex is larger than + * zero, the insertion will happen at that index + */ void addTextarea(Textarea* textarea, int index = -1); + /** + * \brief remove the given textarea from the framelist. + * @param textarea - the textarea to remove. + */ void removeTextarea(Textarea* textarea); + /** + * \brief Swap two textareas in the list. + * @param swapThis - the first textarea to swap. + * @param withThis - the second textarea to swap. + */ bool swapTextareas(Textarea* swapThis, Textarea* withThis); private: class Private;