>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>
>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
>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
>: 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>
>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
>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/"
>) 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
>. 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
>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
> 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
> para se publicarem eles mesmos na interface de utilizador do &chalk;. As opções do menu, as janelas, barras de ferramentas — 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
>. 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>
>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
>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
>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"
>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/"
>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
> 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>
> 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
>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' — um ficheiro de inclusão e um ficheiro de implementação. </para
KisToolRegistry * r = dynamic_cast<KisToolRegistry*>( 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
>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>
>. 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>
>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 & 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
>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
>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
>QColor</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
>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>
> 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
>QColor</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>
>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
>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
>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
>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
>. 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"
> 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
>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
>(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 — 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 — 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
>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
> 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>
> é 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
>, 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>
>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>
>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>
>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
>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
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>
>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>
>As ferramentas aparecem na área de ferramentas do &chalk;. Isto significa que existe um espaço limitado para as ferramentas novas — 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
>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 — 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
>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
>O construtor define o nome interno — que não é traduzido — 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>
>) 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>
> é 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>
> é 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>
>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 — com bastante trabalho — 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
>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
>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
>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>
> com o nome público e o privado da operação de pintura — garanta que o nome privado da sua operação de pintura não entra em conflito com outra operação! — 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
> 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
// 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(), &x, &fraccaoX);
splitCoordinate(pt.y(), &y, &fraccaoY);
KisPaintDeviceSP dab = new KisPaintDevice(espacoCores, "smeary dab");
Q_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
for (int i = 0; i < (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));
>É 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>
>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"
>. É 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
>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>
>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
>, 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
>, 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
>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
