<sect1 id="developers-scripting"> <title >Programação</title> <para >No &chalk;, poderá criar programas em Ruby ou Python (a disponibilidade dos interpretadores poderá depender das suas distribuições ou se o administrador da sua máquina os instalou). Aqui poderá encontrar uma descrição da API de programação. </para ><para >Alguns dos exemplos são distribuídos com o &chalk; e poderá encontrá-los em <filename >/usr/share/apps/chalk/scripts</filename > (ou <filename >/opt/kde/share/apps/chalk/scripts</filename >). </para> <sect2 id="developers-scripting-variables"> <title >Variáveis do módulo <classname >Krosschalkcore</classname ></title> <itemizedlist> <listitem ><para >O <varname >ChalkDocument</varname > devolve um objecto <classname >Document</classname ></para ></listitem> <listitem ><para >O <varname >ChalkScript</varname > devolve um objecto <classname >ScriptProgress</classname ></para ></listitem> </itemizedlist> <para >Poderá obter um objecto com a função <function >get</function > do módulo <classname >Krosschalkcore</classname >; no Ruby, terá de escrever algo do género: <programlisting >doc = Krosschalkcore::get("ChalkDocument") programa = Krosschalkcore::get("ChalkScript") </programlisting> </para> </sect2> <sect2 id="developers-scripting-functions"> <title >Funções no módulo <classname >Krosschalkcore</classname ></title> <itemizedlist> <listitem ><para >Função: <function >getBrush</function ></para ><para >Esta função devolve um <classname >Brush</classname > obtido da lista de recursos do &chalk;. Recebe um argument: o nome do pincel. Por exemplo (em Ruby): <programlisting >Krosschalkcore::getBrush("Circle (05)") </programlisting ></para ></listitem> <listitem ><para >Função: <function >getFilter</function ></para ><para >Esta função devolve um <classname >Filter</classname > obtido da lista de recursos do &chalk;. Recebe um argumento: o nome do filtro. Por exemplo (em Ruby): <programlisting >Krosschalkcore::getFilter("invert") </programlisting ></para ></listitem> <listitem ><para >Função: <function >getPattern</function ></para ><para >Esta função devolve um <classname >Pattern</classname > obtido da lista de recursos do &chalk;. Recebe um argumento: o nome do padrão. Por exemplo (em Ruby): <programlisting >Krosschalkcore::getPattern("Bricks") </programlisting ></para ></listitem> <listitem ><para >Função: <function >loadBrush</function ></para ><para >Esta função carrega um <classname >Brush</classname > e devolve-o de seguida. Ela recebe um argumento: o nome do ficheiro do pincel.</para ></listitem> <listitem ><para >Função: <function >loadPattern</function ></para ><para >Esta função carrega um <classname >Pattern</classname > e devolve-o de seguida. Ela recebe um argumento: o nome do ficheiro do padrão.</para ></listitem> <listitem ><para >Função: <function >newCircleBrush</function ></para ><para >Esta função devolve um <classname >Brush</classname > com uma forma circular. Recebe pelo menos dois argumentos: a largura e a altura. Poderá receber outros dois argumentos: a largura e a altura do sombreado. Se não for indicado qualquer sombreado, este não será usado. Por exemplo (em Ruby): <programlisting >Krosschalkcore::newCircleBrush(10,20) # cria um círculo simples Krosschalkcore::newCircleBrush(10,20,5,10) # cria um gradiente </programlisting ></para ></listitem> <listitem ><para >Função: <function >newHSVColor</function ></para ><para >Esta função devolve uma nova <classname >Color</classname > com o tuplo de HSV indicado. Recebe três argumentos: a componente do matiz (0 a 255), da saturação (0 a 255) e do valor (0 to 255). Por exemplo (em Ruby): <programlisting >Krosschalkcore::newRGBColor(255,125,0) </programlisting ></para ></listitem> <listitem ><para >Função: <function >newImage</function ></para ><para >Esta função recebe uma nova <classname >Image</classname >. Recebe quatro argumentos: largura, altura, ID do espaço de cores, nome da imagem. Como resultado, irá obter um objecto <classname >Image</classname >. Por exemplo (em Ruby): <programlisting >Krosschalkcore::newImage(10,20, "RGBA", "kikoo") </programlisting ></para ></listitem> <listitem ><para >Função: <function >newRectBrush</function ></para ><para >Esta função devolve um <classname >Brush</classname > com uma forma rectangular. Recebe pelo menos dois argumentos: a largura e a altura. Poderá receber outros dois argumentos: a largura e a altura do sombreado. Se não for indicado qualquer sombreado, este não será usado. Por exemplo (em Ruby): <programlisting >Krosschalkcore::newRectBrush(10,20) # criar um rectângulo simples Krosschalkcore::newRectBrush(10,20,5,10) # criar um gradiente </programlisting ></para ></listitem> <listitem ><para >Função: <function >newRGBColor</function ></para ><para >Esta função devolve uma nova <classname >Color</classname > com o tuplo de RGB indicado. Recebe três argumentos: a componente do vermelho (0 a 255), do verde (0 a 255) e do azul (0 to 255). Por exemplo (em Ruby): <programlisting >Krosschalkcore::newRGBColor(255,0,0) # criar uma cor vermelha Krosschalkcore::newRGBColor(255,255,255) # criar uma cor branca </programlisting ></para ></listitem> </itemizedlist> </sect2> <sect2 id="developers-scripting-objects"> <title >Descrições e listas de funções dos vários objectos no <classname >Krosschalkcore</classname ></title> <itemizedlist> <listitem ><para >Objecto: PaintLayer</para> <itemizedlist> <listitem ><para >Função: <function >beginPainting</function ></para ></listitem> <listitem ><para >Função: <function >convertToColorspace</function ></para ><para >Converte a imagem para um espaço de cores. Esta função recebe um argumento: o nome do espaço de cores de destino. Por exemplo (em Ruby): <programlisting >image.convertToColorspace("CMYK") </programlisting ></para ></listitem> <listitem ><para >Função: <function >createHistogram</function ></para ><para >Esta função cria um histograma para esta camada. Recebe dois argumentos: o tipo do histograma ("RGB8HISTO") e 0 se o histograma for linear ou 1 se for logarítmico.</para ></listitem> <listitem ><para >Função: <function >createHLineIterator</function ></para ><para >Cria um iterador sobre uma camada, o qual irá percorrer uma linha. Esta função recebe três argumentos: <varname >x</varname > (início na linha), <varname >y</varname > (posição vertical da linha), largura da linha.</para ></listitem> <listitem ><para >Função: <function >createPainter</function ></para ><para >Esta função cria um <classname >Painter</classname > que lhe permitirá pintar algumas coisas na camada. </para ></listitem> <listitem ><para >Função: <function >createRectIterator</function ></para ><para >Cria um iterador sobre uma camada, que irá funcionar sobre uma área rectangular. Esta função recebe quatro argumentos: <varname >x</varname >, <varname >y</varname >, largura do rectângulo, altura do rectângulo.</para ></listitem> <listitem ><para >Função: <function >createVLineIterator</function ></para ><para >Cria um iterador sobre uma camada, o qual irá percorrer uma coluna. Esta função recebe três argumentos: <varname >x</varname > (posição horizontal da coluna), <varname >y</varname > (início da coluna), altura da coluna.</para ></listitem> <listitem ><para >Função: <function >endPainting</function ></para ><para >Usa esta função para fechar o item a desfazer actual e adicioná-lo ao histórico.</para ></listitem> <listitem ><para >Função: <function >fastWaveletTransformation</function ></para ><para >Devolve a transformada por ondulação da camada.</para ></listitem> <listitem ><para >Função: <function >fastWaveletUntransformation</function ></para ><para >Anula uma ondulação desta camada. Recebe um argumento: um objecto de ondulação. Por exemplo (em Ruby): <programlisting >wavelet = camada.fastWaveletTransformation() camada.fastWaveletUntransformation(wavelet) </programlisting ></para ></listitem> <listitem ><para >Função: <function >getHeight</function ></para ><para >Devolve a altura da camada.</para ></listitem> <listitem ><para >Função: <function >getWidth</function ></para ><para >Devolve a largura da camada.</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Objecto: <classname >Filter</classname ></para> <itemizedlist> <listitem ><para >Função: <function >getFilterConfiguration</function ></para ><para >Esta função devolve a <classname >FilterConfiguration</classname > associada com este filtro.</para ></listitem> <listitem ><para >Função: <function >process</function ></para ><para >Esta função irá aplicar o filtro. Recebe pelo menos um argumento: a camada de origem. Poderá também usar estes quatro argumentos: <varname >x</varname >, <varname >y</varname >, <varname >largura</varname >, <varname >altura</varname >. O (<varname >x</varname >,<varname >y</varname >,<varname >largura</varname >,<varname >altura</varname >) define a área rectangular na qual será calculado o filtro. Se o rectângulo não for definido, então o filtro será aplicado na camada de origem inteira. Por exemplo (em Ruby) <programlisting >doc = Krosschalkcore::get("ChalkDocument") imagem = doc.getImage() camada = imagem.getActivePaintLayer() largura = camada.getWidth() altura = camada.getHeight() filtro = Krosschalkcore::getFilter("invert") filtro.process(camada, camada) filtro.process(camada, camada, 10, 10, 20, 20 ) </programlisting ></para ></listitem> </itemizedlist ></listitem> <listitem ><para >Objecto: <classname >FilterConfiguration</classname ></para> <itemizedlist> <listitem ><para >Função: <function >getProperty</function ></para ><para >Esta função devolve o valor de um parâmetro do <classname >Filter</classname > associado. Ele recebe um argumento: o nome do parâmetro.</para ></listitem> <listitem ><para >Função: <function >setProperty</function ></para ><para >Esta função define um parâmetro do <classname >Filter</classname > associado. Ela recebe dois argumentos: o nome do parâmetro e o valor, cujo tipo depende do <classname >Filter</classname >.</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Objecto: <classname >Histogram</classname ></para> <para >Esta classe permite-lhe aceder ao histograma de um <classname >PaintLayer</classname >. Exemplo (em Ruby): <programlisting >doc = krosschalkcore::get("ChalkDocument") imagm = doc.getImage() camada = imagem.getActiveLayer() histo = camada.createHistogram("RGB8HISTO",0) min = camada.getMin() * 255 max = camada.getMax() * 255 for i in min..max print camada.getValue(i) print "\n" end </programlisting> </para> <itemizedlist> <listitem ><para >Função: <function >getChannel</function ></para ><para >Devolve o canal seleccionado.</para ></listitem> <listitem ><para >Função: <function >getCount</function ></para ><para >Esta função devolve o número de pixel usado pelo histograma.</para ></listitem> <listitem ><para >Função: <function >getHighest</function ></para ><para >Esta função devolve o valor mais elevado do histograma.</para ></listitem> <listitem ><para >Função: <function >getLowest</function ></para ><para >Esta função devolve o valor mínimo do histograma.</para ></listitem> <listitem ><para >Função: <function >getMax</function ></para ><para >Esta função devolve o limite máximo do histograma (os valores com maior posição que o máximo são nulos). O valor está no intervalo 0.0 – 1.0.</para ></listitem> <listitem ><para >Função: <function >getMean</function ></para ><para >Esta função devolve a média do histograma.</para ></listitem> <listitem ><para >Função: <function >getMin</function ></para ><para >Esta função devolve o limite mínimo do histograma (os valores com menor posição que o máximo são nulos). O valor está no intervalo 0.0 – 1.0.</para ></listitem> <listitem ><para >Função: <function >getNumberOfBins</function ></para ><para >Devolve o número de abcissas deste histograma. </para ></listitem> <listitem ><para >Função: <function >getTotal</function ></para ><para >Esta função devolve o somatório de todos os valores do histograma.</para ></listitem> <listitem ><para >Função: <function >getValue</function ></para ><para >Devolve o valor de uma abcissa do histograma. Esta função recebe um argumento 'índice' no intervalo [0..255].</para ></listitem> <listitem ><para >Função: <function >setChannel</function ></para ><para >Selecciona o canal da camada para o qual irá obter o resultado do histograma. Esta função recebe um argumento: o número do canal.</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Objecto: <classname >ScriptProgress</classname ></para> <para >O <classname >ScriptProgress</classname > é usado para gerir a barra de progresso da barra de estado do &chalk;. Por exemplo (em Ruby): <programlisting >programa = Krosschalkcore::get("ChalkScript") programa.setProgressTotalSteps(1000) programa.setProgressStage("progressive", 0) for i in 1..900 programa.incProgress() end programa.setProgressStage("brutal", 1000) </programlisting ></para> <itemizedlist> <listitem ><para >Função: <function >incProgress</function ></para ><para >Esta função avança um passo no progresso.</para ></listitem> <listitem ><para >Função: <function >setProgress</function ></para ><para >Esta função altera o valor do progresso. Recebe um argumento: o valor do progresso.</para ></listitem> <listitem ><para >Função: <function >setProgressStage</function ></para ><para >Esta função altera o valor do progresso e mostra o texto.</para ></listitem> <listitem ><para >Função: <function >setProgressTotalSteps</function ></para ><para >Esta função define o número de passos que o programa irá necessitar. Recebe um argumento: o valor máximo do progresso</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Objecto: <classname >Wavelet</classname ></para ><para >Este objecto contém os coeficientes de uma transformação por ondulação de um <classname >PaintLayer</classname >.</para> <itemizedlist> <listitem ><para >Função: <function >getDepth</function ></para ><para >Devolve a profundidade da camada.</para ></listitem> <listitem ><para >Função: <function >getNCoeff</function ></para ><para >Devolve o valor o N-ésimo coeficiente. A função recebe um argumento: o índice do coeficiente.</para ></listitem> <listitem ><para >Função: <function >getNumCoeffs</function ></para ><para >Devolve o número de coeficientes nesta ondulação (= tamanho * tamanho * profundidade).</para ></listitem> <listitem ><para >Função: <function >getSize</function ></para ><para >Devolve o tamanho da ondulação (tamanho = largura = altura).</para ></listitem> <listitem ><para >Função: <function >getXYCoeff</function ></para ><para >Devolve o valor de um coeficiente. A função recebe dois argumentos: <varname >x</varname > e <varname >y</varname >.</para ></listitem> <listitem ><para >Função: <function >setNCoeff</function ></para ><para >Altera o valor do N-ésimo coeficiente. A função recebe dois argumentos: o índice do coeficiente e o novo valor do coeficiente.</para ></listitem> <listitem ><para >Função: <function >setXYCoeff</function ></para ><para >Altera o valor de um coeficiente. A função recebe três argumentos: <varname >x</varname >, <varname >y</varname > e o novo valor do coeficiente.</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Objecto: <classname >Painter</classname ></para> <itemizedlist> <listitem ><para >Função: <function >convolve</function ></para ><para >Esta função aplica um módulo de convolução a uma imagem. Recebe pelo menos três argumentos: uma lista de listas com o módulo (todas as listas deverão ter o mesmo tamanho), o factor e o deslocamento. </para ><para >O valor de um pixel será dado pela seguinte função: K * P / factor + deslocamento, onde o K é o módulo e o P a vizinhança. </para ><para >Poderá receber os seguintes argumentos opcionais: <varname >opContorno</varname > (controla como fazer a convolução dos pixels no extremo de uma imagem: 0 = usar a cor predefinida, 1 = usa o pixel do lado oposto da imagem, 2 = usar o pixel do contorno, 3 = evitar os pixels do contorno), <varname >canal</varname > (1 para a cor, 2 para o alfa, 3 para ambos), <varname >x</varname >, <varname >y</varname >, <varname >largura</varname >, <varname >altura</varname >.</para ></listitem> <listitem ><para >Função: <function >setFillThreshold</function ></para ><para >Define o limiar de preenchimento. Recebe um argumento: o limite.</para ></listitem> <listitem ><para >Função: <function >fillColor</function ></para ><para >Começa a preencher com uma cor. Recebe dois argumentos: <varname >x</varname > e <varname >y</varname >.</para ></listitem> <listitem ><para >Função: <function >fillPattern</function ></para ><para >Começa a preencher com um padrão. Recebe dois argumentos: <varname >x</varname > e <varname >y</varname >.</para ></listitem> <listitem ><para >Função: <function >paintPolyline</function ></para ><para >Esta função irá pintar uma linha poligonal. Recebe dois argumentos: uma lista de posições em X e uma lista de posições em Y.</para ></listitem> <listitem ><para >Função: <function >paintLine</function ></para ><para >Esta função irá pintar uma linha. Ele recebe cinco argumentos: <varname >x1</varname >, <varname >y1</varname >, <varname >x2</varname >, <varname >y2</varname > e <varname >pressão</varname >. </para ></listitem> <listitem ><para >Função: <function >paintBezierCurve</function ></para ><para >Esta função irá pintar uma curva Bezier. Recebe dez argumentos: <varname >x1</varname >, <varname >y1</varname >, <varname >p1</varname >, <varname >cx1</varname >, <varname >cy1</varname >, <varname >cx2</varname >, <varname >cx2</varname >, <varname >x2</varname >, <varname >y2</varname >, <varname >p2</varname >, onde o (<varname >x1</varname >,<varname >y1</varname >) é a posição inicial, o <varname >p1</varname > é a pressão inicial, (<varname >x2</varname >,<varname >y2</varname >) é a posição final, <varname >p2</varname > é a pressão no fim. O (<varname >cx1</varname >,<varname >cy1</varname >) e o (<varname >cx2</varname >,<varname >cy2</varname >) são as posições dos pontos de controlo.</para ></listitem> <listitem ><para >Função: <function >paintEllipse</function ></para ><para >Esta função irá pintar uma elipse. Recebe cinco argumentos: <varname >x1</varname >, <varname >y1</varname >, <varname >x2</varname >, <varname >y2</varname >, <varname >pressão</varname >, onde o (<varname >x1</varname >,<varname >y1</varname >) e o (<varname >x2</varname >,<varname >y2</varname >) são as posições dos dois centros.</para ></listitem> <listitem ><para >Função: <function >paintPolygon</function ></para ><para >Esta função irá pintar um polígono. Recebe dois argumentos: uma lista de posições em X e uma lista de posições em Y.</para ></listitem> <listitem ><para >Função: <function >paintRect</function ></para ><para >Esta função irá pintar um rectângulo. Recebe cinco argumentos: <varname >x</varname >, <varname >y</varname >, <varname >largura</varname > <varname >altura</varname >, <varname >pressão</varname >.</para ></listitem> <listitem ><para >Função: <function >paintAt</function ></para ><para >Esta função irá pintar numa dada posição. Recebe três argumentos: <varname >x</varname >, <varname >y</varname >, <varname >pressão</varname >.</para ></listitem> <listitem ><para >Função: <function >setPaintColor</function ></para ><para >Esta função define a cor de pintura (também chamada de cor principal). Recebe um argumento: um <classname >Color</classname >.</para ></listitem> <listitem ><para >Função: <function >setBackgroundColor</function ></para ><para >Esta função altera a cor de fundo. Recebe um argumento: uma <classname >Color</classname >.</para ></listitem> <listitem ><para >Função: <function >setPattern</function ></para ><para >Esta função altera o padrão usado no preenchimento. Recebe um argumento: um objecto <classname >Pattern</classname >.</para ></listitem> <listitem ><para >Função: <function >setBrush</function ></para ><para >Esta função altera o pincel usado na pintura. Recebe um argumento: um objecto <classname >Brush</classname >.</para ></listitem> <listitem ><para >Função: <function >setPaintOp</function ></para ><para >Esta função define a operação de pintura. Recebe um argumento: o nome da operação de pintura.</para ></listitem> <listitem ><para >Função: <function >setDuplicateOffset</function ></para ><para >Esta função define o deslocamento do duplicado. Recebe dois argumentos: o deslocamento horizontal e o vertical.</para ></listitem> <listitem ><para >Função: <function >setOpacity</function ></para ><para >Esta função altera a opacidade da pintura. Recebe um argumento: a opacidade, no intervalo de 0 a 255.</para ></listitem> <listitem ><para >Função: <function >setStrokeStyle</function ></para ><para >Esta função define o estilo do traço. Recebe um argumento: 0 para nenhum e 1 para pincel.</para ></listitem> <listitem ><para >Função: <function >setFillStyle</function ></para ><para >Esta função altera o estilo de preenchimento do <classname >Painter</classname >. Recebe um argumento: 0 para nada, 1 para o preenchimento com a cor principal, 2 para o preenchimento com a cor de fundo e 3 para o preenchimento com um padrão.</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Objecto: <classname >Iterator</classname ></para ><para >Este objecto permite-lhe alterar os valores dos pixels um a um. O nome de algumas funções depende do espaço de cores; por exemplo, se o espaço de cores da camada for o RGB, terá o <function >setR</function >, <function >setG</function > e o <function >setB</function > e, no caso do CMYK: <function >setC</function >, <function >setM</function >, <function >setY</function > e <function >setK</function >. Na documentação abaixo, assumir-se-á que o espaço de cores se chamada ABC, com três canais: A, B e C.</para> <itemizedlist> <listitem ><para >Funções: <function >setA</function >, <function >setB</function >, <function >setC</function ></para ><para >Estas funções recebem um argumento: o novo valor de um dos canais deste pixel.</para ></listitem> <listitem ><para >Função: <function >setABC</function ></para ><para >Altera o valor de todos os canais. Esta função recebe um argumento: uma lista com os valores novos de todos os canais.</para ></listitem> <listitem ><para >Função <function >getA</function >, <function >getB</function >, <function >getC</function ></para ><para >Devolve o valor de um dos canais deste pixel.</para ></listitem> <listitem ><para >Função: <function >getABC</function ></para ><para >Devolve uma lista com os valores de todos os canais.</para ></listitem> <listitem ><para >Função: <function >darken</function ></para ><para >Torna um pixel mais escuro. Esta função recebe pelo menos um argumento: <varname >sombra</varname > (quantidade usada para escurecer todos os canais de cores). Esta função poderá recebe o seguinte argumento opcional: <varname >compensação</varname > (para limitar o escurecimento).</para ></listitem> <listitem ><para >Função: <function >invertColor</function ></para ><para >Inverte a cor de um pixel.</para ></listitem> <listitem ><para >Função: <function >next</function ></para ><para >Incrementa a posição, indo para o pixel seguinte.</para ></listitem> <listitem ><para >Função: <function >isDone</function ></para ><para >Devolve 'true' (verdadeiro) se o iterador estiver no fim (não existirem mais pixels).</para ></listitem> </itemizedlist> </listitem> </itemizedlist> </sect2> <sect2 id="developers-scripting-resources"> <title >Recursos</title> <para >Aqui estão sugestões ou listas parciais de recursos do &chalk;. </para ><para >Para o <classname >Brush</classname > e o <classname >Pattern</classname >: Poderá obter o nome e o pincel ou padrão associado do selector da barra de ferramentas do &chalk;. </para ><para >Uma lista de identificadores de espaços de cores no &chalk;: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16. </para> </sect2> </sect1>