# Guía del programador

## Cómo usar &kugar; para hacer informes en sus propios programas

### Hay varias formas de usar &kugar;

- Crear un archivo temporal y rellenarlo con datos, organizados de acuerdo a la definición del tipo de documento deKugarData. Luego llame al shell del comando `kugar` (

       kugar  -d archivo de datos de Kugar   -r archivo de plantilla kugar

  ) para ver e imprimir el informe. Vea la sección Usando el shell de &kugar; para visualizar informes para una descripción detallada.

- Use &kugar; directamente en el código de la aplicación. Vea la sección Usando las clases de &kugar; para hacer informes para una descripción detallada.

- Cree un plugin para &Qt; designer, úselo para construir el &GUI; de la aplicación en el designer y enlácelo con el programa dinámicamente. Vea la sección Creando un plugin para &Qt; designer para una descripción detallada.

Las últimas dos formas son aceptables para desarrolladores de &Qt; y &kde;. Pero &kugar; está diseñado para ser un generador de informes, independientemente de un lenguaje de programación y/o IDE. Usa el formato &XML; para describir plantillas de informes y archivos de datos. Así que cualquier programa puede producir salida en formato de archivo de datos de &kugar; como se describe en DTD de KugarData o incluso el formato de archivo de plantilla de informe (vea DTD de KugarTemplate). Un shell de &kugar; (visor de informes) se puede usar para ver e imprimir los informes generados.

## Usando el shell de &kugar; para visualizar informes

### La forma de crear y visualizar (imprimir) informes es:

1. Cree una plantilla de informe con &kudesigner;

2. Cree un archivo de datos con valores de columnas para las bandas detalladas del informe. Use el DTD de KugarData para producir archivos de datos correctos.

3. Lance el shell de &kugar; para visualizar e imprimir el informe. Por ejemplo, haga esto, en llamadas de lengaje de c o c++:

       system("kugar -r template_file.kut-d data_file.kud").

   No olvide incluir `stdlib.h`.

## Usando clases de &kugar; para el informe

La biblioteca de &kugar; incluye dos elementos para que los use.

La clase `KReportViewer` está diseñada para desarrolladores de &kde;. Admite un sistema de impresión de &kde; y localización de &UNIX; vía llamadas a `i18n()`.

La clase `MReportViewer` está diseñada para desarrolladores de &Qt; y proporciona multiplataforma real. No sólo se puede usar en plataformas &UNIX;, sino también en &Windows; y &Mac;.

Para construir un programa que utilice la biblioteca kugar, se debe enlazar con la biblioteca compartida `libkugar.so`, que se proporciona con la distribución de kugar en todas las plataformas &UNIX;.

Los archivos que hay que incluir incluir son `kugarqt.h` y `kugar.h` para los programas de &Qt; y &kde;.

Para un ejemplo detallado de cómo se usan las clases de &kugar;, vea el directorio `/shell` en las fuentes de &kugar;.

`MReportViewer` (y `KReportViewer` también) contiene varios métodos públicos que se pueden usar.

    void renderReport

    Visualiza el informe en pantalla.

    void printReport

    LLama al cuadro de diálogo de impresión para imprimir el informe.

    void clearReport

    Limpia el informe en una pantalla y libera los datos del informe. Llame a esta función antes de abrir el informe nuevo.

    bool setReportData const QString &nombre_arch_datos
    Toma los datos para el informe del archivo nombre_arch_datos.

    bool setReportData const QIODevice &disp_datos_es
    Toma los datos para el informe del archivo disp_datos_es file. El dispositivo de E/S puede ser cualquier heredero de la clase QIODevice. Por ejemplo, para recoger registros directamente de la base de datos, cree un heredero de QIODevice y redefina toda la funcionalidad necesaria.

    bool setReportTemplate const QString &nombre_arch_plantilla
    Toma loa plantilla del informe del archivo nombre_arch_plantilla.

    bool setReportTemplate const QIODevice &disp_es_plantilla
    Toma la plantilla del informe del archivo disp_es_plantilla . El dispositivo de E/S puede ser cualquier heredero de la clase QIODevice. Por ejemplo, para obtener una plantilla del informe de algún sitio de la red o una base de datos, cree un heredero de QIODevice y redefina toda la funcionalidad necesaria.

## Creando un plugin de &Qt; designer

Este es el código de ejemplo de cómo se crea el plugin del diseñador. El código de abajo crea el plugin para un elemento de `KReportViewer` de &kde;.

Si se desea un plugin para &Qt;, cambie `KReportViewer` por `MReportViewer` y `kugar.h` por `kugarqt.h` en el código del plugin.

### Uso del plugin

El plugin del diseñador permitirá el uso de &Qt; Designer para ubicar el elemento `KReportViewer` en una ventana y visualizarlo correctamente.

Los programas que hacen uso de este plugin se deben enlazar con él dinámicamente. La biblioteca correspondiente se llama `libkugar_plugin.so`. Los elementos o diálogos que incluyen el elemento `KReportViewer` deben incluir include <kugar.h> en la implementación y tener una declaración más adelante de la clase `class KReportViewer`. Se pueden hacer los includes con el Explorador de objetos de &Qt; Designer (pestaña Fuente).

Para construir un plugin, ejecute:

    qmake kugar_plugin.pro

    make

### Código del plugin

#### El código del plugin consta de tres archivos:

kugar_plugin.h
kugar_plugin.cpp
kugar_plugin.pro
Un archivo de encabezado para `KugarWidgetPlugin`, heredero de `QWidgetPlugin`;
Un archivo fuente para `KugarWidgetPlugin`, heredero de `QWidgetPlugin`;
Archivo de proyecto para la utilidad 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++