From Scribus Documentation Project
Scripter is a plugin which allows for the use of the Python programming language to carry out a series of operations within Scribus. In general, one should consider using a script whenever there are a series of precise, repetitive tasks you want to do in Scribus, particularly when you will be doing this in a number of documents you create. Another advantage of the Scribus scripting engine – the Scripter – is that you can easily add a feature you are missing by using Python. Python is a powerful, yet easily learned programming language which is readily available for all operating systemsENDNOTE.
There are a number of scripts included with your Scribus distribution which you may find useful for a variety of tasks, but also as examples which you can modify for customized purposes, as well as helping to understand Python syntax and associated Scribus commands. In addition, there are many more to be found on the Scribus WikiENDNOTE.
The requirements for being able to use Scripter are as follows:
- Python development libraries if you are going to compile Scribus with Scripter enabled.
- Tk and Tkinter – not always needed, but many of the scripts shipped with Scribus require Tkinter for the creation of various dialogs.
- Some 3rd party scripts may also require PyQt.
There are some fundamental differences between scripts and other functions of Scribus. For instance, a script will perform the task it is written for and then finish. Scripts that use dialogs will close them once they're finished. You have to re-run the script to use it again. Also, scripts can't be translated like other elements of the Scribus user interface. If you want a version of a script in your language, you have to edit the source file yourself. It's also impossible to add tooltips to scripts. Finally, Scribus uses Tk/Tkinter for building a user interface by default. As you will see in the examples below, this user interface toolkit has a different "look and feel" than the rest of the Scribus interface.
There are three different ways to run a script within Scribus.
- The first is to go on the menu go to Scripts > Scribus Scripts, which will show you all of the scripts mentioned above. These "Scribus Scripts" have the default location in Linux of
- Under Scripts > Execute Script... you will be presented with a file dialog to find your desired script. Some additional scripts can be found in
/usr/share/scribus/samplesor wherever Scribus is installed, and if you make your own, you can of course save them wherever you like.
- Once you have used a script, it will be saved in a list under Scripts > Recent Scripts.
Simply select a script in the file dialog, click "OK", and it will be executed. Be aware that each script will have certain requirements, which, if not met, will generate a failure, hopefully with a helpful error message. For example, some scripts require a document to be open or a frame selected. In case of a failure, the error message will be copied to the clipboard automatically, so that you can copy it into an email program and send it to the author of the script.
The Python Console
The Python Console is a helper tool for small Python code bits. Use standalone scripts when you need to perform complex or repeating tasks. This console might show some unexpected behavior in some cases. You can use the 3rd party Extension Script (IDE)ENDNOTE from Henning Schröder in case you're facing some limitations or just when you like to have more functionality.
Since this is not a manual on Python programming, we'll cover just a few elements of console functions. As you see below, in the top of the Console window you enter one or more commands. If a command would result in output such as the
This simple console is really mainly useful for small parts of a Python program for troubleshooting. It may have trouble interpreting blank lines or indentations, so error messages can sometimes be hard to understand.
The Python Console Menus
- "Open..." opens a Python script in the console.
- "Save" saves the content of the console editor into a text file with the file extension *.py.
- "Save As..." saves the content of the console editor into a text file with the file extension *.py.
- "Exit" closes the console window.
- "Run" runs the whole editor text or a selection as one Python statement.
- "Run As Console" runs the statement and waits for next one then. It's the same as in the Python interactive console mode.
- "Save Output..." saves the current console output into a text file.
Open File > Preferences > Scripter menu from the Scribus main window.
You can change syntax highlighting colors for the console editor in this dialog. There is no need to change it in standard environments, but it's very useful when you are using dark desktop theme. You can set the console colors as you wish.
A programmer can use this feature to provide information about a script. If a user clicks on Script > About Script a file dialog appears, in which a Python script can be selected. After selecting a script and clicking "Save" the text will be displayed in the Help Browser.
Python scripts should contain the so-called Docstring. It's a general documentation about a program (script, module, etc.). Let's have a sample script
""" This is a hello world example. """ if __name__ == '__main__': print "Hello World!"
The Help Browser will now display the following text:
Documentation for: foo.py
This is a hello world example.
It is recommended that script authors add the following information to the docstring:
- Copyright and licensing informations
- A short description of what the script does
- Basic instructions on use
If the Python script doesn't contain any docstring, it will display the text "Script measurements.py doesn't contain any docstring!" and the content of the script is shown instead.
Extension Scripts, like the one mentioned above, can enhance the functionality of the Scripter. Since those scripts aren't controlled by the Scribus team, you need to permit their execution before you are able to use them for security reasons. Go to File > Preferences > Scripter and check "Enable Extension Script". Now you can load an Extension Script via Script > Execute Script.
If you want an Extension Script to be automatically started with Scribus, you can select one by clicking on the "Change..." button in this tab. You will be presented a file dialog, where you can choose the Extension Script. Note that you can only set a default Extension Script in the Preferences, not per document.