# Tutorial

Este tutorial tenta ser uma breve introdução ao Kugar.

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

O código-fonte para os modelos dos exemplos e os ficheiros de dados poderão ser encontrados no `sample1.ktf` e no `sample1.kdf` que são distribuídos com o &kugar;.

## Criar o modelo de relatório com o &kudesigner;

Execute o Kugar Designer ao escrever `kudesigner` na linha de comandos.

Depois de iniciar o desenhador, escolha a opção Ficheiro|Novo e configure o tamanho da página para Carta e a direcção do papel como Paisagem. Configure as margens esquerda e direita iguais a 48 e as margens inferior e superior como 40. Todas as dimensões do &kudesigner; (margens da página, tamanhos, posições, &etc;) são medidas em milímetros. Janela de Novo Relatório

Está criado agora um novo relatório e todos os botões da Barra de Itens e da Barra de Secções estão agora activos (os itens de menu correspondentes em Itens e Secções ficam também activos). Janela de Relatório Vazio

Agora é a altura de adicionar algumas secções ao relatório e de determinar os seus tamanhos. Serão adicionados o cabeçalho e o rodapé do relatório, o cabeçalho e o rodapé da página e uma única secção de detalhe. Os cabeçalhos e rodapés do relatório são impressos primeiro, bem como as últimas páginas do relatório ante s e depois de quaisquer dados do relatório. Os rodapés dos relatórios são locais óptimos para os campos calculados. Os cabeçalhos e rodapés das páginas são impressos no início e no fim de cada página. O relatório do exemplo irá ter uma secção de detalhe com o nível 0. Isto significa que todas as linhas de dados irão ter uma estrutura idêntica (&ie;, campos). Se a estrutura de dados for mais complexa ou se for organizada com uma relação de mestre-detalhe, poderão ser criados mais níveis de detalhe. Veja o `sample3.kut` e o `sample3.kud` para ver um exemplo de como isto poderá ser feito. Veja as descrições dos elementos do modelo para mais informações.

As secções são adicionadas ao usar o menu Secções ou uma Barra de Secções. A partir de agora, adicione o cabeçalho e o rodapé do relatório e das páginas e, finalmente, o detalhe. Ao adicionar a secção de detalhe, coloque o seu nível a 0 como é mostrado na imagem em baixo. Modificar o nível de detalhe

O relatório deverá agora ficar parecido com o desta imagem. Relatório com secções

Todas as secções do exemplo têm uma altura predefinida - 50 mm; esta será agora alterada. Para o fazer, carregue com o &RMB; na secção do Cabeçalho do Relatório ou carregue no botão Editar as Propriedades da Barra de Edição e, finalmente, escolha uma secção. A janela de propriedades deverá então aparecer. Altura da edição da secção

Defina agora a altura do Cabeçalho do Relatório como sendo igual a 70. Este procedimento vai ser repetido para todas as outras secções. Configure a altura do Cabeçalho da Página para ser igual a 45 e do Detalhe como sendo igual a 30. Os Rodapés da Página e do Relatório deverão ter 32 mm de altura.

Um modelo de relatório com as secções devidamente dimensionadas está pronto a ser preenchido com os itens do relatório. Relatório com secções dimensionadas

Poderá agora adicionar itens às secções do relatório. Poderão ser adicionados cinco tipos diferentes de itens. A Legenda é uma área rectangular que poderá ter um contorno e poderá ser preenchida com qualquer tipo de dados em texto. O texto em si e as cores de fundo, assim como os tipos de letra, poderão ser alterados. Os tipos de contorno e as cores das linhas poderão também ser personalizadas. O Campo poderá ser colocado numa secção de detalhe. Os campos representam campos de dados e os seus valores serão obtidos a partir de um ficheiro de dados ao gerar um relatório. As quantidades, somas, médias, &etc; dos valores dos campos poderão ser impressas no relatório através dos Campos Calculados. Os Especiais são legendas com algum texto predefinido, como a data actual ou o número de página. A aparência geral do relatório pode ser refinada com as Linhas.

Para adicionar um item do relatório, carregue no botão do item corresponde da Barra de Itens e coloque-o na secção. O item seleccionado será posicionado na secção seleccionada com o canto superior esquerdo nas coordenadas indicadas. As outras propriedades ficam configuradas com os valores predefinidos e poderão ser alteradas com a janela das Opções do Item de Relatório (da mesma forma como foi alterada a altura da secção).

Assim, serão adicionadas legendas ao cabeçalho e ao rodapé do relatório, tal como se demonstra na imagem abaixo. Lembre-se que a legenda Mutiny Bay Software tem o seu BorderStyle e o seu BorderWidth iguais a 0 e o Software Inventory Report - 1mm. Todas as cores estão definidas como uma combinação de três valores (RGB- vermelho, verde e azul) separados por vírgulas.

Adicione também elementos de campos na secção do detalhe. Assumindo que existem quatro campos - título, versão, plataforma e cópias. Deste modo, deverão ser colocados quatro elementos Campo, assim como deverão ser configuradas as propriedades do Campo. Lembre-se que a propriedade do Texto é configurada automaticamente como [`nome_campo`].

O rodapé da página é um bom sítio onde mostrar a data actual e o número da página, como tal deverão ser adicionados dois campos especiais e configurado o seu Type como sendo 0 e 1. O especial com Type=0 irá representar a data e o Type=1 o número da página. Repare que a propriedade Text do item especial é alterada automaticamente.

O último elemento a ser colocado é o Campo Calculado para o campo cópias. Para adquirir um conjunto de som da cópias, configure a propriedade Field do campo calculado como sendo o copies e o CalculationType igual a 1 (a função de soma).

Finalmente, o nosso modelo de relatório deve ter este aspecto: Relatório completo

## Criar o ficheiro de dados do relatório

De um modo geral, os ficheiros de dados poderão ser criados de várias formas. Alguns irão usar tabelas de transformação de XSL para gerar um &XML; válido a partir de outro documento em &XML; (como uma folha de cálculo do &kspread;); os outros irão usar o seu próprio programa para obter os dados de uma base de dados e preencher o ficheiro de dados. Neste tutorial, este será criado à mão. O código-fonte do exemplo, poderá ser encontrado no ficheiro `sample1.kdf` ou copiado do exemplo abaixo.

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

    <!DOCTYPE KugarData [
        <!ELEMENT KugarData (Row* )>
        <!ATTLIST KugarData
            Template CDATA #REQUIRED>

        <!ELEMENT Row EMPTY>
        <!ATTLIST Row
            level CDATA #REQUIRED
            title CDATA #REQUIRED
            version CDATA #REQUIRED
            platform CDATA #REQUIRED
            copies CDATA #REQUIRED>
    ]>

    <KugarData Template="sample1.ktf">
        <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>

## Gerar o relatório

Neste momento temos um modelo de relatório (`sample1.ktf`) e um ficheiro de dados de relatório (`sample1.kdf`).

Para gerar um relatório, escreva o seguinte comando na consola: `kugar `-r `sample1.ktf`` `-d `sample1.kdf```

Isto faz aparecer uma janela do &kugar; com o relatório gerado. Relatório gerado