<!-- If you want to validate or edit this document separately, uncomment
this prolog

<?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd">

-->
<chapter id="tutorial">
<chapterinfo>
<authorgroup>
<author
><firstname
>Alexander</firstname
> <surname
>Dymo</surname
> <affiliation
> <address
><email
>cloudtemple@mksat.net</email
></address>
</affiliation>
</author>
<author
><firstname
>Phil</firstname
> <surname
>Thompson</surname
> <affiliation
> <address
><email
>phil@river-bank.demon.co.uk</email
></address>
</affiliation>
</author>
<othercredit role="translator"
><firstname
>Juan Manuel</firstname
><surname
>García Molina</surname
><affiliation
><address
><email
>juanma@superiodico.net</email
></address
></affiliation
><contrib
>Traductor</contrib
></othercredit
> 
</authorgroup>
</chapterinfo>
<title
>Tutorial</title>

<para
>Este tutorial intenta ser una introducción breve a Kugar.</para>

<para
>Creará un informe de ejemplo con &kudesigner;, un archivo de datos de ejemplo, y finalmente generará un informe completo.</para>

<para
>El código fuente de las plantillas de ejemplo y los archivos de datos se puede encontrar en <filename
>sample1.ktf</filename
> y <filename
>sample1.kdf</filename
>, que se distribuyen con &kugar;.</para>


<sect1 id="tut-1">
<title
>Creando la plantilla del informe con &kudesigner;</title>

<para
>Ejecute el diseñador de Kugar tecleando <command
>kudesigner</command
> en el shell. </para>

<para
>Tras iniciar el diseñador, seleccione <guimenu
>Archivo</guimenu
>|<guilabel
>Nuevo</guilabel
> y fije el tamaño de página a <guilabel
>Carta</guilabel
> y la orientación del papel a <guilabel
>Apaisado</guilabel
>. Fije los márgenes izquierdo y derecho a 48, los márgenes superior e inferior a 40. Todas las dimensiones en &kudesigner; (márgenes de página, tamaños, posiciones, etc.) se miden en milímetros. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_file_new.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Diálogo <interface
>Nuevo informe</interface
></phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>El nuevo informe se crea ahora y todos los botones de la <guilabel
>Barra de herramientas de elementos</guilabel
> y <guilabel
>Barra de herramientas de secciones</guilabel
> se activan (también se activan los elementos del menú correspondientes de <guilabel
>Elementos</guilabel
> y <guilabel
>Secciones</guilabel
>). <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_empty_report.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Ventana de informe vacío</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Ahora hay que añadir algunas secciones al informe y determinar sus tamaños. Añadiremos <link linkend="report-header-and-footer"
>encabezado y pie del informe</link
>, <link linkend="page-header-and-footer"
>encabezados y pies de la página</link
> y una sección de <link linkend="detail"
>detalle</link
> sencilla. Los encabezados y los pies del informe se imprimen en la primera y en la última página del informe antes de cualquier otro dato del informe. Los pies del informe son buenos sitios para los <link linkend="calculated-field-element"
>datos calculados</link
>. Los encabezados y pies de página se imprimen arriba y abajo de cada página. Nuestro informe tendrá una sección de detalle con el nivel 0. Esto significa que todas nuestras filas de datos tienen idéntica estructura (&ie;, campos). Si la estructura de datos es más compleja o si está organizada de acuerdo a una relación maestro-detalle, se pueden crear más niveles de detalle. Vea <filename
>sample3.ktf</filename
> y <filename
>sample3.kdf</filename
> para un ejemplo de cómo se puede hacer esto. Vea las <link linkend="template-elements"
>descripciones de los elementos de la plantilla</link
> para obtener información adicional. </para>

<para
>Las secciones se añaden usando el menú <guilabel
>Secciones</guilabel
> o la <guilabel
>barra de herramientas Secciones</guilabel
>. Ahora añada un encabezado y pie del informe, encabezado y pie de la página y luego una sección de detalle. Al añadir la sección del detalle, fije su nivel a 0 como se muestra en la captura de pantalla de abajo. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_set_level.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Establecer el nivel de detalle</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Nuestro informe se debe parecer a éste de la captura de pantalla. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_look1.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Informe con secciones</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Todas nuestras secciones tienen una altura predefinida - 50mm. Cambiémosla. Para ello, haga clic &RMB; sobre la sección de encabezado del informe o haga clic en el botón <guilabel
>Editar propiedades</guilabel
> de la <guilabel
>barra de herramientas de edición</guilabel
> y luego elija una sección. Se debe mostrar la ventana de propiedades. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_edit_height.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Editando la altura de la sección</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Ahora fije una altura del encabezado del informe de 70. Realice este proceso para todas las demás secciones. Defina la altura del encabezado de la página a 45 y la del detalle a 30. Los encabezados de la página y del informe debieran tener una altura de 32 mm. </para>

<para
>La plantilla del informe con los tamaños de secciones adecuados ya está lista para ser rellenada con elementos del informe. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_look2.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Informe con secciones con tamaño</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Ahora puede añadir elementos a las secciones del informe. Se pueden añadir al informe cinco tipos diferentes de elementos. <link linkend="label-element"
>Etiqueta</link
> es un área rectangular que puede tener bordes y se puede rellenar con cualquier clase de datos de texto. Tanto el color de primer plano de la etiqueta como los colores de fondo y las tipografías se pueden cambiar. Los tipos de líneas de bordes y los colores de las líneas también son personalizables. <link linkend="field-element"
>Campo</link
> se puede poner en una sección de detalle. El campo representa los campos de datos, sus valores serán capturados de un archivos de datos al generar el informe. Se pueden imprimir contadores, sumas, promedios, etc. para los valores del campo en el informe por medio de los <link linkend="calculated-field-element"
>Campos calculados</link
>. <link linkend="special-element"
>Especiales</link
> son etiquetas con texto predefinido, como la fecha actual o el número de página. El aspecto general del informe se puede refinar con las <link linkend="line-element"
>Líneas</link
>. </para>

<para
>Para añadir un elemento del informe, haga clic sobre el botón del elemento correspondiente en la <guilabel
>barra de herramientas Elementos</guilabel
> y póngalo (clic) en la sección. Los elementos elegidos se ponen en la sección seleccionada con la esquina superior izquierda en las coordenadas dadas. Otras propiedades se fijan a los valores predeterminados y se pueden cambiar con el diálogo <guilabel
>Opciones del elemento del informe</guilabel
> (de la misma forma que solíamos cambiar el alto de la sección). </para>

<para
>Por tanto, añada etiquetas al encabaezado del informe y al encabezado de página como se muestra en la captura de pantalla de abajo. Tenga en cuenta que la etiqueta <quote
>Mutiny Bay Software</quote
> tiene su <guilabel
>BorderStyle</guilabel
> y <guilabel
>BorderWidth</guilabel
> fijados a 0 y <quote
>Software Inventory Report</quote
> - 1mm. Cualquier color se fija como una combinación de tres valores (RGB - rojo, verde, azul) divididos por comas. </para>

<para
>También añadiremos elementos de campos a la sección de detalle. Simplemente, suponga que tenemos cuatro campos - título, versión, plataforma y copias. Por tanto, se deben poner cuatro elementos <guilabel
>Campo</guilabel
> y fijar sus propiedades de <guilabel
>Campo</guilabel
>. Tenga en cuenta que la propiedad <guilabel
>Texto</guilabel
> se pone automáticamente a <quote
>[<userinput
>nombre_campo</userinput
>]</quote
> </para>

<para
>El pie de página hay un buen sitio para mostrar la fecha y el número de la página actual, así que añada dos campos especiales y fije sus propiedades <guilabel
>Tipo</guilabel
> a 0 y 1 respectivamente. En especial, con Tipo=0 representará la fecha y en el Tipo=1, el número de página. Tenga en cuenta que la propiedad <guilabel
>Texto</guilabel
> de los campos especiales se cambia automáticamente. </para>

<para
>El último elemento a ubiar es <guilabel
>Campo calculado</guilabel
>, para el campo <quote
>copias</quote
>. Para lograr una suma de las copias, fije la propieda <guilabel
>Campo</guilabel
> del campo calculado a <quote
>copias</quote
> y <guilabel
>Tipo de cálculo</guilabel
> a 1 (función suma). </para>

<para
>Al final, la plantilla de informe debe parecerse a ésta. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_complete.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Informe completo</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

</sect1>



<sect1 id="tut-2">
<title
>Creando el archivo de datos del informe</title>

<para
>Los archivos de datos se pueden crear de varias formas. Unos pueden usar las tablas de transformación xsl para generar &XML; válido desde otro documento &XML; (como la hoja de datos &kspread;), otros usarán sus propios programas para capturar datos de una base de datos y rellenar el archivo de datos. En este tutorial, simplemente lo crearemos a mano. El código fuente para el ejemplo se puede encontrar en el archivo <filename
>sample1.kdf</filename
> o se puede copiar del ejemplo de abajo. </para>

<programlisting
>&lt;?xml version=<quote
>1.0</quote
> encoding=<quote
>UTF-8</quote
>?&gt;

&lt;!DOCTYPE KugarData [
    &lt;!ELEMENT KugarData (Row* )&gt;
    &lt;!ATTLIST KugarData
        Template CDATA #REQUIRED&gt;

    &lt;!ELEMENT Row EMPTY&gt;
    &lt;!ATTLIST Row
        level CDATA #REQUIRED
        title CDATA #REQUIRED
        version CDATA #REQUIRED
        platform CDATA #REQUIRED
        copies CDATA #REQUIRED&gt;
]&gt;

&lt;KugarData Template="sample1.ktf"&gt;
    &lt;Row level="0" title="  BRU" version="15.0" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Caldera Open Linux" version="2.2" platform="x86" copies="3"/&gt;
    &lt;Row level="0" title="  K Desktop" version="1.1.1" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Netscape Communicator" version="4.6" platform="x86" copies="10"/&gt;
    &lt;Row level="0" title="  Redhat Linux" version="5.0" platform="x86" copies="11"/&gt;
    &lt;Row level="0" title="  Redhat Linux" version="5.1" platform="x86" copies="12"/&gt;
    &lt;Row level="0" title="  Redhat Linux" version="5.2" platform="x86" copies="14"/&gt;
    &lt;Row level="0" title="  Redhat Linux" version="6.0" platform="x86" copies="15"/&gt;
    &lt;Row level="0" title="  Star Office" version="5.0" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Star Office" version="5.1" platform="x86" copies="3"/&gt;
    &lt;Row level="0" title="  Microsoft Windows NT" version="3.1" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Microsoft Windows NT" version="3.51" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Microsoft Windows NT" version="4.0" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Microsoft Windows NT" version="5.0" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Sun Solaris" version="2.5" platform="Sparc" copies="1"/&gt;
&lt;/KugarData&gt;
</programlisting>

</sect1>

<sect1 id="tut-3">
<title
>Generar el informe</title>

<para
>Ahora tenemos una plantilla de informe (<filename
>sample1.ktf</filename
>) y los datos del informe (<filename
>sample1.kdf</filename
>). </para>
<para
>Para generar un informe, teclee el siguiente comando en la shell:<command
>kugar <option
>-r <replaceable
>sample1.ktf</replaceable
></option
> <option
>-d <replaceable
>sample1.kdf</replaceable
></option
></command
> </para>

<para
>Esto hará surgir una ventana de shell de &kugar; con el informe generado. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_generated.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Informe generado</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

</sect1>

</chapter>
