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