Alexander
Dymo

    cloudtemple@mksat.net

Phil
Thompson

    phil@river-bank.demon.co.uk

&erik.kjaer.pedersen.role;

# Guide for programmører

## Hvordan &kugar; kan bruges til at lave rapporter i dine egne program

### Der er flere forskellige måder at bruge &kugar;

- Lav en midlertidig fil og fyld den med data, organiseret ifølge KugarData dokumenttypedefinitionen. Kald derefter `kugar`-skalkommandoen

      kugar  -d Kugar datafil   -r Kugar skabelonfil

  for at forhåndsvise og udskrive rapporten. Se Brug &kugar;-skallen til at forhåndsvise rapporter for en detaljeret beskrivelse.

- Brug &kugar; direkte i programmets kode. Se Brug af &kugar;-klasser til rapporter for en detaljeret beskrivelse.

- Lav et &Qt; Designer plugin, brug det til at bygge programmets grafiske grænseflade i Designer, og link det dynamisk til programmet. Se Lav et &Qt; Designer plugin for en detaljeret beskrivelse.

De sidste to måder er nyttige for &Qt;- og &kde;-udviklere. Men &kugar; er konstrueret til at være en rapportgenerator som er uafhængig af programsprog og/eller integreret udviklingsmiljø. Den bruger &XML;-formatet til at beskrive rapportskabeloner og datafiler. Så hvilket som helst program kan oprette uddata på &kugar;s datafilformat som beskrevet i KugarData DTD, eller til og med i rapportskabelonformat (se KugarTemplate DTD). En &kugar;-skal (rapportviser) kan bruges til at forhåndsvise og udskrive de genererede rapporter.

## Brug af &kugar;-skallen til at forhåndsvise rapporter

### Måden at oprette og forhåndsvise (udskrive) en rapport er:

1. Lav en rapportskabelon med &kudesigner;

2. Lav en datafil med søjleværdier for detaljebånd i rapporten. Brug KugarData DTD til at lave rigtige datafiler.

3. Kør &kugar;-skallen for at forhåndsvise og udskrive en rapport. For eksempel gør dette med sprogene C eller C++, kald:

       system("kugar -r template_file.ktf-d data_file.kdf").

   Glem ikke at inkludere `stdlib.h`.

## Brug &kugar;s klasser til rapporter

&kugar;-biblioteket inkluderer to grafiske kontroller som kan bruges.

Klassen `KReportViewer` er konstrueret for &kde;-udviklere. Den understøtter &kde;'s udskriftssystem og oversættelse under &UNIX; via `i18n()`-kald.

Klassen `MReportViewer` er konstrueret for &Qt;-udviklere og sørger for rigtig platformsuafhængighed. Den kan ikke kun bruges på &UNIX;-platforme, men også på &Windows; og &MacOS;.

For at bygge et program som bruger &kugar;-biblioteket, skal det linkes med det delte bibliotek `libkugar.so`, som kommer med &kugar;-distributioner på alle &UNIX;-platforme.

Deklarationsfiler er `kugarqt.h` og `kugar.h` for de respektive &Qt;- og &kde;-programmer.

For et detaljeret eksempel på hvordan &kugar;-klasser kan bruges, kig i mappen `/shell` i &kugar;s kildekode.

`MReportViewer` (og også `KReportViewer`) indeholder flere offentlige metoder som kan bruges.

    void renderReport

    Viser rapporten på skærmen.

    void printReport

    Kalder udskriftsdialogen for at udskrive rapporten.

    void clearReport

    Rydder rapporten på skærmen og frigør rapportdata. Kald dette inden en ny rapport åbnes.

    bool setReportData const QString &datafilnavn
    Henter rapportdata fra filen datafilnavn.

    bool setReportData const QIODevice &data io-enhed
    Henter rapportdata fra filen data io-enhed. I/O-enheden kan være hvilken som helst klasse afledt fra klassen QIODevice. For eksempel for direkte at hente poster fra databasen, opret en afledt klasse fra QIODevice og omdefinér alle nødvendige funktioner.

    bool setReportTemplate const QString &skabelonfilnavn
    Henter rapportskabelon fra filen skabelonfilnavn.

    bool setReportTemplate const QIODevice &skabelon_io_enhed
    Sætter rapportskabelon fra filen skabelon_io_enhed. I/O-enheden kan være en hvilken som helst klasse afledt fra klassen QIODevice. For eksempel for at hente en rapportskabelon direkte fra netværket eller en database, opret en afledt klasse fra QIODevice og omdefinér alle nødvendige funktioner.

## Lav et &Qt; Designer plugin

Dette er eksempelkode på hvordan et plugin til Designer laves. Koden nedenfor laver et plugin for en &kde; `KReportViewer` grafisk kontrol.

Hvis en &Qt; grafisk komponent ønskes, erstattes `KReportViewer` med `MReportViewer` og `kugar.h` med `kugarqt.h` i pluginkoden.

### Brug af plugin

Designer-plugin gør at &Qt; Designer kan bruges til at placere den grafiske kontrol `KReportViewer` i et vindue, og forhåndsvise den på en rigtig måde.

Programmer som bruger dette plugin skal linkes dynamisk med det. Tilsvarende biblioteker hedder `libkugar.so`. Grafiske kontroller eller dialoger som indeholder kontrollen `KReportViewer` skal inkludere <kugar.h> i en implementering og indeholde deklarationen `class KReportViewer`. Det går at inkludere ved hjælp af &Qt; Designers objektudforsker (kildekodefanebladet).

For at bygge pluginnet køres:

    qmake kugar_plugin.pro

    make

### Pluginkode

#### Pluginkoden består af tre filer:

kugar_plugin.h
kugar_plugin.cpp
kugar_plugin.pro
En deklarationsfil for `KugarWidgetPlugin`, efterfølgeren til `QWidgetPlugin`.
En kildekodefil for `KugarWidgetPlugin`, efterfølgeren til `QWidgetPlugin`.
Projektfil for værktøjet 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++