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 #include "KwBibleExport.h"
  31
  32 #include <QString>
  33
  34 class QDomDocument;
  35 class QDomElement;
  36
  37 /** A passage of rendered bible text.
  38  * Stores enough information to adjust settings.
  39  * Can be used as a cache.
  40  */
  41 class KWBIBLE_EXPORT KwBiblePassage
  42 {
  43   public:
  44
  45     /*
  46      * Constructors + destructor
  47      */
  48
  49     /// Default constructor.
  50     KwBiblePassage();
  51
  52     /// Destructor.
  53     virtual ~KwBiblePassage();
  54
  55     /*
  56      * DOM filters
  57      */
  58
  59     /// Import the passage in a DOM.
  60     void importFromDom(const QDomElement& element);
  61
  62     /// Export the passage using DOM.
  63     void exportToDom(QDomDocument& document, QDomElement& element) const;
  64
  65     /*
  66      * Main interface
  67      */
  68
  69     /** Clear the passage.
  70      * Deletes all books.
  71      */
  72     void clearBooks();
  73
  74     /** Clear the chapters in a book.
  75      * Deletes all chapters.
  76      */
  77     void clearChapters(int bookNumber);
  78
  79     /** Clear the verses in a chapter.
  80      * Deletes all verses.
  81      */
  82     void clearVerses(int bookNumber, int chapterNumber);
  83
  84     /** Set the source module.
  85      * @param managerId ID of the bible manager.
  86      * @param moduleId ID of the bible module.
  87      * @param rightToLeft Whether the text is right-to-left.
  88      */
  89     void setSource(const QString& managerId, const QString& moduleId, bool rightToLeft);
  90
  91     /** Initialise the books in the passage.
  92      * If books are already initialised they will be cleared first.
  93      * @param firstBook Number of first book in passage.
  94      * @param numBooks Number of books covered in this passage.
  95      * @param numBooks > 0
  96      */
  97     void initBooks(int firstBook, int numBooks);
  98
  99     /** Initialise a book in the passage.
 100      * If the book is already initialised it will be cleared first.
 101      * @param bookNumber Number of the book to initialise.
 102      * @param name Name of the book.
 103      * @param firstChapter Number of first chapter in book.
 104      * @param numChapters Number of chapters covered in this book.
 105      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 106      * @pre numChapters > 0
 107      */
 108     void initBook(int bookNumber,
 109                   const QString& name, int firstChapter, int numChapters);
 110
 111     /** Initialise a chapter in the passage.
 112      * If the chapter is already initialised it will be cleared first.
 113      * @param bookNumber Number of the book with the chapter to initialise.
 114      * @param chapterNumber Number of the chapter to initialise.
 115      * @param firstVerse Number of first verse in chapter.
 116      * @param numVerses Number of verses covered in this chapter.
 117      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 118      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 119      * @pre numVerses > 0
 120      */
 121     void initChapter(int bookNumber, int chapterNumber,
 122                      int firstVerse, int numVerses);
 123
 124     /** Initialise a verse in the passage.
 125      * If the verse is already initialised it will be cleared first.
 126      * @param bookNumber Number of the book with the chapter to initialise.
 127      * @param chapterNumber Number of the chapter with the verse to initialise.
 128      * @param verseNumber Number of the verse to initialise.
 129      * @param headings Headings HTML preceeding this verse.
 130      * @param content Main HTML in this verse.
 131      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 132      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 133      * @pre firstVerseNumber(bookNumber) <= verseNumber <= lastVerseNumber(bookNumber)
 134      */
 135     void initVerse(int bookNumber, int chapterNumber, int verseNumber,
 136                    const QString& headings, const QString& content);
 137
 138     /*
 139      * Accessors
 140      */
 141
 142     /// Find whether the passage is empty.
 143     bool isEmpty() const;
 144
 145     /// Get textual key of this passage.
 146     QString textualKey() const;
 147
 148     /// Find whether the text is right to left.
 149     bool isRightToLeft() const;
 150
 151     /// Get the first book number in the passage.
 152     int firstBookNumber() const;
 153     /// Get the last book number in the passage.
 154     int lastBookNumber() const;
 155
 156     /** Get the first chapter number in a book of the passage.
 157      * @param bookNumber The number of the book.
 158      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 159      */
 160     int firstChapterNumber(int bookNumber) const;
 161     /** Get the last chapter number in a book of the passage.
 162      * @param bookNumber The number of the book.
 163      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 164      */
 165     int lastChapterNumber(int bookNumber) const;
 166
 167     /** Get the first verse number in a chapter of the passage.
 168      * @param bookNumber The number of the book.
 169      * @param chapterNumber The number of the chapter within the book.
 170      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 171      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 172      */
 173     int firstVerseNumber(int bookNumber, int chapterNumber) const;
 174     /** Get the last verse number in a chapter of the passage.
 175      * @param bookNumber The number of the book.
 176      * @param chapterNumber The number of the chapter within the book.
 177      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 178      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 179      */
 180     int lastVerseNumber(int bookNumber, int chapterNumber) const;
 181
 182     /** Get the headings before a verse.
 183      * @param bookNumber The number of the book.
 184      * @param chapterNumber The number of the chapter within the book.
 185      * @param verseNumber The number of the verse within the chapter.
 186      * @param plain Whether to return plain text instead of HTML.
 187      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 188      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 189      * @pre firstVerseNumber(bookNumber, chapterNumber) <= verseNumber <= lastVerseNumber(bookNumber, chapterNumber)
 190      * @return Headings before verse.
 191      */
 192     QString verseHeadings(int bookNumber, int chapterNumber, int verseNumber, bool plain = false) const;
 193
 194     /** Get the content of a verse.
 195      * @param bookNumber The number of the book.
 196      * @param chapterNumber The number of the chapter within the book.
 197      * @param verseNumber The number of the verse within the chapter.
 198      * @param plain Whether to return plain text instead of HTML.
 199      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 200      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 201      * @pre firstVerseNumber(bookNumber, chapterNumber) <= verseNumber <= lastVerseNumber(bookNumber, chapterNumber)
 202      * @return Content of verse.
 203      */
 204     QString verseContent(int bookNumber, int chapterNumber, int verseNumber, bool plain = false) const;
 205
 206     /*
 207      * Text extraction
 208      */
 209
 210     /// Get the entire passaage rendered as HTML.
 211     /// @todo Needs some rendering options, headings, footnotes etc.
 212     QString renderedText() const;
 213
 214   private:
 215
 216     /*
 217      * Types
 218      */
 219
 220     /// A verse in a chapter in a book.
 221     struct Verse
 222     {
 223       /// The headings preceeding this verse.
 224       QString headings;
 225       /// The main HTML content of this verse.
 226       QString content;
 227       /// @todo Footnotes
 228     };
 229
 230     /// A chapter in a book containing verses.
 231     struct Chapter
 232     {
 233       /// The number of the first verse in this chapter.
 234       int firstVerse;
 235       /// The number of verses in this chapter.
 236       int numVerses;
 237       /// The array of verses.
 238       Verse* verses;
 239     };
 240
 241     /// A book containing chapters.
 242     struct Book
 243     {
 244       /// The name of this book.
 245       QString name;
 246       /// The number of the first chapter in this book.
 247       int firstChapter;
 248       /// The number of chapters in this book.
 249       int numChapters;
 250       /// The array of chapters.
 251       Chapter* chapters;
 252     };
 253
 254     /*
 255      * Variables
 256      */
 257
 258     /// Bible manager id.
 259     QString m_managerId;
 260     /// Bible module id.
 261     QString m_moduleId;
 262
 263     /// Whether the text is right-to-left.
 264     bool m_rightToLeft;
 265
 266     /// The number of the first book.
 267     int m_firstBook;
 268     /// The number of books.
 269     int m_numBooks;
 270     /// The array of books.
 271     Book* m_books;
 272 };
 273
 274 #endif // _KwBiblePassage_h_
 275