Alexander
Dymo

    cloudtemple@mksat.net

Phil
Thompson

    phil@river-bank.demon.co.uk

Natalie
Koning

     nat@switch.demon.nl

Vertaler

# Gids voor programmeurs

## &kugar; in uw eigen programma's gebruiken

### Er zijn verschillende manieren om &kugar; te gebruiken

- Creëer een tijdelijk bestand met gegevens die volgens de KugarData Document Type Definition georganiseerd zijn. Voer dan het `kugar`-shell-commando uit (

       kugar  -d Kugar-gegevensbestand   -r Kugar-sjabloonbestand

  ) om een voorbeeld van het rapport te zien en het af te drukken. U kunt een gedetailleerde beschrijving vinden in het gedeelte &kugar;-shell gebruiken om rapporten te bekijken.

- Gebruik &kugar; direct in de code van de toepassing. U kunt een gedetailleerde beschrijving vinden in het gedeelte &kugar;-classes gebruiken voor het rapporteren.

- Creëer een &Qt;-designer-plugin, gebruik de plugin om de &GUI; van de toepassing in de designer te bouwen en link deze dynamisch aan het programma. U kunt een gedetailleerde beschrijving vinden in het gedeelte Een &Qt;-designer-plugin creëren.

De twee laatstgenoemde methoden zijn vooral voor &Qt;- en &kde;-ontwikkelaars; &kugar; is echter ontworpen als rapportengenerator die onafhankelijk is van een programmeertaal en/of IDE. Er wordt gebruik gemaakt van &XML;-opmaak om rapportsjablonen en gegevensbestanden te beschrijven. Andere programma's kunnen ook uitvoer produceren in de opmaak van een &kugar;-gegevensbestand (zoals beschreven is in KugarData DTD) of in de opmaak van een rapportsjabloon (zie KugarTemplate DTD). Een &kugar;-shell kan gebruikt worden om het gegenereerde rapport te bekijken en af te drukken.

## &kugar;-shell gebruiken om rapporten te bekijken

### De methode om een rapport te creëren, te bekijken en af te drukken:

1. Creëer een rapportsjabloon met behulp van &kudesigner;

2. Creëer een gegevensbestand met kolomwaarden voor de detailgroepen van het rapport. Gebruik KugarData DTD om correcte gegevensbestanden te produceren.

3. Voer &kugar;-shell uit om het rapport te bekijken en af te drukken. Om dit in bijvoorbeeld C of C++ te doen:

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

   Vergeet niet om `stdlib.h` te "include"-en.

## &kugar;-classes gebruiken voor het rapporteren

In de &kugar;-library zijn twee widgets inbegrepen.

De `KReportViewer`-class is ontworpen voor &kde;-ontwikkelaars. Deze ondersteunt een &kde;-afdruksysteem en &UNIX;-lokalisatie via `i18n()`-calls.

De `MReportViewer`-class is ontworpen voor &Qt;-ontwikkelaars en is geschikt voor meerdere platforms. Deze kan zowel op &UNIX;-platforms als op &Windows; en &MacOS; gebruikt worden.

Om een programma te maken dat de &kugar;-library gebruikt, moet het gelinkt worden met de shared library `libkugar.so`, die inbegrepen is in de &kugar;-distributie voor alle &UNIX;-platforms.

Include-bestanden zijn `kugarqt.h` en `kugar.h`, respectievelijk voor &Qt;-en &kde;-programma's.

Een gedetailleerd voorbeeld van het gebruik van &kugar;-classes kunt u vinden in de map `/shell` in de &kugar;-broncode.

`MReportViewer` (evenals `KReportViewer`) bevat verscheidene public methoden die gebruikt kunnen worden.

    void renderReport

    Rendert het rapport op een scherm.

    void printReport

    Opent het dialoogvenster om het rapport af te drukken.

    void clearReport

    Maakt het scherm schoon en geeft de rapportgegevens vrij. Gebruik deze functie vóór u een nieuw rapport opent.

    bool setReportData const QString &data_file_name
    Gebruik het bestand data_file_name als bron voor rapportgegevens.

    bool setReportData const QIODevice &data_io_device
    Gebruik het bestand data_io_device als bron voor rapportgegevens. IO-device kan elke successor van de QIODevice-class zijn. Om bijvoorbeeld records direct uit een database te halen creëert u een QIODevice-successor en herdefinieert u de benodigde functionaliteit.

    bool setReportTemplate const QString &template_file_name
    Gebruik het bestand template_file_name als bron voor de rapportsjabloon.

    bool setReportTemplate const QIODevice &template_io_device
    Gebruik het bestand template_io_device als bron voor de rapportsjabloon. IO-device kan elke successor van de QIODevice-class zijn. Om bijvoorbeeld een rapportsjabloon vanaf een netwerk of uit een database te halen creëert u een QIODevice-successor en herdefinieert u de benodigde functionaliteit.

## Een &Qt;-designer-plugin creëren

Dit is de voorbeeldcode voor een designer-plugin. De onderstaande code is voor een plugin voor een `KReportViewer`-widget voor &kde;.

Om een &Qt;-widget te maken moet u `KReportViewer` in de code vervangen door `MReportViewer` en `kugar.h` door `kugarqt.h`.

### De plugin gebruiken

De designer-plugin maakt het mogelijk om de &Qt;-Designer te gebruiken om een `KReportViewer`-widget in een venster te plaatsen en correct weer te geven.

Programma's die deze plugin gebruiken, moeten er dynamisch mee gelinkt worden. De overeenkomstige library is `libkugar_plugin.so`. Widgets of dialoogvensters met de `KReportViewer`-widget moeten bij de implementatie <kugar.h> includen en een declaration `class KReportViewer` hebben. Includes kunnen met behulp van de Object Explorer van &Qt;-Designer (Source tab) gemaakt worden.

Om de plugin te maken:

    qmake kugar_plugin.pro

    make

### De plugin-code

#### De plugin-code bestaat uit drie bestanden:

kugar_plugin.h
kugar_plugin.cpp
kugar_plugin.pro
Een header-bestand voor de `KugarWidgetPlugin`, `QWidgetPlugin`-successor;
Een source-bestand voor de `KugarWidgetPlugin`, `QWidgetPlugin`-successor;
Een project-bestand voor de QMake-utility.

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