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 /** A passage of rendered bible text.
  34  * Stores enough information to adjust settings.
  35  * Can be used as a cache.
  36  */
  37 class KwBiblePassage
  38 {
  39   public:
  40
  41     /*
  42      * Constructors + destructor
  43      */
  44
  45     /// Default constructor.
  46     KwBiblePassage();
  47
  48     /// Destructor.
  49     virtual ~KwBiblePassage();
  50
  51     /*
  52      * Main interface
  53      */
  54
  55     /** Clear the passage.
  56      * Deletes all books.
  57      */
  58     void clear();
  59
  60     /** Set the source module.
  61      * @param managerId ID of the bible manager.
  62      * @param moduleId ID of the bible module.
  63      */
  64     void setSource(const QString& managerId, const QString& moduleId);
  65
  66     /** Initialise the books in the passage.
  67      * If books are already initialised they will be cleared first.
  68      * @param firstBook Number of first book in passage.
  69      * @param numBooks Number of books covered in this passage.
  70      * @param numBooks > 0
  71      */
  72     void initBooks(int firstBook, int numBooks);
  73
  74     /** Initialise a book in the passage.
  75      * If the book is already initialised it will be cleared first.
  76      * @param bookNumber Number of the book to initialise.
  77      * @param name Name of the book.
  78      * @param firstChapter Number of first chapter in book.
  79      * @param numChapters Number of chapters covered in this book.
  80      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
  81      * @pre numChapters > 0
  82      */
  83     void initBook(int bookNumber,
  84                   const QString& name, int firstChapter, int numChapters);
  85
  86     /** Initialise a chapter in the passage.
  87      * If the chapter is already initialised it will be cleared first.
  88      * @param bookNumber Number of the book with the chapter to initialise.
  89      * @param chapterNumber Number of the chapter to initialise.
  90      * @param firstVerse Number of first verse in chapter.
  91      * @param numVerses Number of verses covered in this chapter.
  92      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
  93      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
  94      * @pre numVerses > 0
  95      */
  96     void initChapter(int bookNumber, int chapterNumber,
  97                      int firstVerse, int numVerses);
  98
  99     /** Initialise a verse in the passage.
 100      * If the verse is already initialised it will be cleared first.
 101      * @param bookNumber Number of the book with the chapter to initialise.
 102      * @param chapterNumber Number of the chapter with the verse to initialise.
 103      * @param verseNumber Number of the verse to initialise.
 104      * @param headings Headings HTML preceeding this verse.
 105      * @param content Main HTML in this verse.
 106      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 107      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 108      * @pre firstVerseNumber(bookNumber) <= verseNumber <= lastVerseNumber(bookNumber)
 109      */
 110     void initVerse(int bookNumber, int chapterNumber, int verseNumber,
 111                    const QString& headings, const QString& content);
 112
 113     /*
 114      * Accessors
 115      */
 116
 117     /// Find whether the passage is empty.
 118     bool isEmpty() const;
 119
 120     /// Get textual key of this passage.
 121     QString textualKey() const;
 122
 123     /// Get the first book number in the passage.
 124     int firstBookNumber() const;
 125     /// Get the last book number in the passage.
 126     int lastBookNumber() const;
 127
 128     /** Get the first chapter number in a book of the passage.
 129      * @param bookNumber The number of the book.
 130      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 131      */
 132     int firstChapterNumber(int bookNumber) const;
 133     /** Get the last chapter number in a book of the passage.
 134      * @param bookNumber The number of the book.
 135      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 136      */
 137     int lastChapterNumber(int bookNumber) const;
 138
 139     /** Get the first verse number in a chapter of the passage.
 140      * @param bookNumber The number of the book.
 141      * @param chapterNumber The number of the chapter within the book.
 142      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 143      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 144      */
 145     int firstVerseNumber(int bookNumber, int chapterNumber) const;
 146     /** Get the last verse number in a chapter of the passage.
 147      * @param bookNumber The number of the book.
 148      * @param chapterNumber The number of the chapter within the book.
 149      * @pre firstBookNumber() <= bookNumber <= lastBookNumber()
 150      * @pre firstChapterNumber(bookNumber) <= chapterNumber <= lastChapterNumber(bookNumber)
 151      */
 152     int lastVerseNumber(int bookNumber, int chapterNumber) const;
 153
 154     /*
 155      * Text extraction
 156      */
 157
 158     /// Get the entire passaage rendered as HTML.
 159     /// @todo Needs some rendering options, headings, footnotes etc.
 160     QString renderedText();
 161
 162   private:
 163
 164     /*
 165      * Types
 166      */
 167
 168     /// A verse in a chapter in a book.
 169     struct Verse
 170     {
 171       /// The headings preceeding this verse.
 172       QString headings;
 173       /// The main HTML content of this verse.
 174       QString content;
 175       /// @todo Footnotes
 176     };
 177
 178     /// A chapter in a book containing verses.
 179     struct Chapter
 180     {
 181       /// The number of the first verse in this chapter.
 182       int firstVerse;
 183       /// The number of verses in this chapter.
 184       int numVerses;
 185       /// The array of verses.
 186       Verse* verses;
 187     };
 188
 189     /// A book containing chapters.
 190     struct Book
 191     {
 192       /// The name of this book.
 193       QString name;
 194       /// The number of the first chapter in this book.
 195       int firstChapter;
 196       /// The number of chapters in this book.
 197       int numChapters;
 198       /// The array of chapters.
 199       Chapter* chapters;
 200     };
 201
 202     /*
 203      * Variables
 204      */
 205
 206     /// Bible manager id.
 207     QString m_managerId;
 208     /// Bible module id.
 209     QString m_moduleId;
 210     /// Original module key.
 211     KwBibleModule::Key m_key;
 212
 213     /// The number of the first book.
 214     int m_firstBook;
 215     /// The number of books.
 216     int m_numBooks;
 217     /// The array of books.
 218     Book* m_books;
 219 };
 220
 221 #endif // _KwBiblePassage_h_
 222