<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<title>Comment
écrire une extension pour Scribus
</title>
</head>
<body>
<h2>Comment
écrire une extension pour Scribus
</h2>
<h3>Pr
éface
</h3>
<p>La pr
ésente section vous montre comment
écrire une extension pour Scribus. Les extensions sont des librairies qui sont charg
ées dans
l'application principale au moment de l'ex
écution. Les extensions peuvent
étendre, voire modifier le comportement de l'application sans n
écessiter de r
éécriture ni de recompilation. Elles
permettent d'ajouter des outils suppl
émentaires, de nouvelles fonctions d'importation et d'exportation, et plusieurs autres fonctionnalit
és
évolu
ées.
</p>
<p>Ce document pr
ésuppose une connaissance de base du langage C++. Vous devez savoir ce qu'est un fichier d'en-t
ête
et comment fonctionne l'inclusion de fichier;aussi, vous devez poss
éder des connaissance sur l'h
éritage des classes et une certaine ma
îtrise du langage C++. La connaissance de Qt - principalement QString et QObject - sera
également utile. Des questions comme les fonctions virtuelles et purement virtuelles, les d
éclarations "extern C", les d
étails de la gestion de m
émoire, etc. sont
élud
ées dans ce document. Vous n'avez pas
à les conna
ître, mais elles pourraient vous aider
à mieux suivre ce qui ce passe.
</p>
<p>Nous n'allons pas tenter d'expliquer ici les d
étails du fonctionnement du syst
ème d'extensions de Scribus. Le pr
ésent document explique seulement comment
écrire une extension. La documentation des texte d'aide
<code>scplugin.h
</code> et
<code>pluginmanager.h
</code> explique le fonctionnement du syst
ème.
</p>
<h3>O
ù puis-je trouver les extensions Scribus ?
</h3>
<p>Scribus est livr
é avec un certain nombre d'extensions standard. Celles-ci seront install
ées en m
ême temps que le programme Scribus et ses autres fichiers. Sous UNIX, les extensions seront install
ées sous le m
ême pr
éfixe que l'application principale. Sous Mac OS X elles sont incluses avec l'application. Si vous voulez savoir ce que font ces extensions, le meilleur moyen de le d
écouvrir est de d
émarrer Scribus et d'aller dans
<code>Fichier-
>Pr
éf
érences
</code>
puis de cliquer sur l'ic
ône "extensions".
À partir de l
à, vous obtiendrez une liste des extensions install
ées, des types d'extensions associ
és et des emplacements des fichiers.
</p>
<p>En plus des extensions livr
ées en standard avec Scribus, il est possible de compiler et d'installer des extensions obtenues ailleurs, ou d'
écrire et d'ajouter la v
ôtre.
</p>
<h3>Avant de commencer
à coder
</h3>
<p>Supposons que vous avez eu une bonne id
ée pour am
éliorer Scribus et que vous
êtes impatient d'
écrire un code C++ de qualit
é.
<b>Patientez quelques minutes
</b> et lisez la pr
ésente section; vous pourriez gagner du temps et vous
éviter des probl
èmes.
</p>
<h4>Important
</h4>
<p>Peut-
être que vous
êtes sur le point de "r
éinventer la roue", c'est-
à-dire de r
é-
écrire ce que quelqu'un d'autre a d
éj
à fait. Vous devriez vous joindre
à la liste de diffusion et afficher votre id
ée, ou vous connecter au canal
<code>#scribus
</code> sur
<code>irc.freenode.net
</code>. Votre sujet sera soumis
à l'
étude, et vous obtiendrez probablement de l'aide et des id
ées des d
éveloppeurs et des utilisateurs. Comme Scribus est distribu
é sous licence libre, vous pouvez travailler en solitaire, mais vous devriez au moins avoir une conversation d'introduction sur IRC ou envoyer un courriel
à la liste de diffusion, ce qui pourrait vous
éviter des heures de travail et des maux de t
ête. Nous voulons faciliter l'
écriture d'extensions le plus possible pour les personnes int
éress
ées.
<h4>Compatibilit
é</h4>
<p>Scribus n'a pas une API fixe en C++ pour accommoder les extensions. Les versions ne sont pas compatibles en binaire, et les versions instables enfreignent souvent la compatibilit
é avec le code source.
La compatibilit
é source n'est pas garantie actuellement, m
ême entre des versions stables, lorsque des changements sont requis pour corriger un probl
ème. Nous esp
érons redresser la situation dans l'avenir et fournir une API C++ stable pour le code externe. Pour l'instant, vous devez tenter d'int
égrer l'essentiel de vos fonctionnalit
és dans un module s
épar
é qui d
épend le moins possible des rouages internes de Scribus.
</p>
<p>Ce document traite de la mise en oeuvre d'une extension pour Scribus 1.3.1cvs. Les exigences sont radicalement diff
érentes de celles des versions 1.2.x. Les changements futurs devraient
être moins importants.
</p>
<p>Il est peu pratique de pr
évoir l'
écriture d'une extension pouvant fonctionner sous les versions 1.2.x et 1.3.x de Scribus.
</p>
<h3>D
émarrage rapide
</h3>
<p>Il n'est pas trop difficile de se mettre
à écrire une extension. La documentation ci-dessous d
écrit l'implantation d'une extension et vous renvoie
à des compl
éments d'information au besoin. Un "mod
èle d'extension" vous est fourni, et vous pouvez en faire une copie au moment de d
ébuter la programmation. Des instructions de base sont incluses dans le fichier et, en cas doute, vous pouvez consulter ce document.
</p>
<p>Nous allons b
âtir l'extension comme un composant de Scribus. C'est la mani
ère la plus simple de commencer,
m
ême si vous pr
évoyez de la distribuer s
épar
ément plus tard (voir plus loin). Pour commencer
à travailler sur une extension (de type Action) :
</p>
<ul>
<li>Copiez
<code>scribus/plugins/myplugin
</code>
dans
<code>scribus/plugins/pluginname
</code>
(o
ù "pluginname" est le nom que vous voulez donner
à votre extension).
pluginname doit
être un identifiant C valide - je sugg
ère d'utiliser seulement les caract
ères minuscules.
</li>
<li>Éditez
<code>scribus/plugins/Makefile.am
</code> et ajoutez "pluginname"
à Makefile.am. Cela indique au syst
ème d'int
égration de Scribus de compiler votre extension.
</li>
<li>Renommez tous les fichiers dans
<code>scribus/plugins/pluginname/
</code>
de
<code>myplugin
</code> en
<code>pluginname
</code>, par exemple
<code>myplugin.h
</code> en
<code>pluginname.h
</code>.
<i>Ne renommez pas Makefile.am
</i>.
</li>
<li>Renommez
<code>myplugin
</code> l
à o
ù il figure dans les fichiers en
<code>pluginname
</code>, par exemple
<code>myplugin_getPluginAPIVersion()
</code>
en
<code>pluginname_getPluginAPIVersion()
</code>. Faites de m
ême pour
<code>MyPlugin
</code> et
<code>MYPLUGIN
</code>. Sous UNIX, vous pouvez utiliser cette commande :
<br/>
<code>sed -i -e "s/myplugin/pluginname/g" -e "s/MyPlugin/PluginName/g" -e "s/MYPLUGIN/PLUGINNAME/g" myplugin*
</code><br/>
(tout sur une ligne, ex
écut
é à partir de
<code>scribus/plugins/pluginname/
</code>).
</li>
</ul>
<p>Vous
êtes maintenant pr
êt
à commencer
à travailler sur votre extension. Premi
èrement, vous devez entrer des renseignements
à propos de votre extension dans
<code>pluginname.cpp
</code> :
</p>
<ul>
<li>Dans
<code>PluginName::languageChange()
</code> :
<ul>
<li>Changez
<code>m_actionInfo.text
</code> pour le texte de l'
él
ément de menu qui doit lancer votre extension.
</li>
<li>Changez
<code>m_actionInfo.menu
</code> pour le nom du menu qui doit afficher cet
él
ément. Voir
<b><i>FIXME where????
FIXME
</i></b> pour une liste de noms de menu.
</li>
<li>Pour activer un raccourci clavier, d
écommentez
<code>m_actionInfo.keySequence
</code> et inscrivez-y votre raccourci pr
éf
ér
é. L'exemple ci-dessousdevrait vous montrer comment cela fonctionne.
</li>
</ul>
</li>
<li>Changez le nom inscrit dans
<code>PluginName::fullTrName()
</code>
pour le nom de votre extension tel que vous voulez qu'il figure
à l'
écran Aide-
>À propos des extensions et dans le panneau de gestion des extensions (dans les pr
éf
érences).
</li>
<li>Si vous souhaitez afficher de l'information (p. ex. l'auteur et la description)
à l'utilisateur qui clique sur Aide-
>À propos des extensions, remplissez les zones pr
évues
à cet effet en assignant les membres de la section
<code>À propos
</code>. Pour conna
ître l'information possible, consultez la d
éfinition de
<code>AboutData
</code> dans
<code>scplugin.h
</code>.
</li>
</ul>
<p>Vous avez termin
é la mise en place de l'extension et vous pouvez maintenant commencer
à programmer. Votre code
doit
être plac
é dans
<code>pluginnameimpl.cpp
</code> et
<code>pluginnameimpl.h
</code>. Le code existant devrait afficher une bo
îte de dialogue contenant un message.
</p>
<p>Pour compiler l'extension, il suffit d'ex
écuter une nouvelle fois
<code>make -f Makefile.cvs
</code>,
<code>./configure
</code>, et
<code>make
</code> dans le r
épertoire sup
érieur de Scribus.
Une fois la compilation termin
ée, ex
écutez
<code>make install
</code> et d
émarrez Scribus.
Votre extension doit maintenant figurer dans le gestionnaire d'extensions (dans les pr
éf
érences) et doit
être associ
ée
à un
él
ément de menu. Si vous appuyez sur l'
él
ément de menu, vous devriez obtenir une bo
îte de dialogue.
</p>
<h3>B
âtir les extension en dehors de la hi
érarchie de Scribus
</h3>
<h4>Utilisation rapide et directe de QMake
</h4>
<b>Avertissement
</b>
<p>Attention, il est facile d'utiliser un projet qmake, mais il ne s'agit pas n
écessairement de la m
éthode standard pour distribuer un logiciel sur une plateforme Linux. Le processus sert
à titre d'exemple seulement, pour le d
éveloppement. Quand vous cr
éerez votre progiciel op
érationnel, sans bogues, prenez le temps de pr
éparer la distribution compl
ète automagic (autoconf, automake)
tel que d
écrit dans la prochaine section.
</p>
<p>Compilons maintenant l'extension (ce n'est pas aussi simple que de taper
<code>gcc
myplugin.cpp
</code> ;). Voici un proc
éd
é simple : qmake de Qt (parce que certaines personnes h
ésitent
à utiliser autoconf et automake en raison de leur complexit
é). Nota : vous devrez cr
éer un fichier vide
<code>config.h
</code> avant d'ex
écuter ces
étapes.
</p>
<blockquote><table width="100%" border="1" bgcolor="#eeeeee"><tr><td border="0">
<pre>
#qmake -project
</pre>
</td></tr></table></blockquote>
<p>Maintenant que le fichier projet est cr
éé, nous allons y apporter quelques petits changements.
</p>
<blockquote><table width="100%" border="1" bgcolor="#eeeeee"><tr><td border="0">
<pre>
######################################################################
# Automatically generated by qmake (1.06c) Sun Dec 14 13:32:11 2003
######################################################################
#change TEMPLATE = app. Nous ne travaillons pas sur l'application, seulement sur l'extension
TEMPLATE = lib
INCLUDEPATH += .
#Comme nous travaillons avec Scribus, nous avons besoin des inclusions de Scribus aussi.
INCLUDEPATH += /home/subzero/devel/Scribus/include/Scribus/
#Et Scribus doit utiliser freetype2.
#Donc nous devons le lier aussi. Utilisez les chemins retourn
és par
##freetype-config --cflags and --libs
INCLUDEPATH += /usr/include/freetype2
LIBS += -lfreetype -lz
# Entr
ée
#cr
ée un fichier config.h vide
HEADERS += myplugin.h config.h
SOURCES += myplugin.cpp
</pre>
</td></tr></table></blockquote>
<p>Apr
ès ces changements, vous
êtes pr
êt
à compiler
</p>
<blockquote><table width="100%" border="1" bgcolor="#eeeeee"><tr><td border="0">
<pre>
#qmake
#make
</pre>
</td></tr></table></blockquote>
<p>Ex
écuter Qmake cr
ée le Makefile et, en l'ex
écutant, vous compilez votre extension.
</p>
<p>Ensuite : Copiez seulement les fichiers *so* dans le r
épertoire d'extensions de Scribus et lancez Scribus.
Vous lirez "Do Nothing Plugin" dans le menu Extra.
</p>
<p>Il est clair que vous devez utiliser une autre m
éthode pour distribuer votre code aux autres utilisateurs - certains utilisent les fichiers autog
én
ér
és qmake pro, d'autres, la combinaison autoconf/automake.
</p>
<h4>Distribuez-le! (autrement dit compilez-le! 2e
édition)
</h4>
<p>Qmake est facile
à utiliser et convient bien
à un d
éveloppement rapide, mais il y a une mani
ère standard de compiler ou de distribuer un logiciel pour Linux, *BSD, etc. : autoconf et automake. Nous d
ésignerons ces deux programmes sous l'acronyme automagic dans le texte qui suit.
</p>
<p>Pour utiliser automagic avec succ
ès, vous aurez besoin d'un pentagramme dessin
é à la craie sur le sol et orient
é au nord (Carrefour, 2
€), d'un costume de diablotin rouge et noir (Hugo Boss, 2000
€) et d'un pingouin sacrifi
é sur l'autel domestique (une heure de frayeur au zoo le plus proche). Ce n'
était
qu'une blague... ne faites pas de mal aux mignons pingouins, ce n'est pas n
écessaire!!
</p>
<p>T
él
échargez l'exemple
<code>donothingplugin-1.0.tar.gz
</code> à partir de http://docs.scribus.net, d
écomprimez-le et parcourez son contenu.
</p>
<p>Quand vous acc
édez au r
épertoire principal, vous apercevez beaucoup de fichiers et de r
épertoires.
<b>Attention
</b> : Ne changez rien dans le r
épertoire admin.
Ce contenu vous est INTERDIT!
</p>
<p>Puisque vous avez lu la documentation d'automagic (s
ûrement), vous savez que chaque r
épertoire de votre projet contient un fichier important appel
é <code>Makefile.am
</code>. Voici un court exemple comment
é :
</p>
<blockquote><table width="100%" border="1" bgcolor="#eeeeee"><tr><td border="0">
<pre>
# indique o
ù l'extension sera install
ée
pluginsdir = $(prefix)/lib/scribus/plugins
# sp
écifie les inclusions additionnelles pour la compilation
AM_CPPFLAGS = -I$(prefix)/include/scribus
# sp
écifie les r
épertoires
à parcourir (avec les sous-niveaux)
SUBDIRS = translation doc
# nom de l'extension = librairie
plugins_LTLIBRARIES = libscribusvlna.la
# join toutes les inclusions
INCLUDES = $(LIBFREETYPE_CFLAGS) $(all_includes)
# divers relatifs
à la librairie - symlinks, etc.
libscribusvlna_la_LDFLAGS = -version-info 0:0:0
libscribusvlna_la_METASOURCES = AUTO
#
# liste des fichiers source de votre projet
libscribusvlna_la_SOURCES = frame.cpp selection.cpp vlnadialog.cpp vlnapage.cpp svlna.cpp
EXTRA_DIST = frame.cpp selection.cpp svlna.cpp vlnadialog.cpp vlnapage.cpp frame.h /
selection.h svlna.h vlnadialog.h vlnapage$
# comment compiler
KDE_OPTIONS = qtonly
AM_LDFLAGS = -s $(LIBFREETYPE_LIBS)
</pre>
</td></tr></table></blockquote>
<p>Pour r
écapituler : Si vous prenez le fichier
<code>donothingplugin-1.0.tar.gz
</code> (si vous le renommez, bien s
ûr) et si vous analysez le contenu des fichiers
<code>Makefile.am
</code>, vous obtiendrez un progiciel op
érationnel.
</p>
<p>Il reste une derni
ère chose
à faire. Vous devez aussi sp
écifier la structure de r
épertoire dans le fichier
<code>configure.in
</code> du r
épertoire racine du projet :
</p>
<blockquote><table width="100%" border="1" bgcolor="#eeeeee"><tr><td border="0">
<pre>
AC_CONFIG_FILES([Makefile])
AC_CONFIG_FILES([svlna/Makefile])
AC_CONFIG_FILES([svlna/translation/Makefile])
AC_CONFIG_FILES([svlna/doc/Makefile])
</pre>
</td></tr></table></blockquote>
<p>Et maintenant, comment
ça marche?
</p>
<p>Premi
èrement lancez
<code>make -f Makefile.dist
</code> dans le r
épertoire racine. Les mod
èles
de
<code>Makefile.in
</code> sont cr
éés (comme par magie).
</p>
<p>Ensuite,
<code>./configure ; make ; make install
</code>
devrait fonctionnner pour vous. Profitez-en.
</p>
<h3>Compl
ément d'information
</h3>
<p>À ce stade, vous devriez lire
<code>scplugin.h
</code> et comprendre le texte d'aide. Pour des pr
écisions sur le fonctionnement du syst
ème d'extensions
<a href="WHERE">ici
</a>. Surtout, vous apprendrez la proc
édure en lisant les autres extensions et le code central de Scribus.
</p>
<h4>Comment conserver les pr
éf
érences de votre extension :
</h4>
<p>Scribus fournit une API de pr
éf
érences pour les d
éveloppeurs d'extensions qui permet de conserver les donn
ées entre les d
émarrages de Scribus. Il y a deux types de formats disponibles : Paires "cl
é-valeur" et Tables.
</p>
<p>Tout d'abord, vous devrez obtenir l'objet
<code>PrefsContext
</code> pour votre extension. Ensuite, vous pouvez extraire de
<code>PrefsContext
</code> une valeur de cl
é sp
écifique ou vous pouvez solliciter
<code>PrefsTable
</code> par son nom. Voici un court exemple qui utilise les paires cl
é-valeur.
</p>
<pre>
#include
<prefsfile.h
>
#include
<prefscontext.h
>
extern PrefsFile* prefsFile;
PrefsContext *myPluginPrefs = prefsFile-
>getPluginContext("MyPlugin");
// la valeur par d
éfaut 1 sera utilis
ée si "i" n'existe pas d
éj
à
int i = myPluginPrefs-
>getInt("i");
// la valeur par d
éfaut "chien" sera utilis
ée si "s" n'existe pas
QString s = myPluginPrefs-
>get("s", "chien");
myPluginPrefs-
>set("i", 221);
myPluginPrefs-
>set("s", "chat");
</pre>
<h4>Mod
èle objet de Scribus
</h4>
<p>Le code source de Scribus n'est pas document
é en d
étail. Beaucoup d'efforts sont d
éploy
és pour corriger la situation, mais
étant donn
é la taille du code, cela prend du temps. Essayez de suivre l'
évolution en vous basant sur les fichiers d'en-t
ête et sur le code. En cas de doute, n'h
ésitez pas
à consulter le canal IRC ou
à poser des questions via la liste de diffusion, et vous obtiendrez probablement une r
éponse. Soyezpatient, car nous ne sommes pas toujours disponibles ou pr
ésents sur IRC.
</p>
<p>Si vous souhaitez am
éliorer la documentation ou corriger l'API de g
én
ération doxygen api, nous vous en saurons gr
é.
</p>
<p>Il est important de noter que l'acc
ès au coeur de l'application Scribus passe par l'aide du pointeur statique global
<code>ScApp
</code>, d
éclar
é dans
<code>scribus.h
</code>. Attention
à la confusion : c'est aussi une sous-classe de QMainWindow.
Vous pouvez
également aller
à la sous-classe QApplication utilis
ée comme
<code>ScQApp
</code> à partir de
<code>scribusapp.h
</code>.
</p>
<p>Certains sous-syst
èmes majeurs sont des classes uniques qui sont accessibles via ClassName::instance() . Il y a par exemple
<code>PluginManager
</code>,
<code>ScPaths
</code>, ainsi qu'un nombre croissant d'autres classes. L'avantage
de cette approche est de vous permettre d'interagir avec ces classes sans p
én
étrer dans les rouages de ScApp.
</p>
<h3>Liens associ
és aux extensions
</h3>
<a href="http://doc.trolltech.com/">Documentation de Qt par Trolltech
</a><br />
<a href="http://doc.trolltech.com/3.3/qmake-manual.html">Documentation de QMake par Trolltech
</a><br />
<a href="http://www.murrayc.com/learning/linux/automake/automake.shtml">Exemple automake/autoconf
</a><br />
</body>
</html>
o