Comment écrire une extension "Importer un texte" pour Scribus

Interface d'extension et article écrits par Riku Leino

Préface

La présente section vous montre comment écrire une extension "Importer un texte" pour Scribus. Les extensions sont des librairies chargées dynamiquement au format "so". Les extensions "Importer un texte" servent à importer du texte dans un cadre de texte Scribus, quel qu'en soit le format.

Important

Attendez! Vous êtes peut-être sur le point de réinventer la roue - Joignez la liste de diffusion ou visitez le canal #scribus à irc.freenode.net. Votre sujet sera mis à l'étude, et vous obtiendrez également du soutien. Il ne s'agit pas de vous empêcher d'écrire quoi que ce soit, mais bien de vous aider.:)))

Un exemple d'extension

myimporter.h

#ifndef MYIMPORTER_H
#define MYIMPORTER_H

#include <scribus.h>
#include <gtwriter.h>

extern "C" void GetText(QString nomFichier, QString encodage, bool texteSeul, gtWriter *ecriveur);

extern "C" QString FileFormatName();

extern "C" QStringList FileExtensions();

#endif // MYIMPORTER_H

Décrivons maintenant le code source. La déclaration MYIMPORTER_H est le moyen standard de s'assurer qu'une seule insertion du fichier d'en-tête a eu lieu. Scribus.h est requis pour accéder aux objets Scribus. La fonction GetText() est appelée lorsqu'un utilisateur décide d'importer un fichier qui possède une extension associée à l'un des éléments deQStringList retourné par FileExtensions(). FileFormatName() doit retourner le nom du format de fichier traité par ce module d'importation, par exemple "Fichier texte" dans le cas d'un format "texte seulement".

Paramètre de GetText

nomFichier : Chemin vers le fichier que l'utilisateur veut importer
encodage : Encodage des caractères sélectionnés par l'utilisateur dans le dialogue de fichiers
texteSeul : La valeur True signifie qu'un utilisateur veut importer du texte à partir d'un fichier sans aucun formatage
ecriveur : L'objet gtWriter sollicité pour importer le texte

Extensions de fichier

Si votre extension est la seule qui existe pour le format de fichier visé, le module retourne un QStringList avec les extensions du format de fichier. S'il existe déjà un importateur pour le format visé, le module ne retourne pas d'extensions de fichier, mais un QStringList vide. L'extension la plus courante et la plus utilisée pour un format de fichier donné doit retourner les extensions. Les cas plus rares ne doivent pas retourner d'extension. Vous pouvez utiliser les extensions en les choisissant dans le dialogue de fichier de "Importer un texte".

myimporter.cpp

#include "myimporter.h"
#include <qstring.h>
#include <qstringlist.h>

QString FileFormatName()
{
    return QObject::tr("Rien à importer");
}

QStringList FileExtensions()
{
    // QStringList list("htm"); list << "html" << "php"; return list;
    return QStringList();
}

void GetText(QString filename, QString encoding, bool textOnly, gtWriter *writer)
{

}

importnothingplugin-1.0.tar.bz2 de http://docs.scribus.net peut être utilisé comme base pour votre extension personnalisée "Importer un texte".

Comment cela fonctionne?

Le texte peut être ajouté à la fin d'un cadre de texte avec les méthodes gtWriter::append(). append(QString text) ajoute le texte formaté avec le style du cadre de texte. append(QString text, gtStyle *style) utilisera le style donné en paramètre.

gtStyle, gtParagraphStyle et gtFrameStyle peuvent être utilisés pour définir le style du texte importé. La manière la plus simple de débuter est d'utiliser la méthode getDefaultStyle() de gtWriter pour obtenir le style courant du cadre de texte, puis d'utiliser le gtFrameStyle retourné pour créer de nouveaux styles.

gtStyle agit sur les styles de caractères et peut être utilisé à l'intérieur d'un style de paragraphe. gtParagraphStyle crée un style de paragraphe dans Scribus et peut être utilisé pour appliquer un style de paragraphe au texte lors de l'importation. gtFrameStyle offre la possibilité de changer le style par défaut du cadre de texte. La relation entre ces trois classes est la suivante : gtStyle agit comme classe de base. gtParagraphStyle étend gtStyle et gtFrameStyle étend gtParagraphStyle. Elles possèdent toutes un objet gtFont qui peut être obtenu avec la méthode getFont(). Vous pouvez utiliser l'objet gtFont pour définir certains formatages de polices de caractères. Examinez les fichiers d'en-tête gtfont.h, gtstyle.h, gtparagraphstyle.h et gtframestyle.h pour vous faire une meilleure idée des interfaces.

Il existe aussi une classe d'appoint gtMeasure avec des méthodes statiques qui permet de convertir les unités de longueur en points, c'est-à-dire l'unité par défaut de Scribus. Par exemple, pour convertir 25 millimètres en points, il est possible d'utiliser la méthode de gtMeasure soit i2d() (int to double): gtMeasure::i2d(25, MM). Le second paramètre indique l'unité à partir de laquelle la conversion en points est effectuée. Toutes les unités possibles sont définies sous la forme "enumeration Unit" (voir le fichier gtmeasure.h).

Exemple simple

Texte à importer

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut a sapien. Aliquam aliquet purus molestie dolor. Integer quis eros ut erat posuere dictum. Curabitur dignissim. Integer orci. Fusce vulputate lacus at ipsum. Quisque in libero nec mi laoreet volutpat.
Aliquam eros pede, scelerisque quis, tristique cursus, placerat convallis, velit. Nam condimentum. Nulla ut mauris. Curabitur adipiscing, mauris non dictum aliquam, arcu risus dapibus diam, nec sollicitudin quam erat quis ligula. Aenean massa nulla, volutpat eu, accumsan et, fringilla eget, odio. Nulla placerat porta justo. Nulla vitae turpis. Praesent lacus.

Code pour l'importation

#include <gtparagraphstyle.h>
#include <gtframestyle.h>
#include <gtmeasure.h>

...

void GetText(QString nomFichier, QString encodage, bool texteSeul, gtWriter *ecriveur)
{

/***** Crée les styles de paragraphe *************************************************/
    gtFrameStyle* fstyle = writer->getDefaultStyle();
    
    gtParagraphStyle* firstPara = new gtParagraphStyle(*fstyle);
    firstPara->setName("Premier paragraphe");
    firstPara->getFont()->setSize(12.0);
    firstPara->setLineSpacing(14.4);
    
    gtParagraphStyle* trailingPara = new gtParagraphStyle(*firstPara);
    trailingPara->setName("Dernier paragraphe");
    trailingPara->setFirstLineIndent(gtMeasure::i2d(15, MM));
    
/***** Importer le texte *************************************************************/
    writer->append("Lorem ipsum dolor sit amet, consectetuer adipiscing elit. ", firstPara);
    
    QString currentWeight = firstPara->getFont()->getWeight();
    firstPara->getFont()->setWeight(BOLD); // de l'enum FontWeight (gtfont.h)
    writer->append("Ut a sapien.", firstPara); // importer avec une police en gras
    
    firstPara->getFont()->setWeight(currentWeight);
    writer->append(" Aliquam aliquet purus molestie dolor. Integer quis eros ut "
                   "erat posuere dictum. Curabitur dignissim. Integer orci. Fusce "
                   "vulputate lacus at ipsum. Quisque in libero nec mi laoreet "
                   "volutpat.\n", firstPara);
    
    // 2ème paragraphe
    writer->append("Aliquam eros pede, scelerisque quis, tristique cursus, placerat "
                   "convallis, velit. Nam condimentum. Nulla ut mauris. Curabitur "
                   "adipiscing, mauris non dictum aliquam, arcu risus dapibus diam, nec "
                   "sollicitudin quam erat quis ligula. Aenean massa nulla, "
                   "volutpat eu, accumsan et, fringilla eget, odio. Nulla placerat porta "
                   "justo. Nulla vitae turpis. Praesent lacus.", trailingPara);

    delete firstPara;
    delete trailingPara;
}

...

Maintenant, en cliquant avec le bouton droit sur un cadre de texte, choisissez "Importer un texte..." et sélectionnez le module que vous venez de créer pour ouvrir un fichier; le cadre contient maintenant le texte échantillon, formaté correctement.

Si vous avez des questions, envoyez un courriel à Riku Leino (IRC nick:Tsoots) tsoots à gmail.com, inscrivez-vous à la liste de diffusion de Scribus ou joignez-vous au canal irc #scribus à irc.freenode.net.