<!-- 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
>Marcus</firstname
><surname
>Gama</surname
><affiliation
><address
><email
>marcus_gama@uol.com.br</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
</authorgroup>
</chapterinfo>
<title
>Tutorial</title>

<para
>Este tutorial tenta ser uma rápida introdução ao Kugar.</para>

<para
>Você criará um modelo de relatório exemplo com o &kudesigner;, um arquivo de dados exemplo e finalmente irá gerar um relatório completo.</para>

<para
>O código fonte para os modelos exemplo e arquivos de dados podem ser encontrados em <filename
>sample1.kut</filename
> e <filename
>sample1.kud</filename
> que são distribuídos com o &kugar;.</para>


<sect1 id="tut-1">
<title
>Criando um modelo de relatório com o &kudesigner;</title>

<para
>Execute o Kugar Designer digitando <command
>kudesigner</command
> no shell. </para>

<para
>Após você iniciar o designer, escolha <guimenu
>Arquivo</guimenu
>|<guilabel
>Novo</guilabel
> e configure o tamanho da página para <guilabel
>Carta</guilabel
> e a orientação do papel para <guilabel
>Paisagem</guilabel
>. Configure as margens esquerda e direita para 48, e as margens superior e inferior para 40. Todas as dimensões no &kudesigner; (margens de página, tamanhos, posições, &etc;) são mensuradas em milímetros. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_file_new.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Diálogo <interface
>Novo Relatório</interface
></phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Um novo relatório é agora criado e todos os botões na <guilabel
>Barra de Ferramentas Items</guilabel
> e <guilabel
>Barra de Ferramentas Seções</guilabel
> são agora habilitados (os ítens correspondentes de menu no <guilabel
>Ítems</guilabel
> e <guilabel
>Seções</guilabel
> são também habilitados). <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_empty_report.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Diálogo de Relatório Vazio</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Agora é a hora de adicionar algumas seções ao relatório e determinar seus tamanhos. Nós adicionaremos seções de <link linkend="report-header-and-footer"
>cabeçalho e rodapé de relatório</link
>, <link linkend="page-header-and-footer"
>cabeçalho e rodapé de página</link
> e uma única seção de <link linkend="detail"
>detalhes</link
>. Cabeçalhos e rodapés de relatório são impressos nas primeira e última páginas do relatório antes de depois de qualquer outro dado do relatório, respectivamente. Rodapés de relatório são bons lugares para <link linkend="calculated-field-element"
>campos calculados</link
>. Cabeçalhos e rodapés de páginas são impressos na parte superior e inferior de cada página. Nosso relatório terá um seção de detalhe com nível 0. Isto significa que todas as nossas linhas de dados terão estrutura idêntica (&ie; campos). Se a estrutura de dados é mais complexa ou está organizada de acordo com um relacionamento baseada num detalhe-mestre, mais níveis de detalhes podem ser criados. Veja o <filename
>sample3.kut</filename
> e <filename
>sample3.kud</filename
> para um exemplo de como isto pode ser feito. Veja o <link linkend="template-elements"
>descrições dos elementos de modelo</link
> para informações adicionais. </para>

<para
>Seções são adicionadas usando o menu <guilabel
>Seções</guilabel
> ou a <guilabel
>Barra de Ferramentas Seções</guilabel
>. Agora adicione um cabeçalho e rodapé de relatório, cabeçalho e rodapé de página e então um detalhe. Quando adicionar a seção detalhe, configure seu nível para 0 como mostrado na captura de tela abaixo. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_set_level.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Configurar nível de detalhe</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Nosso relatório deverá parecer agora como este na captura de tela. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_look1.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Relatório com seções</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Todas as nossas seções possuem uma altura pré-definida - 50mm. Vamos mudá-la.Para fazer isto &RMB; na seção Cabeçalho do Relatório ou clique no botão <guilabel
>Editar Propriedades</guilabel
> na <guilabel
>Barra de Ferramentas Editar</guilabel
> e então escolha um seção. A janela de Propriedades deverá aparecer. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_edit_height.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Edição da altura da seção</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Agora configure a altura do Cabeçalho do Relatório para 70. Vamos executar este procedimento para todas as outras seções. Configure a altura do Cabeçalho da Página para 45 e a do Detalhe para 30. Rodapés de Página e Relatório devem ter 32 mm de altura. </para>

<para
>Um modelo de relatório com as seções dimensionadas corretamente está pronto para ser preenchido com itens de relatório. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_look2.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Relatório com as seções dimensionadas</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Você pode agora adicionar itens às seções do relatório. Cinco diferentes tipos de itens podem ser adicionados ao relatório. <link linkend="label-element"
>Rótulo</link
> é uma área retangular que pode ter bordas e pode ser preenchida com qualquer tipo de dados de texto. Cores de texto e fundo bem como fontes podem ser mudadas para o Rótulo. Tipos de linha de borda e cores de linha podem também ser customizadas. <link linkend="field-element"
>Campo</link
> pode ser colocado numa seção de detalhe. Campos representam campos de dados, seus valores serão coletados de um arquivo de dados durante a geração de um relatório. Contagens, somatórios, médias, &etc;, para os valores dos campos podem ser impressos no relatório através de <link linkend="calculated-field-element"
>Campos Calculados</link
>. <link linkend="special-element"
>Especiais</link
> são rótulos com texto pré-definido, como a data atual ou o número da página. A aparência geral do relatório pode ser refinada com <link linkend="line-element"
>Linhas</link
>. </para>

<para
>Para adicionar um item de relatório clique o botão do item correspondente na <guilabel
>Barra de Ferramentas Items</guilabel
> e coloque-o (clique) na seção. O item escolhido será colocado na seção selecionada com o canto superior esquerdo nas coordenadas fornecidas. Outras propriedades são configuradas com os valores padrão e podem ser mudadas com o diálogo <guilabel
>Opções de Item de Relatório</guilabel
> (da mesma maneira que nós fizemos para mudar a altura da seção). </para>

<para
>Então, vamos adicionar rótulos ao cabeçalho do relatório e cabeçalho da página como mostrado na captura de tela abaixo. Observe, que o rótulo <quote
>Mutiny Bay Software</quote
> tem seu <guilabel
>BorderStyle</guilabel
> e <guilabel
>BorderWidth</guilabel
> configurado para 0 e <quote
>Software Inventory Report</quote
> - 1mm. Qualquer cor é configurada com uma combinação de três valores (RGB - red,green,blue - vermelho,verde,azul) separados por vírgula. </para>

<para
>Adicione também elementos de campo à seção detalhe. Apenas considere que nós temos quatro campos - título, versão, plataforma e cópias. Então, quatro elementos<guilabel
>Campo</guilabel
> devem ser colocados e suas propriedades de <guilabel
>Campo</guilabel
> configuradas. Observe que a propriedade <guilabel
>Texto</guilabel
> é automaticamente configurada para <quote
>[<userinput
>nome_do_campo</userinput
>]</quote
> </para>

<para
>Nosso rodapé de página é um bom lugar para colocar a data atual e o número da página, então adicione dois campos especiais e configure suas propriedades <guilabel
>Tipe</guilabel
> para 0 e 1. Especial com Tipo=0 representará a data e o com o Tipo=1 - o número da página. Observe que a propriedade <guilabel
>Text</guilabel
> do especial é mudada automaticamente. </para>

<para
>O último elemento a ser colocado é um <guilabel
>Campo Calculado</guilabel
> para o campo <quote
>cópies</quote
>. Para obter um somatório(cópias) configure a propriedade <guilabel
>Campo</guilabel
> do Campo para <quote
>cópias</quote
> e <guilabel
>CalculationType</guilabel
> para 1 (função somatório). </para>

<para
>Finalmente, nosso modelo de relatório deve parecer-se com isto: <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_complete.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Relatório completo</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

</sect1>



<sect1 id="tut-2">
<title
>Criando um arquivo de dados de relatório</title>

<para
>Falando genericamente, arquivos de dados podem ser criados de diversas formas. Pode-se usar tabelas de transformação xsl para gerar o &XML; apropriado de outro documento &XML; (como uma planilha &kspread;), ou usar um programa próprio para obter dados de um banco de dados e preencher um arquivo de dados. Neste tutorial nós iremos simplesmente criá-lo manualmente. O código fonte para o exemplo pode ser encontrado no arquivo <filename
>sample1.kud</filename
> ou copiado do exemplo abaixo. </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 #NECESSÁRIO&gt;

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

&lt;KugarData Template="sample1.kut"&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
>Gerando o relatório</title>

<para
>Neste momento nós temos um modelo de relatório (<filename
>sample1.kut</filename
>) e um arquivo de dados (<filename
>sample1.kud</filename
>). </para>
<para
>Para gerar um relatório, digite o seguinte comando no shell: <command
>kugar <option
>-r <replaceable
>sample1.kut</replaceable
></option
> <option
>-d <replaceable
>sample1.kud</replaceable
></option
></command
> </para>

<para
>Isto trará uma janela de shell do &kugar; com o relatório gerado. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_generated.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Relatório gerado</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

</sect1>

</chapter>
