# Tutorial

Este tutorial tenta ser uma rápida introdução ao Kugar.

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

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

## Criando um modelo de relatório com o &kudesigner;

Execute o Kugar Designer digitando `kudesigner` no shell.

Após você iniciar o designer, escolha Arquivo|Novo e configure o tamanho da página para Carta e a orientação do papel para Paisagem. 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. Diálogo Novo Relatório

Um novo relatório é agora criado e todos os botões na Barra de Ferramentas Items e Barra de Ferramentas Seções são agora habilitados (os ítens correspondentes de menu no Ítems e Seções são também habilitados). Diálogo de Relatório Vazio

Agora é a hora de adicionar algumas seções ao relatório e determinar seus tamanhos. Nós adicionaremos seções de cabeçalho e rodapé de relatório, cabeçalho e rodapé de página e uma única seção de detalhes. 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 campos calculados. 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 `sample3.kut` e `sample3.kud` para um exemplo de como isto pode ser feito. Veja o descrições dos elementos de modelo para informações adicionais.

Seções são adicionadas usando o menu Seções ou a Barra de Ferramentas Seções. 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. Configurar nível de detalhe

Nosso relatório deverá parecer agora como este na captura de tela. Relatório com seções

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 Editar Propriedades na Barra de Ferramentas Editar e então escolha um seção. A janela de Propriedades deverá aparecer. Edição da altura da seção

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.

Um modelo de relatório com as seções dimensionadas corretamente está pronto para ser preenchido com itens de relatório. Relatório com as seções dimensionadas

Você pode agora adicionar itens às seções do relatório. Cinco diferentes tipos de itens podem ser adicionados ao relatório. Rótulo é 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. Campo 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 Campos Calculados. Especiais 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 Linhas.

Para adicionar um item de relatório clique o botão do item correspondente na Barra de Ferramentas Items 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 Opções de Item de Relatório (da mesma maneira que nós fizemos para mudar a altura da seção).

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 Mutiny Bay Software tem seu BorderStyle e BorderWidth configurado para 0 e Software Inventory Report - 1mm. Qualquer cor é configurada com uma combinação de três valores (RGB - red,green,blue - vermelho,verde,azul) separados por vírgula.

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 elementosCampo devem ser colocados e suas propriedades de Campo configuradas. Observe que a propriedade Texto é automaticamente configurada para [`nome_do_campo`]

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 Tipe 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 Text do especial é mudada automaticamente.

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

Finalmente, nosso modelo de relatório deve parecer-se com isto: Relatório completo

## Criando um arquivo de dados de relatório

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 `sample1.kud` ou copiado do exemplo abaixo.

    <?xml version=1.0 encoding=UTF-8?>

    <!DOCTYPE KugarData [
        <!ELEMENT KugarData (Row* )>
        <!ATTLIST KugarData
            Template CDATA #NECESSÁRIO>

        <!ELEMENT Row EMPTY>
        <!ATTLIST Row
            level CDATA #NECESSÁRIO
            title CDATA #NECESSÁRIO
            version CDATA #NECESSÁRIO
            platform CDATA #NECESSÁRIO
            copies CDATA #NECESSÁRIO>
    ]>

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

## Gerando o relatório

Neste momento nós temos um modelo de relatório (`sample1.kut`) e um arquivo de dados (`sample1.kud`).

Para gerar um relatório, digite o seguinte comando no shell: `kugar `-r `sample1.kut`` `-d `sample1.kud```

Isto trará uma janela de shell do &kugar; com o relatório gerado. Relatório gerado