koffice-i18n/koffice-i18n-pt_BR/docs/koffice/chalk/developers-plugins.docbook

<sect1 id="developers-plugins">
<title
>Desenvolvendo Plugins para o &chalk;</title>

<sect2 id="developers-plugins-introduction">
<title
>Introdução</title>

<para
>O &chalk; é infinitamente extensível com plugins. As ferramentas, filtros e grandes blocos da interface do usuário, ou até mesmo os espaços de cores, são plugins. De fato, o &chalk; reconhece estes seis tipos de plugins: </para>

<itemizedlist>
<listitem
><para
>espaços de cores &mdash; eles definem os canais que constituem um único pixel</para
></listitem>
<listitem
><para
>ferramentas &mdash; tudo o que é feito com um mouse ou outro dispositivo de apontamento</para
></listitem>
<listitem
><para
>operações de pintura &mdash; efeitos de pintura acopláveis para as ferramentas</para
></listitem>
<listitem
><para
>filtros de imagens &mdash; muda todos os pixels, ou apenas os pixels selecionados de uma camada</para
></listitem>
<listitem
><para
>plugins de visualização &mdash; estende a interface de usuário do Chalk com novas janelas, paletas e operações</para
></listitem>
<listitem
><para
>filtros de importação/exportação &mdash; lê e grava todos os tipos de formatos de imagem</para
></listitem>
</itemizedlist>

<para
>O &chalk; em si consiste de três bibliotecas em camadas e de uma pasta com algumas classes comuns de suporte: chalkcolor, chalkimage e chalkui. Dentro do &chalk;, os objetos podem ser identificados por um <classname
>KisID</classname
>, que é a combinação de um texto não-traduzido único (usado ao salvar, por exemplo) e um texto traduzido, para fins de interface. </para
><para
>Uma palavra sobre a compatibilidade: o &chalk; está ainda em desenvolvimento. Do &chalk; 1.5 até o 1.6, não são esperadas muitas mudanças da API, mas poderão ocorrer algumas. Do &chalk; 1.6 para o 2.0 haverá uma mudança do &Qt;3 para o &Qt;4, do &kde;3 para o &kde;4, do <command
>automake</command
> para o <command
>cmake</command
>: esperam-se muitas alterações. Se desenvolver um plugin para o &chalk; e optar por fazê-lo na versão em Subversion do &chalk;, você tem grandes chances de obter ajuda da equipe de desenvolvimento na passagem para a nova versão. Estas alterações também poderão levantar algumas partes deste documento que estejam desatualizadas. Verifique sempre a última documentação da API ou os arquivos de inclusão instalados no seu sistema. </para>

<sect3 id="developers-plugins-introduction-chalkcolor">
<title
>ChalkColor</title>

<para
>A primeira biblioteca é a 'chalkcolor'. Esta biblioteca carrega os plugins de espaços de cores. </para
><para
>Um plugin de espaço de cores deverá implementar a classe abstrata <classname
>KisColorSpace</classname
> ou, se as capacidades básicas do novo espaço de cores forem implementadas pelo <command
>lcms</command
> (<ulink url="http://www.littlecms.com/"
></ulink
>), estender o <classname
>KisAbstractColorSpace</classname
>. A biblioteca 'chalkcolor' poderá ser usada em outras aplicações e não depende do &koffice;. </para>
</sect3>

<sect3 id="developers-plugins-introduction-chalkimage">
<title
>ChalkImage</title>

<para
>A biblioteca 'libchalkimage' carrega os plugins de filtros e operações de pintura, e é responsável por lidar com os dados da imagem: mudar os pixels, compor e pintar. Os pincéis, paletas, gradientes e padrões são também carregados pela 'libchalkimage'. O nosso objetivo é tornar a 'libchalkimage' independente do &koffice;, mas atualmente nós compartilhamos o código de carregamento dos gradientes com o &koffice;. </para
><para
>Não é possível, por enquanto, adicionar tipos novos de recursos, como os pincéis, paletas, gradientes ou padrões ao &chalk;. (A adição de pincéis, paletas, gradientes e padrões novos, obviamente.). O &chalk; segue as linhas-guia do projeto Create (<ulink url="http://create.freedesktop.org/"
></ulink
>) para isso. A adição do suporte para o formato de pincéis do Photoshop precisa de algumas alterações na 'libchalkimage'; por outro lado, a adição de mais arquivos de dados de pincéis do 'gimp' não precisa. </para
><para
>O <classname
>ChalkImage</classname
> carrega os seguintes tipos de plugins: </para>

<itemizedlist>
<listitem
><para
>Os filtros do &chalk; deverão estender e implementar a classe abstrata <classname
>KisFilter</classname
>, <classname
>KisFilterConfiguration</classname
> e, possivelmente, a <classname
>KisFilterConfigurationWidget</classname
>. Um exemplo destes filtros é a Máscara Não-Nítida.</para
></listitem>
<listitem
><para
>As operações de pintura são o conjunto de operações de pintura, como o desenho livre ou a circunferência, os sprays ou a borracha. As operações de pintura deverão estender a classe de base <classname
>KisPaintop</classname
>. Os exemplos de novas operações de pintura seriam o pincel de giz, um pincel a óleo ou um pincel programável complexo.</para
></listitem>
</itemizedlist>

</sect3>

<sect3 id="developers-plugins-introduction-chalkui">
<title
>ChalkUI</title>

<para
>A biblioteca 'libchalkui' carrega os plugins de ferramentas e de visualização. Esta biblioteca é um componente do &koffice;, mas também contém um conjunto de elementos úteis para outras aplicações gráficas. Talvez nós tenhamos que dividir esta biblioteca em 'chalkpart' e 'chalkui' na versão 2.0. Por enquanto, os criadores de programas não têm acesso a esta biblioteca e os criadores de plugins só têm permissão para usar esta biblioteca ao criar ferramentas ou plugins de visualização. O <classname
>ChalkUI</classname
> carrega os seguintes tipos de plugins: </para>

<itemizedlist>
<listitem
><para
>As ferramentas derivam da <classname
>KisTool</classname
> ou de uma das classes de base especializadas, como a <classname
>KisToolPaint</classname
>, a <classname
>KisToolNonPaint</classname
> ou a <classname
>KisToolFreehand</classname
>. Uma nova ferramenta poderia ser uma ferramenta de seleção do objeto em primeiro plano. As ferramentas de pintura (e estas incluem as que pintam sobre os dados selecionados) poderão usar qualquer operação de pintura para determinar a forma como os pixels são alterados.</para
></listitem>
<listitem
><para
>Os plugins de visualização são KParts normais que usam o <command
>kxmlgui</command
> para se publicarem eles mesmos na interface de usuário do &chalk;. As opções do menu, as janelas, barras de ferramentas &mdash; qualquer tipo de extensão da interface poderá ser um plugin de visualização. De fato, algumas funcionalidades importantes como o suporte de programação do &chalk; é feita como um plugin de visualização.</para
></listitem>
</itemizedlist>

</sect3>

<sect3 id="developers-plugins-introduction-importexport">
<title
>Filtros de importação/exportação</title>

<para
>Os filtros de importação/exportação são os filtros do &koffice;, sub-classes de  <classname
>KoFilter</classname
>. Os filtros lêem e salvam os dados da imagem, em qualquer um da miríade de formatos de imagem existentes. Um exemplo de um novo filtro de importação/exportação do &chalk; será um filtro de PDF. Os filtros são carregados pelas bibliotecas do &koffice;. </para>

</sect3>

</sect2>

<sect2 id="developers-plugins-creating">
<title
>Criando plugins</title>

<para
>Os plugins são escritos em C++ e poderão usar toda a API de programação do &kde;, do &Qt; e do &chalk;. Somente os plugins de visualização deverão usar a API do &koffice;. Não se preocupe: as APIs do &chalk; são bem claras e relativamente bem documentadas (no caso do 'software' livre); além disso, a codificação do seu primeiro filtro é realmente simples. </para
><para
>Se você não quiser usar o C++, poderá criar programas em Python ou em Ruby; isto já é uma coisa diferente, e você atualmente não consegue criar ferramentas, espaços de cores, operações de pintura ou filtros de importação/exportação desta forma. </para
><para
>Os plugins do &chalk; usam o mecanismo de componentes do &kde; para se carregarem; por isso, a documentação de componentes em <ulink url="http://developer.kde.org"
></ulink
> também é aqui relevante. </para
><para
>A sua distribuição já deverá ter instalado os arquivos de inclusão relevantes para o &chalk;, ou poderá ter dividido os arquivos em pacotes de desenvolvimento do &koffice; ou do &chalk;. Você poderá encontrar a documentação da API pública do &chalk; em <ulink url="http://koffice.org/developer/apidocs/chalk/html/"
></ulink
>. </para>

<sect3 id="developers-plugins-creating-automake">
<title
>Automake (e CMake)</title>

<para
>O &kde; 3.x e, deste modo, o &koffice; 1.5 e o 1.6 usam o <command
>automake</command
>; o &kde; 4.0 e o &koffice; 2.0 usam o <command
>cmake</command
>. Este tutorial descreve a forma do <command
>automake</command
> criar plugins. </para
><para
>Os plugins são módulos do &kde; e deverão ser assinalados como tal no seu <filename
>Makefile.am</filename
>. Os filtros, ferramentas, operações de pintura, espaços de cores e filtros de importação/exportação necessitam dos arquivos <literal role="extension"
>.desktop</literal
>; os plugins de visualização necessitam de um arquivo do <application
>KXMLGui</application
> <filename
>nomeplugin.rc</filename
> adicionalmente. A forma mais simples de começar é extrair o projeto 'chalk-plugins', do repositório de Subversion do &koffice;, e usá-lo como base para o seu próprio projeto. Nós pretendemos preparar um pacote com um esqueleto de plugin do &chalk; para o KDevelop, mas isso ainda não foi feito. </para>

<sect4 id="d-p-c-a-makefile">
<title
><filename
>Makefile.am</filename
></title>

<para
>Vejamos um esqueleto de um módulo de plugin. Em primeiro lugar, o <filename
>Makefile.am</filename
>. Isto é o que o &kde; usa para gerar a Makefile que cria o seu plugin: <programlisting>
kde_services_DATA = chalkNOMEBIBLIOTECA.desktop

INCLUDES = $(all_includes)

chalkNOMEBIBLIOTECA_la_SOURCES = arquivo1.cpp arquivo2.cpp

kde_module_LTLIBRARIES = chalkNOMEBIBLIOTECA.la
noinst_HEADERS = inclusao1.h inclusao2.h

chalkNOMEBIBLIOTECA_la_LDFLAGS = $(all_libraries) -module $(KDE_PLUGIN)
chalkBIBLIOTECA_la_LIBADD = -lchalkcommon

chalkextensioncolorsfilters_la_METASOURCES = AUTO
</programlisting
> Este é o Makefile de um plugin de filtro. Substitua o <replaceable
>NOMEBIBLIOTECA</replaceable
> pelo nome da seu trabalho, e é tudo. </para
><para
>Se o seu plugin for de visualização, provavelmente você também instalou um arquivo <literal role="extension"
>.rc</literal
> com ítens para os menus e as barras de ferramentas. Da mesma forma, você poderá ter que instalar os cursores e os ícones. Isto tudo é feito com as magias do <filename
>Makefile.am</filename
> do &kde;: <programlisting
>chalkrcdir = $(kde_datadir)/chalk/chalkplugins
chalkrc_DATA = NOMEBIBLIOTECA.rc
EXTRA_DIST = $(chalkrc_DATA)

chalkpics_DATA = \
   bla.png \
   bla_cursor.png
chalkpicsdir = $(kde_datadir)/chalk/pics
</programlisting>

</para>
</sect4>

<sect4 id="d-p-c-a-desktop">
<title
>Arquivos 'desktop'</title>

<para
>O arquivo <literal role="extension"
>.desktop</literal
> anuncia o tipo de plugin: <programlisting
>[Desktop Entry]
Encoding=UTF-8
Icon=
Name=Nome Visível
ServiceTypes=Chalk/Filter
Type=Service
X-TDE-Library=chalkNOMEBIBLIOTECA
X-TDE-Version=2
</programlisting>
</para
><para
>Os ServiceTypes (tipos de serviços) possíveis são: </para>

<itemizedlist>
<listitem
><para
>Chalk/Filter</para
></listitem>
<listitem
><para
>Chalk/Paintop</para
></listitem>
<listitem
><para
>Chalk/ViewPlugin</para
></listitem>
<listitem
><para
>Chalk/Tool</para
></listitem>
<listitem
><para
>Chalk/ColorSpace</para
></listitem>
</itemizedlist>

<para
>Os filtros de importação e exportação de arquivos usam a plataforma de filtros genérica do &koffice; e precisam ser discutidos separadamente. </para>
</sect4>

<sect4 id="d-p-c-a-boilerplate">
<title
>Auxiliares</title>

<para
>Você também precisa de um pouco de código auxiliar, chamado de plataforma de componentes do &kde;, para instanciar o plugin &mdash; um arquivo de inclusão e um arquivo de implementação. </para
><para
>Um arquivo de inclusão: <programlisting
>#ifndef FERRAMENTA_ESTRELA_H_
#define FERRAMENTA_ESTRELA_H_

#include &lt;tdeparts/plugin.h&gt;

/**
* Um módulo que oferece uma ferramenta de estrela.
*/
class FerramentaEstrela : public KParts::Plugin
{
   TQ_OBJECT
public:
   FerramentaEstrela(TQObject *mae, const char *nome, const QStringList &amp;);
   virtual ~FerramentaEstrela();

};

#endif // TOOL_STAR_H_
</programlisting>
</para>

<para
>E um arquivo de implementação: <programlisting
>#include &lt;kinstance.h&gt;
#include &lt;kgenericfatory.h&gt;

#include &lt;kis_tool_registry.h&gt;

#include "ferramenta_estrela.h"
#include "kis_ferramenta_estrela.h"


typedef KGenericfatory&lt;FerramentaEstrela&gt; FerramentaEstrelafatory;
K_EXPORT_COMPONENT_fatoRY( chalktoolstar, FerramentaEstrelafatory( "chalk" ) )


FerramentaEstrela::FerramentaEstrela(TQObject *mae, const char *nome, const QStringList &amp;)
   : KParts::Plugin(mae, nome)
{
   setInstance(FerramentaEstrelafatory::instance());
   if ( mae->inherits("KisToolRegistry") )
   {
       KisToolRegistry * r = dynamic_cast&lt;KisToolRegistry*&gt;( mae );
       r -> add(new KisFerramentaEstrelafatory());
   }

}

FerramentaEstrela::~FerramentaEstrela()
{
}

#include "ferramenta_estrela.moc"
</programlisting>
</para>
</sect4>

<sect4 id="d-p-c-a-registries">
<title
>Registros</title>

<para
>As ferramentas são carregadas pelo registro de ferramentas e registram-se elas mesmas com o registro de ferramentas. Os plugins, como as ferramentas, os filtros e as operações de pintura são carregados apenas uma vez: os plugins de visualização são carregados para cada janela criada. Note que são registradas 'factories' (fábricas de objetos), de um modo geral. Por exemplo, com as ferramentas, é criada uma nova instância de uma ferramenta para cada ponteiro (mouse, tablete, borracha). Uma operação de pintura nova é criada sempre que uma ferramenta recebe um evento de botão do mouse pressionado. </para>

<para
>Os filtros invocam o registro de filtros: <programlisting
>if (mae->inherits("KisFilterRegistry")) {
       KisFilterRegistry * gestor = dynamic_cast&lt;KisFilterRegistry *&gt;(mae);
       gestor->add(new KisFilterInvert());
   }
</programlisting>
</para
><para
>As operações de pintura invocam o seu próprio registro: <programlisting
>if ( mae->inherits("KisPaintOpRegistry") ) {
           KisPaintOpRegistry * r = dynamic_cast&lt;KisPaintOpRegistry*&gt;(mae);
           r -> add ( new KisSmearyOpfatory );
   }
</programlisting>
</para
><para
>Os espaços de cores procuram no registro de espaços de cores (com mais algumas complicações): <programlisting
>if ( mae->inherits("KisColorSpacefatoryRegistry") ) {
        KisColorSpacefatoryRegistry * f = dynamic_cast&lt;isColorSpacefatoryRegistry*&gt;(mae);

       KisProfile *perfilOmissao = new KisProfile(cmsCreate_sRGBProfile());
       f->addProfile(perfilOmissao);

       KisColorSpacefatory * fabrica = new KisRgbColorSpacefatory();
       f->add(fabrica);
   
       KisColorSpace * espacoCoresRGBA = new KisRgbColorSpace(f, 0);
       KisHistogramProducerfatoryRegistry::instance() -> add(
               new KisBasicHistogramProducerfatory&lt;KisBasicU8HistogramProducer&gt;
               (KisID("RGB8HISTO", i18n("RGB8 Histogram")), espacoCoresRGBA) );
   }
</programlisting>
</para
><para
>Os plugins de visualização não têm que se registrar eles mesmos, obtendo o acesso a um objeto <classname
>KisView</classname
>: <programlisting
>if ( mae->inherits("KisView") )
   {
       setInstance(ShearImagefatory::instance());
       setXMLFile(locate("data","chalkplugins/shearimage.rc"), true);

       (void) new TDEAction(i18n("&amp;Shear Image..."), 0, 0, this, TQ_SLOT(slotShearImage()), actionCollection(), "shearimage");
       (void) new TDEAction(i18n("&amp;Shear Layer..."), 0, 0, this, TQ_SLOT(slotShearLayer()), actionCollection(), "shearlayer");

       m_vista = (KisView*) mae;
   }
</programlisting>
</para
><para
>Lembre-se que isto significa que será criado um plugin de visualização para cada visualização que o usuário cria: a divisão de uma janela significa carregar todos os plugins de visualização novamente. </para>
</sect4>

<sect4 id="d-p-c-a-versioning">
<title
>Versões dos plugins</title>

<para
>O &chalk; 1.5 carrega os plugins com o <literal
>X-TDE-Version=2</literal
> definido no arquivo <literal role="extension"
>.desktop</literal
>. Os plugins do &chalk; 1.6 serão provavelmente incompatíveis a nível binário com os do 1.5 e irão necessitar da versão 3. Os plugins do &chalk; 2.0 irão necessitar do número de versão 3. Sim, isto não totalmente lógico. </para>

</sect4>
</sect3>
</sect2>

<sect2 id="developers-plugins-colorspaces">
<title
>Espaços de Cores</title>

<para
>Os espaços de cores implementam a classe virtual pura <classname
>KisColorSpace</classname
>. Existem dois tipos de espaços de cores: aqueles que podem usar o <command
>lcms</command
> para as transformações de espaços de cores e aqueles que são muito estranhos para o <command
>lcms</command
> lidar com eles. Os exemplos dos primeiros são o 'cmyk', o 'rgb' ou o 'yuv'. Um exemplo do último é o de cores de água ou o molhado &amp; pegajoso. Os espaços de cores que usam o <command
>lcms</command
> podem ser derivados do <classname
>KisAbstractColorSpace</classname
> ou de uma das classes de base especializadas para um determinado número de 'bits' por canal. </para
><para
>A implementação de um espaço de cores é relativamente simples. O princípio geral é que os espaços de cores funcionam com uma lista simples de 'bytes'. A interpretação desses 'bytes' pertence ao espaço de cores. Por exemplo, um pixel em Cinza de 16 bits consiste em quatro 'bytes': dois para o valor de cinza e dois para o valor do 'alfa'. Você é livre para usar uma estrutura, de modo a lidar com a disposição em memória de um pixel, na sua implementação do espaço de cores, mas essa representação não é exportada. A única forma com que o resto do &chalk; consegue saber os canais e tipos de canais em que os pixels do seu espaço de cores consistem é através da classe <classname
>KisChannelInfo</classname
>. </para
><para
>Os filtros e operações de pintura tiram partido do rico conjunto de métodos oferecidos pelo <classname
>KisColorSpace</classname
>, para fazer o seu trabalho. Em muitos dos casos, a implementação padrão no <classname
>KisAbstractColorSpace</classname
> irá funcionar, mas de forma mais lenta que uma implementação personalizada no seu espaço de cores, uma vez que o <classname
>KisAbstractColorSpace</classname
> irá converter todos os pixels para L*a*b de 16 bits e vice-versa. </para>

<sect3 id="developers-plugins-colorspaces-kischannelinfo">
<title
><classname
>KisChannelInfo</classname
></title>

<programlisting
>(http://websvn.kde.org/trunk/koffice/chalk/chalkcolor/kis_channelinfo.h)
</programlisting>
<para
>Esta classe define os canais que compõem um único pixel num espaço de cores em particular. Um canal tem as seguintes características importantes: </para>
<itemizedlist>
<listitem
><para
>um nome a apresentar na interface do usuário</para
></listitem>
<listitem
><para
>uma posição: o 'byte' onde os 'bytes' que representam este canal começam no pixel.</para
></listitem>
<listitem
><para
>um tipo: cor, alfa, substância ou substrato. A cor é uma cor simples, o 'alfa' é a capacidade de transparência, a substância é uma representação da quantidade de pigmento ou outras coisas do género e o substrato é a representação da área de desenho ou tela. (Lembre-se que isto pode ser mudado em breve.)</para
></listitem>
<listitem
><para
>um tipo de valor: 'byte', 'short', 'integer', 'float' — ou outro.</para
></listitem>
<listitem
><para
>tamanho: o número de 'bytes' que este canal ocupa</para
></listitem>
<listitem
><para
>cor: uma representação num <classname
>TQColor</classname
> deste canal, para ser visualizado na interface do usuário como, por exemplo, em histogramas.</para
></listitem>
<listitem
><para
>uma abreviatura a usar na GUI, quando não existir muito espaço</para
></listitem>
</itemizedlist>
</sect3>

<sect3 id="developers-plugins-colorspaces-kiscompositeop">
<title
><classname
>KisCompositeOp</classname
></title>

<para
>Um Porter-Duff por original; existem várias formas de combinar os pixels para obter uma cor nova. A classe <classname
>KisCompositeOp</classname
> define a maior parte delas: este conjunto não é facilmente extensível, exceto modificando a biblioteca 'chalkcolor'. </para
><para
>Um plugin de espaço de cores consegue suportar qualquer sub-conjunto destas operações de composição possíveis, mas o conjunto deverá sempre incluir o "OVER" (o mesmo que o "NORMAL") e o "COPY". O resto é mais ou menos opcional, ainda que quanto mais, melhor, obviamente. </para>
</sect3>

<sect3 id="developers-plugins-colorspaces-kiscolorspace">
<title
><classname
>KisColorSpace</classname
></title>

<para
>Os métodos da classe virtual pura <classname
>KisColorSpace</classname
> podem ser divididos num conjunto de grupos: conversão, identificação e manipulação. </para
><para
>Todas as classes deverão ser capazes de converter um pixel de e para RGB de 8 bits (i.e., um <classname
>TQColor</classname
>) e, de preferência, de e para L*a*b de 16 bits. Além disso, existe um método para converter para qualquer espaço de cores a partir do atual. </para
><para
>Os espaços de cores são descritos pelo vetor <classname
>KisChannelInfo</classname
>, o número de canais, o número de 'bytes' em cada pixel, se suporta imagens de Intervalo Altamente Dinâmico, entre outras definições. </para
><para
>A manipulação é, por exemplo, a combinação de dois pixels num único novo: bitBlt, escurecimento ou convolução de pixels. </para
><para
>Consulte por favor a documentação da API para uma descrição completa de todos os métodos que precisa implementar num espaço de cores. </para
><para
>O <classname
>KisAbstractColorSpace</classname
> implementa muitos dos métodos virtuais do <classname
>KisColorSpace</classname
>, usando as funções da biblioteca <command
>lcms</command
>. Sobre a classe <classname
>KisAbstractColorSpace</classname
>, existem classes de espaços de cores de inteiros de 8 e 16 bits, assim como de ponto flutuante de 16 e 32 bits, definindo as operações comuns para mudar a profundidade de cor. </para>

</sect3>
</sect2>

<sect2 id="developers-plugins-filters">
<title
>Filtros</title>

<para
>Os filtros são plugins que examinam os pixels de uma camada e fazem alterações sobre eles. Apesar do &chalk; usar uma infra-estrutura de memória em blocos eficiente para guardar os pixels, os pixels criados pelos filtros não precisam se preocupar com a API de imagens do &Java;, Photoshop ou The Gimp, tendo apenas de tomar conta dos extremos dos blocos e de como <quote
>colar</quote
> os blocos em conjunto: o &chalk; oculta esse detalhe de implementação. </para>
<note
><para
>Lembre-se que é, teoricamente, simples substituir o armazenamento dos dados da imagem por outra infra-estrutura, mas essas infra-estruturas não são atualmente plugins reais, por razões de desempenho.</para
></note>
<para
>O &chalk; usa iteradores para ler e gravar os valores dos pixels. Em alternativa, você poderá ler um bloco de pixels para uma área de memória, modificá-la e depois gravá-la de novo como um bloco. Mas isto não é necessariamente mais eficiente, até poderá ser mais lento que usar os iteradores; isto poderá ser apenas mais conveniente. Veja a documentação da API. </para
><para
>As imagens do &chalk; são compostas por camadas, existindo atualmente em quatro tipos: camadas de pintura, camadas de grupo, camadas de ajuste (que contém um filtro aplicado, de forma dinâmica, às camadas abaixo da camada de ajuste) e camadas de componentes. Os filtros funcionam sempre em camadas de pintura. As camadas de pintura contém dispositivos de pintura, da classe <classname
>KisPaintDevice</classname
>. Um dispositivo de pintura, por sua vez, dá acesso aos pixels em si. </para
><para
>Os <classname
>PaintDevice</classname
>s são normalmente passados como ponteiros compartilhados. Um ponteiro compartilhado mantém um registro dos locais em que o dispositivo de pintura é usado de fato e remove o dispositivo de pintura quando não for mais usado. Você poderá reconhecer a versão do ponteiro compartilhado de um dispositivo de pintura pelo seu sufixo <literal
>SP</literal
>. Basta lembrar-se que nunca terá que remover explicitamente um <classname
>KisPaintDeviceSP</classname
>. </para
><para
>Vejamos um filtro bastante simples, que inverte cada um dos pixels. O código para esse filtro está na pasta <filename class="directory"
>koffice/chalk/plugins/filters/example</filename
> directory. O método principal é o <programlisting>
KisFilterInvert::process(KisPaintDeviceSP orig, KisPaintDeviceSP dest,
                        KisFilterConfiguration* /*config*/, const QRect&amp; rect).
</programlisting
> A função recebe dois dispositivos de pintura, um objeto de configuração (que não é usado neste filtro de exemplo) e um <varname
>rect</varname
>. O <varname
>rect</varname
> descreve a área do dispositivo de pintura, sobre a qual o filtro deverá atuar. Esta área está descrita em valores inteiros, o que significa que não existe qualquer precisão de sub-pixels. </para
><para
>O dispositivo de pintura <varname
>orig</varname
> é o local de onde ler, enquanto o <varname
>dest</varname
> serve para escrever nele. Estes parâmetros poderão apontar para o mesmo dispositivo de pintura atual ou serem dois dispositivos diferentes. (Nota: isto poderá mudar para apenas um dispositivo no futuro.) </para
><para
>Agora, vejamos o código linha-a-linha: </para>
<programlisting
>void KisFilterInvert::process(KisPaintDeviceSP orig, KisPaintDeviceSP dest,
                             KisFilterConfiguration* /*config*/, const QRect&amp; rect)
{
   Q_ASSERT(src != 0);
   Q_ASSERT(dst != 0);

   KisRectIteratorPixel origIt = orig->createRectIterator(rect.x(), rect.y(), rect.width(), rect.height(), false); <co id="invert1" />
   KisRectIteratorPixel destIt = dest->createRectIterator(rect.x(), rect.y(), rect.width(), rect.height(), true ); <co id="invert2" />

   int pixelsProcessados = 0;
   setProgressTotalSteps(rect.width() * rect.height());

   KisColorSpace * cs = orig->colorSpace();
   Q_INT32 ptamanho = cs->pixelSize();

   while( ! origIt.isDone() )
   {
       if(origIt.isSelected()) <co id="invert3" />
       {
           memcpy(destIt.rawData(), origIt.oldRawData(), ptamanho); <co id="invert4" />

           cs->invertColor( destIt.rawData(), 1); <co id="invert5" />
       }
       setProgress(++pixelsProcessados);
       ++origIt;
       ++destIt;
   }
   setProgressDone(); // Deverá ser chamado, mesmo que não suporte de fato a progressão
}
</programlisting>

<calloutlist>
<callout arearefs="invert1">
<para
>Isto cria um iterador para ler os pixels existentes. O Chalk possui três tipos de iteradores: horizontal, vertical e retangular. O iterador de retângulos é o caminho mais eficiente através dos dados da imagem, mas não garante nada sobre a localização do próximo pixel que devolve. Isto significa que não poderá garantir que o pixel que vai obter será adjacente ao pixel que você acabou de obter. Os iteradores de linhas verticais e horizontais, esses sim garantem a localização dos pixels que devolvem. </para
></callout>
<callout arearefs="invert2"
><para
>(2) É criado o iterador de destino com a opção <literal
>write</literal
> igual a <literal
>true</literal
>. Isto significa que, se o dispositivo de pintura de destino for menor que o retângulo gravado, será automaticamente aumentado para caber todos os pixels sobre os quais vai iterar. Repare que existe aqui um potencial erro: se o <varname
>dest</varname
> e o <varname
>orig</varname
> não forem o mesmo dispositivo de pintura, então é bastante possível que os pixels devolvidos pelos iteradores não correspondam. Para cada posição do iterador, o <varname
>orig</varname
> poderá estar, por exemplo, em 165,200, enquanto o <varname
>dest</varname
> poderá estar em 20,8 &mdash; assim, a cópia que efetuar aqui poderá distorcer a imagem... </para
></callout>
<callout arearefs="invert3"
><para
>Você deseja saber se um pixel está selecionado? Isso é fácil &mdash; use o método <methodname
>isSelected</methodname
>. Mas o estado de selecionado não é uma propriedade binária de um pixel; um pixel poderá estar meio-selecionado, pouco selecionado ou praticamente selecionado. Esse valor também poderá ser obtido do iterador. As seleções são, de fato, um dispositivo de pintura de máscara, com um intervalo entre 0 e 255, onde o 0 é a ausência de seleção e o 255 é a seleção completa. O iterador possui dois métodos: <methodname
>isSelected()</methodname
> e <methodname
>selectedNess()</methodname
>. O primeiro devolve 'true' (verdadeiro), se um pixel estiver selecionado de qualquer forma (i.e., o valor da máscara é maior que 1), enquanto o outro devolve o valor da máscara. </para
></callout>
<callout arearefs="invert4"
><para
>Como observado acima, este <literal
>memcpy</literal
> é um grande erro, de fato... o <methodname
>rawData()</methodname
> devolve o vetor de 'bytes' que é o estado atual; o <methodname
>oldRawData()</methodname
> devolve o vetor de 'bytes', tal como estava antes de ter sido criado o iterador. Contudo, nós podemos estar copiando o pixel errado aqui. Na prática, isto não irá acontecer com muita freqüência, a menos que o <varname
>dest</varname
> já exista e não esteja alinhado com o <varname
>orig</varname
>. </para
></callout>
<callout arearefs="invert5"
><para
>Mas isto é correto: em vez de descobrir qual o 'byte' que corresponde a cada canal, usa-se uma função fornecida com todos os espaços de cores, para inverter os pixels atuais. Os espaços de cores possuem muitas operações com pixels que poderão ser usadas. </para
></callout>
</calloutlist>

<para
>Isto não tudo que existe para criar um filtro. Os filtros possuem outras duas componentes importantes: um objeto de configuração e um elemento gráfico de configuração. Os dois interagem intimamente. O elemento gráfico de configuração cria um objeto de configuração, mas também pode ser preenchido a partir de um objeto de configuração previamente existente. Os objetos de configuração poderão representar eles próprios como XML e poderão ser criados a partir de XML. Isto é o que torna as camadas de ajuste possíveis. </para>

<sect3 id="developers-plugins-filters-iterators">
<title
>Iteradores</title>

<para
>Existem três tipos de iteradores: </para>

<itemizedlist>
<listitem
><para
>Linhas horizontais</para
></listitem>
<listitem
><para
>Linhas verticais</para
></listitem>
<listitem
><para
>Iteradores retangulares</para
></listitem>
</itemizedlist>

<para
>Os iteradores de linhas horizontais e verticais possuem um método para mover o iterador para a próxima linha ou coluna: <methodname
>nextRow()</methodname
> e <methodname
>nextCol()</methodname
>. Usá-los é mais rápido que criar um iterador novo para cada linha ou coluna. </para
><para
>Os iteradores são seguros em ambiente multitarefa no &chalk;; por isso, é possível dividir o trabalho por várias tarefas. Contudo, as versões futuras do &chalk; irão usar o método <methodname
>supportsThreading()</methodname
> para saber se o seu filtro poderá ser aplicado em blocos da imagem (&ie;, todos os pixels modificados de forma independente, em vez de serem alterados por um valor determinado a partir de um exame sobre todos os pixels da imagem), distribuindo assim a execução do seu filtro por várias tarefas. </para>
</sect3>

<sect3 id="developers-plugins-filters-kisfilterconfiguration">
<title
><classname
>KisFilterConfiguration</classname
></title>

<para
>O <classname
>KisFilterConfiguration</classname
> é uma estrutura que é usada para gravar a configuração do filtro em disco como, por exemplo, nas camadas de ajuste. O plugin de programação usa o mapa de propriedades, que está na base do <classname
>KisFilterConfigaration</classname
>, para ser possível programar os filtros. Os filtros poderão oferecer um elemento gráfico personalizado, que o &chalk; irá mostrar na galeria de filtros, na janela de previsão do filtro ou na página de opções da ferramenta de pintura-com-filtros. </para>
<para
>Um exemplo, retirado do filtro de pintura à óleo: </para>
<programlisting
>class KisOilPaintFilterConfiguration : public KisFilterConfiguration
{

public:

   KisOilPaintFilterConfiguration(Q_UINT32 brushSize, Q_UINT32 smooth)
       : KisFilterConfiguration( "oilpaint", 1 )
       {
           setProperty("brushSize", brushSize);
           setProperty("smooth", smooth);
       };
public:

   inline Q_UINT32 brushSize() { return getInt("brushSize"); };
   inline Q_UINT32 smooth() {return getInt("smooth"); };

};
</programlisting>
</sect3>

<sect3 id="developers-plugins-filters-kisfilterconfigurationwidget">
<title
><classname
>KisFilterConfigurationWidget</classname
></title>

<para
>A maioria dos filtros poderá ser ajustada pelo usuário. Você poderá criar um elemento gráfico de configuração que o Chalk irá usar, sempre que o filtro for usado. Um exemplo: </para>

<para>
<screenshot>
<screeninfo
>A janela de <guilabel
>Pintura à Óleo</guilabel
></screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-oilpaint.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>A janela de <guilabel
>Pintura à Óleo</guilabel
></phrase>
</textobject>
<caption
><para
>A janela de <guilabel
>Pintura à Óleo</guilabel
></para
></caption>
</mediaobject>
</screenshot>
</para>

<para
>Repare que só a parte esquerda desta janela é da sua responsabilidade: o &chalk; toma conta do resto. Existem três abordagens para criar um elemento gráfico de opção: </para>

<itemizedlist>
<listitem
><para
>Use o &Qt; Designer para criar um base para o elemento gráfico e crie uma sub-classe para o seu filtro</para
></listitem>
<listitem
><para
>Use um dos elementos gráficos simples que mostram um conjunto de barras deslizantes, no caso das listas de números inteiros, números de ponto flutuante ou booleanos. Eles são úteis se, como na imagem acima, se o seu filtro puder ser configurado com um conjunto de inteiros, números de ponto flutuante ou booleanos. Veja a documentação da API do <classname
>KisMultiIntegerFilterWidget</classname
>, <classname
>KisMultiDoubleFilterWidget</classname
> e <classname
>KisMultiBoolFilterWidget</classname
>.</para
></listitem>
<listitem
><para
>Crie um elemento gráfico manualmente. Esta forma não é a recomendada e, se você fizer isso e quiser que o seu filtro se torne parte da versão oficial do &chalk;, então recomenda-se que substitua o seu elemento gráfico codificado à mão por uma versão com o &Qt; Designer.</para
></listitem>
</itemizedlist>

<para
>O filtro de pintura à óleo usa o elemento multi-inteiros: </para>

<programlisting
>KisFilterConfigWidget * KisOilPaintFilter::createConfigurationWidget(TQWidget* parent, KisPaintDeviceSP /*dev*/)
{
   vKisIntegerWidgetParam param;
   param.push_back( KisIntegerWidgetParam( 1, 5, 1, i18n("Brush size"), "brushSize" ) );
   param.push_back( KisIntegerWidgetParam( 10, 255, 30, i18n("Smooth"), "smooth" ) );
   return new KisMultiIntegerFilterWidget(parent, id().id().ascii(), id().id().ascii(), param );
}

KisFilterConfiguration* KisOilPaintFilter::configuration(TQWidget* nwidget)
{
   KisMultiIntegerFilterWidget* widget = (KisMultiIntegerFilterWidget*) nwidget;
   if( widget == 0 )
   {
       return new KisOilPaintFilterConfiguration( 1, 30);
   } else {
       return new KisOilPaintFilterConfiguration( widget->valueAt( 0 ), widget->valueAt( 1 ) );
   }
}

std::list&lt;KisFilterConfiguration*&gt; KisOilPaintFilter::listOfExamplesConfiguration(KisPaintDeviceSP )
{
   std::list&lt;KisFilterConfiguration*&gt; list;
   list.insert(list.begin(), new KisOilPaintFilterConfiguration( 1, 30));
   return list;
}
</programlisting>

<para
>Você pode ver como ele funciona: ele preenche um vetor com os seus parâmetros inteiros e cria o elemento gráfico. O método <methodname
>configuration()</methodname
> inspeciona o elemento e cria o objeto de configuração do filtro correto, nesse caso, o <classname
>KisOilPaintFilterConfiguration</classname
>. O método <methodname
>listOfExamplesConfiguration</methodname
> (que deverá mudar de nome para um Inglês correto...) devolve uma lista com objetos de configuração de exemplo, para a janela da galeria de filtros. </para>
</sect3>

<sect3 id="developers-plugins-filters-conclusion">
<title
>Conclusão dos filtros</title>

<para
>Existem mais alguns pontos sobre a codificação de filtros interessantes mas, com esta explicação, a documentação da API e o acesso ao nosso código-fonte, você deverá ser capaz de ter uma boa introdução. Não hesite em contactar a equipe de desenvolvimento do &chalk; no IRC ou na lista de correio. </para>
</sect3>

</sect2>

<sect2 id="developers-plugins-tools">
<title
>Ferramentas</title>

<para
>As ferramentas aparecem na área de ferramentas do &chalk;. Isto significa que existe um espaço limitado para as ferramentas novas &mdash; pense com cuidado, sempre que uma operação de pintura não for o suficiente para os seus fins. As ferramentas poderão usar o mouse/tablete e o teclado de formas complexas, coisa que as operações de pintura não conseguem. Esta é a razão pela qual o Duplicar é uma ferramenta e o spray é uma operação de pintura. </para
><para
>Tenha cuidado com os dados estáticos na sua ferramenta: é criada uma instância nova da sua ferramenta para cada dispositivo de entrada: o mouse, caneta, borracha, spray &mdash; o que for. As ferramentas estão divididas em grupos lógicos: </para>
<itemizedlist>
<listitem
><para
>ferramentas de desenho de formas (círculo, retângulo)</para
></listitem>
<listitem
><para
>ferramentas de desenho livre (pincel)</para
></listitem>
<listitem
><para
>ferramentas de transformação que mexem na geometria de uma camada</para
></listitem>
<listitem
><para
>ferramentas de preenchimento (como o balde ou o gradiente)</para
></listitem>
<listitem
><para
>ferramentas de visualização (que não mudam os pixels, mas sim a forma como você vê a tela, como a ampliação)</para
></listitem>
<listitem
><para
>ferramentas de seleção (que mudam a máscara de seleção)</para
></listitem>
</itemizedlist>

<para
>A interface da ferramenta está descrita na documentação da API da classe <classname
>KisTool</classname
>. Existem três sub-classes: <classname
>KisToolPaint</classname
>, <classname
>KisToolNonPaint</classname
> e <classname
>KisToolShape</classname
> (que é, de fato, uma sub-classe de <classname
>KisToolPaint</classname
>), que especializa a <classname
>KisTool</classname
> para as ferramentas de pintura (i.e., mudando os pixels), as tarefas sem ser de pintura e as tarefas de pintura de formas. </para
><para
>Uma ferramenta possui um elemento gráfico de opções, como os filtros. Atualmente, os elementos gráficos aparecem numa página de uma janela acoplável. Nós poderemos mudar esta para uma barra fina, sob o menu principal (que por sua vez substitui a barra de ferramentas) no &chalk; 2.0 mas, por enquanto, desenhe o seu elemento gráfico de opções para caber numa página. Como sempre, é melhor usar o &Qt; Designer para desenhar este elemento gráfico. </para
><para
>Um bom exemplo de uma ferramenta é a estrela: </para>

<screen
>kis_ferramenta_estrela.cpp       Makefile.am   ferramenta_estrela_cursor.png  wdg_ferramenta_estrela.ui
kis_ferramenta_estrela.h        Makefile.in   ferramenta_estrela.h           
chalkferramentaestrela.desktop  ferramenta_estrela.cpp  ferramenta_estrela.png         
</screen>

<para
>Como pode ver, são necessárias duas imagens: uma para o cursor e outra para a caixa de ferramentas. O <filename
>ferramenta_estrela.cpp</filename
> é apenas o carregador do plugin, semelhante ao que foi visto anteriormente. O recheio real está na implementação: </para>

<programlisting
>KisFerramentaEstrela::KisFerramentaEstrela()
   : KisToolShape(i18n("Star")),
     m_dragging (false),
     m_currentImage (0)
{
   setName("tool_star");
   setCursor(KisCursor::load("ferramenta_estrela_cursor.png", 6, 6));
   m_innerOuterRatio=40;
   m_vertices=5;
}
</programlisting>

<para
>O construtor define o nome interno &mdash; que não é traduzido &mdash; e a chamada à super-classe define o nome visível. Nós também poderemos carregar a imagem do cursor e definir um conjunto de variáveis. </para>

<programlisting
>void KisToolStar::update (KisCanvasSubject *assunto)
{
   KisToolShape::update (assunto);
   if (m_subject)
       m_currentImage = m_subject->currentImg();
}
</programlisting>

<para
>O método <methodname
>update()</methodname
> é chamado quando a ferramenta é selecionada. Este não é um método da <classname
>KisTool</classname
>, mas sim um método da classe <classname
>KisCanvasObserver</classname
>. Os observadores da área de trabalho são notificados sempre que ocorrerem alterações na tela, o que poderá ser útil para as ferramentas. </para
><para
>Os seguintes métodos (<methodname
>buttonPress</methodname
>, <methodname
>move</methodname
> e <methodname
>buttonRelease</methodname
>) são invocados pelo &chalk; quando o dispositivo de entrada (mouse, caneta, borracha, etc.) for pressionado, mudado de posição ou solto. Lembre-se que você também obtém mais eventos se o botão do mouse não for pressionado. Os eventos não são os normais, mas sim eventos sintéticos do &chalk;, uma vez que ele tira partido de alguns truques de baixo nível para obter eventos suficientes para desenhar uma linha suave. Por padrão, as bibliotecas, como o &Qt; (e o GTK), perdem eventos se estiverem muito ocupadas para tratar deles, e nós desejamos obter todos eles. </para>

<programlisting
>void KisFerramentaEstrela::buttonPress(KisButtonPressEvent *evento)
{
   if (m_currentImage &amp;&amp; evento->button() == LeftButton) {
       m_dragging = true;
       m_dragStart = evento->pos();
       m_dragEnd = evento->pos();
       m_vertices = m_optWidget->verticesSpinBox->value();
       m_innerOuterRatio = m_optWidget->ratioSpinBox->value();
   }
}

void KisFerramentaEstrela::move(KisMoveEvent *evento)
{
   if (m_dragging) {
       // apagar as linhas antigas da área de desenho
       draw(m_dragStart, m_dragEnd);
       // mover (alt) ou dimensionar a estrela
       if (evento->state() &amp; TQt::AltButton) {
           KisPoint trans = evento->pos() - m_dragEnd;
           m_dragStart += trans;
           m_dragEnd += trans;
       } else {
           m_dragEnd = evento->pos();
       }
       // desenhar as linhas novas na área de desenho
       draw(m_dragStart, m_dragEnd);
   }
}

void KisFerramentaEstrela::buttonRelease(KisButtonReleaseEvent *evento)
{
   if (!m_subject || !m_currentImage)
       return;

   if (m_dragging &amp;&amp; evento->button() == LeftButton) {
       // apagar as linhas antigas da área de desenho
       draw(m_dragStart, m_dragEnd);
       m_dragging = false;

       if (m_dragStart == m_dragEnd)
           return;

       if (!m_currentImage)
           return;

       if (!m_currentImage->activeDevice())
           return;
       
       KisPaintDeviceSP dispositivo = m_currentImage->activeDevice ();;
       KisPainter pintor (dispositivo);
       if (m_currentImage->undo()) pintor.beginTransaction (i18n("Star"));

       pintor.setPaintColor(m_subject->fgColor());
       pintor.setBackgroundColor(m_subject->bgColor());
       pintor.setFillStyle(fillStyle());
       pintor.setBrush(m_subject->currentBrush());
       pintor.setPattern(m_subject->currentPattern());
       pintor.setOpacity(m_opacity);
       pintor.setCompositeOp(m_compositeOp);
       KisPaintOp * op =
           KisPaintOpRegistry::instance()->paintOp(m_subject->currentPaintop(), m_subject->currentPaintopSettings(), &amp;pintor.;
       pintor.setPaintOp(op); // O Pintor fica como dono

       vKisPoint coord = starCoordinates(m_vertices, m_dragStart.x(), m_dragStart.y(), m_dragEnd.x(), m_dragEnd.y());

       pintor.paintPolygon(coord);
       
       device->setDirty( pintor.dirtyRect() );
       notifyModified();

       if (m_currentImage->undo()) {
           m_currentImage->undoAdapter()->addCommand(pintor.endTransaction());
       }
   }
}
</programlisting>

<para
>O método <methodname
>draw()</methodname
> é um método interno da classe <classname
>KisToolStar</classname
> e desenha o contorno da estrela. Ele é chamado a partir do método <methodname
>move()</methodname
>, para dar alguma reação ao usuário sobre o tamanho e a forma da sua estrela. Note que se usa a operação de desenho <varname
>TQt::NotROP</varname
>, o que significa que, ao invocar o <methodname
>draw()</methodname
> uma segunda vez com o mesmo início e fim, a estrela anteriormente desenhada será removida. </para>

<programlisting
>void KisToolStar::draw(const KisPoint&amp; inicio, const KisPoint&amp; fim )
{
   if (!m_subject || !m_currentImage)
       return;

   KisCanvasController *controller = m_subject->canvasController();
   KisCanvas *canvas = controller->kiscanvas();
   KisCanvasPainter p (canvas);
   QPen pen(TQt::SolidLine);

   KisPoint posInicio;
   KisPoint posFim;
   posInicio = controller->windowToView(inicio);
   posFim = controller->windowToView(fim);

   p.setRasterOp(TQt::NotROP);

   vKisPoint pontos = starCoordinates(m_vertices, posInicio.x(), posInicio.y(), posFim.x(), posFim.y());

   for (uint i = 0; i &lt; pontos.count() - 1; i++) {
       p.drawLine(pontos[i].floorQPoint(), pontos[i + 1].floorQPoint());
   }
   p.drawLine(pontos[pontos.count() - 1].floorQPoint(), pontos[0].floorQPoint());

   p.end ();
}
</programlisting>

<para
>O método <methodname
>setup()</methodname
> é essencial: aqui nós criamos a ação que será ligada à área de ferramentas, para que os usuários possam de fato selecionar a ferramenta. Também é possível atribuir uma tecla de atalho. Repare que existem alguns truques aqui: lembre-se que é criada uma instância da ferramenta para cada dispositivo de entrada. Isto também significa que é chamado o método <methodname
>setup()</methodname
> para cada dispositivo de entrada, e isso significa que é adicionada uma ação com o mesmo nome, várias vezes, à coleção de ações. Contudo, tudo parece funcionar, então porque preocupar-se? </para>

<programlisting
>void KisToolStar::setup(TDEActionCollection *colleccao)
{
   m_action = static_cast&lt;TDERadioAction *&gt;(colleccao->action(name()));

   if (m_action == 0) {
       TDEShortcut atalho(TQt::Key_Plus);
       atalho.append(TDEShortcut(TQt::Key_F9));
       m_action = new TDERadioAction(i18n("&amp;Star"),
                                   "ferramenta_estrela",
                                   atalho,
                                   this,
                                   TQ_SLOT(activate()),
                                   colleccao,
                                   name());
       TQ_CHECK_PTR(m_action);

       m_action->setToolTip(i18n("Draw a star"));
       m_action->setExclusiveGroup("tools");
       m_ownAction = true;
   }
}
</programlisting>

<para
>O método <methodname
>starCoordinates()</methodname
> contém alguma matemática engraçada &mdash; mas não é muito interessante para a discussão sobre a criação dos plugins de ferramentas. </para>

<programlisting
>KisPoint KisToolStar::starCoordinates(int N, double mx, double my, double x, double y)
{
   double R=0, r=0;
   Q_INT32 n=0;
   double angulo;

   vKisPoint listaCoordenadasEstrela(2*N);

   // o raio dos lados exteriores
   R=sqrt((x-mx)*(x-mx)+(y-my)*(y-my));

   // o raio dos lados interiores
   r=R*m_innerOuterRatio/100.0;

   // o ângulo
   angulo=-atan2((x-mx),(y-my));

   //definir os lados exteriores
   for(n=0;n&lt;N;n++){
       listaCoordenadasEstrela[2*n] = KisPoint(mx+R*cos(n * 2.0 * M_PI / N + angulo),my+R*sin(n *2.0 * M_PI / N+angulo));
   }

   //definir os lados interiores
   for(n=0;n&lt;N;n++){
       listaCoordenadasEstrela[2*n+1] = KisPoint(mx+r*cos((n + 0.5) * 2.0 * M_PI / N + angulo),my+r*sin((n +0.5) * 2.0 * M_PI / N + angulo));
   }

   return listaCoordenadasEstrela;
}
</programlisting>

<para
>O método <methodname
>createOptionWidget()</methodname
> é chamado para criar o elemento gráfico das opções que o &chalk; irá mostrar na página. Uma vez que existe uma ferramenta para cada dispositivo de entrada, para cada janela, o estado de uma ferramenta poderá ser mantido na ferramenta. Este método só é chamado uma vez: o elemento de opções é guardado e obtido da próxima vez que a ferramenta for ativada. </para>

<programlisting
>TQWidget* KisFerramentaEstrela::createOptionWidget(TQWidget* mae)
{
   TQWidget *elemento = KisToolShape::createOptionWidget(mae);

   m_optWidget = new WdgFerramentaEstrela(elemento);
   TQ_CHECK_PTR(m_optWidget);

   m_optWidget->ratioSpinBox->setValue(m_innerOuterRatio);

   QGridLayout *disposicaoOpcoes = new QGridLayout(elemento, 1, 1);
   super::addOptionWidgetLayout(disposicaoOpcoes);

   disposicaoOpcoes->addWidget(m_optWidget, 0, 0);

   return elemento;
}
</programlisting>

<sect3 id="developers-plugins-tools-conclusions">
<title
>Conclusões das Ferramentas</title>

<para
>As ferramentas são plugins relativamente simples de criar. Você terá que combinar as interfaces <classname
>KisTool</classname
> e <classname
>KisCanvasObserver</classname
> para criar de fato uma ferramenta. </para>

</sect3>

</sect2>

<sect2 id="developers-plugins-paintoperations">
<title
>Operações de pintura</title>

<para
>As operações de pintura são um dos tipos de plugins mais inovadores no Chalk (em conjunto com os espaços de cores acopláveis). Uma operação de pintura define a forma como as ferramentas mudam os pixels que tocam. O 'spray', o lápis ou o pincel suave: todos eles são operações de pintura. Mas você pode &mdash; com muito trabalho &mdash; criar uma operação de pintura que leia as definições de pincéis do Corel Painter em XML e usá-las para determinar a forma como a pintura é feita. </para
><para
>As operações de pintura são instanciadas sempre que uma ferramenta de pintura receber um evento <literal
>mouseDown</literal
> e são removidas quando o evento 'mouseUp' for recebido por uma ferramenta de pintura. Entretanto, a operação poderá manter um registro das posições anteriores e os outros dados, como os níveis de pressão, se o usuário usar uma tablete. </para
><para
>A operação básica de uma operação de pintura é mudar os pixels na posição atual do cursor de uma ferramenta. Isto só poderá ser feito uma vez, ou a ferramenta poderá pedir para ser executada em intervalos regulares, graças a um temporizador. A primeira seria útil para uma operação do tipo lápis, enquanto a segunda, obviamente, para uma operação do tipo 'spray'. </para
><para
>As operações de pintura poderão ter um pequeno elemento gráfico, que é colocado numa barra de ferramentas. Deste modo, os elementos de configuração das operações de pintura precisam ter uma disposição horizontal dos elementos gráficos, não mais altas do que um botão da barra de ferramentas. Caso contrário, o &chalk; ficará bastante engraçado. </para
><para
>Vejamos um simples plugin de pintura, um que mostra alguma inteligência de programação. Primeiro, no arquivo de inclusão, está definida uma 'factory' (fábrica de instâncias). Este objeto cria uma operação de pintura, sempre que a ferramenta ativa precisar de uma: </para>

<programlisting
>public:
   KisSmearyOpfatory() {}
   virtual ~KisSmearyOpfatory() {}

   virtual KisPaintOp * createOp(const KisPaintOpSettings *configuracao, KisPainter * pintor);
   virtual KisID id() { return KisID("paintSmeary", i18n("Smeary Brush")); }
   virtual bool userVisible(KisColorSpace * ) { return false; }
   virtual TQString pixmap() { return ""; }

};
</programlisting>

<para
>A 'factory' também contém o <classname
>KisID</classname
> com o nome público e o privado da operação de pintura &mdash; certifique-se de que o nome privado da sua operação de pintura não entra em conflito com outra operação! &mdash; e poderá devolver, opcionalmente, uma imagem. O &chalk; poderá então mostrar a imagem em conjunto com o nome, para uma identificação visual da sua operação. Por exemplo, uma operação de faca do pintor teria a imagem com um instrumento desse tipo. </para
><para
>A implementação de uma operação de pintura é bastante intuitiva: </para>

<programlisting
>KisSmearyOp::KisSmearyOp(KisPainter * pintor)
   : KisPaintOp(pintor)
{
}

KisSmearyOp::~KisSmearyOp()
{
}
void KisSmearyOp::paintAt(const KisPoint &amp;pos, const KisPaintInformation&amp; info)
{
</programlisting>

<para
>O método <methodname
>paintAt()</methodname
> está realmente onde deveria estar, com as operações de pintura. Este método recebe dois parâmetros: a posição atual (que está com números de ponto flutuante, não em pixels) e um objeto <classname
>KisPaintInformation</classname
>, que contém a pressão, o toque em 'x' e 'y' e o vetor de movimento, podendo ser extendido no futuro com outras informações. </para>

<programlisting
>if (!m_painter->device()) return;

   KisBrush *pincel = m_painter->brush();
</programlisting>

<para
>Um <classname
>KisBrush</classname
> é a representação de um arquivo de pincel do Gimp: ele é uma máscara, seja ela simples ou uma série de máscaras. De fato, não é usado aqui o pincel, exceto para determinar o <quote
>ponto focal</quote
> sob o cursor. </para>

<programlisting
>Q_ASSERT(pincel);

   if (!pincel) return;

   if (! pincel->canPaintFor(info) )
       return;

   KisPaintDeviceSP dispositivo = m_painter->device();
   KisColorSpace * espacoCores = dispositivo->colorSpace();
   KisColor kc = m_painter->paintColor();
   kc.convertTo(colorSpace);

   KisPoint ponto = pincel->hotSpot(info);
   KisPoint pt = pos - ponto;

   // Dividir as coordenadas em partes inteira e fracionária. A parte inteira
   // é onde ficará o 'dab' e a parte fracionária determina a posição nos
   // sub-pixels
   Q_INT32 x, y;
   double fraccaoX, fraccaoY;

   splitCoordinate(pt.x(), &amp;x, &amp;fracaoX);
   splitCoordinate(pt.y(), &amp;y, &amp;fracaoY);

   KisPaintDeviceSP dab = new KisPaintDevice(espacoCores, "smeary dab");
   TQ_CHECK_PTR(dab);
</programlisting>

<para
>Não são alterados diretamente os pixels de um dispositivo de pintura: em vez disso, é criado um pequeno dispositivo de pintura, um 'dab', sendo ele composto no dispositivo de pintura atual. </para>

<programlisting
>m_painter->setPressure(info.pressure);
</programlisting>

<para
>Como dizem os comentários, o próximo bloco de código efetua algum trabalho de programação para criar o 'dab' atual. Nesse caso, é desenhado um conjunto de linhas. Quando se terminar esta operação de pintura, o comprimento, a posição e a espessura das linhas será dependente da pressão e carga da tinta, e nós criamos um pincel forte e húmido. Mas ainda eu ainda não tive tempo para terminar isto. </para>

<programlisting
>// Calcular a posição dos tufos. Os tufos estão organizados numa linha
   // perpendicular ao movimento do pincel, i.e, a linha a direito entre
   // a posição atual e a posição anterior.
   // Os tufos estão espalhados ao longo da pressão

   KisPoint pontoAnterior = info.movement.toKisPoint();
   KisVector2D vectorPincel(-pontoAnterior.y(), pontoAnterior.x());
   KisVector2D listaPontoatual = KisVector2D(pos);
   vectorPincel.normalize();

   KisVector2D vl, vr;

   for (int i = 0; i &lt; (NUMBER_OF_TUFTS / 2); ++i) {
       // Calcular as posições do vetor novo.
       vl = listaPontoatual + i * vetorPincel;
       KisPoint pl = vl.toKisPoint();
       dab->setPixel(pl.roundX(), pl.roundY(), kc);

       vr = listaPontoatual - i * vetorPincel;
       KisPoint pr = vr.toKisPoint();
       dab->setPixel(pr.roundX(), pr.roundY(), kc);
   }

   vr = vr - vl;
   vr.normalize();
</programlisting>

<para
>Finalmente, é desenhado o 'dab' no dispositivo de pintura original e é dito ao pintor que se atualizou um pequeno retângulo do dispositivo de pintura. </para>

<programlisting
>if (m_source->hasSelection()) {
       m_painter->bltSelection(x - 32, y - 32, m_painter->compositeOp(), dab.data(),
                               m_source->selection(), m_painter->opacity(), x - 32, y -32, 64, 64);
   }
   else {
       m_painter->bitBlt(x - 32, y - 32, m_painter->compositeOp(), dab.data(), m_painter->opacity(), x - 32, y -32, 64, 64);
   }

   m_painter->addDirtyRect(QRect(x -32, y -32, 64, 64));
}


KisPaintOp * KisSmearyOpfatory::createOp(const KisPaintOpSettings */*configuracao*/, KisPainter * pintor)
{
   KisPaintOp * op = new KisSmearyOp(pintor);
   TQ_CHECK_PTR(op);
   return op;
}
</programlisting>

<para
>Isto é tudo: as operações de pintura são simples e divertidas! </para>

</sect2>

<sect2 id="developers-plugins-viewplugins">
<title
>Plugins de visualização</title>

<para
>Os plugins de visualização ou da janela são os mais esquisitos do grupo: um plugin de visualização é um KPart normal, que poderá fornecer alguma interface do usuário e alguma funcionalidade. Por exemplo, a página do histograma é um plugin de visualização, assim como a janela de rotação. </para>

</sect2>

<sect2 id="developers-plugins-importexport">
<title
>Filtros de importação/exportação</title>

<para
>O &chalk; funciona com a arquitetura de filtros de arquivos do &koffice;. Existe um tutorial, um pouco antigo mas ainda útil, em: <ulink url="http://koffice.org/developer/filters/oldfaq.php"
></ulink
>. É provavelmente melhor cooperar com a equipe do &chalk; ao desenvolver filtros de arquivos e fazer o desenvolvimento na árvore de filtros do &koffice;. Lembre-se que você poderá testar os seus filtros, sem executar o &chalk;, usando o utilitário <command
>koconverter</command
>. </para
><para
>Os filtros possuem duas faces: importação e exportação. Eles são, normalmente, dois plugins diferentes que poderão compartilhar algum código. </para
><para
>Os ítens importantes do <filename
>Makefile.am</filename
> são: </para>

<programlisting
>service_DATA = chalk_XXX_import.desktop chalk_XXX_export.desktop
servicedir = $(kde_servicesdir)
kdelnk_DATA = chalk_XXX.desktop
kdelnkdir = $(kde_appsdir)/Office
libchalkXXXimport_la_SOURCES = XXXimport.cpp
libchalkXXXexport_la_SOURCES = XXXexport.cpp
METASOURCES = AUTO
</programlisting>

<para
>Não importa se você está criando um filtro de importação ou de exportação, o seu trabalho sempre passa por implementar a função a seguir: </para>

<programlisting
>virtual KoFilter::ConversionStatus convert(const QCString&amp; de, const QCString&amp; para);
</programlisting>

<para
>É a configuração dos arquivos <literal role="extension"
>.desktop</literal
> que determina a forma como um filtro converte: </para
><para
>Importar: </para>

<programlisting
>X-TDE-Export=application/x-chalk
X-TDE-Import=image/x-xcf-gimp
X-TDE-Weight=1
X-TDE-Library=libchalkXXXimport
ServiceTypes=KOfficeFilter
</programlisting>

<para
>Exportar: </para>

<programlisting
>X-TDE-Export=image/x-xcf-gimp
X-TDE-Import=application/x-chalk
ServiceTypes=KOfficeFilter
Type=Service
X-TDE-Weight=1
X-TDE-Library=libchalkXXXexport
</programlisting>

<para
>E sim, o tipo MIME escolhido para o exemplo é uma sugestão. Por favor, pode implementar um filtro de XCF? </para>

<sect3 id="plugins-developers-importexport-import">
<title
>Importar</title>

<para
>O grande problema com os filtros de importação é, obviamente, o seu código para ler os dados em disco. O código auxiliar que invoca este código é relativamente simples: </para>

<note
><para
>Nota: é mesmo realmente necessária uma forma para permitir ao &chalk; manter um arquivo aberto, e ler apenas os dados à medida das necessidades, em vez de copiar o conteúdo inteiro para a representação interna do dispositivo de pintura. Mas isso iria significar infra-estruturas de gerenciamento de dados que percebam os arquivos TIFF, entre outros, e isso ainda não está implementado atualmente. Seria o ideal se alguns filtros de arquivos pudessem implementar uma classe temporária chamada <classname
>KisFileDataManager</classname
>, criassem um objeto dessa instância com o arquivo atual e o passassem ao KisDoc. Mas o &chalk; lida com o armazenamento por camadas, não por documentos, por isso seria uma fatorização difícil de fazer.</para
></note>

<programlisting
>KoFilter::ConversionStatus XXXImport::convert(const QCString&amp;, const QCString&amp; para)
{
   if (para != "application/x-chalk") <co id="import1" />
       return KoFilter::BadMimeType;

   KisDoc * doc = dynamic_cast&lt;KisDoc*&gt;(m_chain -> outputDocument()); <co id="import2" />
   KisView * vista = static_cast&lt;KisView*&gt;(doc -> views().getFirst()); <co id="import3" />
   
   TQString arquivo = m_chain -> inputFile(); <co id="import4" />
   
   if (!doc)
       return KoFilter::CreationError;

   doc -> prepareForImport(); <co id="import5" />

   if (!arquivo.isEmpty()) {
   
       KURL url(arquivo);

       if (url.isEmpty())
           return KoFilter::FileNotFound;
           
       KisImageXXXConverter ib(doc, doc -> undoAdapter()); <co id="import6" />

       if (vista != 0)
           vista -> canvasSubject() ->  progressDisplay() -> setSubject(&amp;ib, false, true);

       switch (ib.buildImage(url)) <co id="import7" /> {
           case KisImageBuilder_RESULT_UNSUPPORTED:
               return KoFilter::NotImplemented;
               break;
           case KisImageBuilder_RESULT_INVALID_ARG:
               return KoFilter::BadMimeType;
               break;
           case KisImageBuilder_RESULT_NO_URI:
           case KisImageBuilder_RESULT_NOT_LOCAL:
               return KoFilter::FileNotFound;
               break;
           case KisImageBuilder_RESULT_BAD_FETCH:
           case KisImageBuilder_RESULT_EMPTY:
               return KoFilter::ParsingError;                
               break;
           case KisImageBuilder_RESULT_FAILURE:
               return KoFilter::InternalError;
               break;
           case KisImageBuilder_RESULT_OK:
               doc -> setCurrentImage( ib.image()); <co id="import8" />
               return KoFilter::OK;
           default:
               break;
       }

   }
   return KoFilter::StorageCreationError;
}
</programlisting>

<calloutlist>
<callout arearefs="import1"
><para
>Isto é supostamente um filtro de importação; por isso, se não for invocado para converter para uma imagem do &chalk;, algo está errado.</para
></callout>
<callout arearefs="import2"
><para
>A cadeia de filtros já criou um documento de saída para nós. É preciso convertê-lo para um <classname
>KisDocM</classname
>, uma vez que os documentos do &chalk; precisam de um tratamento especial. Não seria, contudo, má ideia verificar se o resultado da conversão não é 0, porque se for, a importação irá falhar.</para
></callout>
<callout arearefs="import3"
><para
>Se invocarmos este filtro a partir da GUI, teremos que obter uma visão. Se existir, o código de conversão poderá tentar atualizar a barra de progresso.</para
></callout>
<callout arearefs="import4"
><para
>O filtro tem o nome do arquivo de entrada.</para
></callout>
<callout arearefs="import5"
><para
>O <classname
>KisDoc</classname
> precisa se preparar para a importação. Algumas configurações são inicializadas e a opção para desfazer é desativada. Caso contrário, poderia anular a adição de camadas efetuadas pelo filtro de importação, e isso seria um comportamento estranho.</para
></callout>
<callout arearefs="import6"
><para
>Eu optei por implementar o código de importação atual numa classe separada que é aqui instanciada. Você poderá também colocar todo o seu código neste método, mas isso ficaria um pouco confuso.</para
></callout>
<callout arearefs="import7"
><para
>O módulo de importação devolve um código de estado que poderá ser usado para configurar depois o estado do filtro de importação. O &koffice; toma conta de mostrar as mensagens de erro.</para
></callout>
<callout arearefs="import8"
><para
>Se a criação do <classname
>KisImage</classname
> foi bem sucedida, nós configuraremos a imagem atual do documento com a imagem recém criada. Então, isto é tudo: <literal
>return KoFilter::OK;</literal
>.</para
></callout>
</calloutlist>

</sect3>

</sect2>

</sect1>