Alexander Dymo

    cloudtemple@mksat.net

Phil Thompson

    phil@river-bank.demon.co.uk

Marcus Gama

    marcus.gama@gmail.com

Tradução

# 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 dos exemplos e os arquivos de dados poderão ser encontrados no `sample1.ktf` e no `sample1.kdf` 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).

Janela de Relatório Vazio

Agora é hora de adicionar algumas seções ao relatório e determinar os seus tamanhos. Nós adicionaremos o cabeçalho e o rodapé do relatório, o cabeçalho e o rodapé da página e uma única seção de detalhe. Os cabeçalhos e rodapés do relatório são impressos na primeira página e na última página do relatório antes 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 seçã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 seções são adicionadas usando o menu Seções ou uma Barra de Seçõ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 seção de detalhe, coloque o seu nível a 0 como é mostrado na imagem abaixo.

Configurando o nível de detalhe

Nosso relatório deverá parecer agora como este na captura de tela.

Relatório com seções

Todas as seções do exemplo possuem uma altura pré-definida - 50 mm. Vamos mudá-la. Para fazer isso, clique com o &RMB; na seção do Cabeçalho do Relatório ou clique no botão Editar Propriedades da Barra de Edição e, finalmente, escolha uma seção. A janela de propriedades deverá então aparecer.

Edição da altura da seção

Defina agora a altura do Cabeçalho do Relatório como sendo igual a 70. Vamos executar este procedimento para todas as outras seçõ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 seções dimensionadas corretamente está pronto para ser preenchido com itens de relatório.

Relatório com as seções dimensionadas

Você poderá agora adicionar itens às seções do relatório. Poderão ser adicionados cinco tipos diferentes de itens. A Legenda é uma área retangular que poderá ter uma borda 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 fonte, poderão ser alterados. Os tipos de borda e as cores das linhas poderão também ser personalizadas. O Campo poderá ser colocado numa seção de detalhe. Os campos representam campos de dados e os seus valores serão obtidos a partir de um arquivo 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 pré-definido, como a data atual ou o número de página. A aparência geral do relatório pode ser refinada com as 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).

Assim, vamos adicionar legendas ao cabeçalho e ao rodapé do relatório, tal como mostrado na imagem abaixo. Note 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.

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

O rodapé da página é um bom local para mostrar a data atual e o número da página, assim deverão ser adicionados dois campos especiais e configurados 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. Note que a propriedade Text do ítem especial é alterada automaticamente.

O último elemento a ser colocado é o Campo Calculado para o campo cópias. Para adquirir um conjunto de soma 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, nosso modelo de relatório deve parecer-se com isto:

Relatório completo

## Criando um arquivo de dados de relatório

De um modo geral, os arquivos 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 planilha do &kspread;); outros irão usar o seu próprio programa para obter os dados de um banco de dados e preencher o arquivo de dados. Neste tutorial, nós simplesmente criaremos este arquivo de maneira manual. O código-fonte do exemplo, poderá ser encontrado no arquivo `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>

## Gerando o relatório

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

Para gerar um relatório, digite o seguinte comando no console: `kugar `-r sample1.ktf` `-d sample1.kdf``

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

Relatório gerado