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