Alexander
Dymo

    cloudtemple@mksat.net

Phil
Thompson

    phil@river-bank.demon.co.uk

Marek
Laane

    bald@starman.ee

Tõlge eesti keelde

# Juhiseid programmeerijatele

## Kuidas kasutada &kugar;it aruannete loomiseks oma rakendustes

### &kugar;it saab kasutada mitmel viisil

- Luues ajutise faili, milles olevad andmed on organiseeritud vastavalt Kugari andmete dokumenditüübi definitsioonile. Seejärel käivita käsk `kugar` (

       kugar  -d Kugari andmefail   -r Kugari mallifail

  ) aruande eelvaatluseks. Täpsemat infot vaata osast &kugar;i kasutamine aruannete eelvaatluseks.

- Kasutades &kugar;it vahetult rakenduse koodis. Täpsemat infot vaata osast &kugar;i klasside kasutamine aruannete loomisel.

- Luues &Qt; disaineri plugina ja kasutades seda disaineris rakenduse &GUI; loomiseks ning selle dünaamiliseks linkimiseks rakendusega. Täpsemat infot vaata osast &Qt; disaineri plugina loomine.

Viimased kaks võimalust meeldivad loodetavasti hästi &Qt; ja &kde; arendajatele. Kuid &kugar; on mõeldud aruannete generaatoriks sõltumata kasutatavast programeerimiskeelest ja/või IDE-st. Kugar kasutab aruande mallide ja andmefailide kirjeldamisel &XML;-vormingut, nii et põhimõtteliselt võib suvaline rakendus leida väljundi &kugar;i andmefailis, mida kirjeldab KugarData DTD või isegi aruande mallis (vaata KugarTemplate DTD). Genereeritud aruannete eelvaatluseks saab kasutada &kugar;i shelli (aruannete näitajat).

## &kugar;i kasutamine aruannete eelvaatluseks

### Aruande loomise ja eelvaatluse meetod on järgmine:

1. Loo aruande malli fail &kudesigner;i abil

2. Loo korrektne andmefail. Kuidas see välja peab nägema, saab teada osast KugarData DTD.

3. Käivita &kugar;i shell aruande eelvaatluseks. Näiteks C või C++ keeles:

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

   Ära unusta kaasamast faili `stdlib.h`.

## &kugar;i klasside kasutamise aruannete loomisel

&kugar;i teegis on kaks kasutuskõlbulikku vidinat.

Klass `KReportViewer` on mõeldud &kde; arendajatele. See toetab &kde; trükkimissüsteemi ja &UNIX; lokaliseerimist väljakutsetega `i18n()`.

Klass `MReportViewer` on mõeldud &Qt; arendajatele ning pakub tõelist vabadust platvormist. Seda saab kasutada mitte ainult &UNIX; platvormil, vaid ka &Windows; ja &MacOS; puhul.

&kugar;i teegi kasutamiseks rakenduse loomisel tuleb see linkida jagatud teegiga `libkugar.so`, mida pakub &kugar;i pakett kõigile &UNIX; platvormidele.

Kaasatud failid on `kugarqt.h` ja `kugar.h` (vastavalt &Qt; ja &kde; rakendustele).

Üksikasjalikku näidet, kuidas kasutada &kugar;i klasse, vaata &kugar;i lähtekoodi kataloogis `/shell`.

`MReportViewer` (aga ka `KReportViewer`) sisaldab mitu kasutatavat avalikku meetodit.

    void renderReport

    Teisendab aruande ekraanile.

    void printReport

    Kutsub välja dialoogi aruande trükkimiseks.

    void clearReport

    Puhastab aruande ekraanil ja vabastab aruande andmed. Seda tasub välja kutsuda enne uue aruande avamist.

    bool setReportData const QString &andmefaili_nimi
    Määrab võtmega andmefaili_nimi, millisest failist aruanne andmeid võtab.

    bool setReportData const QIODevice &andmete_IO_seade
    Määrab võtmega andmete_IO_seade, millisest failist aruanne andmeid võtab. IO-seade võib olla suvaline klassi QIODevice järglane. Näiteks andmete tõmbamiseks vahetult andmebaasist loo QIODevice järglane ning defineeri vajalikud funktsioonid ümber.

    bool setReportTemplate const QString &mallifaili_nimi
    Määrab võtmega mallifaili_nimi aruande malli.

    bool setReportTemplate const QIODevice &malli_IO_seade
    Määrab võtmega malli_IO_seade aruande malli. IO-seade võib olla suvaline klassi QIODevice järglane. Näiteks aruande malli hankimiseks võrgust või andmebaasist loo QIODevice järglane ja defineeri kõik vajalikud funktsioonid ümber.

## &Qt; disaineri plugina loomine

Siin on toodud näide disaineri plugina loomise kohta. Allpool esitatud kood loob plugina &kde; elemendile `KReportViewer`.

Kui soovid luua &Qt; elementi, asenda plugina koodis `KReportViewer` klassiga `MReportViewer` ning `kugar.h` failiga `kugarqt.h`'ga.

### Plugina kasutamine

Disaineri plugin võimaldab kasutada &Qt; disainerit `KReportViewer`'i aknasse saatmiseks ja selle korrektseks näitamiseks.

Seda pluginat kasutavad rakendused tuleb sellega dünaamiliselt linkida. Vastav teek kannab nime `libkugar_plugin.so`. Elemendid või dialoogid, mis kaasavad elemendi `KReportViewer`, peavad kaasama väljakutsesse <kugar.h> ning neil peab olema `class KReportViewer`'i edasideklaratsioon. Kaasata saab &Qt; disaineri objektivaatleja (kaart Allikas) abil.

Plugina loomiseks anna käsk:

    qmake kugar_plugin.pro

    make

### Plugina kood

#### Plugina kood koosneb kolmest failist:

kugar_plugin.h
kugar_plugin.cpp
kugar_plugin.pro
Klassi `KugarWidgetPlugin` päisefail, klassi `QWidgetPlugin` pärija;
Klassi `KugarWidgetPlugin` lähtefail, klassi `QWidgetPlugin` pärija;
QMake utiliidi projektifail.

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