diff --git a/src/contentlist/BalooContentLister.h b/src/contentlist/BalooContentLister.h --- a/src/contentlist/BalooContentLister.h +++ b/src/contentlist/BalooContentLister.h @@ -35,8 +35,15 @@ explicit BalooContentLister(QObject* parent = nullptr); ~BalooContentLister() override; + /** + * @returns whether Baloo is enabled. If baloo is not available on the system, we cannot use it. + */ bool balooEnabled() const; + /** + * \brief Start a search. + * @param queries List of ContentQueries that the search should be limited to. + */ void startSearch(const QList& queries) override; private: diff --git a/src/contentlist/ContentList.h b/src/contentlist/ContentList.h --- a/src/contentlist/ContentList.h +++ b/src/contentlist/ContentList.h @@ -28,43 +28,122 @@ #include "ContentQuery.h" +/** + * \brief Class to handle searching all the book entries. + * + * This class handles the queries and the contentlisterbase + * that in turn handles the actual searching. + * + * When searching is done, the entries are filled into this model. + */ class ContentList : public QAbstractListModel, public QQmlParserStatus { Q_OBJECT Q_CLASSINFO("DefaultProperty", "queries") + /** + * \brief The list of query parameters that make up this search. + */ Q_PROPERTY(QQmlListProperty queries READ queries) + /** + * TODO: No idea. + */ Q_PROPERTY(bool autoSearch READ autoSearch WRITE setAutoSearch NOTIFY autoSearchChanged) + /** + * \brief Whether to cache the search results for later. + */ Q_PROPERTY(bool cacheResults READ cacheResults WRITE setCacheResults NOTIFY cacheResultsChanged) public: explicit ContentList(QObject* parent = nullptr); ~ContentList() override; + /** + * Extra roles for the different kinds of data that can be searched. + */ enum Roles { FilenameRole = Qt::UserRole + 1, FilePathRole, MetadataRole }; + /** + * @returns the list of search parameters as a list of content queries. + */ QQmlListProperty queries(); + /** + * @return whether to do auto search. + */ bool autoSearch() const; + + /** + * @return whether to cache the results. + */ bool cacheResults() const; + /** + * \brief QStrings with names for the extra roles. + */ QHash roleNames() const override; + /** + * \brief Access the search results inside the model. + * @param index The QModelIndex at which you wish to access the data. + * @param role An enumerator of the type of data you want to access. + * Is extended by the Roles enum. + * + * @return a QVariant with the search entry data. + */ QVariant data(const QModelIndex& index, int role = Qt::DisplayRole) const override; + /** + * @param parent The QModel index of the parent. This only counts for + * tree like page structures, and thus defaults to a freshly constructed + * QModelIndex. A wellformed QModelIndex will cause this function to return 0 + * @returns the number of total rows(search results) there are in this model. + */ int rowCount(const QModelIndex& parent = QModelIndex()) const override; + /** + * Inherited from QmlParserStatus, not implemented. + */ void classBegin() override; + /** + * \brief loads the cached results or autosearch + * into the model if either is enabled. + * + * Inherited from QmlParserStatus. + */ void componentComplete() override; + /** + * \brief Set whether to do autoSearch. + * @param autoSearch whether to do autoSearch. + */ Q_SLOT void setAutoSearch(bool autoSearch); + /** + * \brief Set whether to cache the results. + * @param cacheResults whether to cache the results. + */ Q_SLOT void setCacheResults(bool cacheResults); + /** + * \brief Fill the model with the results. + * + * This clears the model of search entries and then + * fills it up with the new entries. + * + * @param results a stringlist with paths to the new + * search results. + */ Q_SLOT void setKnownFiles(const QStringList& results); + /** + * \brief Start searching with the current queries list. + */ Q_SLOT void startSearch(); Q_SIGNAL void autoSearchChanged(); Q_SIGNAL void cacheResultsChanged(); + /** + * \brief Fires when the search is completed. + */ Q_SIGNAL void searchCompleted(); Q_INVOKABLE static QString getMimetype(QString filePath); diff --git a/src/contentlist/ContentListerBase.h b/src/contentlist/ContentListerBase.h --- a/src/contentlist/ContentListerBase.h +++ b/src/contentlist/ContentListerBase.h @@ -25,19 +25,39 @@ #include class ContentQuery; - +/** + * \brief Class to handle the search. + * + * This class can be extended to handle other search engines, + * such as baloo and the file system content lister. + * + * By default it only searches the KFileMetaData available to it. + */ class ContentListerBase : public QObject { Q_OBJECT public: explicit ContentListerBase(QObject* parent = nullptr); ~ContentListerBase() override; + /** + * \brief Start a search. + * @param queries List of ContentQueries that the search should be limited to. + */ Q_SLOT virtual void startSearch(const QList& queries); + /** + * \brief Fires when a matching file is found. + */ Q_SIGNAL void fileFound(const QString& filePath, const QVariantMap& metadata); + /** + * \brief Fires when the search was completed. + */ Q_SIGNAL void searchCompleted(); + /** + * @return the available metadata for the filepath so that it can be searched. + */ static QVariantMap metaDataForFile(const QString& file); }; diff --git a/src/contentlist/FilesystemContentLister.h b/src/contentlist/FilesystemContentLister.h --- a/src/contentlist/FilesystemContentLister.h +++ b/src/contentlist/FilesystemContentLister.h @@ -32,7 +32,10 @@ public: explicit FilesystemContentLister(QObject* parent = nullptr); ~FilesystemContentLister() override; - + /** + * \brief Start a search. + * @param queries List of ContentQueries that the search should be limited to. + */ void startSearch(const QList& queries) override; private: diff --git a/src/contentlist/qmlplugin.h b/src/contentlist/qmlplugin.h --- a/src/contentlist/qmlplugin.h +++ b/src/contentlist/qmlplugin.h @@ -23,7 +23,13 @@ #define _QML_PLUGIN_H #include - +/** + * \brief The QML plugin file. + * + * This takes the different classes in this folder and turns them into + * a QML plugin, so the properties can be accessed and modified from a + * QML file. + */ class QmlPlugins : public QQmlExtensionPlugin { Q_OBJECT diff --git a/src/qtquick/ArchiveBookModel.h b/src/qtquick/ArchiveBookModel.h --- a/src/qtquick/ArchiveBookModel.h +++ b/src/qtquick/ArchiveBookModel.h @@ -23,7 +23,15 @@ #define ARCHIVEBOOKMODEL_H #include "BookModel.h" - +/** + * \brief Class to hold pages and metadata for archive based books. + * + * In particular, ArchiveBookModel handles CBZ and CBR files, reads + * potential metadata and holds that into the acbfdata object. + * + * ArchiveBookModel extends BookModel, which handles the functions for + * setting the current page, and returning basic metadata. + */ class KArchiveFile; class ArchiveBookModel : public BookModel { @@ -35,33 +43,103 @@ explicit ArchiveBookModel(QObject* parent = nullptr); ~ArchiveBookModel() override; + /** + * \brief Set the filename that points to the archive that describes this book. + */ void setFilename(QString newFilename) override; + /** + * The author name will be either the default bookmodel author name, or + * if ACBF data is available, the first authorname in the list of ACBF authors. + * + * @return the author name as a QString. + */ QString author() const override; + /** + * \brief Set the main author's nickname. + * + * If there is no ACBF data, this will set the author to BookModel's author. + * If there is ACBF data, this will set the nickname entry on the name of the + * first possible author. + * + * Preferably authors should be added by editing the author list in the bookinfo + * of the ACBF metadata this book holds. + * + * @param newAuthor The main author's nickname. + */ void setAuthor(QString newAuthor) override; + /** + * @return the name of the publisher as a QString. + */ QString publisher() const override; + /** + * \brief Set the name of the publisher. + * @param newPublisher QString with the name of the publisher. + */ void setPublisher(QString newPublisher) override; + /** + * @return The proper title of this book as a QString. + */ QString title() const override; + /** + * \brief Set the default title of this book. + * @param newTitle The default title of this book as a QString. + */ void setTitle(QString newTitle) override; + /** + * @return a QQmlEngine associated with this book. + * TODO: What is the QML engine and what is its purpose? + * Used in the cbr.qml + */ QObject* qmlEngine() const; + /** + * \brief Set the QML engine on this book. + * @param newEngine A QQmlEngine object. + */ void setQmlEngine(QObject* newEngine); + /** + * \brief Fires when a new QQmlEngine is set on this book. + */ Q_SIGNAL void qmlEngineChanged(); + /** + * TODO: What is this? Only used in book.qml once? + */ bool readWrite() const; void setReadWrite(bool newReadWrite); Q_SIGNAL void readWriteChanged(); + /** + * @return whether the book has been modified and has unsaved changes. + * + * Used in PeruseCreator to determine whether to enable the save dialog. + */ bool hasUnsavedChanges() const; + /** + * \brief Set that the book has been modified. + * @param isDirty whether the book has been modified. + */ Q_INVOKABLE void setDirty(bool isDirty = true); + /** + * \brief Fires when there are unsaved changes. + */ Q_SIGNAL void hasUnsavedChangesChanged(); /** - * Saves the archive back to disk + * \brief Saves the archive back to disk * @return True if the save was successful */ Q_INVOKABLE bool saveBook(); + /** + * \brief add a page to this book. + * + * This adds it to the ACBF metadata too. + * + * @param url The resource location of the page as an url. + * @param title The title of the page. This is shown in a table of contents. + */ void addPage(QString url, QString title) override; /** * Adds a new page to the book archive on disk, by copying in the file @@ -87,6 +165,10 @@ * Creates a new book in the folder, with the given title and cover. * A filename will be constructed to fit the title, and which does not already exist in the * directory. + * + * @param folder the path to the folder to create this book in. + * @param title The title of the book. + * @param coverUrl A resource location pointing at the image that will be the coverpage. */ Q_INVOKABLE QString createBook(QString folder, QString title, QString coverUrl); diff --git a/src/qtquick/ArchiveImageProvider.h b/src/qtquick/ArchiveImageProvider.h --- a/src/qtquick/ArchiveImageProvider.h +++ b/src/qtquick/ArchiveImageProvider.h @@ -24,17 +24,45 @@ #include +/** + * \brief Class to return images for archives. + * + * ArchiveImageProvider is for getting images out of + * archives(zip, rar, cbz, cbr), as well as getting image data out of ACBF files. + */ class ArchiveBookModel; class ArchiveImageProvider : public QQuickImageProvider { public: explicit ArchiveImageProvider(); ~ArchiveImageProvider() override; + /** + * \brief Request a given image. + * + * @param id The url of the image to provide. + * @param size A QSize containing the original size of the image. Not used. + * @param requestedSize A QSize containing the required size of the image. Not used. + * + * @return A QImage. + */ QImage requestImage(const QString& id, QSize* size, const QSize& requestedSize) override; + /** + * \brief Set the ArchiveBookModel to get images for. + * @param model ArchiveBookModel to get images for. + */ void setArchiveBookModel(ArchiveBookModel* model); + + /** + * \brief Set the prefix. + * @param prefix The prefix as a string. + * TODO: What is the prefix and why is it necessary? + */ void setPrefix(QString prefix); + /** + * @returns the prefix as a QString. + */ QString prefix() const; private: class Private; diff --git a/src/qtquick/ArchiveImageProvider.cpp b/src/qtquick/ArchiveImageProvider.cpp --- a/src/qtquick/ArchiveImageProvider.cpp +++ b/src/qtquick/ArchiveImageProvider.cpp @@ -64,6 +64,7 @@ * In ACBF, image references starting with a '#' refer to files embedded * in the section of the .acbf file. * see: http://acbf.wikia.com/wiki/Body_Section_Definition#Image + * TODO: binary files can also handle fonts, and those cannot be loaded into a QImage. */ if (id.startsWith('#')) { auto document = qobject_cast(d->bookModel->acbfData()); diff --git a/src/qtquick/BookDatabase.h b/src/qtquick/BookDatabase.h --- a/src/qtquick/BookDatabase.h +++ b/src/qtquick/BookDatabase.h @@ -25,14 +25,29 @@ #include struct BookEntry; +/** + * \brief A Class to hold a cache of known books to reduce the amount of time spent indexing. + * + * BookDatabase handles holding the conversion between SQL entry and + * BookEntry structs. + * + * The BookEntry struct is defined in CategoryEntriesModel. + */ class BookDatabase : public QObject { Q_OBJECT public: explicit BookDatabase(QObject* parent = nullptr); ~BookDatabase() override; + /** + * @return a list of all known books in the database. + */ QList loadEntries(); + /** + * \brief Add a new book to the cache. + * @param entry The entry to add. + */ void addEntry(BookEntry* entry); private: class Private; diff --git a/src/qtquick/BookListModel.h b/src/qtquick/BookListModel.h --- a/src/qtquick/BookListModel.h +++ b/src/qtquick/BookListModel.h @@ -24,27 +24,77 @@ #include "CategoryEntriesModel.h" #include - +/** + * \brief Main catalogue model class. + * + * BookListModel extends CategoryEntriesModel, and is the main model that + * handles book entries and the different categories that books can be in. + * + * It also extends QQmlParseStatus to ensure that the loading the cache of + * books is postponed until the application UI has been painted at least once. + * + * BookListModel keeps track of which books there are, how they can be sorted + * and how far the reader is in reading a specific book. + * + * It caches its entries in the BookDataBase. + * + * ContentModel is the model used to enable searching the collection, it is + * typically a ContentList. + */ class BookListModel : public CategoryEntriesModel, public QQmlParserStatus { Q_OBJECT + /** + * \brief count holds how many entries there are in the catalogue. + */ Q_PROPERTY(int count READ count NOTIFY countChanged) + /** + * \brief The content model is an abstract list model that holds data to search through. + */ Q_PROPERTY(QObject* contentModel READ contentModel WRITE setContentModel NOTIFY contentModelChanged) + /** + * \brief The "newly added" category entries model manages the newly added entries. + */ Q_PROPERTY(QObject* newlyAddedCategoryModel READ newlyAddedCategoryModel NOTIFY newlyAddedCategoryModelChanged) + /** + * \brief The "title" category entries model manages the sorting of entries by title. + */ Q_PROPERTY(QObject* titleCategoryModel READ titleCategoryModel NOTIFY titleCategoryModelChanged) + /** + * \brief The "author" category entries model manages the sorting of entries by author. + */ Q_PROPERTY(QObject* authorCategoryModel READ authorCategoryModel NOTIFY authorCategoryModelChanged) + /** + * \brief The "series" category entries model managed the sorting of entry by series. + */ Q_PROPERTY(QObject* seriesCategoryModel READ seriesCategoryModel NOTIFY seriesCategoryModelChanged) + /** + * \brief The "series" category entries model managed the sorting of entry by file system folder. + */ Q_PROPERTY(QObject* folderCategoryModel READ folderCategoryModel NOTIFY folderCategoryModelChanged) + /** + * \brief cacheLoaded holds whether the database cache has been loaded.. + */ Q_PROPERTY(bool cacheLoaded READ cacheLoaded NOTIFY cacheLoadedChanged) Q_ENUMS(Grouping) Q_INTERFACES(QQmlParserStatus) public: explicit BookListModel(QObject* parent = nullptr); ~BookListModel() override; + /** + * Inherited from QmlParserStatus, not implemented. + */ void classBegin() override {}; + /** + * \brief triggers the loading of the cache. + * Inherited from QmlParserStatus + */ void componentComplete() override; + /** + * \brief Enum holding the different categories implemented. + */ enum Grouping { GroupByNone = 0, GroupByRecentlyAdded, @@ -54,42 +104,115 @@ GroupByPublisher }; + /** + * @return the contentModel. Used for searching. + */ QObject* contentModel() const; + /** + * \brief set the ContentModel. + * @param newModel The new content model. + */ void setContentModel(QObject* newModel); + /** + * \brief Fires when the content model has changed. + */ Q_SIGNAL void contentModelChanged(); + /** + * @returns how many entries there are in the catelogue. + */ int count() const; + /** + * \brief Fires when the count has changed. + */ Q_SIGNAL void countChanged(); + /** + * @return The categoryEntriesModel that manages the sorting of entries by title. + */ QObject* titleCategoryModel() const; + /** + * \brief Fires when the titleCategoryModel has changed or finished initializing. + */ Q_SIGNAL void titleCategoryModelChanged(); + /** + * @return The categoryEntriesModel that manages the recently added entries. + */ QObject* newlyAddedCategoryModel() const; + /** + * \brief Fires when the newlyAddedCategoryModel has changed or finished initializing. + */ Q_SIGNAL void newlyAddedCategoryModelChanged(); + /** + * @return The categoryEntriesModel that manages the sorting of entries by author. + */ QObject* authorCategoryModel() const; + /** + * \brief Fires when the authorCategoryModel has changed or finished initializing. + */ Q_SIGNAL void authorCategoryModelChanged(); + /** + * @return The categoryEntriesModel that manages the sorting of entries by series. + */ QObject* seriesCategoryModel() const; + /** + * \brief Fires when the seriesCategoryModel has changed or finished initializing. + */ Q_SIGNAL void seriesCategoryModelChanged(); - // Returns the leaf model representing the series the entry with the passed URL is a part of - // Base assumption: A book is only part of one series. This is not always true, but not sure how - // to sensibly represent that + + /** + * Returns the leaf model representing the series the entry with the passed URL is a part of + * Base assumption: A book is only part of one series. This is not always true, but not sure how + * to sensibly represent that. + * + * @param fileName the File Name of the entry to get the series of. + */ Q_INVOKABLE QObject* seriesModelForEntry(QString fileName); + /** + * @return The categoryEntriesModel that manages the sorting of entries by folder. + */ QObject* folderCategoryModel() const; + /** + * \brief Fires when the folderCategoryModel has changed or finished initializing. + */ Q_SIGNAL void folderCategoryModelChanged(); + /** + * @returns whether the cache is loaded from the database. + */ bool cacheLoaded() const; + /** + * \brief Fires when the cache is done loading. + */ Q_SIGNAL void cacheLoadedChanged(); - // Update the data of a book at runtime - in particular, we need to update totalPages and currentPage + /** + * \brief Update the data of a book at runtime + * + * This is used in to update totalPages and currentPage. + * + * @param fileName The filename to update the page for. + * @param property The property to update, can be "currentPage" or + * "totalPages". + * @param value The value to set it to. + */ Q_INVOKABLE void setBookData(QString fileName, QString property, QString value); - // Delete a book from the model, and optionally delete the entry from file storage + /** + * Delete a book from the model, and optionally delete the entry from file storage. + * @param fileName The filename of the book to remove. + * @param deleteFile Whether to also delete the file from the disk. + */ Q_INVOKABLE void removeBook(QString fileName, bool deleteFile = false); - // A list of the files currently known by the applications + /** + * \brief A list of the files currently known by the applications + * @returns a QStringList with paths to known books. + */ Q_INVOKABLE QStringList knownBookFiles() const; private: class Private; diff --git a/src/qtquick/BookModel.h b/src/qtquick/BookModel.h --- a/src/qtquick/BookModel.h +++ b/src/qtquick/BookModel.h @@ -23,75 +23,216 @@ #define BOOKMODEL_H #include - +/** + * \brief Base Class to handle books, their pages and their metadata + * + * BookModel is an QAbstractListModel, holding the pages as a list of objects. + * + * It also holds metadata for the following entries as Q Properties: + * + * - filename. + * - author + * - publisher + * - title + * - page count. + * - current page. + * - acbf data + * - processing + * + * The book model in turn is extended by ArchiveBookModel and FolderBookModel + * to provide specialised functionality for archives(zip, rar, cbz, cbr) with + * a book and Folders with a book and a description file. + */ class BookModel : public QAbstractListModel { Q_OBJECT + /** + * \brief The filename of the archive that describes this book. + */ Q_PROPERTY(QString filename READ filename WRITE setFilename NOTIFY filenameChanged) + /** + * \brief The main author of this book. + */ Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged) + /** + * \brief the name of the publisher of this book. + */ Q_PROPERTY(QString publisher READ publisher WRITE setPublisher NOTIFY publisherChanged) + /** + * \brief The title of the book. + */ Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged) + /** + * \brief The page count of the book. + */ Q_PROPERTY(int pageCount READ pageCount NOTIFY pageCountChanged) + /** + * \brief The page currently being read of the book. + */ Q_PROPERTY(int currentPage READ currentPage WRITE setCurrentPage NOTIFY currentPageChanged) /** * The Advanced Comic Book Format data management instance associated with this book * This may be null */ Q_PROPERTY(QObject* acbfData READ acbfData NOTIFY acbfDataChanged) + /** + * \brief Whether or not the book is still being processed. + */ Q_PROPERTY(bool processing READ processing WRITE setProcessing NOTIFY processingChanged) public: explicit BookModel(QObject* parent = nullptr); ~BookModel() override; + /** + * Extra roles for the page data access. + */ enum Roles { - UrlRole = Qt::UserRole + 1, - TitleRole, + UrlRole = Qt::UserRole + 1, // This allows access to the resource location of the page. + TitleRole, // This allows access to the title of the page, if it has one. }; + /** + * \brief This gives names for the Roles enum. + */ QHash roleNames() const override; + /** + * \brief Access the data inside the BookModel. + * @param index The QModelIndex at which you wish to access the data. + * @param role An enumerator of the type of data you want to access. + * Is extended by the Roles enum. + * + * @return a QVariant with the page data. + */ QVariant data(const QModelIndex& index, int role = Qt::DisplayRole) const override; + /** + * @param parent The QModel index of the parent, not used here. + * @returns the number of total pages there are in the Book. + */ int rowCount(const QModelIndex& parent = QModelIndex()) const override; + /** + * \brief add a page to this book. + * @param url The resource location of the page as an url. + * @param title The title of the page. This is shown in a table of contents. + */ virtual void addPage(QString url, QString title); + /** + * \brief remove all pages from the book. + */ virtual void clearPages(); + /** + * @return the filename of the file that describes this book. + */ QString filename() const; + /** + * \brief set the filename of the file that describes this book. + */ virtual void setFilename(QString newFilename); + /** + * \brief Fires when the filename is changed via setfilename. + */ Q_SIGNAL void filenameChanged(); + /** + * @returns the main author of the book as a QString. + */ virtual QString author() const; + /** + * \brief set the main author of the book as a single string. + * @param newAuthor The new name associated with the author + * as a single string. + */ virtual void setAuthor(QString newAuthor); + /** + * \brief Fires when the author has changed via setAuthor. + */ Q_SIGNAL void authorChanged(); + /** + * @return the name of the publisher as a QString. + */ virtual QString publisher() const; + /** + * \brief Set the name of the publisher. + * @param newPublisher String that describes the publisher's name. + */ virtual void setPublisher(QString newPublisher); + /** + * \brief Fires when publisher's name has changed with setPublisher. + */ Q_SIGNAL void publisherChanged(); + /** + * @return The proper title of the book as a Qstring. + */ virtual QString title() const; + /** + * \brief Set the title of the book. + * @param newTitle A QString describing the new title. + */ virtual void setTitle(QString newTitle); + /** + * \brief Fires when the book's title has changed via SetTitle + */ Q_SIGNAL void titleChanged(); + /** + * @return the total pages in the book as an int. + */ virtual int pageCount() const; + /** + * \brief Fires when the page count has changed, via for example pages + * being added or removed. + */ Q_SIGNAL void pageCountChanged(); + /** + * @return the number of the current page being viewed as an int. + */ int currentPage() const; /** - * + * \brief Set the current page. + * @param newCurrentPage Int with the index of the page to switch to. * @param updateFilesystem If this is set to false, the attributes do not get written back to the filesystem. Useful for when the information is first filled out */ virtual void setCurrentPage(int newCurrentPage, bool updateFilesystem = true); + /** + * \brief Fires when the current page has changed. + */ Q_SIGNAL void currentPageChanged(); + /** + * @return an object with the acbf data, might be null. + */ QObject* acbfData() const; /** * This is used by subclasses who want to create one such. Until this is called * with a valid object, acbfData is null. This function causes BookModel to take * ownership of the object. It will further delete any previous objects set as * acbfData. */ void setAcbfData(QObject* obj); + /** + * \brief Fires when the ACBF data has changed. + */ Q_SIGNAL void acbfDataChanged(); - // Whether or not the any processing is currently going on + /** + * @return Whether or not the any processing is currently going on + */ bool processing() const; + /** + * \brief Set whether it is processing or done. + * @param processing Whether this model is being processed. + */ void setProcessing(bool processing); + /** + * \brief Fires when the state of processing has changed. + */ Q_SIGNAL void processingChanged(); + /** + * \brief Fires when the book is done loading, and informs whether it was + * succesful. + * @param success Wether the book's loading was succesful + * TODO: This isn't triggered by anything right now? + */ Q_SIGNAL void loadingCompleted(bool success); /** diff --git a/src/qtquick/CategoryEntriesModel.h b/src/qtquick/CategoryEntriesModel.h --- a/src/qtquick/CategoryEntriesModel.h +++ b/src/qtquick/CategoryEntriesModel.h @@ -26,6 +26,9 @@ #include class CategoryEntriesModel; +/** + * \brief A struct for an Entry to the Book Database. + */ struct BookEntry { BookEntry() : totalPages(0) @@ -44,13 +47,30 @@ QString thumbnail; }; +/** + * \brief Model to handle the filter categories. + * + * This model in specific handles which categories there are + * and which books are assigned to a category, if so, which. + * + * Used to handle sorting by author, title and so forth. + * Is extended by BookListModel. + * + * categories and book entries are both in the same model + * because there can be books that are not assigned categories. + * Similarly, categories can contain categories, like in the case + * of folder category. + */ class CategoryEntriesModel : public QAbstractListModel { Q_OBJECT public: explicit CategoryEntriesModel(QObject* parent = nullptr); ~CategoryEntriesModel() override; + /** + * \brief Extra roles for the book entry access. + */ enum Roles { FilenameRole = Qt::UserRole + 1, FiletitleRole, @@ -67,30 +87,109 @@ ThumbnailRole }; + /** + * @returns names for the extra roles defined. + */ QHash roleNames() const override; + /** + * \brief Access the data inside the CategoryEntriesModel. + * @param index The QModelIndex at which you wish to access the data. + * @param role An enumerator of the type of data you want to access. + * Is extended by the Roles enum. + * + * @return a QVariant with the book entry's data. + */ QVariant data(const QModelIndex& index, int role = Qt::DisplayRole) const override; + /** + * @param parent The QModel index of the parent. This only counts for + * tree like page structures, and thus defaults to a freshly constructed + * QModelIndex. A wellformed QModelIndex will cause this function to return 0 + * @returns the number of total rows(bookentries and categories) there are. + */ int rowCount(const QModelIndex& parent = QModelIndex()) const override; + /** + * \brief Add a book entry to the CategoryEntriesModel. + * + * @param entry The BookEntry to add. + * @param compareRole The role that determines the data to sort the entry into. + * Defaults to the Book title. + */ void append(BookEntry* entry, Roles compareRole = TitleRole); + + /** + * \brief Add a book entry to a category. + * + * This also adds it to the model's list of entries. + */ void addCategoryEntry(const QString& categoryName, BookEntry* entry); + /** + * @param index an integer index pointing at the desired book. + * @returns a QObject wrapper around a BookEntry struct for the given index. + */ Q_INVOKABLE QObject* get(int index); - // This is backwards... need to fox this to make get return the actual thing, not just a book, and create a getter for books... + /** + * TODO: This is backwards... need to fox this to make get return the actual thing, not just a book, and create a getter for books... + * @return an entry object. This can be either a category or a book. + * @param index the index of the object. + */ Q_INVOKABLE QObject* getEntry(int index); + /** + * @return an entry object for the given filename. Used to get the recently + * read books. + * @param filename the filename associated with an entry object. + */ Q_INVOKABLE QObject* bookFromFile(QString filename); + /** + * @return an entry index for the given filename. + * @param filename the filename associated with an entry object. + */ Q_INVOKABLE int indexOfFile(QString filename); + /** + * @return whether the entry is a bookentry or a category entry. + * @param index the index of the entry. + */ Q_INVOKABLE bool indexIsBook(int index); + /** + * @return an integer with the total books in the model. + */ int bookCount() const; + /** + * \brief Fires when a book entry is updated. + * @param entry The updated entry + * + * Used in the BookListModel::setBookData() + */ Q_SIGNAL void entryDataUpdated(BookEntry* entry); + /** + * \brief set a book entry as changed. + * @param entry The changed entry. + */ Q_SLOT void entryDataChanged(BookEntry* entry); + /** + * \brief Fires when a book entry is removed. + * @param entry The removed entry + */ Q_SIGNAL void entryRemoved(BookEntry* entry); + /** + * \brief Remove a book entry. + * @param entry The entry to remove. + */ Q_SLOT void entryRemove(BookEntry* entry); // This will iterate over all sub-models and find the model which contains the entry, or null if not found QObject* leafModelForEntry(BookEntry* entry); protected: + /** + * @return the name of the model. + */ QString name() const; + /** + * \brief set the name of the model. + * @param newName QString with the name. + */ void setName(const QString& newName); private: class Private; diff --git a/src/qtquick/ComicCoverImageProvider.h b/src/qtquick/ComicCoverImageProvider.h --- a/src/qtquick/ComicCoverImageProvider.h +++ b/src/qtquick/ComicCoverImageProvider.h @@ -37,6 +37,15 @@ explicit ComicCoverImageProvider(); ~ComicCoverImageProvider() override; + /** + * \brief Get an image. + * + * @param id The source of the image. + * @param size The size of the original image, unused. + * @param requestedSize The required size of the final image, unused. + * + * @return a QImage. + */ QImage requestImage(const QString& id, QSize* size, const QSize& requestedSize) override; private: class Private; diff --git a/src/qtquick/FilterProxy.h b/src/qtquick/FilterProxy.h --- a/src/qtquick/FilterProxy.h +++ b/src/qtquick/FilterProxy.h @@ -23,7 +23,11 @@ #define FILTERPROXY_H #include - +/** + * \brief a Filter proxy for handling search with. + * + * Extends QSortFilterProxyModel, is caseInsensitive. + */ class FilterProxy : public QSortFilterProxyModel { Q_OBJECT diff --git a/src/qtquick/FolderBookModel.h b/src/qtquick/FolderBookModel.h --- a/src/qtquick/FolderBookModel.h +++ b/src/qtquick/FolderBookModel.h @@ -23,14 +23,23 @@ #define FOLDERBOOKMODEL_H #include "BookModel.h" - +/** + * \brief Class to handle a folder of images as a book. + * + * This class will treat a folder of images as a book, with the alphabetical + * order of the files determining the page order. + */ class FolderBookModel : public BookModel { Q_OBJECT public: explicit FolderBookModel(QObject* parent = nullptr); ~FolderBookModel() override; + /** + * \brief Set the folder name of this book or a file describing + * describing the images that belong to this book. + */ void setFilename(QString newFilename) override; }; diff --git a/src/qtquick/PDFCoverImageProvider.h b/src/qtquick/PDFCoverImageProvider.h --- a/src/qtquick/PDFCoverImageProvider.h +++ b/src/qtquick/PDFCoverImageProvider.h @@ -35,6 +35,15 @@ explicit PDFCoverImageProvider(); virtual ~PDFCoverImageProvider(); + /** + * \brief Get an image. + * + * @param id The source of the image. + * @param size The size of the original image, unused. + * @param requestedSize The required size of the final image, unused. + * + * @return a QImage. + */ virtual QImage requestImage(const QString& id, QSize* size, const QSize& requestedSize); private: class Private; diff --git a/src/qtquick/PeruseConfig.h b/src/qtquick/PeruseConfig.h --- a/src/qtquick/PeruseConfig.h +++ b/src/qtquick/PeruseConfig.h @@ -23,15 +23,32 @@ #define PERUSECONFIG_H #include - +/** + * \brief Class to handle reading and writing the configuration. + * + * Peruse will store the data in 'peruserc' at the QStandardPath + * for configuration. + */ class PeruseConfig : public QObject { Q_OBJECT Q_ENUMS(ZoomMode) + /** + * \brief recently opened represents the recently opened books. + */ Q_PROPERTY(QStringList recentlyOpened READ recentlyOpened NOTIFY recentlyOpenedChanged) + /** + * \brief book locations is where Peruse will look for books, whether they have been removed, added, etc. + */ Q_PROPERTY(QStringList bookLocations READ bookLocations NOTIFY bookLocationsChanged) + /** + * \brief new stuff location is for the location of the KNewStuff config for the GHNS protocol. + */ Q_PROPERTY(QString newstuffLocation READ newstuffLocation NOTIFY newstuffLocationChanged) public: + /** + * \brief Enum holding the preferred zoom mode. + */ enum ZoomMode { ZoomFull = 0, ZoomFitWidth = 1, @@ -41,22 +58,60 @@ explicit PeruseConfig(QObject* parent = nullptr); ~PeruseConfig() override; + /** + * \brief Add a book to the recently opened list. + * @param path the path/filename of the newly opened book. + */ Q_INVOKABLE void bookOpened(QString path); + /** + * @return a list of recently opened files. + */ QStringList recentlyOpened() const; + /** + * \brief Fires when the list of recently opened files has changed. + */ Q_SIGNAL void recentlyOpenedChanged(); + /** + * \brief Add a folder to the book locations. + * @param location path to the folder to add. + */ Q_INVOKABLE void addBookLocation(const QString& location); + /** + * \brief Remove a folder from the book locations. + * @param location path of the folder to remove. + */ Q_INVOKABLE void removeBookLocation(const QString& location); + /** + * @return a QStringList with paths to all the folders to check for books. + */ QStringList bookLocations() const; + /** + * \brief Fires when the book locations to check have changed. + */ Q_SIGNAL void bookLocationsChanged(); + /** + * \brief Holds url to the peruse's KNewStuff configuration fle, to + * make it easy to retrieve. + */ QString newstuffLocation() const; + /** + * \brief Fires when the location to the KNewStuff config is changed. + */ Q_SIGNAL void newstuffLocationChanged(); + /** + * \brief Fires when there is an config error message to show. + * @param message The Error message to show. + */ Q_SIGNAL void showMessage(QString message); // This should go somewhere more sensible, really... like a static on Qt. or something :P Q_INVOKABLE QString homeDir() const; + /** + * Creates a KFileMetaData::UserMetaData for this file, propery and value so the information is not lost when files are moved around outside of Peruse + */ Q_INVOKABLE void setFilesystemProperty(QString fileName, QString propertyName, QString value); private: class Private; diff --git a/src/qtquick/PreviewImageProvider.h b/src/qtquick/PreviewImageProvider.h --- a/src/qtquick/PreviewImageProvider.h +++ b/src/qtquick/PreviewImageProvider.h @@ -38,10 +38,34 @@ explicit PreviewImageProvider(QObject* parent = nullptr); ~PreviewImageProvider() override; + /** + * \brief Get an image. + * + * @param id The source of the image. + * @param size The size of the original image. + * @param requestedSize The required size of the final image. + * + * @return a QImage. + */ QImage requestImage(const QString& id, QSize* size, const QSize& requestedSize) override; + /** + *\brief Get an icon associated with the mimetype of the image as a fallback. + * + * @param p Pointer to pixmap to write this fallback into. + */ Q_SLOT void updatePreview(const KFileItem&, const QPixmap& p); + /** + *\brief Get an icon associated with the mimetype of the image as a fallback. + * + * @param item The image to write a fallback for. + */ Q_SLOT void fallbackPreview(const KFileItem& item); + /** + * \brief Set whether the preview generation is finished. + * + * @param job The job to mark finished. + */ Q_SLOT void finishedPreview(KJob* job); private: class Private; diff --git a/src/qtquick/qmlplugin.h b/src/qtquick/qmlplugin.h --- a/src/qtquick/qmlplugin.h +++ b/src/qtquick/qmlplugin.h @@ -23,7 +23,13 @@ #define _QML_PLUGIN_H #include - +/** + * \brief The QML plugin file. + * + * This takes the different classes in this folder and turns them into + * a QML plugin, so the properties can be accessed and modified from a + * QML file. + */ class QmlPlugins : public QQmlExtensionPlugin { Q_OBJECT