scribus scripter api documentation documentation · scribus scripter api documentation...

Scribus Scripter API DocumentationDocumentation

Release version 1.5

Jain Basil Aliyas

Jun 21, 2017

Contents

1 Scripter2 API Specification 3

2 Tutorials 13

3 Python Scripts 15

4 Frequently Asked Questions 17

5 Indices and tables 19

i

Scribus Scripter API Documentation Documentation, Release version 1.5

Scribus is an Open Source program that brings professional page layout to Linux/UNIX, Mac OS X, OS/2 Warp4/eComStation and Windows desktops with a combination of press-ready output and new approaches to page design.Underneath a modern and user-friendly interface, Scribus supports professional publishing features, such as colorseparations, CMYK and Spot Color support, ICC color management, and versatile PDF creation.

Scripter2 is newly developed Scripting Engine for Scribus which enables experienced users to develop python scriptsto perform custom operations like generation of table of contents, barcode or more.

Contents 1


2 Contents

CHAPTER 1

Scripter2 API Specification

Scripter

class ScripterScripter serves as the entry point to Scripting Engine of Scribus. It provides necessary methods to create newdocument, open an existing document etc., as documented in this section.

Scripter Attributes

Scripter.activeDocumentInstance of active document.

Scripter.activeWindowInstance of active scribus window.

Scripter Methods

Scripter.openDocument(docName)Open an existing scribus document.

DocumentAPI

class DocumentAPIDocumentAPI provides properties and methods needed to interact with a Scribus document. An instance ofDocumentAPI may be obtained from Scripter, for eg.

document = Scripter.activeDocument

3


DocumentAPI Attributes

DocumentAPI.nameRead the name of current document.:

print document.name

This will be empty for a new document.

DocumentAPI.availableReturns True if the document is available, else False.:

>>> document = Scripter.activeDocument>>> document.availableTrue>>>

DocumentAPI.marginsReturn an object of type Margins

DocumentAPI.modifiedThis attribute is used to check whether the document is modified or not. It can also be used to set a document asmodified.:

>>> doc = Scripter.activeDocument>>> doc.modifiedFalse>>> doc.modified = True>>> doc.modifiedTrue>>>

DocumentAPI.activePage

DocumentAPI.pageCount

DocumentAPI.activeItem

DocumentAPI.dimensions

DocumentAPI.items

DocumentAPI.selection

DocumentAPI.selectionCount

DocumentAPI.colors

DocumentAPI.layers

DocumentAPI.masterPages

DocumentAPI.styles

DocumentAPI Methods

DocumentAPI.close()Closes a document. Returns True is successful, else return False.

4 Chapter 1. Scripter2 API Specification


>>> document = Scripter.activeDocument>>> document.close()True>>>

DocumentAPI.save()Saves the current document, and return True is successful. If the document is a new one (i.e., you are trying tosave it for the first time), calling this function will result in invocation of Save As dialog, where you can enterthe name for your document.

>>> document = Scripter.activeDocument>>> document.save()True>>>

DocumentAPI.saveAs(name)

DocumentAPI.setInformation(author, title, description)

DocumentAPI.newLayer(name)

DocumentAPI.removeLayer(name)

DocumentAPI.getActiveLayer()Make it property

DocumentAPI.setActiveLayer(name)Make it property

DocumentAPI.getActiveLayerName()Make it property

DocumentAPI.newColorCMYK(c, m, y, k)

DocumentAPI.newColorRGB(r, g, b)

DocumentAPI.getColor(name)Make it property

DocumentAPI.supportedImageTypes()

DocumentAPI.exportAsImages(directoryName, scale, quality, dpi, overwrite)

Margins

class MarginsMargins represents the margins of a document.

Margins Attributes

Margins.topThis attribute is used to read/write the top margin of the document.:

>>> document = Scripter.activeDocument>>> margins = document.margins>>> margins.top40.0>>> margins.top = 60

1.3. Margins 5


>>> margins.top60.0>>>

Margins.bottomThis attribute is used to read/write the bottom margin of the document.:

>>> document = Scripter.activeDocument>>> margins = document.margins>>> margins.bottom40.0>>> margins.bottom = 60>>> margins.bottom60.0>>>

Margins.rightThis attribute is used to read/write the right margin of the document.

>>> document = Scripter.activeDocument>>> margins = document.margins>>> margins.right40.0>>> margins.right = 60>>> margins.right60.0>>>

Margins.leftThis attribute is used to read/write the left margin of the document.

>>> document = Scripter.activeDocument>>> margins = document.margins>>> margins.left40.0>>> margins.left = 60>>> margins.left60.0>>>

Margins Methods

Margins.set(left, top, bottom, right)set() is used to set the margins of a document. All the parameters are of type float.

LayerAPI

class LayerAPILayerAPI represents a layer in Scribus document. The operations on a layer can be achieved through thisclass.



LayerAPI Attributes

LayerAPI.name

LayerAPI.id

LayerAPI.level

LayerAPI.printable

LayerAPI.viewable

LayerAPI.editable

LayerAPI.flowControl

LayerAPI.outlineMode

LayerAPI.transparency

LayerAPI.blendMode

LayerAPI.active

LayerAPI.items

ItemAPI

class ItemAPIItemAPI represents an item in Scribus document. TextAPI and ScribusImageItem are inherited fromthis class to provide more specific attributes and methods to it. All the attributes and methods of ItemAPI areapplicable to TextAPI and ImageAPI.

ItemAPI Attributes

ItemAPI.itemName

ItemAPI.fillColor

ItemAPI.lineColor

ItemAPI.fillShade

ItemAPI.lineShade

ItemAPI.fillTransparency

ItemAPI.lineTransparency

ItemAPI.locked

ItemAPI.sizeLocked

ItemAPI.flipVertical

ItemAPI.flipHorizontal

ItemAPI.lineWidth

ItemAPI.customLineStyle

ItemAPI.startArrowIndex

ItemAPI.endArrowIndex

1.5. ItemAPI 7


ItemAPI.printEnabled

ItemAPI.xPos

ItemAPI.yPos

ItemAPI.width

ItemAPI.height

ItemAPI.rotation

ItemAPI.reversed

ItemAPI.cornerRadius

ItemAPI.columnGap

ItemAPI.columns

ItemAPI Methods

ItemAPI.move(dx, dy)

ItemAPI.moveAbs(x, y)

ItemAPI.rotate(rotation)

ItemAPI.rotateAbs(rotation)

ItemAPI.resize(width, height)

TextAPI

class TextAPITextAPI inherits ItemAPI. It adds attributes and methods that are specific to Text Items in a Scribus docu-ment.

TextAPI Attributes

TextAPI.fontUsed to get/set the font of text frame.

>>> textItem.fontu'Arial Regular'>>> textItem.font = "Times New Roman Regular">>>

TextAPI.fontSizeUsed to get/set the font size of text frame.

>>> textItem.fontSize12.0>>> textItem.fontSize = 18.0>>>

TextAPI.textUsed to get/set the text in text frame.



>>> textItem.textu'This is a sample text'>>> textItem.text = "Sample text has been changed">>>

Note that using this function to set text content will erase the existing content in text frame.

TextAPI.textLinesUsed to get the number of lines in the content of text frame.

>>> textItem.textLines1>>>

TextAPI.textLengthUsed to get the length of text content in the frame.

>>> textItem.textLength28>>>

TextAPI.lineSpacingUsed to get/set the linespacing for text frame.

>>> textItem.lineSpacing15.0>>> textItem. lineSpacing = 16.0>>>

TextAPI.distancesUsed to get the text distances of the frame. It will return a list.

>>> textItem.distances[0.0, 0.0, 0.0, 0.0]>>>

TextAPI.deleteTextUsed to delete the text in a text frame.

>>> textItem.deleteText>>>

TextAPI.traceTextUsed to trace the text frame.

>>> textItem.traceTextTrue>>>

TextAPI.hyphenate

TextAPI.dehyphenate

TextAPI.PDFBookMark

1.6. TextAPI 9


TextAPI Methods

TextAPI.insertText(text, position)

TextAPI.setLineSpacing(mode)

TextAPI.setDistances(left, right, top, bottom)

TextAPI.setTextColor(color)

TextAPI.setTextStroke(color)

TextAPI.setTextScalingV(value)

TextAPI.setTextScalingH(value)

TextAPI.setTextShade(shade)

TextAPI.selectText(start, selectCount)

TextAPI.linkToTextFrame(name)

TextAPI.unLinkTextFrames()

ImageAPI

class ImageAPIImageAPI is used to access an Image Item in a Scribus document. It inherits the attributes and methods ofItemAPI, along with the following Attributes and Methods.

ImageAPI Attributes

ImageAPI.xScaleUsed to read/write the Image Scale along X Axis.

>>> print imageItem.xScale #reading the xScale1.0>>> imageItem.xScale = 0.5 #setting the value of xScale>>>

ImageAPI.yScaleUsed to read/write the Image Scale along Y Axis.

>>> print imageItem.yScale #reading the yScale1.0>>> imageItem.yScale = 2.0 #setting the value of yScale>>>

ImageAPI.xOffsetUsed to read/write the Image Offset along X Axis.

>>> print imageItem.xOffset #reading the xOffset0.0>>> imageItem.xOffset = 2.0 #setting the value of xOffset>>>

ImageAPI.yOffsetUsed to read/write the Image Offset along Y Axis.



>>> print imageItem.yOffset #reading the yOffset0.0>>> imageItem.yOffset = 2.0 #setting the value of yOffset>>>

ImageAPI Methods

ImageAPI.load(filename)Load an image into the Image Frame.

Parameters filename – name of the image file to be loaded into the image frame.

>>> imageItem.load("/Users/scribus/logo.jpg")>>>

ImageAPI.scale(x, y)Set the scaling of loaded image.

Parameters

• x – Set the scaling along X Axis.

• y – Set the scaling along Y Axis.

ImageAPI.offset(x, y)Set the offsets of loaded image.

Parameters

• x – Set the offset along X Axis.

• y – Set the offset along Y Axis.

ImageAPI.setBrightness(amount)Set the brightness of the loaded image.

>>> imageItem.setBrightness(100)>>>

ImageAPI.setGrayscale()Set the loaded image to Grayscale.

>>> imageItem.setGrayscale()>>>

ImageAPI.scaleToFrame(scale, proportional)Scale the loaded image to image frame.

Parameters

• scale – Set True for scaleToFrame.

• proportional – Set True for scaling proportionally.

>>> imageItem.scaleToFrame(True, True)>>>

1.7. ImageAPI 11

CHAPTER 2

Tutorials

13


14 Chapter 2. Tutorials

CHAPTER 3

Python Scripts

Add a menu to Scribus MenuBar

The following script will add a new menu to Scribus MainWindow menubar.:

# -*- coding: utf-8 -*-from __future__ import with_statementfrom PyQt4.QtGui import qApp, QMenu, QAction

def add_test():menuBar = Scripter.dialogs.mainWindow.qt.menuBar()item_action = Nonefor action in menuBar.actions():

if action.text() == "&View":item_action = action

menuBar.insertMenu(item_action, QMenu("&TTest", menuBar))

def run():add_test()

run()

15


16 Chapter 3. Python Scripts

CHAPTER 4

Frequently Asked Questions

How to submit scripts and tutorials to this documentation?

Scripter documentation is generated using Sphinx documentation system, and is maintained in Github Repository. Youmay fork this repository, add your submissions and commit it to your forked repository.

To submit to Scribus Scripter official documentation, you should submit a pull request to official git repository (repos-itory from which you forked). Moderators will evaluate your script/tutorial and add it to official documentation, ifvalid.

Repository Details

• Official Repository (Maintained by Jain Basil Aliyas) <http://github.com/jainbasil/scripter-doc>

17

http://github.com/jainbasil/scripter-doc


18 Chapter 4. Frequently Asked Questions

CHAPTER 5

Indices and tables

• genindex

• modindex

• search

19


20 Chapter 5. Indices and tables

Index

Aactive (LayerAPI attribute), 7activeDocument (Scripter attribute), 3activeItem (DocumentAPI attribute), 4activePage (DocumentAPI attribute), 4activeWindow (Scripter attribute), 3available (DocumentAPI attribute), 4

BblendMode (LayerAPI attribute), 7bottom (Margins attribute), 6

Cclose() (DocumentAPI method), 4colors (DocumentAPI attribute), 4columnGap (ItemAPI attribute), 8columns (ItemAPI attribute), 8cornerRadius (ItemAPI attribute), 8customLineStyle (ItemAPI attribute), 7

Ddehyphenate (TextAPI attribute), 9deleteText (TextAPI attribute), 9dimensions (DocumentAPI attribute), 4distances (TextAPI attribute), 9DocumentAPI (built-in class), 3

Eeditable (LayerAPI attribute), 7endArrowIndex (ItemAPI attribute), 7exportAsImages() (DocumentAPI method), 5

FfillColor (ItemAPI attribute), 7fillShade (ItemAPI attribute), 7fillTransparency (ItemAPI attribute), 7flipHorizontal (ItemAPI attribute), 7flipVertical (ItemAPI attribute), 7flowControl (LayerAPI attribute), 7

font (TextAPI attribute), 8fontSize (TextAPI attribute), 8

GgetActiveLayer() (DocumentAPI method), 5getActiveLayerName() (DocumentAPI method), 5getColor() (DocumentAPI method), 5

Hheight (ItemAPI attribute), 8hyphenate (TextAPI attribute), 9

Iid (LayerAPI attribute), 7ImageAPI (built-in class), 10insertText() (TextAPI method), 10ItemAPI (built-in class), 7itemName (ItemAPI attribute), 7items (DocumentAPI attribute), 4items (LayerAPI attribute), 7

LLayerAPI (built-in class), 6layers (DocumentAPI attribute), 4left (Margins attribute), 6level (LayerAPI attribute), 7lineColor (ItemAPI attribute), 7lineShade (ItemAPI attribute), 7lineSpacing (TextAPI attribute), 9lineTransparency (ItemAPI attribute), 7lineWidth (ItemAPI attribute), 7linkToTextFrame() (TextAPI method), 10load() (ImageAPI method), 11locked (ItemAPI attribute), 7

MMargins (built-in class), 5margins (DocumentAPI attribute), 4masterPages (DocumentAPI attribute), 4

21


modified (DocumentAPI attribute), 4move() (ItemAPI method), 8moveAbs() (ItemAPI method), 8

Nname (DocumentAPI attribute), 4name (LayerAPI attribute), 7newColorCMYK() (DocumentAPI method), 5newColorRGB() (DocumentAPI method), 5newLayer() (DocumentAPI method), 5

Ooffset() (ImageAPI method), 11openDocument() (Scripter method), 3outlineMode (LayerAPI attribute), 7

PpageCount (DocumentAPI attribute), 4PDFBookMark (TextAPI attribute), 9printable (LayerAPI attribute), 7printEnabled (ItemAPI attribute), 7

RremoveLayer() (DocumentAPI method), 5resize() (ItemAPI method), 8reversed (ItemAPI attribute), 8right (Margins attribute), 6rotate() (ItemAPI method), 8rotateAbs() (ItemAPI method), 8rotation (ItemAPI attribute), 8

Ssave() (DocumentAPI method), 5saveAs() (DocumentAPI method), 5scale() (ImageAPI method), 11scaleToFrame() (ImageAPI method), 11Scripter (built-in class), 3selection (DocumentAPI attribute), 4selectionCount (DocumentAPI attribute), 4selectText() (TextAPI method), 10set() (Margins method), 6setActiveLayer() (DocumentAPI method), 5setBrightness() (ImageAPI method), 11setDistances() (TextAPI method), 10setGrayscale() (ImageAPI method), 11setInformation() (DocumentAPI method), 5setLineSpacing() (TextAPI method), 10setTextColor() (TextAPI method), 10setTextScalingH() (TextAPI method), 10setTextScalingV() (TextAPI method), 10setTextShade() (TextAPI method), 10setTextStroke() (TextAPI method), 10sizeLocked (ItemAPI attribute), 7

startArrowIndex (ItemAPI attribute), 7styles (DocumentAPI attribute), 4supportedImageTypes() (DocumentAPI method), 5

Ttext (TextAPI attribute), 8TextAPI (built-in class), 8textLength (TextAPI attribute), 9textLines (TextAPI attribute), 9top (Margins attribute), 5traceText (TextAPI attribute), 9transparency (LayerAPI attribute), 7

UunLinkTextFrames() (TextAPI method), 10

Vviewable (LayerAPI attribute), 7

Wwidth (ItemAPI attribute), 8

XxOffset (ImageAPI attribute), 10xPos (ItemAPI attribute), 8xScale (ImageAPI attribute), 10

YyOffset (ImageAPI attribute), 10yPos (ItemAPI attribute), 8yScale (ImageAPI attribute), 10

22 Index

scribus scripter api documentation documentation · scribus scripter api documentation...

Documents