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

<sect1 id="developers-plugins">
<title
>Criar 'Plugins' do &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 utilizador, ou até mesmo os espaços de cores, são 'plugins'. De facto, o &chalk; reconhece estes seis tipos de 'plugins': </para>

<itemizedlist>
<listitem
><para
>espaços de cores &mdash; estes definem os canais que constituem um único pixel</para
></listitem>
<listitem
><para
>ferramentas &mdash; tudo o que é feito com um rato 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 seleccionados de uma camada</para
></listitem>
<listitem
><para
>'plugins' de visualização &mdash; extende a interface de utilizador 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 em três bibliotecas em camadas e numa pasta com algumas classes comuns de suporte: chalkcolor, chalkimage e chalkui. Dentro do &chalk;, os objectos podem ser identificados por um <classname
>KisID</classname
>, que é a combinação de um texto não-traduzido único (usado ao gravar, por exemplo) e um texto traduzido, para fins de interface. </para
><para
>Uma palavra acerca da compatibilidade: o &chalk; está ainda em desenvolvimento. Desde o &chalk; 1.5 até ao 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;, tem excelentes hipóteses de obter ajuda da equipa de desenvolvimento na passagem para a nova versão. Estas alterações também poderão levantar algumas partes deste documento que estejam desactualizadas. Verifique sempre a última documentação da API ou os ficheiros 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 abstracta <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
>), extender o <classname
>KisAbstractColorSpace</classname
>. A biblioteca 'chalkcolor' poderá ser usada noutras 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 objectivo é tornar a 'libchalkimage' independente do &koffice;, mas partilha-se neste momento o código de carregamento dos gradientes no &koffice;. </para
><para
>Não é possível, de momento, 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 projecto Create (<ulink url="http://create.freedesktop.org/"
></ulink
>) para tal. A adição do suporte para o formato de pincéis do Photoshop precisa de algumas alterações na 'libchalkimage'; a adição de mais ficheiros de dados de pincéis do 'gimp' não precisa, por outro lado. </para
><para
>O <classname
>ChalkImage</classname
> carrega os seguintes tipos de 'plugins': </para>

<itemizedlist>
<listitem
><para
>Os filtros do &chalk; deverão extender e implementar a classe abstracta <classname
>KisFilter</classname
>, <classname
>KisFilterConfiguration</classname
> e, possivelmente, a <classname
>KisFilterConfigurationWidget</classname
>. Um exemplo destes filtros é a Máscara Não-Afiada.</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 extender 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 completo.</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 se tenha de dividir esta biblioteca em 'chalkpart' e 'chalkui' na versão 2.0. Por agora, 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 selecção do objecto em primeiro plano. As ferramentas de pintura (e estas incluem as que pintam sobre os dados seleccionados) 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 utilizador 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 facto, 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 gravam 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
>Criar 'plugins'</title>

<para
>Os 'plugins' são criados em C++ e poderão usar toda a API de programação do &kde;, do &Qt; e do &chalk;. Só os 'plugins' de visualização deverão usar a API do &koffice;. Não se preocupe: as APIs do &chalk; são bastantes claras e relativamente bem documentadas (no caso do 'software' livre); para além disso, a codificação do seu primeiro filtro é realmente simples. </para
><para
>Se não quiser usar o C++, poderá criar programas em Python ou em Ruby; isto já é uma coisa diferente, e não consegue criar de momento as ferramentas, os espaços de cores, as operações de pintura ou os 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 ficheiros de inclusão relevantes para o &chalk; em si, ou poderá ter dividido os ficheiros em pacotes de desenvolvimento do &koffice; ou do &chalk;. 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 descrevem 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 ficheiros <literal role="extension"
>.desktop</literal
>; os 'plugins' de visualização necessitam de um ficheiro do <application
>KXMLGui</application
> <filename
>nomeplugin.rc</filename
> adicionalmente. A forma mais simples de começar é extrair o projecto 'chalk-plugins', do repositório de Subversion do &koffice;, e usá-lo como base para o seu próprio projecto. Pretende-se preparar um pacote com um esqueleto de 'plugin' do &chalk; para o KDevelop, mas tal 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 = ficheiro1.cpp ficheiro2.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
> Esta é a 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 também instalou um ficheiro <literal role="extension"
>.rc</literal
> com itens para os menus e as barras de ferramentas. Da mesma forma, poderá ter de 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
>Ficheiros 'desktop'</title>

<para
>O ficheiro <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 ficheiros usam a plataforma de filtros genérica do &koffice; e necessitam de ser discutidos em separado. </para>
</sect4>

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

<para
>Também precisa de um pouco de código auxiliar, chamado de plataforma de componentes do &kde;, para instanciar o 'plugin' &mdash; um ficheiro de inclusão e um ficheiro de implementação. </para
><para
>Um ficheiro 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 ficheiro de implementação: <programlisting
>#include &lt;kinstance.h&gt;
#include &lt;kgenericfactory.h&gt;

#include &lt;kis_tool_registry.h&gt;

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


typedef KGenericFactory&lt;FerramentaEstrela&gt; FerramentaEstrelaFactory;
K_EXPORT_COMPONENT_FACTORY( chalktoolstar, FerramentaEstrelaFactory( "chalk" ) )


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

}

FerramentaEstrela::~FerramentaEstrela()
{
}

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

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

<para
>As ferramentas são carregadas pelo registo de ferramentas e registam-se elas mesmas com o registo 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 por cada janela criada. Repare que são registadas 'factories' (fábricas de objectos), de um modo geral. Por exemplo, com as ferramentas, é criada uma nova instância de uma ferramenta por cada ponteiro (rato, tablete, borracha). Uma operação de pintura nova é criada sempre que uma ferramenta recebe um evento de botão do rato pressionado. </para>

<para
>Os filtros invocam o registo 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 registo respectivo: <programlisting
>if ( mae->inherits("KisPaintOpRegistry") ) {
           KisPaintOpRegistry * r = dynamic_cast&lt;KisPaintOpRegistry*&gt;(mae);
           r -> add ( new KisSmearyOpFactory );
   }
</programlisting>
</para
><para
>Os espaços de cores procuram no registo de espaços de cores (com mais algumas complicações): <programlisting
>if ( mae->inherits("KisColorSpaceFactoryRegistry") ) {
        KisColorSpaceFactoryRegistry * f = dynamic_cast&lt;isColorSpaceFactoryRegistry*&gt;(mae);

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

       KisColorSpaceFactory * fabrica = new KisRgbColorSpaceFactory();
       f->add(fabrica);
   
       KisColorSpace * espacoCoresRGBA = new KisRgbColorSpace(f, 0);
       KisHistogramProducerFactoryRegistry::instance() -> add(
               new KisBasicHistogramProducerFactory&lt;KisBasicU8HistogramProducer&gt;
               (KisID("RGB8HISTO", i18n("RGB8 Histogram")), espacoCoresRGBA) );
   }
</programlisting>
</para
><para
>Os 'plugins' de visualização não têm de se registar elas mesmas, obtendo o acesso a um objecto <classname
>KisView</classname
> object: <programlisting
>if ( mae->inherits("KisView") )
   {
       setInstance(ShearImageFactory::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, de cada vez que o utilizador cria: a divisão de uma janela significa um novo carregamento de todos os 'plugins' de visualização de novo. </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 ficheiro <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 de todo 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 demasiado 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 dado 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 Cinzento de 16 bits consiste em quatro 'bytes': dois para o valor de cinzento e dois para o valor do 'alfa'. Está à vontade 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 conjunto rico de métodos oferecidos pelo <classname
>KisColorSpace</classname
>, para fazer o seu trabalho. Em muitos dos casos, a implementação predefinida no <classname
>KisAbstractColorSpace</classname
> irá funcionar, mas de forma mais lenta que uma implementação personalizada no seu espaço de cores, dado 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 utilizador</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 factorizado 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 utilizador 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, excepto se modificar 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, como é óbvio. </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. Para além disso, existe um método para converter para qualquer espaço de cores a partir do actual. </para
><para
>Os espaços de cores são descritos pelo vector <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 necessita de 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 vírgula flutuante de 16 e 32 bits, definindo as operações comuns para mudar de profundidades 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. Ainda que o &chalk; usa uma infra-estrutura de memória em blocos eficiente, para guardar os pixels, os criados de filtros não têm de se preocupar com a API de imagens do &Java;, o Photoshop ou o The Gimp, tendo apenas de tomar conta dos extremos dos blocos e de como <quote
>colar</quote
> os blocos em conjunto: o &chalk; esconde esse detalhe de implementação. </para>
<note
><para
>Lembre-se que é, teoricamente, simples de substituir o armazenamento dos dados da imagem por outra infra-estrutura, mas essas infra-estruturas não são 'plugins' reais de momento, por razões de performance.</para
></note>
<para
>O &chalk; usa iteradores para ler e gravar os valores dos pixels. Em alternativa, 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; poderá ser apenas mais conveniente. Veja a documentação da API. </para
><para
>As imagens do &chalk; são compostas por camadas, das quais existem de momento 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 partilhados. Um ponteiro partilhado mantém um registo dos locais em que o dispositivo de pintura é usado de facto e remove o dispositivo de pintura quando não for mais usado. Poderá reconhecer a versão do ponteiro partilhado de um dispositivo de pintura pelo seu sufixo <literal
>SP</literal
>. Basta lembrar-se que nunca terá de 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 objecto 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á actuar. 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 actual 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 facto a progressão
}
</programlisting>

<calloutlist>
<callout arearefs="invert1">
<para
>Isto cria um iterador para ler os pixels existentes. O Chalk tem três tipos de iteradores: horizontal, vertical e rectangular. O iterador de rectângulos é o caminho mais eficiente pelos 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 tem de momento. 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 rectâ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; como tal, a cópia que efectuar aqui poderá distorcer a imagem... </para
></callout>
<callout arearefs="invert3"
><para
>Deseja saber se um pixel está seleccionado? Isso é fácil &mdash; use o método <methodname
>isSelected</methodname
>. Mas o estado de seleccionado não é uma propriedade binária de um pixel; um pixel poderá estar meio-seleccionado, pouco seleccionado ou praticamente seleccionado. Esse valor também poderá ser obtido do iterador. As selecções são, de facto, um dispositivo de pintura de máscara, com um intervalo entre 0 e 255, onde o 0 é a ausência de selecção e o 255 é a selecção completa. O iterador tem dois métodos: <methodname
>isSelected()</methodname
> e <methodname
>selectedNess()</methodname
>. O primeiro devolve 'true' (verdadeiro), se um pixel estiver seleccionado 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 se aponta acima, este <literal
>memcpy</literal
> é um grande erro, de facto... o <methodname
>rawData()</methodname
> devolve o vector de 'bytes' que é o estado actual; o <methodname
>oldRawData()</methodname
> devolve o vector de 'bytes', tal como estava antes de ter sido criado o iterador. Contudo, poder-se-á estar a copiar o pixel errado aqui. Na prática, isto não irá acontecer com muita frequê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 é correcto: 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 actuais. Os espaços de cores têm bastantes 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 têm outras duas componentes importantes: um objecto de configuração e um elemento gráfico de configuração. Os dois interagem intimamente. O elemento gráfico de configuração cria um objecto de configuração, mas também pode ser preenchido a partir de um objecto de configuração previamente existente. Os objectos de configuração poder-se-ão representar a 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 rectangulares</para
></listitem>
</itemizedlist>

<para
>Os iteradores de linhas horizontais e verticais têm um método para mover o iterador para a próxima linha ou coluna: <methodname
>nextRow()</methodname
> e <methodname
>nextCol()</methodname
>. Se os usar, é 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 antevisã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 a ó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 afinado pelo utilizador. 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 a Óleo</guilabel
></screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-oilpaint.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>A janela de <guilabel
>Pintura a Óleo</guilabel
></phrase>
</textobject>
<caption
><para
>A janela de <guilabel
>Pintura a Ó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 vírgula flutuante ou booleanos. Este são úteis se, como acontece na imagem acima, o seu filtro puder ser configurado com um conjunto de inteiros, números de vírgula 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 à mão. Esta forma não é a recomendada e, se o fizer 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 a ó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
>Pode ver como ele funciona: este preenche um vector com os seus parâmetros inteiros e cria o elemento gráfico. O método <methodname
>configuration()</methodname
> inspecciona o elemento e cria o objecto de configuração do filtro correcto, nesse caso, o <classname
>KisOilPaintFilterConfiguration</classname
>. O método <methodname
>listOfExamplesConfiguration</methodname
> (que deverá mudar de nome para um Inglês correcto...) devolve uma lista com objectos 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, deverá ser capaz de ter uma boa introdução. Não hesite em contactar a equipa 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 rato/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 com cada dispositivo de entrada: o rato, 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, rectâ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 vê a tela, como a ampliação)</para
></listitem>
<listitem
><para
>ferramentas de selecção (que mudam a máscara de selecçã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 facto, uma sub-classe de <classname
>KisToolPaint</classname
>), a qual 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 tem um elemento gráfico de opções, como os filtros. De momento, os elementos gráficos aparecem numa página de uma janela acoplável. Poder-se-á 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 agora, 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 poderá 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 se viu 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. Também se poderá 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 é seleccionada. 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 (rato, caneta, borracha, etc.) for pressionado, mudado de posição ou largado. Lembre-se que também obtém mais eventos se o botão do rato não for pressionado. Os eventos não são os normais, mas sim eventos sintéticos do &chalk;, dado que se tira partido de alguns truques de baixo nível para obter eventos suficientes para desenhar uma linha suave. Por omissão, as bibliotecas, como o &Qt; (e o GTK), perdem eventos se estiverem demasiado ocupados para tratar deles, e aqui pretende-se ter todos. </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. Este é chamado a partir do método <methodname
>move()</methodname
>, para dar alguma reacção ao utilizador sobre o tamanho e a forma da sua estrela. Repare 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
> é essencialmente: aqui é criada a acção que será ligada à área de ferramentas, para que os utilizadores possam de facto seleccionar 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 por cada dispositivo de entrada. Isto também significa que é chamado o método <methodname
>setup()</methodname
> por cada dispositivo de entrada, e isso significa que é adicionada uma acção com o mesmo nome, várias vezes, à colecção de acções. Contudo, tudo parece funcionar, daí porquê as preocupações? </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. Dado que existe uma ferramenta por cada dispositivo de entrada, por 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 activada. </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. Terá de combinar as interfaces <classname
>KisTool</classname
> e <classname
>KisCanvasObserver</classname
> para criar de facto 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 com que mexem. O 'spray', o lápis ou o pincel suave: todos estes são operações de pintura. Mas você pode &mdash; com bastante 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 registo das posições anteriores e os outros dados, como os níveis de pressão, se o utilizador usar uma tablete. </para
><para
>A operação básica de uma operação de pintura é mudar os pixels na posição actual do cursor de uma ferramenta. Isto só poderá ser feito uma vez, caso contrário 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, o qual é colocado numa barra de ferramentas. Deste modo, os elementos de configuração das operações de pintura precisam de ter uma disposição horizontal dos elementos gráficos, não superiores a 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 ficheiro de inclusão, está definida uma 'factory' (fábrica de instâncias). Este objecto cria uma operação de pintura, sempre que a ferramenta activa precisar de uma: </para>

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

   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; garanta que o nome privado da sua operação de pintura não entra em conflito com outra operação! &mdash; e poderá devolver, a título opcional, 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 deverá ficar, com as operações de pintura. Este método recebe dois parâmetros: a posição actual (que está com números de vírgula flutuante, não em pixels) e um objecto <classname
>KisPaintInformation</classname
>, que contém a pressão, o toque em 'x' e 'y' e o vector de movimento, podendo ser extendida 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 ficheiro de pincel do Gimp: este é uma máscara, seja esta simples ou uma série de máscaras. De facto, não é usado aqui o pincel, excepto para determinar o <quote
>ponto fulcral</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 fraccionária. A parte inteira
   // é onde ficará o 'dab' e a parte fraccionária determina a posição nos
   // sub-pixels
   Q_INT32 x, y;
   double fraccaoX, fraccaoY;

   splitCoordinate(pt.x(), &amp;x, &amp;fraccaoX);
   splitCoordinate(pt.y(), &amp;y, &amp;fraccaoY);

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

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

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

<para
>Como dizem os comentários, o próximo bloco de código efectua algum trabalho de programação para criar o 'dab' actual. 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, tendo assim sido criado um pincel forte e húmido. Mas ainda não chegou a altura de terminar. </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 actual 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 listaPontoActual = KisVector2D(pos);
   vectorPincel.normalize();

   KisVector2D vl, vr;

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

       vr = listaPontoActual - i * vectorPincel;
       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 actualizou um pequeno rectâ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 * KisSmearyOpFactory::createOp(const KisPaintOpSettings */*configuracao*/, KisPainter * pintor)
{
   KisPaintOp * op = new KisSmearyOp(pintor);
   TQ_CHECK_PTR(op);
   return op;
}
</programlisting>

<para
>É 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 utilizador 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 arquitectura de filtros de ficheiros 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 equipa do &chalk; ao desenvolver filtros de ficheiros e fazer o desenvolvimento na árvore de filtros do &koffice;. Lembre-se que poderá testar os seus filtros, sem executar o &chalk;, usando o utilitário <command
>koconverter</command
>. </para
><para
>Os filtros têm duas faces: importação e exportação. Estes são, normalmente, dois 'plugins' diferentes que poderão partilhar algum código. </para
><para
>Os itens 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
>Quer esteja a criar um filtro de importação ou de exportação, o seu trabalho sempre passa por implementar a função que se segue: </para>

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

<para
>É a configuração dos ficheiros <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 de permitir ao &chalk; manter um ficheiro 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 que as infra-estruturas de gestão de dados que percebam os ficheiros TIFF, entre outros, e isso ainda não está implementado de momento. Seria o ideal se alguns filtros de ficheiros pudessem implementar uma classe temporária chamada <classname
>KisFileDataManager</classname
>, criassem um objecto dessa instância com o ficheiro actual e o passassem ao KisDoc. Mas o &chalk; lida com o armazenamento por camadas, não por documentos, por isso seria uma factorizaçã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 ficheiro = m_chain -> inputFile(); <co id="import4" />
   
   if (!doc)
       return KoFilter::CreationError;

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

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

       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 é suposto ser um filtro de importação; por isso, se não for invocado para converter para uma imagem do &chalk;, algo se passa de 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
>, dado 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 invocar este filtro a partir da GUI, terá de se obter uma vista. Se existir, o código de conversão poderá tentar actualizar a barra de progresso.</para
></callout>
<callout arearefs="import4"
><para
>O filtro tem o nome do ficheiro de entrada.</para
></callout>
<callout arearefs="import5"
><para
>O <classname
>KisDoc</classname
> precisa de se preparar para a importação. Algumas configurações são inicializadas e a opção para desfazer é desactivada. Caso contrário, poderia anular a adição de camadas efectuadas pelo filtro de importação, e isso seria um comportamento estranho.</para
></callout>
<callout arearefs="import6"
><para
>Optou-se por implementar o código de importação actual numa classe separada que é aqui instanciada. 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, será configurada a imagem actual do documento com a imagem acabada de criar. Aí, é tudo: <literal
>return KoFilter::OK;</literal
>.</para
></callout>
</calloutlist>

</sect3>

</sect2>

</sect1>