<!-- 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 >Pedro</firstname ><surname >Morais</surname ><affiliation ><address ><email >morais@kde.org</email ></address ></affiliation ><contrib >Tradução</contrib ></othercredit > </authorgroup> </chapterinfo> <title >Tutorial</title> <para >Este tutorial tenta ser uma breve introdução ao Kugar.</para> <para >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.</para> <para >O código-fonte para os modelos dos exemplos e os ficheiros de dados poderão ser encontrados no <filename >sample1.ktf</filename > e no <filename >sample1.kdf</filename > que são distribuídos com o &kugar;.</para> <sect1 id="tut-1"> <title >Criar o modelo de relatório com o &kudesigner;</title> <para >Execute o Kugar Designer ao escrever <command >kudesigner</command > na linha de comandos. </para> <para >Depois de iniciar o desenhador, escolha a opção <guimenu >Ficheiro</guimenu >|<guilabel >Novo</guilabel > e configure o tamanho da página para <guilabel >Carta</guilabel > e a direcção do papel como <guilabel >Paisagem</guilabel >. 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. <screenshot > <mediaobject> <imageobject> <imagedata fileref="tut_file_new.png" format="PNG"/> </imageobject> <textobject> <phrase >Janela de <interface >Novo Relatório</interface ></phrase> </textobject> </mediaobject> </screenshot> </para> <para >Está criado agora um novo relatório e todos os botões da <guilabel >Barra de Itens</guilabel > e da <guilabel >Barra de Secções</guilabel > estão agora activos (os itens de menu correspondentes em <guilabel >Itens</guilabel > e <guilabel >Secções</guilabel > ficam também activos). <screenshot > <mediaobject> <imageobject> <imagedata fileref="tut_empty_report.png" format="PNG"/> </imageobject> <textobject> <phrase >Janela de Relatório Vazio</phrase> </textobject> </mediaobject> </screenshot> </para> <para >Agora é a altura de adicionar algumas secções ao relatório e de determinar os seus tamanhos. Serão adicionados o <link linkend="report-header-and-footer" >cabeçalho e o rodapé do relatório</link >, o <link linkend="page-header-and-footer" >cabeçalho e o rodapé da página</link > e uma única secção de <link linkend="detail" >detalhe</link >. 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 <link linkend="calculated-field-element" >campos calculados</link >. 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 <filename >sample3.kut</filename > e o <filename >sample3.kud</filename > para ver um exemplo de como isto poderá ser feito. Veja as <link linkend="template-elements" >descrições dos elementos do modelo</link > para mais informações. </para> <para >As secções são adicionadas ao usar o menu <guilabel >Secções</guilabel > ou uma <guilabel >Barra de Secções</guilabel >. 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. <screenshot > <mediaobject> <imageobject> <imagedata fileref="tut_set_level.png" format="PNG"/> </imageobject> <textobject> <phrase >Modificar o nível de detalhe</phrase> </textobject> </mediaobject> </screenshot> </para> <para >O relatório deverá agora ficar parecido com o desta imagem. <screenshot > <mediaobject> <imageobject> <imagedata fileref="tut_rep_look1.png" format="PNG"/> </imageobject> <textobject> <phrase >Relatório com secções</phrase> </textobject> </mediaobject> </screenshot> </para> <para >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 <guilabel >Editar as Propriedades</guilabel > da <guilabel >Barra de Edição</guilabel > e, finalmente, escolha uma secção. A janela de propriedades deverá então aparecer. <screenshot > <mediaobject> <imageobject> <imagedata fileref="tut_edit_height.png" format="PNG"/> </imageobject> <textobject> <phrase >Altura da edição da secção</phrase> </textobject> </mediaobject> </screenshot> </para> <para >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. </para> <para >Um modelo de relatório com as secções devidamente dimensionadas está pronto a ser preenchido com os itens do relatório. <screenshot > <mediaobject> <imageobject> <imagedata fileref="tut_rep_look2.png" format="PNG"/> </imageobject> <textobject> <phrase >Relatório com secções dimensionadas</phrase> </textobject> </mediaobject> </screenshot> </para> <para >Poderá agora adicionar itens às secções do relatório. Poderão ser adicionados cinco tipos diferentes de itens. A <link linkend="label-element" >Legenda</link > é 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 <link linkend="field-element" >Campo</link > 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 <link linkend="calculated-field-element" >Campos Calculados</link >. Os <link linkend="special-element" >Especiais</link > 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 <link linkend="line-element" >Linhas</link >. </para> <para >Para adicionar um item do relatório, carregue no botão do item corresponde da <guilabel >Barra de Itens</guilabel > 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 <guilabel >Opções do Item de Relatório</guilabel > (da mesma forma como foi alterada a altura da secção). </para> <para >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 <quote >Mutiny Bay Software</quote > tem o seu <guilabel >BorderStyle</guilabel > e o seu <guilabel >BorderWidth</guilabel > iguais a 0 e o <quote >Software Inventory Report</quote > - 1mm. Todas as cores estão definidas como uma combinação de três valores (RGB- vermelho, verde e azul) separados por vírgulas. </para> <para >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 <guilabel >Campo</guilabel >, assim como deverão ser configuradas as propriedades do <guilabel >Campo</guilabel >. Lembre-se que a propriedade do <guilabel >Texto</guilabel > é configurada automaticamente como <quote >[<userinput >nome_campo</userinput >]</quote >. </para> <para >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 <guilabel >Type</guilabel > 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 <guilabel >Text</guilabel > do item especial é alterada automaticamente. </para> <para >O último elemento a ser colocado é o <guilabel >Campo Calculado</guilabel > para o campo <quote >cópias</quote >. Para adquirir um conjunto de som da cópias, configure a propriedade <guilabel >Field</guilabel > do campo calculado como sendo o <quote >copies</quote > e o <guilabel >CalculationType</guilabel > igual a 1 (a função de soma). </para> <para >Finalmente, o nosso modelo de relatório deve ter este aspecto: <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 >Criar o ficheiro de dados do relatório</title> <para >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 <filename >sample1.kdf</filename > ou copiado do exemplo abaixo. </para> <programlisting ><?xml version=<quote >1.0</quote > encoding=<quote >UTF-8</quote >?> <!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> </programlisting> </sect1> <sect1 id="tut-3"> <title >Gerar o relatório</title> <para >Neste momento temos um modelo de relatório (<filename >sample1.ktf</filename >) e um ficheiro de dados de relatório (<filename >sample1.kdf</filename >). </para> <para >Para gerar um relatório, escreva o seguinte comando na consola: <command >kugar <option >-r <replaceable >sample1.ktf</replaceable ></option > <option >-d <replaceable >sample1.kdf</replaceable ></option ></command > </para> <para >Isto faz aparecer uma janela 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>