Introduction video

I will try to add some comments later. Here you can see a recorded sessions with ScripterNG in action.

It includes

• the object explorer
• the script editor with interactive console
  
• the error handler
• the source checker
• and an example script which shows to main window in full-screen mode

How to add functions to the scripting interface

First a little bit about good API-design. The (mostly) property-based object model in InDesign is a great example how to create a well-designed easy API. Take a look at this guide (PDF, 3.2 MB).

You start with a scaffolding-like script:

Go to the scripterng plug-in directory and call
./new_api.py test
This will generate two files:

• api_test.h
• api_test.cpp

from api_example.{h,cpp} as a template.

The files are added to CMakeLists.txt and the header file is included in scripterngimpl.h

Inside these files there is a class TestAPI defined. By default the class is a child of ScriperNGImpl and has the object-name Test. So the class will be automatically available under the name ScriperNG.Test from Python or QtScript.

The class is created at start-up in scriperngimpl.cpp but you might want to change that. Look for the activeDocument Q_PROPERTY in scripterngimpl to see how to create an object on demand.

To write a function which is available for scripting you have to write a public slot method. Allowed as parameters and as return types are basic types (int, bool, ..) and Qt objects. Pointers to pointers and complicated stuff like that does not work - but would not make any sense anyway...
One caveat: If you want to return instances of QObject or QWidget you have to declare the base class QObject or QWidget as return type. The correct typecasting is done later at runtime via the Qt Meta-Object system.

That's all. You do not have to know anything about the scripting language or about any binding api to do parameter conversation and validation. This is done by ScripterNG.

Script Descriptor Files

These files describe a script. Its extension is .scs and you can write them easily by hand. Here are the possible options and their defaults:

name =
title =
description =
icon =
menu = ScripterNG
shortcut =                # A valid QKeySequence as a string, see Qt4-docs
filename =                # name of script file
subroutine =              # additional entry point?
author =
contact =
homepage =
version =
copyright =               # GPL2
scribus_version =
redraw = True
mode = interactive        # allowed: batch, interactive, extension
language = python         # allowed: python, qtscript
separator_before = False  # in menu
separator_after = False   # in menu
background_mode = False   # threaded execution only for non-gui scripts

More options are already planned and will come with a later release. Feedback on needed features is always welcome.

If you put a script descriptor file inside the scripterng/autoload or ~/.scribus/scripterng/autoload folder it will be loaded at startup, added to the menu bar, etc.
Every entry you see in the ScriperNG menu is already a separate script in autoload.

You can also put the script descriptor inside a source file at the top in double comments. Python files have to be called .spy and look like this:

# -*- coding: utf-8 -*-
## name = about
## title = About ScripterNG
## shortcut = Esc,a
# ScripterNG is a builtin and does not need to be imported
ScripterNG.aboutScripterNG()

With QtScript (extension is .sqts) the same is possible:

/// name = aboutqts
/// title = About ScripterNG from QtScript
ScripterNG.aboutScripter();

Support for .zip-packaged scripts is on the TODO.

Dockable dialogs - manipulate the GUI with PyQt and ScripterNG

With ScripterNG and PyQt you have access to the GUI and you can test new stuff easily.

Here is an example with dockwidgets, which are curently not used inside Scribus:

If you look in the lower left you can see that overlapping dockwidgets get tabbed. This is a new feature in Qt4.


This is done by the following code:

from PyQt4.QtCore import *
from PyQt4.QtGui import *

class DockDialog(QDockWidget):

 def __init__(self, dlg, area=Qt.RightDockWidgetArea):
     QDockWidget.__init__(self, dlg.windowTitle())
     self.setObjectName(dlg.objectName() or i18n(dlg.windowTitle()))
     self.resize(dlg.size())
     dlg.parent().addDockWidget(area, self)
     dlg.setParent(self)
     dlg.move(0, 0)
     self.setWidget(dlg)
     self.show()
     dlg.installEventFilter(self)

 def eventFilter(self, obj, event):
     return False
     if isinstance(event, QCloseEvent) or isinstance(event, QHideEvent):
         obj.hide()
         self.hide()
         return True
     elif isinstance(event, QShowEvent):
         self.show()
     return QDockWidget.eventFilter(self, obj, event)


dockables = ["Properties", "Outline", "Layers", "Arrange Pages",
          "Scrapbook", "Bookmarks", "Align and Distribute"]
docks = qApp.docks = {}

for tlw in qApp.topLevelWidgets():
 if isinstance(tlw, QDialog):
     title = str(tlw.windowTitle())
     if i18n(title) in dockables:
        docks[title] = DockDialog(tlw)

This is more a proof of concept and the code should not be used in production, of course. But you can see what is possible with a few lines. And it might be an inspiration how to improve the GUI of Scribus.

Sorry no updates right now

I am busy with doing stuff for University but I hope I will find some time the next days to complete the core. Therefore I have to add support for the new script descriptor files. More on that later in a separate post.

ScripterNG plug-in documentation

In progress documentation is now available at http://docs.google.com/Doc?id=ddggcjfj_205f5wsvf2

There is also a document about my previous evaluation at http://docs.google.com/Doc?id=ddggcjfj_16ccjdxrcp

ChangeLog, part 2

2008-06-19 22:55 henning

* src/scripterng_plugin/scripterngimpl.cpp: forgot to raise error
if openDocument fails

2008-06-19 22:55 henning

* src/scripterng_plugin/python/init_scripterng.py: make mikro.Error
class available as ScripterNG.Error

2008-06-19 22:06 henning

* src/scripterng_plugin/api_prefs.cpp,
src/scripterng_plugin/scripterng.cpp,
src/scripterng_plugin/scripterngimpl.cpp,
src/scripterng_plugin/scripterngimpl.h: added checkDocument,
haveDocument, closeDocument, openDocument and setModified

2008-06-19 21:52 henning

* src/scripterng_plugin/python/init_scripterng.py,
src/scripterng_plugin/python/sceditor/__init__.py,
src/scripterng_plugin/python/sceditor/mainwindow.py: menu and
mainwindow are now attributes of ScripterNG. EditorMainWindow is
now a child of ScribusMainWindow

2008-06-19 21:50 henning

* src/scripterng_plugin/python/mikro.py: added exception support.
Use RAISE from scripterimpl.h

2008-06-19 02:05 henning

* playground/ElementPath.py, playground/ElementTree.py,
playground/scxml.py: further work on xml support
(now needs newest version of elementtree)

2008-06-19 00:46 henning

* src/scripterng_plugin/python/sceditor/console.py,
src/scripterng_plugin/python/sceditor/highlighter.py,
src/scripterng_plugin/python/sceditor/widget.py: Ported source
editor from QTextEdit to QPlainTextEdit which is faster.
Disabled empty_format in highlighter.

2008-06-17 02:04 henning

* playground/full_issue_draft_1.sla, playground/scxml.py: Scirbus
XML file-format support module

2008-06-17 02:02 henning

* playground/compat.py: compat module stub

2008-06-16 23:05 henning

* src/scripterng_plugin/python/mikro.py: improved speed of child
object access

2008-06-16 01:43 henning

* src/scripterng_plugin/api_prefs.cpp,
src/scripterng_plugin/python/init_scripterng.py,
src/scripterng_plugin/scripterngimpl.cpp: ScripterNG(impl) is now
top-level object (from the scripting point of view),
changed parent for ApiPrefs.
Removed not working reload menu item and added a run script menu
item

2008-06-14 23:41 henning

* src/scripterng_plugin/python/excepthook.py,
src/scripterng_plugin/python/excepthook.ui,
src/scripterng_plugin/python/excepthook_ui.py,
src/scripterng_plugin/python/init_scripterng.py,
src/scripterng_plugin/scripterngimpl.cpp: Added a nice looking
error handler if a script raises an exception

2008-06-14 05:11 henning

* src/scripterng_plugin/CMakeLists.txt,
src/scripterng_plugin/python/sandbox.py,
src/scripterng_plugin/python/sceditor,
src/scripterng_plugin/python/sceditor/__init__.py,
src/scripterng_plugin/python/sceditor/assist.py,
src/scripterng_plugin/python/sceditor/console.py,
src/scripterng_plugin/python/sceditor/highlighter.py,
src/scripterng_plugin/python/sceditor/indenter.py,
src/scripterng_plugin/python/sceditor/mainwindow.py,
src/scripterng_plugin/python/sceditor/mainwindow.ui,
src/scripterng_plugin/python/sceditor/mainwindow_ui.py,
src/scripterng_plugin/python/sceditor/rope.zip,
src/scripterng_plugin/python/sceditor/widget.py: Removed sandbox.
Added a small editor/console for Python and (partly) QtScript

2008-06-14 05:08 henning

* src/scripterng_plugin/scripterngimpl.cpp: removed a warning

2008-06-14 05:08 henning

* src/scripterng_plugin/python/init_scripterng.py: cleaner init

2008-06-14 05:07 henning

* src/scripterng_plugin/python/mikro.py, tests/test_mikro.py:
Better introspection support for ScripterNG object (via
__members__)