Development/Tutorials/KWord Scripting

< Development‎ | Tutorials
Revision as of 20:52, 29 June 2011 by Neverendingo (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search



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

With the 2.0 release the scripts Application Programming Interface (API) is unsupported and unfinished and known to change. Use the API at your own risk! When the API is stable you can depend on future versions not breaking your scripts, this support is not present in the 2.0 release of KWord.

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 the functionality accessible from within the scripting backends.

The Handbook is generated from the sourcecode using doxygen and KWord's Import Doxygen XML File python script.


Load and save documents

Following Python script demonstrates how to load and save files;

import KWord

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

Import and export content

The 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()) )
#doc.setHtml( ' '.join(f.readlines()) )

The 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() )
#f.write( doc.toHtml() )

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 Python script implements inserting of a shape into the document.

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

The Python script just adds all shapes into the document.

import KWord
for shapeId in KWord.shapeKeys():
    frame = KWord.addFrame("myshape", shapeId)
    if frame:
        frame.setPosition(200, 50)
        frame.resize(160, 80)

Text content

The 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("<b>Some text</b>")

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 <b>Hello World</b>")

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 Python script demonstrates how to create lists with HTML.

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

The Python script demonstrates how to deal with tables.

KoStore and XML

The following python sample does demonstrate how to print the element-names of all xml-files that are within the KWord KoStore backend (see KoScriptingOdf.h) for our current document.

import KWord
store =
reader ="META-INF/manifest.xml")
if not reader:
    raise "Failed to read the mainfest"
paths = []
for i in range( reader.count() ):
    if reader.type(i) == "text/xml":
        paths.append( reader.path(i) )
for p in paths:
    reader =
    if not reader:
        raise "Failed to read %s" % p
    def onElement():
    reader.connect("onElement()", onElement)


The 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 Python script to read a variable from a file.


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

The Python script demonstrates usage of actions.

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

The 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))

The Python script demonstrates how to use the progressbar.

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

The 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 = ""
part = forms.loadPart(page, "libkhtmlpart", url)


Import from a Text or HTML File

The python script allows to import content from text- or html-files.

Import combined Doxygen XML File

The python script implements import of combined doxygen XML files into KWord.

As example this got used to generate the KSpread Scripting API-Reference. This is done by running doxygen with the KSpread doxygen file.

We are able to produce from within the commandline the handbook like demonstrated bellow;

   cd kspread/plugins/scripting/docs
   doxygen kspreadscripting.doxyfile
   cd xml
   xsltproc combine.xslt index.xml | kspread.html

You are also able to just generate a combined doxygen XML file with;

   cd kspread/plugins/scripting/docs
   doxygen kspreadscripting.doxyfile
   cd xml
   xsltproc combine.xslt index.xml > ~/mydoxygen.xml

Such a combined doxygen XML file can then be imported into our running KWord instance by running "Import Doxygen XML File" python script from the Tools/Scripts-menu.

Import File with UNO

The python script uses the PyUNO module to access and import content from any by supported fileformat. For this an optional hidden instance need to be started. Then the script connects as client to this server instance and controls it. If the script got executed and the connecting to the server failed, then it will startup such a hidden 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 should be established. Then a progressdialog will be displayed while in the background we try to connect with and let it load the file and pass the content back to KWord.


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

OpenDocument Text (*.odt), OpenDocument Text Template (*.ott), 1.0 Text Document (*.sxw), 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.

Export to a Text or HTML File

The python script allows to export content to text- or html-files.

XML Viewer

The python script to view the ISO OpenDocumentText XML representation of the current document displayed in KWord.

The XML Viewer does also allow to open the XML of the current document with an external application like KWrite or KXMLEditor. The "Compare..." button enables to compare the current XML with the XML of another ODT file.


Document Structure Viewer

The 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.


This page was last modified on 29 June 2011, at 20:52. This page has been accessed 21,871 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal