Scribus Scripts: Difference between revisions

From Scribus
Jump to navigation Jump to search
No edit summary
 
(13 intermediate revisions by the same user not shown)
Line 2: Line 2:


You might start by reviewing the scripts which are included with your Scribus distribution. As of the 1.5.x versions of Scribus, you have the following included scripts, found and used by selecting from the menu, ''Scripter > Scribus Scripts''.
You might start by reviewing the scripts which are included with your Scribus distribution. As of the 1.5.x versions of Scribus, you have the following included scripts, found and used by selecting from the menu, ''Scripter > Scribus Scripts''.
* Align_image_in_frame
* [[Align_image_in_frame]]
* Autoquote
* [[Autoquote]]
* Autoquote2
* [[Autoquote2]]
* CalendarWizard
* CalendarWizard
* Caption
* [[Caption]]
* color2csv
* color2csv
* ColorChart
* ColorChart
Line 17: Line 17:
The titles of the scripts are terse, and may only give a vague sense of what they do. To learn more, select from the menu ''Scripter > About Script...'' Unfortunately, Scribus will not automatically find the location of these scripts. In Linux, the standard location for Scribus installed on the system you are using should be /usr/share/scribus/scripts. Let's look at the information which is included with the script '''Align_image_in_frame''':
The titles of the scripts are terse, and may only give a vague sense of what they do. To learn more, select from the menu ''Scripter > About Script...'' Unfortunately, Scribus will not automatically find the location of these scripts. In Linux, the standard location for Scribus installed on the system you are using should be /usr/share/scribus/scripts. Let's look at the information which is included with the script '''Align_image_in_frame''':


''This script will align an image inside a frame to one of 9 possible positions: Top left, top center, top right; middle left, middle center, middle right; or bottom left, bottom center, bottom right. USAGE Select one or more image frames. Run the script, which asks for your alignment choice (all selected frames will need to have the same alignment). Choose the position in the dialog radio button grid, click Align. Image(s) are aligned, and script quits. Note There is minimal error checking, in particular no checking for frame type.''
<nowiki>This script will align an image inside a frame to one of 9 possible positions: Top left, top center, top right; middle left, middle center, middle right;  
or bottom left, bottom center, bottom right.  
USAGE Select one or more image frames. Run the script, which asks for your alignment choice (all selected frames will need to have the same alignment).  
Choose the position in the dialog radio button grid, click Align. Image(s) are aligned, and script quits.  
Note There is minimal error checking, in particular no checking for frame type.</nowiki>


From this, we can see that the script positions an image inside a frame, and will do this for one or more image frames, which must be selected before the script is run. The USAGE section tells a bit more specifically how to run the script. If you're still not sure what this is saying, running the script (by selecting ''Scripter > Scribus Scripts > Align_image_in_frame''). As a precaution, you might save your document beforehand, although you should also be able to Undo what this script is accomplishing.
From this, we can see that the script positions an image inside a frame, and will do this for one or more image frames, which must be selected before the script is run. The USAGE section tells a bit more specifically how to run the script. If you're still not sure what this is saying, running the script (by selecting ''Scripter > Scribus Scripts > Align_image_in_frame''). As a precaution, try it out on some test document, or you might save your document beforehand, although you should also be able to Undo what this script is accomplishing.
 
Here is an abbreviated description of what the remaining scripts do:
* Autoquote -- this script, and the next one convert typewriter apostrophes and quotation marks to typographic quotes for a number of languages.
* Autoquote2 -- this script has some additional features.
* CalendarWizard -- automatically creates a multipage calendar for various languages and layouts.
* Caption -- places a caption over, under, or at the side of a selected frame.
* color2csv -- saves the colors of a document in a file listing color names and C, M, Y, K values in a comma-separated-values format.
* ColorChart -- creates a color chart document in Scribus using the colors from the current document.
* csv2color -- does the opposite from color2csv, creating the colors in Scribus using a CSV file.
* DirectImageImport -- a simplified image import, creating an image frame for you.
* FontSample -- creates a document showing a list of fonts used by Scribus with examples of appearance.
* Importcsv2table -- not to be confused with csv2color, this script creates a table in Scribus from a CSV file, the data being whatever the file contains.
* InfoBox -- allows for the insertion of a correctly-sized frame into a column of text.
* LigaturSatz -- documented in the script itself in a rather piecemeal fashion, this is a long and complex script dealing with hyphenation for German text.
==Writing your own Scripts==
If you have some experience with Python, you might simply begin writing your own scripts. At the same time, the power of these scripts comes from using the particular Python commands which are part of Scribus. These can be viewed in the online manual included with Scribus. More instructive, and more convenient would be to scan the Scribus wiki for various scripts which might be of some interest. If you're lucky, you may find some that fill your needs, but even then you may wish to customize them to your particular situation.
 
Most or all scripts begin with these lines or something similar:
 
<nowiki>
#!/usr/bin/env python
# -*- coding: utf-8  -*-
 
"""
© 2017 Gregory Pittman
caption.py
 
"""
try:
    import scribus
except ImportError:
    print ("Unable to import the 'scribus' module. This script will only run within")
    print ("the Python interpreter embedded in Scribus. Try Script->Execute Script.")
    sys.exit(1)</nowiki>
Technically, if you are only using your script in Scribus, you do not need the first line, yet it won't hurt. Next you indicate the character coding of your plain text file. Next will be a block of comments, which starts with 3 double quotes and ends with double quotes. Here is where you might put information on the script's name, its purpose and USAGE information. Even for scripts which will be used only be yourself, this can be helpful for a script you haven't used for months or years.
We must tell Python to incorporate Scribus Python commands when the script runs. The structure you see here, with the '''try''' and '''except ImportError''' commands covers the situation when you might by accident run the script outside of Scribus, where it will surely crash, and then remind you of this fact.  Here are some other sorts of error-checking:
 
<nowiki>
if not scribus.haveDoc():
    scribus.messageBox('Scribus - Script Error', "No document open", scribus.ICON_WARNING, scribus.BUTTON_OK)
    sys.exit(1)
 
if scribus.selectionCount() == 0:
    scribus.messageBox('Scribus - Script Error',
            "There is no object selected.\nPlease select a text frame and try again.",
            scribus.ICON_WARNING, scribus.BUTTON_OK)
    sys.exit(2)
if scribus.selectionCount() > 1:
    scribus.messageBox('Scribus - Script Error',
            "You have more than one object selected.\nPlease select one text frame and try again.",
            scribus.ICON_WARNING, scribus.BUTTON_OK)
    sys.exit(2)</nowiki>
This scripts expects to operate on a single selected object in an existing document. First, it checks to make sure there is a document, then if there are any objects selected, and finally that only one is selected. We might actually have in the second '''if''' clause '''if scribus.selectionCount() != 1:''' and then omitted the third '''if''' clause.
 
Something else to point out is that, when you use a command like '''import scribus''' at the beginning, you '''''must''''' use a prefix of '''scribus.''' to tell Python where to look for a command like '''have.Doc()'''. An alternative you may see in some scripts in the wiki, but I think less desirable would be to begin the script with '''from scribus import *''', in which case you can simply use '''have.Doc()''' (i.e., no prefix). What this is doing is pulling in all of Scribus's Python commands into the compiler when it's running, very inefficient when you consider that you may only use a dozen or so Scripter commands. Another mandatory usage of this prefix is when you use some predefined constant, for example '''ICON_WARNING''' in a '''messageBox()''' specification, or '''PAPER_A4''' when creating a '''newDoc()'''. Use '''scribus.ICON_WARNING''' and '''scribus.PAPER_A4''', respectively.
 
==Some Example Scripts==
[[Setting_Text_Distances_from_a_Script]]

Latest revision as of 23:15, 28 December 2019

Scripting in Scribus refers to the usage of a short program, written in Python in order to automate various tasks. This might be used to carry out a sequence of operations on one or more objects in your document, including creating those objects if necessary. Scripts can also be used to create a document from scratch, and thus would be an alternative to using a template to recreate some set layout, including creating and using the styles needed for the document.

You might start by reviewing the scripts which are included with your Scribus distribution. As of the 1.5.x versions of Scribus, you have the following included scripts, found and used by selecting from the menu, Scripter > Scribus Scripts.

The titles of the scripts are terse, and may only give a vague sense of what they do. To learn more, select from the menu Scripter > About Script... Unfortunately, Scribus will not automatically find the location of these scripts. In Linux, the standard location for Scribus installed on the system you are using should be /usr/share/scribus/scripts. Let's look at the information which is included with the script Align_image_in_frame:

This script will align an image inside a frame to one of 9 possible positions: Top left, top center, top right; middle left, middle center, middle right; 
or bottom left, bottom center, bottom right. 
USAGE Select one or more image frames. Run the script, which asks for your alignment choice (all selected frames will need to have the same alignment). 
Choose the position in the dialog radio button grid, click Align. Image(s) are aligned, and script quits. 
Note There is minimal error checking, in particular no checking for frame type.

From this, we can see that the script positions an image inside a frame, and will do this for one or more image frames, which must be selected before the script is run. The USAGE section tells a bit more specifically how to run the script. If you're still not sure what this is saying, running the script (by selecting Scripter > Scribus Scripts > Align_image_in_frame). As a precaution, try it out on some test document, or you might save your document beforehand, although you should also be able to Undo what this script is accomplishing.

Here is an abbreviated description of what the remaining scripts do:

  • Autoquote -- this script, and the next one convert typewriter apostrophes and quotation marks to typographic quotes for a number of languages.
  • Autoquote2 -- this script has some additional features.
  • CalendarWizard -- automatically creates a multipage calendar for various languages and layouts.
  • Caption -- places a caption over, under, or at the side of a selected frame.
  • color2csv -- saves the colors of a document in a file listing color names and C, M, Y, K values in a comma-separated-values format.
  • ColorChart -- creates a color chart document in Scribus using the colors from the current document.
  • csv2color -- does the opposite from color2csv, creating the colors in Scribus using a CSV file.
  • DirectImageImport -- a simplified image import, creating an image frame for you.
  • FontSample -- creates a document showing a list of fonts used by Scribus with examples of appearance.
  • Importcsv2table -- not to be confused with csv2color, this script creates a table in Scribus from a CSV file, the data being whatever the file contains.
  • InfoBox -- allows for the insertion of a correctly-sized frame into a column of text.
  • LigaturSatz -- documented in the script itself in a rather piecemeal fashion, this is a long and complex script dealing with hyphenation for German text.

Writing your own Scripts

If you have some experience with Python, you might simply begin writing your own scripts. At the same time, the power of these scripts comes from using the particular Python commands which are part of Scribus. These can be viewed in the online manual included with Scribus. More instructive, and more convenient would be to scan the Scribus wiki for various scripts which might be of some interest. If you're lucky, you may find some that fill your needs, but even then you may wish to customize them to your particular situation.

Most or all scripts begin with these lines or something similar:

#!/usr/bin/env python
# -*- coding: utf-8  -*-

"""
© 2017 Gregory Pittman
caption.py

"""
try:
    import scribus
except ImportError:
    print ("Unable to import the 'scribus' module. This script will only run within")
    print ("the Python interpreter embedded in Scribus. Try Script->Execute Script.")
    sys.exit(1)

Technically, if you are only using your script in Scribus, you do not need the first line, yet it won't hurt. Next you indicate the character coding of your plain text file. Next will be a block of comments, which starts with 3 double quotes and ends with double quotes. Here is where you might put information on the script's name, its purpose and USAGE information. Even for scripts which will be used only be yourself, this can be helpful for a script you haven't used for months or years. We must tell Python to incorporate Scribus Python commands when the script runs. The structure you see here, with the try and except ImportError commands covers the situation when you might by accident run the script outside of Scribus, where it will surely crash, and then remind you of this fact. Here are some other sorts of error-checking:

if not scribus.haveDoc():
    scribus.messageBox('Scribus - Script Error', "No document open", scribus.ICON_WARNING, scribus.BUTTON_OK)
    sys.exit(1)

if scribus.selectionCount() == 0:
    scribus.messageBox('Scribus - Script Error',
            "There is no object selected.\nPlease select a text frame and try again.",
            scribus.ICON_WARNING, scribus.BUTTON_OK)
    sys.exit(2)
if scribus.selectionCount() > 1:
    scribus.messageBox('Scribus - Script Error',
            "You have more than one object selected.\nPlease select one text frame and try again.",
            scribus.ICON_WARNING, scribus.BUTTON_OK)
    sys.exit(2)

This scripts expects to operate on a single selected object in an existing document. First, it checks to make sure there is a document, then if there are any objects selected, and finally that only one is selected. We might actually have in the second if clause if scribus.selectionCount() != 1: and then omitted the third if clause.

Something else to point out is that, when you use a command like import scribus at the beginning, you must use a prefix of scribus. to tell Python where to look for a command like have.Doc(). An alternative you may see in some scripts in the wiki, but I think less desirable would be to begin the script with from scribus import *, in which case you can simply use have.Doc() (i.e., no prefix). What this is doing is pulling in all of Scribus's Python commands into the compiler when it's running, very inefficient when you consider that you may only use a dozen or so Scripter commands. Another mandatory usage of this prefix is when you use some predefined constant, for example ICON_WARNING in a messageBox() specification, or PAPER_A4 when creating a newDoc(). Use scribus.ICON_WARNING and scribus.PAPER_A4, respectively.

Some Example Scripts

Setting_Text_Distances_from_a_Script