Alexander
Dymo

    cloudtemple@mksat.net

Phil
Thompson

    phil@river-bank.demon.co.uk

&traducteurGerardDelafond;

# Guide du programmeur

## Comment utiliser &kugar; pour la génération de rapports dans vos propres programmes

### Il y a plusieurs manières d'utiliser &kugar;

- Créez un fichier temporaire et remplissez-le de données organisées selon le document de définition de type de KugarData. Puis, appelez la commande de shell `kugar` (

       kugar  -d fichier de données Kugar   -r fichier modèle Kugar

  ) pour visualiser et afficher le rapport. Voyez Utilisation du shell de &kugar; pour visualiser les rapports pour une description détaillée.

- Utilisez &kugar; directement dans le code de l'application. Voyez Utilisation des classes de &kugar; pour les rapports pour une description détaillée.

- Créez un module externe &Qt; designer, utilisez-le pour construire l'interface graphique de l'application dans le concepteur et liez-le au programme dynamiquement. Consultez Création d'un module externe &Qt; designer pour une description détaillée.

Les deux dernières manières sont acceptables pour les développeurs &Qt; et &kde;, mais &kugar; est conçu pour être un générateur de rapports indépendant d'un langage de programmation et / ou d'un IDE. Il utilise le format &XML; pour décrire les modèles de rapports et les fichiers de données. Ainsi, n'importe quel programme peut produire des données dans le format de fichier de &kugar; comme décrit dans la DTD KugarData ou même un format de fichier de modèle de rapports (voyez la DTD KugarTemplate). Un shell &kugar; (visualisateur de rapports) peut être utilisé pour visualiser et imprimer les rapports générés.

## Utilisation de &kugar; pour visualiser les rapports

### La manière de procéder pour créer et afficher (imprimer) un rapport est :

1. Créez un fichier de modèle de rapport avec &kudesigner;

2. Créez un fichier de données avec des valeurs en colonnes pour les bandes détaillées du rapport. Utilisez la DTD KugarData pour produire des fichiers corrects.

3. Lancez le shell &kugar; pour prévisualiser et imprimer le rapport. Par exemple, pour ce faire, pour les langages C ou C++, appelez :

       system("kugar -r fichier_modèle.ktf-d fichier_de_données.kdf").

   N'oubliez pas d'inclure `stdlib.h`.

## Utilisation des classes de &kugar; pour la génération de rapports

La bibliothèque &kugar; inclut deux composants à utiliser.

La classe `KReportViewer` est conçue pour les développeurs &kde;. Elle gère le système d'impression &kde; et la localisation &UNIX; via les appels `i18n()`.

La classe `MReportViewer` est conçue pour les développeurs &Qt; et permet vraiment de faire du multiplate-forme. Elle peut être utilisée non seulement sur les plates-formes &UNIX;, mais aussi sur &Windows; et &MacOS;.

Dans le but de compiler un programme qui utilise la bibliothèque &kugar;, il devrait être lié avec la bibliothèque partagée `libkugar.so`, qui est fournie avec la distribution de &kugar; sur toutes les plates-formes &UNIX;.

Les fichiers inclus sont `kugarqt.h` et `kugar.h` pour les programmes &Qt; et &kde; respectivement.

Pour un exemple détaillé sur le manière dont les classes &kugar; peuvent être utilisées, voyez le dossier `/shell` dans les sources de &kugar;.

`MReportViewer` (et `KReportViewer`) contiennent plusieurs méthodes publiques qui peuvent être utilisées.

    void renderReport

    Affiche le rapport sur un écran.

    void printReport

    Appelle le dialogue d'impression pour imprimer le rapport.

    void clearReport

    Efface le rapport de l'écran et libère les données du rapport. Appelez cela avant d'ouvrir le nouveau rapport.

    bool setReportData const QString &nom_du_fichier_de_données
    Détermine les données du rapport depuis le fichier nom_du_fichier_de_données.

    bool setReportData const QIODevice &data_io_device
    Détermine les données du rapport depuis le fichier data_io_device. Le périphérique d'entrées-sorties peut être un successeur d'une classe QIODevice. Par exemple, pour chercher des enregistrements directement depuis la base de données, créez un successeur QIODevice et redéfinissez toutes les fonctionnalités nécessaires.

    bool setReportTemplate const QString &nom_du_fichier_modèle
    Détermine le modèle de rapport depuis le fichier nom_du_fichier_modèle.

    bool setReportTemplate const QIODevice &template_io_device
    Détermine le modèle de rapport depuis le fichier template_io_device. Le périphérique d'entrées-sorties peut être un successeur d'une classe QIODevice. Par exemple, pour obtenir un modèle de rapport pour le stockage réseau ou les bases de données, créez un successeur QIODevice et redéfinissez toutes les fonctionnalités nécessaires.

## Création d'un module externe &Qt;

Voici un exemple de code sur la manière dont est conçu un module externe. Le code ci-dessous crée un module externe pour un composant &kde; `KReportViewer`.

Si un composant &Qt; est désiré, remplacez `KReportViewer` par `MReportViewer` et `kugar.h` par `kugarqt.h` dans le code du module externe.

### Utilisation du module externe

Le module externe de dessin permettra l'utilisation de &Qt; Designer pour placer le composant `KReportViewer` dans une fenêtre et l'afficher correctement.

Les programmes qui font usage de ce module externe doivent y être liés dynamiquement. La bibliothèque correspondante est nommée `libkugar_plugin.so`. Les composants ou dialogues qui incluent `KReportViewer` doivent inclure <kugar.h> dans l'implémentation et avoir une déclaration préalable de `class KReportViewer`. Les includes peuvent être faits avec l'Explorateur d'objets de &Qt; Designer (onglet source).

Pour compiler le module externe, lancez :

    qmake kugar_plugin.pro

    make

### Code du module externe

#### Le code du module externe consite en trois fichiers :

kugar_plugin.h
kugar_plugin.cpp
kugar_plugin.pro
Un fichier d'en-tête pour `KugarWidgetPlugin`, le successeur de `QWidgetPlugin` ;
Un fichier source pour `KugarWidgetPlugin`, le successeur de `QWidgetPlugin` ;
Un fichier de projet pour l'utilitaire QMake.

#### kugar_plugin.h

    #include <qwidgetplugin.h
    >>

    class KugarWidgetPlugin:public QWidgetPlugin
    {
    public:
      KugarWidgetPlugin ();

      QStringList keys () const;
      QWidget *create (const QString & classname, QWidget * parent =
                       0, const char *name = 0);
      QString group (const QString &) const;
      QIconSet iconSet (const QString &) const;
      QString includeFile (const QString &) const;
      QString toolTip (const QString &) const;
      QString whatsThis (const QString &) const;
      bool isContainer (const QString &) const;
    };

#### kugar_plugin.cpp

    #include "kugar_plugin.h"
    #include <kugar.h>

    static const char *kugar_pixmap[] = {
      "22 22 127 2",
      ".d c #000000",
      ".c c #131313",
      ".b c #282828",
      ".a c #434241",
      ".e c #4e463a",
      ".# c #595551",
      ".G c #66553b",
      "#F c #68635f",
      "#R c #6b4f23",
      "#q c #6e6862",
      "#M c #6f5229",
      ".n c #6f6146",
      ".w c #735310",
      ".V c #755c2a",
      ".I c #775f34",
      ".0 c #77694a",
      "#n c #7e6434",
      ".o c #806f50",
      "#C c #835d2d",
      ".P c #837c75",
      "#B c #85653a",
      "#k c #85827e",
      ".x c #866d46",
      ".U c #877967",
      ".X c #888888",
      ".F c #89724d",
      "#x c #8b6d2a",
      ".S c #8d7759",
      ".z c #8e733b",
      "#L c #906e49",
      "#Q c #947b56",
      ".r c #948058",
      ".J c #957844",
      ".4 c #987736",
      ".q c #998969",
      ".k c #999897",
      ".R c #9a8a75",
      "#i c #9f8348",
      "#I c #a37c4b",
      ".u c #a38d66",
      ".E c #a58558",
      "#A c #a8834b",
      ".s c #a9967a",
      ".t c #aa9467",
      ".C c #ae9f8d",
      "#6 c #afa49d",
      "#5 c #afa9a4",
      "#W c #b18e4d",
      ".K c #b1935a",
      ".B c #b39660",
      "#V c #b49866",
      "#a c #b49d6c",
      "## c #b49d72",
      ".j c #b5b4b4",
      "#0 c #b7a597",
      ".O c #b9b1a9",
      ".L c #bb9c61",
      ".M c #bb9e6b",
      ".A c #bca778",
      "#j c #bea46b",
      ".T c #bfb37d",
      ".v c #c0b391",
      ".W c #c3a262",
      ".i c #c4c4c4",
      "#m c #c5b7aa",
      "#8 c #c69f80",
      ".D c #c6b79b",
      "#3 c #c7a589",
      ".7 c #c7a76c",
      "#u c #c7bbaf",
      ".6 c #c8ad74",
      "#7 c #c8b7a9",
      "#r c #c8beb5",
      ".m c #c8c8c8",
      "#U c #cbad96",
      "#f c #ccb681",
      "#h c #cdac6c",
      "#P c #cdb49f",
      "#X c #cdb8a6",
      "#H c #ceb7a4",
      ".y c #ceb892",
      ".N c #cecac3",
      "#Z c #cfb16f",
      "#O c #cfbdad",
      ".Z c #cfc7c0",
      "#w c #d0bcab",
      ".5 c #d1ad6b",
      "#s c #d1bfb1",
      ".h c #d5d5d5",
      "#l c #d6cdc6",
      "#D c #d8b36e",
      ".H c #dac592",
      "#t c #dbb977",
      ".g c #dcdcdc",
      ".1 c #e0dcc1",
      ".f c #e0e0df",
      "#1 c #e3c8b1",
      "#S c #e4cdb9",
      ".3 c #e4d9a3",
      "#4 c #e6c1a1",
      "#2 c #e7c4a5",
      "#K c #e9c179",
      "#g c #e9c47e",
      "#Y c #e9c8ac",
      ".2 c #eae6c0",
      "#T c #ebcdb3",
      ".Q c #ebd4b9",
      "#E c #ecca87",
      "#z c #ecd799",
      ".l c #ececeb",
      "#G c #efd7c2",
      "#e c #efe3ab",
      ".8 c #efe8e3",
      "#v c #f1dcca",
      "#. c #f2e2d4",
      ".p c #f4f4f4",
      "#y c #f5daa0",
      "#J c #f6cf7f",
      ".9 c #f7ede4",
      "#p c #f9d995",
      ".Y c #fcf9f6",
      "#d c #fefcc5",
      "#c c #fefdda",
      "#b c #fefee1",
      "#N c #ffd685",
      "#o c #fff0a9",
      "Qt c #ffffff",
      "QtQtQtQtQtQt.#.a.a.a.b.b.b.c.c.d.d.dQtQtQtQt",
      "QtQtQtQtQtQt.e.f.g.g.f.g.g.h.i.j.d.k.dQtQtQt",
      "QtQtQtQtQtQt.a.gQtQtQtQtQtQt.l.f.c.m.k.dQtQt",
      "QtQtQtQtQt.n.n.n.n.n.o.g.pQtQt.l.bQt.m.k.dQt",
      "QtQtQt.q.q.r.q.s.t.r.q.u.u.g.pQt.a.fQt.m.k.d",
      "QtQt.s.s.v.w.x.y.y.t.z.A.t.B.i.p.#.a.b.c.d.d",
      "Qt.C.C.D.E.F.G.A.H.F.I.J.K.L.M.i.p.l.N.O.P.d",
      "Qt.s.v.Q.q.R.S.T.A.R.U.V.L.W.W.X.g.Y.f.Z.k.d",
      ".0.s.t.Q.1.U.R.2.3.S.U.4.5.6.6.7.j.8.9#..O.d",
      ".G##.V#a#b.1#c#c#d#e#f#g#h#i#j.W#k#l.9#.#m.d",
      ".G.4.F#n#c#c#c#d#d#o#p#g.x.w#i.L#q#r#.#.#s.d",
      ".e.J.J.I.3#d.H#j.6#f#p#t#n.w.E.L#q#u#.#v#w.d",
      ".G.A#x.z#y#z#A#B#B#C#D#E.4.4.6#h#F#m#v#G#H.d",
      ".o.s.A#j#E#t#I#I#I#C#A#J#p#p#K#t#F#m#v#G#H.d",
      "Qt##.A.6.7#I#I#A.E#L#M.W#N#J#K.a.U#O#G.Q#P.d",
      "Qt#a.M.L.J#A#I.4.E#Q.x#R#D#J#g.#.C#S.Q#T#U.d",
      "QtQt#V.K.z#Q.s.S.x.S#B#M#W#E.a.U#X.Q#T#Y#U.d",
      "QtQtQt.M#i#B.r#Q#Q.r#Q.z#Z.a#q#0#1#T#Y#2#3.d",
      "QtQtQtQtQt#j.L.L.W.5#t.a.#.U#0#1#T#Y#2#4#3.d",
      "QtQtQtQtQtQt.d#F#q#q#q.P.C#O#S.Q#T#Y#2#4#3.d",
      "QtQtQtQtQtQt.d#5#5#6#6#0#7#w#H#P#U#U#3#3#8.d",
      "QtQtQtQtQtQt.d.d.d.d.d.d.d.d.d.d.d.d.d.d.d.d"
    };

    KugarWidgetPlugin::KugarWidgetPlugin ()
    {
    }

    QStringList KugarWidgetPlugin::keys () const
    {
      QStringList list;
      list << "KReportViewer";
      return list;
    }

    QWidget* KugarWidgetPlugin::create (const QString & key, QWidget * parent,
                                        const char *name)
    {
      if (key == "KReportViewer")
        return new KReportViewer (parent, name);
      return 0;
    }

    QString KugarWidgetPlugin::group (const QString & feature) const
    {
      if (feature == "KReportViewer")
        return "Display";
      return QString::null;
    }

    QIconSet KugarWidgetPlugin::iconSet (const QString &) const
    {
      return QIconSet (QPixmap (kugar_pixmap));
    }

    QString KugarWidgetPlugin::includeFile (const QString & feature) const
    {
      if (feature == "KReportViewer")
        return "kugar.h";
      return QString::null;
    }

    QString KugarWidgetPlugin::toolTip (const QString & feature) const
    {
      if (feature == "KReportViewer")
        return "Kugar report viewer widget";
      return QString::null;
    }

    QString KugarWidgetPlugin::whatsThis (const QString & feature) const
    {
      if (feature == "KReportViewer")
        return "A widget to view xml reports";
      return QString::null;
    }

    bool KugarWidgetPlugin::isContainer (const QString &) const
    {
      return FALSE;
    }

    Q_EXPORT_PLUGIN( KugarWidgetPlugin )

#### kugar_plugin.pro

    SOURCES        += kugar_plugin.cpp
    HEADERS        += kugar_plugin.h

    DESTDIR = $(QTDIR)/plugins/designer
    TARGET  = kugar_plugin

    target.path=$$plugins.path
    isEmpty(target.path):target.path=$$QT_PREFIX/plugins
    PROJECTNAME = KugarPlugin
    TEMPLATE    = lib
    CONFIG           += qt warn_on release plugin
    unix:LIBS  += -lkugar
    LANGUAGE    = C++