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.