<!-- 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="prog-guide">
<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@gmail.com</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
>
</authorgroup>
</chapterinfo>
<title
>Guia do Programador</title>
<sect1 id="how-to-use-in-progs">
<title
>Como usar o &kugar; para criar relatórios em seus próprios programas</title>
<itemizedlist>
<title
>Existem muitas maneiras de usar o &kugar;</title>
<listitem>
<para
>Crie um arquivo temporário e preencha-o com dados, organizados de acordo com a <link linkend="kugardata-dtd"
>Definição do Tipo de Documento KugarData</link
>. Em seguida, invoque o comando <command
>kugar</command
> ( <cmdsynopsis
> <command
>kugar</command
> <group
> <option
>-d <replaceable
>arquivo de dados do Kugar</replaceable
></option
> </group
> <group
> <option
>-r <replaceable
>arquivo de modelo do Kugar</replaceable
></option
> </group
> </cmdsynopsis
> ) para pré-visualizar e imprimir o relatório. Veja a seção <link linkend="prog-using-for-preview"
>Usando o &kugar; para pré-visualizar os relatórios</link
> para uma descrição detalhada. </para>
</listitem>
<listitem>
<para
>Use o &kugar; diretamente no código da aplicação. Veja a seção <link linkend="prog-using-widget"
>Usando as classes do &kugar; para a geração de relatórios</link
> para uma descrição detalhada. </para>
</listitem>
<listitem>
<para
>Crie um plugin no &Qt; designer, use-o para criar a &GUI; da aplicação no desenhador e compile dinamicamente com o programa. Veja a seção <link linkend="prog-designer-plugin"
>Criando um plugin do &Qt; designer</link
> para uma descrição detalhada. </para>
</listitem>
</itemizedlist>
<para
>As duas últimas formas são aceitáveis para os programadores de &Qt; e do &kde;, mas o &kugar; está desenhado para ser um gerador de relatórios independente da linguagem de programação e/ou <acronym
>IDE</acronym
>. Ele usa o formato &XML; para descrever os modelos de relatórios e os arquivos de dados. Assim, qualquer programa consegue produzir resultados no formato do arquivo de dados do &kugar; tal como está descrito na <link linkend="kugardata-dtd"
><acronym
>DTD</acronym
> do KugarData</link
> ou mesmo no formato de arquivo do modelo de relatório (veja a <link linkend="template-dtd"
><acronym
>DTD</acronym
> do KugarTemplate</link
>). Poderá ser usado um comando do &kugar; (visualizador de relatórios) para pré-visualizar e imprimir os resultados gerados. </para>
</sect1>
<sect1 id="prog-using-for-preview">
<title
>Usar o shell &kugar; para visualizar relatórios</title>
<orderedlist>
<title
>A maneira de criar e pré-visualizar (impressão) um relatório é:</title>
<listitem>
<para
>Criar um arquivo de modelo de relatório com o &kudesigner; </para>
</listitem>
<listitem>
<para
>Criar uma arquivo de dados com valores de coluna para as bandas de detalhe do relatório. Use <link linkend="kugardata-dtd"
>KugarData <acronym
>DTD</acronym
></link
> para produzir arquivos de dados corretos. </para>
</listitem>
<listitem>
<para
>Executar o shell &kugar; para visualizar e imprimir um relatório. Por exemplo, para fazer isto, nas linguagens c ou c++ chame:</para>
<programlisting
><function
>system(<option
>"kugar -r <replaceable
>arquivo_modelo.ktf</replaceable
>-d <replaceable
>arquivo_dados.kdf</replaceable
>"</option
>)</function
>.
</programlisting>
<para
>Não esqueça de incluir <filename class="headerfile"
>stdlib.h</filename
>. </para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="prog-using-widget">
<title
>Usar uma classe &kugar; para relatório</title>
<para
>A biblioteca &kugar; contém dois elementos para uso. </para>
<para
>A classe <classname
>KReportViewer</classname
> está desenhada para os programadores do &kde;. Suporta um sistema de impressão do &kde; e a localização no &UNIX; através das chamadas <function
>i18n()</function
>. </para>
<para
>O <classname
>MReportViewer</classname
> está desenhado para os programadores do &Qt; e possibilita o suporte multi-plataforma real. Pode ser usado não só nas plataformas &UNIX;, mas também no &Windows; e no &MacOS;. </para>
<para
>Para conseguir construir programas que usam a biblioteca do &kugar;, ele deve ser ligado com a biblioteca compartilhada <filename
>libkugar.so</filename
>, que é fornecida com a distribuição do &kugar; em todas as plataformas &UNIX;. </para>
<para
>Os arquivos de inclusão são o <filename
>kugarqt.h</filename
> e <filename
>kugar.h</filename
> para os programas &Qt; e &kde; respectivamente. </para>
<para
>Para um exemplo detalhado de como as classe do &kugar; podem ser usadas, veja a pasta <filename class="directory"
>/shell</filename
> nas fontes do &kugar;. </para>
<para
>A <classname
>MReportViewer</classname
> (e a <classname
>KReportViewer</classname
> too) contêm vários métodos públicos que podem ser usados. </para>
<funcsynopsis>
<funcprototype>
<funcdef
>void <function
>renderReport</function
></funcdef>
<void/>
</funcprototype>
<funcsynopsisinfo
>Renderiza o relatório para um tela.</funcsynopsisinfo>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef
>void <function
>printReport</function
></funcdef>
<void/>
</funcprototype>
<funcsynopsisinfo
>Chama o diálogo de impressão para imprimir o relatório.</funcsynopsisinfo>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef
>void <function
>clearReport</function
></funcdef>
<void/>
</funcprototype>
<funcsynopsisinfo
>Limpa o relatório na tela e libera os dados do relatório. Chame isto antes de abrir um novo relatório.</funcsynopsisinfo>
>. Por exemplo, para obter o modelo do relatório a partir de um armazenamento em rede ou de um banco de dados, crie uma filha da classe TQIODevice e redefina toda a funcionalidade necessária. </funcsynopsisinfo>
