Alexander
Dymo

    cloudtemple@mksat.net

Phil
Thompson

    phil@river-bank.demon.co.uk

Federico
Zenith

    zenith@chemeng.ntnu.no

Traduzione della documentazione in italiano

# Guida del programmatore

## Come usare &kugar; per fare rapporti nei tuoi programmi

### Ci sono diversi modi di usare &kugar;

- Crea un file temporaneo e riempilo di dati, organizzati secondo la Definizione del tipo di dati KugarData. Quindi chiama il comando di shell `kugar` (

      kugar -d file KugarData -r file modello Kugar

  ) per fare un'anteprima e stampare il rapporto. Vedi Uso della shell &kugar; per fare anteprime dei rapporti per una descrizione dettagliata.

- Usa &kugar; direttamente nel codice dell'applicazione. Vedi Usare le classi di &kugar; per fare rapporti per una descrizione dettagliata.

- Crea un plugin di &Qt; Designer, usalo per costruire la &GUI; dell'applicazione nel Designer e collegalo dinamicamente al programma. Vedi Creare un plugin di &Qt; Designer per una descrizione dettagliata.

Gli ultimi due modi sono accettabili per gli sviluppatori di &Qt; e &kde;; ma &kugar; è progettato per essere un generatore di rapporti, indipendente da ogni linguaggio di programmazione ovvero IDE. Usa il formato &XML; per descrivere i modelli di rapporto e i file dati. Quindi ogni programma può produrre output nel formato file di &kugar; come descritto in DTD di KugarData o anche un formato file di modello di rapporto (vedi DTD di KugarTemplate). Una shell di &kugar; (visualizzatore di rapporti) può essere usata per fare anteprime e stampare il rapporto generato.

## Uso della shell &kugar; per fare anteprime dei rapporti

### Il modo di creare e fare un'anteprima (o stampare) un rapporto è:

1. Crea un file modello di rapporto con &kudesigner;

2. Crea un file dati con valori di colonna per le righe di dettaglio del rapporto. Usa la DTD KugarData per produrre file dati corretti.

3. Esegui la shell &kugar; per fare un'anteprima e stampare un rapporto. Per esempio, per farlo, nei linguaggi C o C++ chiama:

       system("kugar -r file_modello.ktf-d file_dati.kdf").

   Non dimenticarti di includere `stdlib.h`.

## Usare le classi di &kugar; per fare rapporti

La libreria di &kugar; include due oggetti utilizzabili.

La classe `KReportViewer` è progettata per gli sviluppatori di &kde;. Supporta un sistema di stampa &kde; e la localizzazione &UNIX; attraverso le chiamate a `i18n()`.

La classe `MReportViewer` è progettata per gli sviluppatori &Qt; e fornisce un autentico supporto multipiattaforma. Si può usare non solo su piattaforme &UNIX;, ma anche su &Windows; e &MacOS;.

Per costruire un programma che usi la libreria &kugar;, esso dovrebbe essere collegato alla libreria condivisa `libkugar.so`, che è fornita con la distribuzione di &kugar; su tutte le piattaforme &UNIX;.

I file da includere sono rispettivamente `kugarqt.h` e `kugar.h` per i programmi &Qt; e &kde;.

Per un esempio dettagliato di come si usano le classi di &kugar;, guarda nella cartella `/shell` nel sorgente di &kugar;.

`MReportViewer` (e anche il `KReportViewer`) contiene più metodi pubblici che possono essere usati.

    void renderReport

    Visualizza il rapporto su schermo.

    void printReport

    Chiama la finestra di dialogo di stampa per stampare il rapporto.

    void clearReport

    Pulisce il rapporto su schermo e libera i dati del rapporto. Chiamalo prima di aprire un nuovo rapporto.

    bool setReportData const QString &name_file_dati
    Imposta i dati del rapporto dal file nome_file_dati.

    bool setReportData const QIODevice &dispositivo_io_dati
    Imposta i dati di rapporto dal file dispositivo_io_dati. Il dispositivo IO può essere qualsiasi discendente della classe QIODevice. Per esempio, per prendere dati direttamente dalla banca dati, crea un discendente diQIODevice e ridefiniscine tutte le funzionalità necessarie.

    bool setReportTemplate const QString &nome_file_modello
    Imposta il modello di rapporto dal file nome_file_modello.

    bool setReportTemplate const QIODevice &dispositivo_io_modello
    Imposta il modello di rapporto dal file dispositivo_io_modello. Il dispositivo IO può essere qualsiasi discendente della classe QIODevice. Per esempio, per ottenere un modello di rapporto dalla rete o da una banca dati, crea un discendente diQIODevice e ridefiniscine tutte le funzionalità necessarie.

## Creare un plugin di &Qt; Designer

Questo è il codice esemplificativo di come si crea un plugin per Designer. Il codice sotto crea un plugin per l'oggetto `KReportViewer` di &kde;.

Se si desidera un oggetto &Qt;, sostituisci `KReportViewer` con `MReportViewer` e `kugar.h` con `kugarqt.h` nel codice del plugin.

### Uso del plugin

Il plugin di Designer permetterà l'uso di &Qt; Designer per posizionare un oggetto `KReportViewer` su una finestra e farne correttamente l'anteprima.

I programmi che usano questo plugin devono esserci collegati dinamicamente. La libreria corrispondente è chiamata `libkugar_plugin.so`. Gli oggetti o le finestre di dialogo che includono l'oggetto `KReportViewer` devono includere <kugar.h> nell'implementazione e avere una dichiarazione anticipata di `class KReportViewer`. Le inclusioni possono essere fatte con l'esploratore di oggetti di &Qt; Designer (scheda Sorgente).

Per costruire il plugin esegui:

    qmake kugar_plugin.pro

    make

### Codice del plugin

#### Il codice del plugin consiste di tre file:

kugar_plugin.h
kugar_plugin.cpp
kugar_plugin.pro
Un file d'intestazione per `KugarWidgetPlugin`, successore di `QWidgetPlugin`;
Un file sorgente per `KugarWidgetPlugin`, successore di `QWidgetPlugin`;
Un file di progetto per l'applicazione 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++