# Guide för programmerare

## Hur &kugar; kan användas för att skapa rapporter i dina egna program

### Det finns flera olika sätt att använda &kugar;

- Skapa en tillfällig fil och fyll den med data, organiserad enligt KugarData dokumenttypdefinitionen. Anropa sedan `kugar`-skalkommandot

      kugar  -d Kugar datafil   -r Kugar mallfil

  för att förhandsgranska och skriva ut rapporten. Se avsnittet Använda &kugar;-skalet för att förhandsgranska rapporter för en detaljerad beskrivning.

- Använd &kugar; direkt i programmets kod. Se avsnittet Använda &kugar;-klasser för rapporter för en detaljerad beskrivning.

- Skapa en &Qt; Designer insticksmodul, använd den för att bygga programmets grafiska gränssnitt i Designer, och länka den dynamiskt till programmet. Se Skapa en &Qt; Designer insticksmodul för en detaljerad beskrivning.

De sista två sätten är användbara för &Qt;- och &kde;-utvecklare. Men &kugar; är konstruerad för att vara en rapportgenerator som är oberoende av programspråk och/eller integrerad utvecklingsmiljö. Den använder &XML;-formatet för att beskriva rapportmallar och datafiler. Så vilket program som helst kan skapa utdata på &kugar;s datafilformat som beskrivs i KugarData DTD, eller till och med på rapportmallformat (se KugarTemplate DTD). Ett &kugar;-skal (rapportvisare) kan användas för att förhandsgranska och skriva ut skapade rapporter.

## Använda &kugar;-skalet för att förhandsgranska rapporter

### Sättet att skapa och förhandsgranska (skriva ut) en rapport är:

1. Skapa en rapportmall med &kudesigner;

2. Skapa en datafil med kolumnvärden för detaljband i rapporten. Använd KugarData DTD för att skapa riktiga datafiler.

3. Kör &kugar;-skalet för att förhandsgranska och skriva ut rapporten. För att till exempel göra detta med språken C eller C++, anropa:

       system("kugar -r mall_fil.kut-d data_fil.kud").

   Glöm inte att inkludera `stdlib.h`.

## Använda &kugar;s klasser för rapporter

&kugar;-biblioteket innefattar två grafiska komponenter som kan användas.

Klassen `KReportViewer` är konstruerad för &kde;-utvecklare. Den stöder &kde;:s utskriftssystem och översättning under &UNIX; via `i18n()`-anrop.

Klassen `MReportViewer` är konstruerad för &Qt;-utvecklare och erbjuder riktigt plattformsoberoende. Den kan inte bara användas på &UNIX;-plattformar, utan också på &Windows; och &Mac;.

För att bygga ett program som använder Kugar-biblioteket, ska det länkas med det delade biblioteket `libkugar.so`, som tillhandahålls med Kugar-distributioner på alla &UNIX;-plattformar.

Deklarationsfiler är `kugarqt.h` och `kugar.h` för respektive &Qt;- och &kde;-program.

För ett detaljerat exempel på hur &kugar;-klasser kan användas, se katalogen `/shell` i &kugar;s källkod.

`MReportViewer` (och också `KReportViewer`) innehåller flera synliga metoder som kan användas.

    void renderReport

    Visar rapporten på skärmen.

    void printReport

    Anropar utskriftsdialogrutan för att skriva ut rapporten.

    void clearReport

    Rensar rapporten på skärmen och frigör rapportdata. Anropa detta innan en ny rapport öppnas.

    bool setReportData const QString &datafilnamn
    Hämtar rapportdata från filen datafilnamn.

    bool setReportData const QIODevice &data io-enhet
    Hämtar rapportdata från filen data io-enhet. I/O-enheten kan vara vilken klass som helst härledd från klassen QIODevice. För att till exempel direkt hämta poster från databasen, skapa en härledd klass från QIODevice och definiera om alla nödvändiga funktioner.

    bool setReportTemplate const QString &mallfilnamn
    Hämtar rapportmall från filen mallfilnamn.

    bool setReportTemplate const QIODevice &mall io-enhet
    Hämtar rapportmall från filen mall io-enhet. I/O-enheten kan vara vilken klass som helst härledd från klassen QIODevice. För att till exempel direkt hämta en rapportmall från nätverket eller en databas, skapa en härledd klass från QIODevice och definiera om alla nödvändiga funktioner.

## Skapa en &Qt; Designer insticksmodul

Det här är exempelkod på hur en insticksmodul till Designer skapas. Koden nedan skapar en insticksmodul för en &kde; `KReportViewer` grafisk komponent.

Om en &Qt; grafisk komponent önskas, ersätt `KReportViewer` med `MReportViewer` och `kugar.h` med `kugarqt.h` i insticksprogramkoden.

### Användning av insticksmodulen

Designer-insticksmodulen gör att &Qt; Designer kan användas för att placera den grafiska komponenten `KReportViewer` i ett fönster, och förhandsgranska den på ett riktigt sätt.

Program som använder den här insticksmodulen måste länkas dynamiskt med den. Motsvarande bibliotek heter `libkugar.so`. Grafiska komponenter eller dialogrutor som innehåller komponenten `KReportViewer` måste inkludera <kugar.h> i en implementering och innehålla deklarationen `class KReportViewer`. Det går att inkludera med hjälp av &Qt; Designers objektutforskare (källkodsfliken).

För att bygga insticksmodulen kör:

    qmake kugar_plugin.pro

    make

### Insticksmodulkod

#### Insticksmodulkoden består av tre filer:

kugar_plugin.h
kugar_plugin.cpp
kugar_plugin.pro
En deklarationsfil för `KugarWidgetPlugin`, `QWidgetPlugin` successor;
En källkodsfil för `KugarWidgetPlugin`, `QWidgetPlugin` successor;
Projektfil för QMake-verktyget.

#### 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++