Alexander
Dymo

    cloudtemple@mksat.net

Phil
Thompson

    phil@river-bank.demon.co.uk

Hans-Frieder
Hirsch

    f.hirsch@t-online.de

Deutsche Übersetzung

# Das Handbuch für Programmierer

## Wie Sie &kugar; dazu verwenden können in eigenen Programmen Berichte zu erstellen

### Es gibt verschiedene Möglichkeiten &kugar; zu verwenden

- Erstellen Sie eine temporäre Datei und speichern Sie dort Daten, die mit der KugarData Document Type Definition übereinstimmen. Dann geben Sie den`Kugar` Shell Befehl (

       kugar  -d Kugar Daten Datei   -r Kugar Vorlagen Datei

  ). Damit können Sie sich den Bericht anzeigen lassen und ausdrucken. Ausführliche Informationen dazu finden Sie im AbschnittDie &kugar; Shell für Berichtsvorschau .

- Verwenden Sie &kugar; direkt im Code der Anwendung. Genauere Informationen dazu finden Sie unter &kugar;-Klassen für Berichte verwenden.

- Erstellen Sie ein &Qt;-Designer-Plugin. Verwenden Sie es, um die Anwendungsoberfläche (&GUI;) im Designer zu erstellen und verknüpfen Sie es dynamisch mit dem Programm. Einzelheiten dazu finden Sie im Abschnitt Ein &Qt;-Designer-Plugin erstellen.

Die beiden letzten Wege sind für &Qt; und &kde; Entwickler annehmbar. Aber &kugar; wurde als Bericht-Generator entworfen, der unabhängig von einer Programmiersprache und/oder IDE funktioniert. Er verwendet das &XML;-Format zur Beschreibung von Berichtvorlagen- und Daten-Dateien. Deshalb kann jedes Programm eine Ausgabe im &kugar; Daten-Dateiformat, wie es in KugarData DTD beschrieben ist, oder auch im Berichtvorlagen -Dateiformat erzeugen (vergleichen Sie dazu KugarTemplate DTD). Eine &kugar; Shell (Bericht Vorschaufenster) kann dazu verwendet werden, einen erzeugten Bericht in einer Vorschau anzuzeigen und zu drucken.

## Die &kugar; Shell zur Vorschau von Berichten verwenden

### Sie können Berichte und eine Berichtvorschau (Druck) erstellen, indem Sie:

1. Eine Bericht-Vorlage mit &kudesigner; erstellen

2. Erstellen Sie eine Daten-Datei mit Spaltenwerten für Detail-Gruppen des Berichtes. Verwenden sie dazuKugarData DTD um korrekte Daten-Dateien zu erzeugen.

3. Starten Sie die &kugar; Shell für Bericht-Vorschau und -Druck. Um das zu tun (zum Beispiel in C oder C++ Sprachen), führen Sie aus:

       System("kugar -r Vorlage_Datei.ktf-d Daten_Datei.kdf").

   Vergessen Sie dabei nicht`stdlib.h` einzuschließen ("include stdlib.h").

## &kugar; Klassen für Berichte verwenden

Die &kugar;-Bibliothek enthält zwei Bedienelemente, die Sie verwenden können.

Die Klasse `KReportViewer` ist für &kde;-Entwickler gedacht. Sie unterstützt das &kde;-Drucksystem und die lokale &UNIX;-Sprachanpassung durch `i18n()` Aufrufe.

Die Klasse `MReportViewer` ist für &Qt;-Entwickler entworfen und erlaubt echte Plattform-übergreifende Lösungen. Sie kann nicht nur auf &UNIX;-, sondern auch auf &Windows;- und &Mac;-Plattformen verwendet werden.

Um ein Programm zu erstellen das die Kugar-Bibliothek verwendet, sollte es mit der `libkugar.so` "shared library", verknüpft werden, die in allen Kugar Distributionen auf allen &UNIX; Plattformen enthalten ist.

"Include"-Dateien sind`kugarqt.h` und `kugar.h` sowohl für &Qt; als auch für &kde; Programme .

Ein detailliertes Beispiel dafür, wie &kugar; Klassen verwendet werden können, finden Sie im `/shell` Verzeichnis in den &kugar; Quelltexten.

Die Klassen `MReportViewer` (und auch `KReportViewer`) enthalten verschiedene "Public" Methoden, die Sieverwenden können.

    void renderReport

    Zeigt den Bericht auf einem Bildschirm an.

    void printReport

    Ruft den Druck-Dialog auf, um den Bericht zu drucken.

    void clearReport

    Löscht den Bericht vom Bildschirm und entbindet die Berichtdaten. Führen Sie diesen Befehl aus, bevor Sie einen neuen Bericht öffnen.

    bool setReportData const QString &Daten_Datei_Name
    Fügt Bericht-Daten von der Daten_Datei_Name Datei ein.

    bool setReportData const QIODevice &data_io_device
    Fügt Bericht-Daten aus der Datei  data_io_device ein. IO-Device kann irgend ein Nachfolger der Klasse QIODevice  sein. Ein Beispiel: Um Berichte direkt aus der Datenbank zu erzeugen, erstellen Sie einen QIODevice-Nachfolger und definieren die gesamte erforderliche Funktionalität erneut.

    bool setReportTemplate const QString &template_file_name
    Erstellt die Bericht-Vorlage von der template_file_name  Datei.

    bool setReportTemplate const QIODevice &template_io_device
    Erstellt eine Berichtvorlage aus der Datei template_io_device. IO-Device kann jeder Nachfolger der Klasse QIODevice sein. Ein Beispiel: um eine Berichtvorlage aus einem Speicher im Netzwerk oder einer Datenbank zu erhalten, erstellen Sie einen QIODevice-Nachfolger und definieren die Funktionalität neu.

## Ein &Qt; Designer Plugin erstellen

Das ist der Beispiel Code für das Erstellen eines Designer Plugin. Der Code weiter unten erzeugt ein Plugin für ein &kde; `KReportViewer` Element.

Wenn ein &Qt; Element gewünscht wird, ersetzen Sie`KReportViewer` durch `MReportViewer` und `kugar.h` mit `kugarqt.h` im Plugin Code.

### Die Verwendung von Plugin

Designer-Plugin ermöglicht die Verwendung von &Qt;-Designer um das `KReportViewer` Element auf einem Bildschirm anzuordnen und eine korrekte Vorschau davon anzuzeigen.

Programme die dieses Plugin benutzen müssen dynamisch mit ihm verknüpft sein. Die dazu gehörende Bibliothek ist`libkugar_plugin.so`. Bedienelemente oder Dialoge die ein `KReportViewer` Bedienelement enthalten müssen <kugar.h> in der Implementierung enthalten und eine Vorwärtsdeklaration von `class KReportViewer`. Includes können mit &Qt; Designer's Objekt Explorer (Source tab) gemacht werden.

Das Erstellen des Plugin starten:

    qmake kugar_plugin.pro

    make

### Plugin Code

#### Der Plugin-Code besteht aus drei Dateien:

kugar_plugin.h
kugar_plugin.cpp
kugar_plugin.pro
Eine Header-Datei für `KugarWidgetPlugin`, abgeleitet von `QWidgetPlugin`;
Eine Quelltext-Datei für `KugarWidgetPlugin`, abgeleitet von `QWidgetPlugin`;
Projektdatei für 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++