Calligra/Words/Scripting

See also the Development/Tutorials/KWord Scripting tutorial at techbase.

Design ideas

Frame, FrameSet and Shapes

Currently the Frame class provides us transparent access to flake shapes while the FrameSet class is the container for frames.

The question is, if we need to differ between frames and framesets in the scripting API or if we are able to merge them together into a solution that handles both within one class.

Note from Thomas There is always a FrameSet wrapped around any Frame. For shapes like an arrow or many other shapes the concept of a FrameSet is not really usefull. The whole content is shown in one frame. This in contrary to a TextFrameSet which holds data that can be shown in multiple frames. The one functionality that FrameSets add to normal shapes is the concept of copy-shapes. For instance, you can have a 'star' shape and place it on the first page. The second page can have a copy-frame which is a new frame in the frameset of the star and it holds a KWCopyShape. Due to this limited usage of FrameSets I would like to suggest the API making Frames a first-row-citizen meaning you provide a list of frames in KWord scripting instead of shapes or framesets. Additionally its good to allow the FrameSet to be fetched from the Frame.

Note from Sebastian Frames are first-row-citizen now. The following Python code adds a new polygon-shape. The Frameset and the Frame are automatic created and fetching the FrameSet from the Frame works as well.

TextDocument

If a FrameSet is a TextFrameSet, we provide access to the TextDocument class through the TextFrame that is located in the TextFrameSet.

The TextDocument is the main entry-point to deal with the content displayed within the on the Qt4 Scribe framework based KWord editor. Currently the TextDocument uses TextCursor to offer read/write access. Also things like TextFrame, TextList and TextTable are handled with different objects. It would be nicer to don't present the TextDocument layer that detailed to the user.

• The Document to load, save, import, export, etc. as high-level collection of functionality to deal with the current document as well as access to the Metadata is provided with the KoApplicationAdaptor and KoDocumentAdaptor classes.
• Hyperlink, Table, List and Image are basic parts of a rich text document. This also got extended with Frame and FrameSet within KWord.
• May it be an idea to offer to a script a more structur-driven rather then cursor-driven interface to access the content of a document? The document offers a on OpenDocument based structured treeview of the document. Each node then provides functionality to manipulate it's children and attributes (which includes styles, formats, text, etc.). It may an idea to build something based on the header-recognization work done in a separate branch as gSOC and let scripts access the document that way via it's displayed DOM-tree/render-tree. On the other hand, if we take a look at OpenXML then we may note, that OpenXML uses cursors internally as well what in turn means that we may like to publish our cursor-based API to scripts as well to allow easier implementations of import/export scripts for e.g. OpenXML or other "cursor-based document formats".
• Do we need to take Relations into account to be able to e.g. ask who's linking to a part of a document + be able to access/notify targets/listeners?
• Action vs. Event means that we are on the one hand able to perform actions like copy+paste or replace on a document while an event is then the notification that something was done/changed on the document.
• How to integrate XForms? Maybe reuse khtml as shape?
• Look at the work done on the KDOM2 XPath implementation. Are we able to reuse it for the to a script presented DOM?
• How to integrate Variables and how to let a script get/set them?
• Quotations, Acronyms, Abbreviations and Grouping of content is not handled at all.

Conclusion: All in all, the Scribe interface shouldn't be exposed direct. It provides us much more flexibility to build the presented content-model up on our OpenDocument implementation. So, I am not able to continue to work on it till the OpenDoc-code is in place and does offer a somewhat stable API.

Note from Thomas: Looking at usecases for people currently using WP or other scriptable wordprocessors the usage of a cursor based scripting API is essential for macros. Being able to have an auto-generated script that records that I press 'up' twice and replay that using scripting will be much more intuitive for (non-technical) end users to alter then a structured representation of the document. Ideally; I'd like to see both a cursor based interface as well as a higher level structured-block based API.

Scripting Shape

It would be nice to have a "scripting shape" which paints or displays content provided by a script. It shouldn't be that difficult to get such a shape done.