====== Mini Tutorial ======

Mit Scripten lässt sich Scribus fast beliebig erweitern, Sie könnten beispielsweise...

  * Einen speziell angepassten Kalender erzeugen
  * Aus einer Datenbank Daten holen und in ein Scribus-Dokument einfügen (beispielsweise einen Katalog aus einem Webshop heraus erzeugen)
  * Artikel eines Magazins mit einem Content Managment System (CMS) synchronisieren
  * Serienbriefe erzeugen
  * Formen zeichnen
  * uvm.

Scripte in Scribus werden in der Programmiersprache Python (Version 2) geschrieben und kommunizieren über das Modul ''scribus'' mit Scribus, sodass die Fähigkeiten und Vorteile von Python (Syntax, Dateizugriff, Datenbank-APIs usw.) in Kombination mit denen von Scribus genutzt werden können. Auf diesen Seiten wird lediglich diese Scripter-API erläutert und dokumentiert, allerdings nicht, wie man in Python programmiert – hierfür gibt es bereits eine Vielzahl von freien Tutorials im Web, sodass wir an dieser Stelle auf die Neuerfindung des Rades verzichten.

<note important>Es ist eine schlechte Idee, ein Script als ''scribus.py'' abzulegen, da der Interpreter beim nächsten Ausführen dann das als ''scribus.pyc'' kompilierte ''scribus.py'' als Modul ''scribus'' lädt anstatt das des Programms Scribus!</note>

Wenn sie ein Skript ausführen möchten, öffnen sie es in Scribus über den Menüpunkt //Script// -> //Script ausführen...//

===== Richtige Zeichenkodierung =====
<code python>
#!/usr/bin/env Python
# -*- coding: utf-8 -*-
</code>

Die erste Zeile legt fest, dass es sich um ein Python-Programm handelt und wird eigentlich nur benötigt, wenn man das Script stand-alone also außerhalb von Scribus ausführt und kann daher in Python-Scripten für Scribus weggelassen werden.

Als nächstes legen wir die richtige Zeichenkodierung fest. Da der Standard in Python ASCII ist, sollten wir direkt das bessere UTF-8 wählen, um keine Probleme mit ä, ö und ähnlichen nicht-ASCII-Zeihen zu bekommen.\\
Weitere mögliche Werte für die Codierung sind ''ascii'' und ''latin-1'', allerdings macht es durchaus Sinn, nur noch UTF-8 zu verwenden, da dies heutzutage Standard ist und man sich so am wenigsten Probleme mit der Kompatibilität einhandelt. Das Skript muss dann natürlich im Texteditor auch UTF-8-kodiert abgespeichert werden.

===== Einen Textrahmen anlegen =====
<file python textframe.py>
# -*- coding: utf-8 -*-
import scribus

# Wenn kein Dokument geöffnet ist, Dialog zum Erstellen eines neuen Dokuments anzeigen:
if scribus.haveDoc() == False:
  scribus.newDocDialog()

# Textrahmen erzeugen: (x-Position, y-Postition, Breite, Höhe)
name_des_rahmens = scribus.createText(30, 50, 80, 20)
# ... mit Text füllen ...
scribus.setText('Blabla', name_des_rahmens)
# ... Textfarbe festlegen ....
scribus.setTextColor('Red', name_des_rahmens)
# ... und zuletzt Größe festlegen
scribus.setFontSize(20, name_des_rahmens)

# alternativ Absatzstil festlegen (Stil muss natürlich angelegt sein!) -> zum Ausführen Komentarzeichen # entfernen!
#scribus.setStyle('BeispielStil', name_des_rahmens)
</file>

Dieses Skript fragt als erstes mit einer ''if''-Bedingung ab, ob bereits ein Dokument geöffnet ist und zeigt den Dialog zum Erstellen an, falls nicht. Anschließend legt es einen Textrahmen an, füllt ihn mit Text, legt eine Textfarbe und Schriftgröße fest. Als Alternative dazu können Sie Scribus auch einfach einen Absatzstil darauf anwenden lassen (dieser muss allerdings existieren!).

<note tip>In Scribus lassen sich derzeit nur Absatzstile mit dem Scripter anlegen.</note>

Noch ein paar Anmerkungen zu den **Maßeinheiten**:\\
Wenn Sie in Scripten [[scripter:dokument_befehle#unit_-typen|Längenangaben]] verwenden, werden diese immer in der Einheit des Dokuments interpretiert – erstellen Sie also ein Script und arbeiten immer mit Millimetern, funktioniert alles wie erwartet; wenn Sie das Script allerdings auf ein Dokument in der Maßeinheit Punkt anwenden, passen die Angaben allerdings nicht mehr. Die Lösung ist einfach: Am Anfang des Programms speichern sie die voreingestellte Maßeinheit in einer Variablen, setzen ihre Maßeinheit, führen Ihre Manipulationen am Dokument aus und setzen dann am Schluss die Maßeinheit wieder auf den vorherigen Wert zurück:
<code python>
# -*- coding: utf-8 -*-
import scribus

# Maßeinheit auslesen:
masseinheit = scribus.getUnit()
scribus.messageBox('Maßeinheit', 'Die aktuelle Maßeinheit ist '+str(masseinheit), scribus.ICON_INFORMATION)
# Ihre Maßeinheit setzen, z. B. Zentimeter:
scribus.setUnit(scribus.UNIT_CM)

# Manipulationen am Dokument mit Angaben in Zentimetern, wir zeigen einfach die aktuelle Maßeinheit an:
scribus.messageBox('Maßeinheit', 'Die aktuelle Maßeinheit ist '+str(scribus.getUnit()), scribus.ICON_INFORMATION)

# Wieder ursprüngliche Maßeinheit einsetzen:
scribus.setUnit(masseinheit)
scribus.messageBox('Maßeinheit', 'Die aktuelle Maßeinheit ist '+str(scribus.getUnit()), scribus.ICON_INFORMATION)
</code>
Nach jedem Schritt lassen wir uns die Maßeinheit anzeigen, wobei wir beobachten können, dass Scribus die [[scripter:dokument_befehle#unit_-typen|Einheiten als Zahlen zurückgibt]], beispielsweise steht 4 für Zentimeter.

===== Text an markiertes Textfeld anhängen =====
In diesem Beispiel wählen Sie //ein// Textfeld aus und führen dann ein Skript aus, das an den Text das aktuelle Datum und die Uhrzeit anfügt (deshalb auch ''insertText('Text', -1)'' (-1 für das Anhängen, sonst Positionsangabe im Text) statt ''setText'' wie im zweiten Beispiel, letzteres würde bereits vorhandenen Text ersetzen).
<file python insert-datetime.py>
# -*- coding: utf-8 -*-
import scribus
import datetime

anzahl = scribus.selectionCount()

if anzahl == 0:
  scribus.messageBox('Textrahmen auswählen', 'Es wurde kein Textrahmen ausgewählt, bitte wählen Sie einen aus und führen das Skript erneut aus!', scribus.ICON_INFORMATION)
if anzahl == 1:
  zeit = datetime.datetime.now()
  scribus.insertText('\n'+zeit.strftime("→ %Y-%m-%d %H:%M"), -1)
if anzahl > 1:
  scribus.messageBox('Textrahmen auswählen', 'Es wurden mehrere Objekte ('+str(anzahl)+') ausgewählt, bitte wählen Sie <b>einen Textrahmen</b> aus und führen das Skript erneut aus!', scribus.ICON_INFORMATION)
</file>

Indem wir mit einer ''while''-Schleife über alle ausgewählten Objekte iterieren, können wir das Ganze natürlich auch für mehrere ausgewählte Textrahmen durchführen und an alle das aktuelle Datum anhängen:
<file python insert-multiple.py>
# -*- coding: utf-8 -*-
import scribus
import datetime

anzahl = scribus.selectionCount()


if anzahl == 0:
  scribus.messageBox('Textrahmen auswählen', 'Es wurde kein Textrahmen ausgewählt, bitte wählen Sie welche aus und führen das Skript erneut aus!', scribus.ICON_INFORMATION)
if anzahl > 0:
  zeit = datetime.datetime.now()
  count = 0
  while count < anzahl:
   objekt = scribus.getSelectedObject(count)
   count = count + 1
   scribus.insertText('\n'+zeit.strftime("→ %Y-%m-%d %H:%M"), -1, objekt)
</file>

===== Mehrere Objekte bearbeiten =====
Indem man mit einer ''for''-Schleife über mehrere (ausgewählte) Objekte iteriert, lassen sich Operationen, die auf viele Objekte angewendet werden müssen, automatisieren. Im Beispiel wollen wir auf mehrere ausgewählte Textrahmen einen Absatzstil mittels [[scripter:objekte_erzeugen_und_bearbeiten#setstyle|setStyle]] anwenden, was über die Eigenschaften-Palette nicht möglich ist:
<file python setStyle.py>
# -*- coding: utf-8 -*-
import scribus

anzahl = scribus.selectionCount()

if anzahl >= 1:
  for i in xrange(0, anzahl):
    scribus.selectObject(scribus.getSelectedObject(i))
    scribus.setStyle("BeispielStil")
    #Namen anzeigen, falls benötigt...
    #scribus.messageBox("", str(i)+"=>"+scribus.getSelectedObject(i))
else:
  scribus.messageBox("Keine Objekte ausgewählt", "Es wurden keine Objekte ausgewählt, bitte wählen sie welche aus!", scribus.ICON_WARNING)
</file>

===== Erkennen, ob das Skript innerhalb von Scribus ausgeführt wird =====
<file python erkennung.py>
#!/usr/bin/env Python
# -*- coding: utf-8 -*-
import sys
try:
 import scribus
except ImportError:
  print "Dieses Skript ist ein Script für Scribus und kann nur innerhalb von Scribus ausgeführt werden."
  sys.exit(1)

# Das eigentliche Programm:
scribus.messageBox("Titel", "Hallo Welt!")
</file>
Dieses Skript beendet sich, wenn es nicht innerhalb von Scribus läuft. Alternativ kann man auch Skripte schreiben, die sowohl innerhalb von Scribus als auch von der Kommandozeile aus laufen.

===== Scribus-Version abfragen und auswerten =====
Einige Funktionen sind erst ab einer bestimmten Scribus-Version verfügbar, beispielsweise der [[seiten_befehle#applymasterpage|applyMasterPage()]]-Befehl. Um dem Nutzer eine verständliche Fehlermeldung an die Hand geben zu können, wenn man sich auf diese Funktionen verlässt, kann man die Scribus-Version abfragen und vergleichen:
<file python version-abfragen.py>
# -*- coding: utf-8 -*-
import sys, scribus

if scribus.scribus_version_info[:3] < (1,4,6):
    scribus.messageBox("Alte Scribus-Version",
        "Dieses Skript erfordert Scribus 1.4.6 oder höher. Sie verwenden allerdings noch <em>"+str(scribus.scribus_version)+"</em>.", scribus.ICON_CRITICAL)
    sys.exit()

# Das eigentliche Programm:
scribus.messageBox("Alles ist gut!", "Sie verwenden eine aktuelle Version von Scribus!")
</file>