kworship/bible/KwBiblePassage.h

   1 /***************************************************************************
   2  *   This file is part of KWorship.                                        *
   3  *   Copyright 2008 James Hogan <james@albanarts.com>                      *
   4  *                                                                         *
   5  *   KWorship is free software: you can redistribute it and/or modify      *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation, either version 2 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   KWorship is distributed in the hope that it will be useful,           *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with KWorship.  If not, write to the Free Software Foundation,  *
  17  *   Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.   *
  18  ***************************************************************************/
  19
  20 #ifndef _KwBiblePassage_h_
  21 #define _KwBiblePassage_h_
  22
  23 /**
  24  * @file KwBiblePassage.h
  25  * @brief A passage of rendered bible text.
  26  * @author James Hogan <james@albanarts.com>
  27  */
  28
  29 #include "KwBibleModule.h"
  30
  31 #include <QString>
  32
  33 class QDomDocument;
  34 class QDomElement;
  35
  36 /** A passage of rendered bible text.
  37  * Stores enough information to adjust settings.
  38  * Can be used as a cache.
  39  */
  40 class KwBiblePassage
  41 {
  42   public:
  43
  44     /*
  45      * Constructors + destructor
  46      */
  47
  48     /// Default constructor.
  49     KwBiblePassage();
  50
  51     /// Destructor.
  52     virtual ~KwBiblePassage();
  53
  54     /*
  55      * DOM filters
  56      */
  57
  58     /// Import the passage in a DOM.
  59     void importFromDom(const QDomElement& element);
  60
  61     /// Export the passage using DOM.
  62     void exportToDom(QDomDocument& document, QDomElement& element) const;
  63
  64     /*
  65      * Main interface
  66      */
  67
  68     /** Clear the passage.
  69      * Deletes all books.
  70      */
  71     void clearBooks();
  72
  73     /** Clear the chapters in a book.
  74      * Deletes all chapters.
  75      */
  76     void clearChapters(int bookNumber);
  77
  78     /** Clear the verses in a chapter.
  79      * Deletes all verses.
  80      */
  81     void clearVerses(int bookNumber, int chapterNumber);
  82
  83     /** Set the source module.
  84      * @param managerId ID of the bible manager.
  85      * @param moduleId ID of the bible module.
  86      * @param rightToLeft Whether the text is right-to-left.
  87      */
  88     void setSource(const QString& managerId, const QString& moduleId, bool rightToLeft);
  89
  90     /** Initialise the books in the passage.
  91      * If books are already initialised they will be cleared first.
  92      * @param firstBook Number of first book in passage.
  93      * @param numBooks Number of books covered in this passage.
  94      * @param numBooks > 0
  95      */
  96     void initBooks(int firstBook, int numBooks);
  97
  98     /** Initialise a book in the passage.
  99      * If the book is already initialised it will be cleared first.
 100      * @param bookNumber Number of the book to initialise.
 101      * @param name Name of the book.
 102      * @param firstChapter Number of first chapter in book.
 103      * @param numChapters Number of chapters covered in this book.
 104      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 105      * @pre numChapters > 0
 106      */
 107     void initBook(int bookNumber,
 108                   const QString& name, int firstChapter, int numChapters);
 109
 110     /** Initialise a chapter in the passage.
 111      * If the chapter is already initialised it will be cleared first.
 112      * @param bookNumber Number of the book with the chapter to initialise.
 113      * @param chapterNumber Number of the chapter to initialise.
 114      * @param firstVerse Number of first verse in chapter.
 115      * @param numVerses Number of verses covered in this chapter.
 116      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 117      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 118      * @pre numVerses > 0
 119      */
 120     void initChapter(int bookNumber, int chapterNumber,
 121                      int firstVerse, int numVerses);
 122
 123     /** Initialise a verse in the passage.
 124      * If the verse is already initialised it will be cleared first.
 125      * @param bookNumber Number of the book with the chapter to initialise.
 126      * @param chapterNumber Number of the chapter with the verse to initialise.
 127      * @param verseNumber Number of the verse to initialise.
 128      * @param headings Headings HTML preceeding this verse.
 129      * @param content Main HTML in this verse.
 130      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 131      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 132      * @pre firstVerseNumber(bookNumber) <= verseNumber <= lastVerseNumber(bookNumber)
 133      */
 134     void initVerse(int bookNumber, int chapterNumber, int verseNumber,
 135                    const QString& headings, const QString& content);
 136
 137     /*
 138      * Accessors
 139      */
 140
 141     /// Find whether the passage is empty.
 142     bool isEmpty() const;
 143
 144     /// Get textual key of this passage.
 145     QString textualKey() const;
 146
 147     /// Get the first book number in the passage.
 148     int firstBookNumber() const;
 149     /// Get the last book number in the passage.
 150     int lastBookNumber() const;
 151
 152     /** Get the first chapter number in a book of the passage.
 153      * @param bookNumber The number of the book.
 154      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 155      */
 156     int firstChapterNumber(int bookNumber) const;
 157     /** Get the last chapter number in a book of the passage.
 158      * @param bookNumber The number of the book.
 159      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 160      */
 161     int lastChapterNumber(int bookNumber) const;
 162
 163     /** Get the first verse number in a chapter of the passage.
 164      * @param bookNumber The number of the book.
 165      * @param chapterNumber The number of the chapter within the book.
 166      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 167      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 168      */
 169     int firstVerseNumber(int bookNumber, int chapterNumber) const;
 170     /** Get the last verse number in a chapter of the passage.
 171      * @param bookNumber The number of the book.
 172      * @param chapterNumber The number of the chapter within the book.
 173      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 174      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 175      */
 176     int lastVerseNumber(int bookNumber, int chapterNumber) const;
 177
 178     /*
 179      * Text extraction
 180      */
 181
 182     /// Get the entire passaage rendered as HTML.
 183     /// @todo Needs some rendering options, headings, footnotes etc.
 184     QString renderedText() const;
 185
 186   private:
 187
 188     /*
 189      * Types
 190      */
 191
 192     /// A verse in a chapter in a book.
 193     struct Verse
 194     {
 195       /// The headings preceeding this verse.
 196       QString headings;
 197       /// The main HTML content of this verse.
 198       QString content;
 199       /// @todo Footnotes
 200     };
 201
 202     /// A chapter in a book containing verses.
 203     struct Chapter
 204     {
 205       /// The number of the first verse in this chapter.
 206       int firstVerse;
 207       /// The number of verses in this chapter.
 208       int numVerses;
 209       /// The array of verses.
 210       Verse* verses;
 211     };
 212
 213     /// A book containing chapters.
 214     struct Book
 215     {
 216       /// The name of this book.
 217       QString name;
 218       /// The number of the first chapter in this book.
 219       int firstChapter;
 220       /// The number of chapters in this book.
 221       int numChapters;
 222       /// The array of chapters.
 223       Chapter* chapters;
 224     };
 225
 226     /*
 227      * Variables
 228      */
 229
 230     /// Bible manager id.
 231     QString m_managerId;
 232     /// Bible module id.
 233     QString m_moduleId;
 234
 235     /// Whether the text is right-to-left.
 236     bool m_rightToLeft;
 237
 238     /// The number of the first book.
 239     int m_firstBook;
 240     /// The number of books.
 241     int m_numBooks;
 242     /// The array of books.
 243     Book* m_books;
 244 };
 245
 246 #endif // _KwBiblePassage_h_
 247