1 /* 2 * This file is part of Words 3 * 4 * Copyright (c) 2006 Sebastian Sauer <mail@dipe.org> 5 * Copyright (C) 2010 Thomas Zander <zander@kde.org> 6 * 7 * This program is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU Library General Public License as published by 9 * the Free Software Foundation; either version 2 of the License, or 10 * (at your option) any later version. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU Library General Public License for more details. 16 * 17 * You should have received a copy of the GNU Library General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 20 */ 21 22 #ifndef SCRIPTING_MODULE_H 23 #define SCRIPTING_MODULE_H 24 25 #include <KoScriptingModule.h> 26 27 #include <Words.h> 28 #include <QWeakPointer> 29 30 class KWDocument; 31 32 namespace Scripting 33 { 34 35 /** 36 * The Module class enables access to the Words functionality 37 * from within the scripting backends. 38 * It will be shown as 'Words' entity in scripting code. 39 * 40 * Words provides as top-level containers the \a FrameSet 41 * objects. Each such frameset is then able to contain 42 * multiple \a Frame objects. The frameset also allows to 43 * access the \a TextDocument object to deals with the actual 44 * content within a text document. 45 * 46 * Python example to set the content of the main text document; 47 * \code 48 * import Words 49 * doc = Words.mainFrameSet().document() 50 * doc.setHtml("<b>Hello World</b>") 51 * \endcode 52 * 53 * Python example to append content to the main text document 54 * and set the page header and footer; 55 * \code 56 * import Words 57 * doc = Words.mainFrameSet().document() 58 * doc.lastCursor().insertHtml("Even more <b>Hello World</b>") 59 * Words.firstPageHeaderFrameSet().document().setText("Header") 60 * Words.firstPageFooterFrameSet().document().setText("Footer") 61 * \endcode 62 * 63 * Python example that prints the documents Url and some other 64 * meta information; 65 * \code 66 * import Words 67 * print Words.document().url() 68 * print Words.document().documentInfoTitle() 69 * print Words.document().documentInfoAuthorName() 70 * \endcode 71 */ 72 class Module : public KoScriptingModule 73 { 74 Q_OBJECT 75 public: 76 explicit Module(QObject* parent = 0); 77 virtual ~Module(); 78 79 KWDocument* kwDoc(); 80 virtual KoDocument* doc(); 81 QObject* findFrameSet(Words::TextFrameSetType type); 82 83 public Q_SLOTS: 84 85 /***** Page *****/ 86 87 /** Return total number of pages the document has. */ 88 int pageCount(); 89 90 /** Return the \a Page of the specific page number. 91 * 92 * Python example that iterates over all pages; 93 * \code 94 * import Words 95 * for i in range( Words.pageCount() ): 96 * page = Words.page(i) 97 * print "width=%s height=%s" % (page.width(),page.height()) 98 * \endcode 99 */ 100 QObject* page(int pageNumber); 101 102 /** Insert a new page and returns the new \a Page object. 103 * 104 * The new page is inserted after the page which has the pagenumber 105 * \p afterPageNum . If \p afterPageNum is 0, the new page is 106 * inserted before page 1. In all cases, the new page will have 107 * the number afterPageNum+1. To append a new page use 108 * insertPage( pageCount() ). 109 */ 110 QObject* insertPage(int afterPageNum); 111 /** Remove the page with the pagenumber \p pageNumber . */ 112 void removePage(int pageNumber); 113 114 /***** FrameSet *****/ 115 116 /** Return the amount of framesets this document holds. */ 117 int frameSetCount(); 118 /** Return the \a FrameSet object identified by the index frameSetNr. */ 119 QObject* frameSet(int frameSetNr); 120 /** Return the \a FrameSet object which has the name \p name . */ 121 QObject* frameSetByName(const QString& name); 122 123 /** Return the \a FrameSet that holds the headers for the odd pages */ oddPagesHeaderFrameSet()124 QObject* oddPagesHeaderFrameSet() { 125 return findFrameSet(Words::OddPagesHeaderTextFrameSet); 126 } 127 /** Return the \a FrameSet that holds the headers for the even pages */ evenPagesHeaderFrameSet()128 QObject* evenPagesHeaderFrameSet() { 129 return findFrameSet(Words::EvenPagesHeaderTextFrameSet); 130 } 131 /** Return the \a FrameSet that holds the footers for the odd pages */ oddPagesFooterFrameSet()132 QObject* oddPagesFooterFrameSet() { 133 return findFrameSet(Words::OddPagesFooterTextFrameSet); 134 } 135 /** Return the \a FrameSet that holds the footers for the even pages */ evenPagesFooterFrameSet()136 QObject* evenPagesFooterFrameSet() { 137 return findFrameSet(Words::EvenPagesFooterTextFrameSet); 138 } 139 140 /** Return the \a FrameSet that holds all the frames for the main text area */ mainFrameSet()141 QObject* mainFrameSet() { 142 return findFrameSet(Words::MainTextFrameSet); 143 } 144 145 /** Return any other \a FrameSet not managed by the auto-frame layout */ otherFrameSet()146 QObject* otherFrameSet() { 147 return findFrameSet(Words::OtherTextFrameSet); 148 } 149 150 /** Add and return a new \a FrameSet object for text handled with \a TextDocument . */ 151 QObject* addTextFrameSet(const QString& framesetname); 152 /** Add and return a new \a FrameSet object. */ 153 QObject* addFrameSet(const QString& framesetname); 154 155 /***** Frame *****/ 156 157 /** Return a list of shapeId names. Such a shapeId name could then be 158 used for example with the \a addFrame() method to create a new frame. */ 159 QStringList shapeKeys(); 160 161 /** Return the amount of frames this document holds. */ 162 int frameCount(); 163 /** Return a the \a Frame object identified by the index frameNr. */ 164 QObject* frame(int frameNr); 165 166 /***** Page Layout *****/ 167 168 /** Return the standard page layout. */ 169 QObject* standardPageLayout(); 170 171 /***** Style *****/ 172 173 /** Return the default paragraph \a ParagraphStyle that will always be present in each document. */ 174 QObject* defaultParagraphStyle(); 175 /** Return the \a ParagraphStyle with the defined user-visible-name \p name . */ 176 QObject* paragraphStyle(const QString& name); 177 /** Add and return a new \a ParagraphStyle object. */ 178 QObject* addParagraphStyle(const QString& name); 179 180 /** Return the \a CharacterStyle with the defined user-visible-name \p name . */ 181 QObject* characterStyle(const QString& name); 182 /** Add and return a new \a CharacterStyle object. */ 183 QObject* addCharacterStyle(const QString& name); 184 185 /***** Active selection *****/ 186 187 /** Return a \a Tool object that provides access to functionality 188 like handling for example current/active selections. */ 189 QObject* tool(); 190 191 private: 192 QWeakPointer<KWDocument> m_doc; 193 }; 194 195 } 196 197 #endif 198