Alexander Dymo

    cloudtemple@mksat.net

Phil Thompson

    phil@river-bank.demon.co.uk

Stefan Asserhäll

    stefan.asserhall@comhem.se

Översättare

# 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 skalkommandot `kugar` ( `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 en rapport. För att till exempel göra detta med språken C eller C++, anropa:

       system("kugar -r mall_fil.ktf-d data_fil.kdf").

   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 &MacOS;.

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, titta i 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, efterföljare till QWidgetPlugin. En källkodsfil för KugarWidgetPlugin, efterföljaren till QWidgetPlugin. En projektfil för verktyget 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++