Difference between revisions of "Development/Tutorials/KWord Scripting"

Jump to: navigation, search
(proper highlight the python snippets using <code>)
Line 23: Line 23:
  
 
Following Python script demonstrates how to load and save files;
 
Following Python script demonstrates how to load and save files;
<pre>
+
<code python>
 
import KWord
 
import KWord
 
KWord.document().openURL("/home/myuser/myDoc.odt")
 
KWord.document().openURL("/home/myuser/myDoc.odt")
 
KWord.document().saveAs("/home/myuser/myDocCopy.odt")
 
KWord.document().saveAs("/home/myuser/myDocCopy.odt")
 
KWord.document().saveAs("/home/myuser/myDocAsText.txt")
 
KWord.document().saveAs("/home/myuser/myDocAsText.txt")
</pre>
+
</code>
  
 
All slots and signals within the [http://websvn.kde.org/trunk/koffice/libs/kofficecore/KoDocumentAdaptor.h?view=markup KoDocumentAdaptor] are accessible as KWord.document().
 
All slots and signals within the [http://websvn.kde.org/trunk/koffice/libs/kofficecore/KoDocumentAdaptor.h?view=markup KoDocumentAdaptor] are accessible as KWord.document().
Line 36: Line 36:
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_importfile.py?view=markup sample_importfile.py] Python script implements import of content from a text or html file.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_importfile.py?view=markup sample_importfile.py] Python script implements import of content from a text or html file.
  
<pre>
+
<code python>
 
import KWord
 
import KWord
 
doc = KWord.mainFrameSet().document()
 
doc = KWord.mainFrameSet().document()
Line 43: Line 43:
 
#doc.setHtml( ' '.join(f.readlines()) )
 
#doc.setHtml( ' '.join(f.readlines()) )
 
f.close()
 
f.close()
</pre>
+
</code>
  
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_exportfile.py?view=markup sample_exportfile.py] Python script implements export of content to a text or html file.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_exportfile.py?view=markup sample_exportfile.py] Python script implements export of content to a text or html file.
  
<pre>
+
<code python>
 
import KWord
 
import KWord
 
doc = KWord.mainFrameSet().document()
 
doc = KWord.mainFrameSet().document()
Line 54: Line 54:
 
#f.write( doc.toHtml() )
 
#f.write( doc.toHtml() )
 
f.close()
 
f.close()
</pre>
+
</code>
  
 
=== Document Structure Viewer ===
 
=== Document Structure Viewer ===
Line 67: Line 67:
  
 
The following python script adds a polygon shape and then prints the name and the ID of each shape.
 
The following python script adds a polygon shape and then prints the name and the ID of each shape.
<pre>
+
<code python>
 
import KWord
 
import KWord
 
KWord.addFrame("mypoly", "KoRegularPolygonShape")
 
KWord.addFrame("mypoly", "KoRegularPolygonShape")
Line 73: Line 73:
 
     f = KWord.frame(i)
 
     f = KWord.frame(i)
 
     print "%s %s" % (f.frameSet().name(),f.shapeId())
 
     print "%s %s" % (f.frameSet().name(),f.shapeId())
</pre>
+
</code>
  
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_insertshape.py?view=markup sample_insertshape.py] Python script implements inserting of a shape into the document.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_insertshape.py?view=markup sample_insertshape.py] Python script implements inserting of a shape into the document.
  
<pre>
+
<code python>
 
import KWord
 
import KWord
 
textshape = KWord.addTextFrame("MyTextShape")
 
textshape = KWord.addTextFrame("MyTextShape")
 
textshape.document().setText("Some text")
 
textshape.document().setText("Some text")
</pre>
+
</code>
  
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_allshapes.py?view=markup sample_allshapes.py] Python script just adds all shapes into the document.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_allshapes.py?view=markup sample_allshapes.py] Python script just adds all shapes into the document.
  
<pre>
+
<code python>
 
import KWord
 
import KWord
 
for shapeId in KWord.shapeKeys():
 
for shapeId in KWord.shapeKeys():
Line 93: Line 93:
 
         frame.setPosition(200, 50)
 
         frame.setPosition(200, 50)
 
         frame.resize(160, 80)
 
         frame.resize(160, 80)
</pre>
+
</code>
  
 
=== Text content ===
 
=== Text content ===
Line 100: Line 100:
  
 
The following python sample adds some text at the end of the main framesets document.
 
The following python sample adds some text at the end of the main framesets document.
<pre>
+
<code python>
 
import KWord
 
import KWord
 
doc = KWord.mainFrameSet().document()
 
doc = KWord.mainFrameSet().document()
 
cursor = doc.rootFrame().lastCursorPosition()
 
cursor = doc.rootFrame().lastCursorPosition()
 
cursor.insertHtml("<b>Some text</b>")
 
cursor.insertHtml("<b>Some text</b>")
</pre>
+
</code>
  
 
This python sample adds some text and sets the page header and the page footer.
 
This python sample adds some text and sets the page header and the page footer.
<pre>
+
<code python>
 
import KWord
 
import KWord
 
doc = KWord.mainFrameSet().document()
 
doc = KWord.mainFrameSet().document()
Line 114: Line 114:
 
KWord.firstPageHeaderFrameSet().document().setText("Header")
 
KWord.firstPageHeaderFrameSet().document().setText("Header")
 
KWord.firstPageFooterFrameSet().document().setText("Footer")
 
KWord.firstPageFooterFrameSet().document().setText("Footer")
</pre>
+
</code>
  
 
Python sample that prints the url and some metainformations of the document.
 
Python sample that prints the url and some metainformations of the document.
<pre>
+
<code python>
 
import KWord
 
import KWord
 
print KWord.document().url()
 
print KWord.document().url()
 
print KWord.document().documentInfoTitle()
 
print KWord.document().documentInfoTitle()
 
print KWord.document().documentInfoAuthorName()
 
print KWord.document().documentInfoAuthorName()
</pre>
+
</code>
  
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_lists_html.py?view=markup sample_lists_html.py] Python script demonstrates how to create lists with HTML.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_lists_html.py?view=markup sample_lists_html.py] Python script demonstrates how to create lists with HTML.
Line 134: Line 134:
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_variables.py?view=markup sample_variables.py] Python script demonstrates how to handle variables.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_variables.py?view=markup sample_variables.py] Python script demonstrates how to handle variables.
  
<pre>
+
<code python>
 
import KWord
 
import KWord
 
doc = KWord.mainFrameSet().document()
 
doc = KWord.mainFrameSet().document()
 
for v in doc.variableNames():
 
for v in doc.variableNames():
 
     print "name=%s value=%s" % (v, doc.variableValue(v))
 
     print "name=%s value=%s" % (v, doc.variableValue(v))
</pre>
+
</code>
  
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/variable_readfile.py?view=markup variable_readfile.py] Python script to read a variable from a file.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/variable_readfile.py?view=markup variable_readfile.py] Python script to read a variable from a file.
Line 149: Line 149:
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_actions.py?view=markup sample_actions.py] Python script demonstrates usage of actions.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_actions.py?view=markup sample_actions.py] Python script demonstrates usage of actions.
  
<pre>
+
<code python>
 
import KWord
 
import KWord
 
KWord.shell().slotFileNew()
 
KWord.shell().slotFileNew()
 
KWord.mainWindow().setCaption("My Caption")
 
KWord.mainWindow().setCaption("My Caption")
</pre>
+
</code>
  
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_toolactions.py?view=markup sample_toolactions.py] Python script demonstrates how to trigger actions the current tool provides.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_toolactions.py?view=markup sample_toolactions.py] Python script demonstrates how to trigger actions the current tool provides.
  
<pre>
+
<code python>
 
import KWord
 
import KWord
 
tool = KWord.tool()
 
tool = KWord.tool()
Line 163: Line 163:
 
     print "%s: %s" % (n, tool.actionText(n))
 
     print "%s: %s" % (n, tool.actionText(n))
 
     tool.triggerAction(n)
 
     tool.triggerAction(n)
</pre>
+
</code>
  
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_progressbar.py?view=markup sample_progressbar.py] Python script demonstrates how to use the progressbar.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_progressbar.py?view=markup sample_progressbar.py] Python script demonstrates how to use the progressbar.
  
<pre>
+
<code python>
 
import KWord
 
import KWord
 
for i in range(1,101):
 
for i in range(1,101):
 
     KWord.shell().slotProgress(i)
 
     KWord.shell().slotProgress(i)
 
KWord.shell().slotProgress(-1)
 
KWord.shell().slotProgress(-1)
</pre>
+
</code>
  
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_onlinehelp.py?view=markup sample_onlinehelp.py] Python script uses the KHTML Part to display the KWord Scripting online help.
 
The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_onlinehelp.py?view=markup sample_onlinehelp.py] Python script uses the KHTML Part to display the KWord Scripting online help.
  
<pre>
+
<code python>
 
import Kross
 
import Kross
 
forms = Kross.module("forms")
 
forms = Kross.module("forms")
Line 184: Line 184:
 
part = forms.loadPart(page, "libkhtmlpart", url)
 
part = forms.loadPart(page, "libkhtmlpart", url)
 
dialog.exec_loop()
 
dialog.exec_loop()
</pre>
+
</code>
  
 
== Connect KWord with OpenOffice.org ==
 
== Connect KWord with OpenOffice.org ==

Revision as of 11:36, 28 May 2007

Contents

Intro

KWord uses Kross to provide scripting with Python, Ruby and KDE JavaScript.

The Scripting Plugin

The KWord Scripting Plugin implements a plugin to dynamic access the scripting functionality from within KWord.

  • The KWScriptingPart class implements a KPart component to integrate scripting as plugin into KWord.
  • The Scripting::Module class enables access to the KWord functionality from within the scripting backends.
  • The FrameSet and Frame classes are holding the content that is displayed on screen.
  • The TextDocument class represents a QTextDocument within the Scribe text-engine KWord uses to enable editing of text content. The TextCursor implements a control structure for the successive traversal of content within such a TextDocument .

Scripting Handbook

The KWord Scripting Handbook contains a full reference of all objects and methods accessible from within the scripting backends.

The Handbook is generated from the sourcecode using doxygen and the doxy2doc.py Python script as postprocessor to create visible output from the by doxygen produced XML files.

Samples

Load and save documents

Following Python script demonstrates how to load and save files; import KWord KWord.document().openURL("/home/myuser/myDoc.odt") KWord.document().saveAs("/home/myuser/myDocCopy.odt") KWord.document().saveAs("/home/myuser/myDocAsText.txt")

All slots and signals within the KoDocumentAdaptor are accessible as KWord.document().

Import and export content

The sample_importfile.py Python script implements import of content from a text or html file.

import KWord doc = KWord.mainFrameSet().document() f = open("/home/myuser/mytextfile.txt", "r") doc.setText( ' '.join(f.readlines()) )

  1. doc.setHtml( ' '.join(f.readlines()) )

f.close()

The sample_exportfile.py Python script implements export of content to a text or html file.

import KWord doc = KWord.mainFrameSet().document() f = open("/home/myuser/mytextfile.txt", "w") f.write( doc.toText() )

  1. f.write( doc.toHtml() )

f.close()

Document Structure Viewer

The sample_doctree.rb QtRuby script implement a document structur viewer.

The viewer displays the framesets, frames, documents and there objects as tree where each node may provide additional functionality like a collection of properties, text or styles.

Kwordscriptingdoctree.jpg

Framesets, Frames and Shapes

The following python script adds a polygon shape and then prints the name and the ID of each shape. import KWord KWord.addFrame("mypoly", "KoRegularPolygonShape") for i in range( KWord.frameCount() ):

   f = KWord.frame(i)
   print "%s %s" % (f.frameSet().name(),f.shapeId())

The sample_insertshape.py Python script implements inserting of a shape into the document.

import KWord textshape = KWord.addTextFrame("MyTextShape") textshape.document().setText("Some text")

The sample_allshapes.py Python script just adds all shapes into the document.

import KWord for shapeId in KWord.shapeKeys():

   frame = KWord.addFrame("myshape", shapeId)
   if frame:
       frame.setTextRunAround(frame.RunThrough)
       frame.setPosition(200, 50)
       frame.resize(160, 80)

Text content

The sample_text.py Python script demonstrates usage of the text engine.

The following python sample adds some text at the end of the main framesets document. import KWord doc = KWord.mainFrameSet().document() cursor = doc.rootFrame().lastCursorPosition() cursor.insertHtml("Some text")

This python sample adds some text and sets the page header and the page footer. import KWord doc = KWord.mainFrameSet().document() doc.lastCursor().insertHtml("Even more Hello World") KWord.firstPageHeaderFrameSet().document().setText("Header") KWord.firstPageFooterFrameSet().document().setText("Footer")

Python sample that prints the url and some metainformations of the document. import KWord print KWord.document().url() print KWord.document().documentInfoTitle() print KWord.document().documentInfoAuthorName()

The sample_lists_html.py Python script demonstrates how to create lists with HTML.

The sample_lists_cursor.py Python script demonstrates how to create lists with a cursor.

The sample_tables.py Python script demonstrates how to deal with tables.

Variables

The sample_variables.py Python script demonstrates how to handle variables.

import KWord doc = KWord.mainFrameSet().document() for v in doc.variableNames():

   print "name=%s value=%s" % (v, doc.variableValue(v))

The variable_readfile.py Python script to read a variable from a file.

KWord

The sample_cursor.rb Ruby script demonstrates how to control the cursor.

The sample_actions.py Python script demonstrates usage of actions.

import KWord KWord.shell().slotFileNew() KWord.mainWindow().setCaption("My Caption")

The sample_toolactions.py Python script demonstrates how to trigger actions the current tool provides.

import KWord tool = KWord.tool() for n in tool.actionNames():

   print "%s: %s" % (n, tool.actionText(n))
   tool.triggerAction(n)

The sample_progressbar.py Python script demonstrates how to use the progressbar.

import KWord for i in range(1,101):

   KWord.shell().slotProgress(i)

KWord.shell().slotProgress(-1)

The sample_onlinehelp.py Python script uses the KHTML Part to display the KWord Scripting online help.

import Kross forms = Kross.module("forms") dialog = forms.createDialog("KHTML Part") page = dialog.addPage("", "") url = "http://wiki.koffice.org" part = forms.loadPart(page, "libkhtmlpart", url) dialog.exec_loop()

Connect KWord with OpenOffice.org

Import File with OpenOffice.org

The python script ooimport.py uses the PyUNO module to access OpenOffice.org and import content from any by OpenOffice.org supported fileformat. For this an optional hidden OpenOffice.org instance need to be started. Then the script connects as client to this OpenOffice.org server instance and controls it. If the script got executed and the connecting to the server failed, then it will startup such a hidden OpenOffice.org server instance and shuts it down again once the work is done.

If the script got executed from within KWord (e.g. by using the "Tools=>Script Manager") the following dialog is displayed. The user chooses the file he likes to import and may also able to change settings related to how the connection to OpenOffice.org should be established. Then a progressdialog will be displayed while in the background we try to connect with OpenOffice.org and let it load the file and pass the content back to KWord.

Kwordscriptingooimport.jpg

That way KWord is able to optional use the OpenOffice.org import-filters to import content from file formats like;

OpenDocument Text (*.odt), OpenDocument Text Template (*.ott), OpenOffice.org 1.0 Text Document (*.sxw), OpenOffice.org 1.0 Text Document Template (*.stw), Microsoft Word 95/97/2000/XP (*.doc), Microsoft Word 95/97/2000/XP Template (*.dot), Microsoft Word 2003 XML (*.xml), Rich Text Format (*.rtf), Text (*.txt), HTML Document (*.html *.htm), DocBook (*.xml), StarWriter 1.0 - 5.0 (*.sdw), StarWriter 3.0 - 5.0 Templates (*.vor), WordPerfect Document (*.wpd), Lotus WordPro Document (*.lwp), Ichitaro 8/9/10/11 (*.jtd), Ichitaro 8/9/10/11 Template (*.jtt), Hangul WP 97 (*.hwp), WPS 2000/Office 1.0 (*.wps), etc.


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal