# Programação

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.

Alguns dos exemplos são distribuídos com o &chalk; e poderá encontrá-los em `/usr/share/apps/chalk/scripts` (ou `/opt/kde/share/apps/chalk/scripts`).

## Variáveis do módulo `Krosschalkcore`

- O `ChalkDocument` devolve um objecto `Document`

- O `ChalkScript` devolve um objecto `ScriptProgress`

Poderá obter um objecto com a função `get` do módulo `Krosschalkcore`; no Ruby, terá de escrever algo do género:

    doc = Krosschalkcore::get("ChalkDocument")
    programa = Krosschalkcore::get("ChalkScript")

## Funções no módulo `Krosschalkcore`

- Função: `getBrush`

  Esta função devolve um `Brush` obtido da lista de recursos do &chalk;. Recebe um argument: o nome do pincel. Por exemplo (em Ruby):

      Krosschalkcore::getBrush("Circle (05)")

- Função: `getFilter`

  Esta função devolve um `Filter` obtido da lista de recursos do &chalk;. Recebe um argumento: o nome do filtro. Por exemplo (em Ruby):

      Krosschalkcore::getFilter("invert")

- Função: `getPattern`

  Esta função devolve um `Pattern` obtido da lista de recursos do &chalk;. Recebe um argumento: o nome do padrão. Por exemplo (em Ruby):

      Krosschalkcore::getPattern("Bricks")

- Função: `loadBrush`

  Esta função carrega um `Brush` e devolve-o de seguida. Ela recebe um argumento: o nome do ficheiro do pincel.

- Função: `loadPattern`

  Esta função carrega um `Pattern` e devolve-o de seguida. Ela recebe um argumento: o nome do ficheiro do padrão.

- Função: `newCircleBrush`

  Esta função devolve um `Brush` 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):

      Krosschalkcore::newCircleBrush(10,20) # cria um círculo simples
      Krosschalkcore::newCircleBrush(10,20,5,10) # cria um gradiente

- Função: `newHSVColor`

  Esta função devolve uma nova `Color` 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):

      Krosschalkcore::newRGBColor(255,125,0)

- Função: `newImage`

  Esta função recebe uma nova `Image`. Recebe quatro argumentos: largura, altura, ID do espaço de cores, nome da imagem. Como resultado, irá obter um objecto `Image`. Por exemplo (em Ruby):

      Krosschalkcore::newImage(10,20, "RGBA", "kikoo")

- Função: `newRectBrush`

  Esta função devolve um `Brush` 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):

      Krosschalkcore::newRectBrush(10,20) # criar um rectângulo simples
       Krosschalkcore::newRectBrush(10,20,5,10) # criar um gradiente

- Função: `newRGBColor`

  Esta função devolve uma nova `Color` 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):

      Krosschalkcore::newRGBColor(255,0,0) # criar uma cor vermelha
      Krosschalkcore::newRGBColor(255,255,255) # criar uma cor branca

## Descrições e listas de funções dos vários objectos no `Krosschalkcore`

- Objecto: PaintLayer

  - Função: `beginPainting`

  - Função: `convertToColorspace`

    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):

        image.convertToColorspace("CMYK")

  - Função: `createHistogram`

    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.

  - Função: `createHLineIterator`

    Cria um iterador sobre uma camada, o qual irá percorrer uma linha. Esta função recebe três argumentos: `x` (início na linha), `y` (posição vertical da linha), largura da linha.

  - Função: `createPainter`

    Esta função cria um `Painter` que lhe permitirá pintar algumas coisas na camada.

  - Função: `createRectIterator`

    Cria um iterador sobre uma camada, que irá funcionar sobre uma área rectangular. Esta função recebe quatro argumentos: `x`, `y`, largura do rectângulo, altura do rectângulo.

  - Função: `createVLineIterator`

    Cria um iterador sobre uma camada, o qual irá percorrer uma coluna. Esta função recebe três argumentos: `x` (posição horizontal da coluna), `y` (início da coluna), altura da coluna.

  - Função: `endPainting`

    Usa esta função para fechar o item a desfazer actual e adicioná-lo ao histórico.

  - Função: `fastWaveletTransformation`

    Devolve a transformada por ondulação da camada.

  - Função: `fastWaveletUntransformation`

    Anula uma ondulação desta camada. Recebe um argumento: um objecto de ondulação. Por exemplo (em Ruby):

        wavelet = camada.fastWaveletTransformation()
        camada.fastWaveletUntransformation(wavelet)

  - Função: `getHeight`

    Devolve a altura da camada.

  - Função: `getWidth`

    Devolve a largura da camada.

- Objecto: `Filter`

  - Função: `getFilterConfiguration`

    Esta função devolve a `FilterConfiguration` associada com este filtro.

  - Função: `process`

    Esta função irá aplicar o filtro. Recebe pelo menos um argumento: a camada de origem. Poderá também usar estes quatro argumentos: `x`, `y`, `largura`, `altura`. O (`x`,`y`,`largura`,`altura`) 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)

        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 )

- Objecto: `FilterConfiguration`

  - Função: `getProperty`

    Esta função devolve o valor de um parâmetro do `Filter` associado. Ele recebe um argumento: o nome do parâmetro.

  - Função: `setProperty`

    Esta função define um parâmetro do `Filter` associado. Ela recebe dois argumentos: o nome do parâmetro e o valor, cujo tipo depende do `Filter`.

- Objecto: `Histogram`

  Esta classe permite-lhe aceder ao histograma de um `PaintLayer`. Exemplo (em Ruby):

      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

  - Função: `getChannel`

    Devolve o canal seleccionado.

  - Função: `getCount`

    Esta função devolve o número de pixel usado pelo histograma.

  - Função: `getHighest`

    Esta função devolve o valor mais elevado do histograma.

  - Função: `getLowest`

    Esta função devolve o valor mínimo do histograma.

  - Função: `getMax`

    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.

  - Função: `getMean`

    Esta função devolve a média do histograma.

  - Função: `getMin`

    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.

  - Função: `getNumberOfBins`

    Devolve o número de abcissas deste histograma.

  - Função: `getTotal`

    Esta função devolve o somatório de todos os valores do histograma.

  - Função: `getValue`

    Devolve o valor de uma abcissa do histograma. Esta função recebe um argumento 'índice' no intervalo [0..255].

  - Função: `setChannel`

    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.

- Objecto: `ScriptProgress`

  O `ScriptProgress` é usado para gerir a barra de progresso da barra de estado do &chalk;. Por exemplo (em Ruby):

      programa = Krosschalkcore::get("ChalkScript")
      programa.setProgressTotalSteps(1000)
      programa.setProgressStage("progressive", 0)
      for i in 1..900
        programa.incProgress()
      end
      programa.setProgressStage("brutal", 1000)

  - Função: `incProgress`

    Esta função avança um passo no progresso.

  - Função: `setProgress`

    Esta função altera o valor do progresso. Recebe um argumento: o valor do progresso.

  - Função: `setProgressStage`

    Esta função altera o valor do progresso e mostra o texto.

  - Função: `setProgressTotalSteps`

    Esta função define o número de passos que o programa irá necessitar. Recebe um argumento: o valor máximo do progresso

- Objecto: `Wavelet`

  Este objecto contém os coeficientes de uma transformação por ondulação de um `PaintLayer`.

  - Função: `getDepth`

    Devolve a profundidade da camada.

  - Função: `getNCoeff`

    Devolve o valor o N-ésimo coeficiente. A função recebe um argumento: o índice do coeficiente.

  - Função: `getNumCoeffs`

    Devolve o número de coeficientes nesta ondulação (= tamanho * tamanho * profundidade).

  - Função: `getSize`

    Devolve o tamanho da ondulação (tamanho = largura = altura).

  - Função: `getXYCoeff`

    Devolve o valor de um coeficiente. A função recebe dois argumentos: `x` e `y`.

  - Função: `setNCoeff`

    Altera o valor do N-ésimo coeficiente. A função recebe dois argumentos: o índice do coeficiente e o novo valor do coeficiente.

  - Função: `setXYCoeff`

    Altera o valor de um coeficiente. A função recebe três argumentos: `x`, `y` e o novo valor do coeficiente.

- Objecto: `Painter`

  - Função: `convolve`

    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.

    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.

    Poderá receber os seguintes argumentos opcionais: `opContorno` (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), `canal` (1 para a cor, 2 para o alfa, 3 para ambos), `x`, `y`, `largura`, `altura`.

  - Função: `setFillThreshold`

    Define o limiar de preenchimento. Recebe um argumento: o limite.

  - Função: `fillColor`

    Começa a preencher com uma cor. Recebe dois argumentos: `x` e `y`.

  - Função: `fillPattern`

    Começa a preencher com um padrão. Recebe dois argumentos: `x` e `y`.

  - Função: `paintPolyline`

    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.

  - Função: `paintLine`

    Esta função irá pintar uma linha. Ele recebe cinco argumentos: `x1`, `y1`, `x2`, `y2` e `pressão`.

  - Função: `paintBezierCurve`

    Esta função irá pintar uma curva Bezier. Recebe dez argumentos: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2`, `p2`, onde o (`x1`,`y1`) é a posição inicial, o `p1` é a pressão inicial, (`x2`,`y2`) é a posição final, `p2` é a pressão no fim. O (`cx1`,`cy1`) e o (`cx2`,`cy2`) são as posições dos pontos de controlo.

  - Função: `paintEllipse`

    Esta função irá pintar uma elipse. Recebe cinco argumentos: `x1`, `y1`, `x2`, `y2`, `pressão`, onde o (`x1`,`y1`) e o (`x2`,`y2`) são as posições dos dois centros.

  - Função: `paintPolygon`

    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.

  - Função: `paintRect`

    Esta função irá pintar um rectângulo. Recebe cinco argumentos: `x`, `y`, `largura` `altura`, `pressão`.

  - Função: `paintAt`

    Esta função irá pintar numa dada posição. Recebe três argumentos: `x`, `y`, `pressão`.

  - Função: `setPaintColor`

    Esta função define a cor de pintura (também chamada de cor principal). Recebe um argumento: um `Color`.

  - Função: `setBackgroundColor`

    Esta função altera a cor de fundo. Recebe um argumento: uma `Color`.

  - Função: `setPattern`

    Esta função altera o padrão usado no preenchimento. Recebe um argumento: um objecto `Pattern`.

  - Função: `setBrush`

    Esta função altera o pincel usado na pintura. Recebe um argumento: um objecto `Brush`.

  - Função: `setPaintOp`

    Esta função define a operação de pintura. Recebe um argumento: o nome da operação de pintura.

  - Função: `setDuplicateOffset`

    Esta função define o deslocamento do duplicado. Recebe dois argumentos: o deslocamento horizontal e o vertical.

  - Função: `setOpacity`

    Esta função altera a opacidade da pintura. Recebe um argumento: a opacidade, no intervalo de 0 a 255.

  - Função: `setStrokeStyle`

    Esta função define o estilo do traço. Recebe um argumento: 0 para nenhum e 1 para pincel.

  - Função: `setFillStyle`

    Esta função altera o estilo de preenchimento do `Painter`. 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.

- Objecto: `Iterator`

  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 `setR`, `setG` e o `setB` e, no caso do CMYK: `setC`, `setM`, `setY` e `setK`. Na documentação abaixo, assumir-se-á que o espaço de cores se chamada ABC, com três canais: A, B e C.

  - Funções: `setA`, `setB`, `setC`

    Estas funções recebem um argumento: o novo valor de um dos canais deste pixel.

  - Função: `setABC`

    Altera o valor de todos os canais. Esta função recebe um argumento: uma lista com os valores novos de todos os canais.

  - Função `getA`, `getB`, `getC`

    Devolve o valor de um dos canais deste pixel.

  - Função: `getABC`

    Devolve uma lista com os valores de todos os canais.

  - Função: `darken`

    Torna um pixel mais escuro. Esta função recebe pelo menos um argumento: `sombra` (quantidade usada para escurecer todos os canais de cores). Esta função poderá recebe o seguinte argumento opcional: `compensação` (para limitar o escurecimento).

  - Função: `invertColor`

    Inverte a cor de um pixel.

  - Função: `next`

    Incrementa a posição, indo para o pixel seguinte.

  - Função: `isDone`

    Devolve 'true' (verdadeiro) se o iterador estiver no fim (não existirem mais pixels).

## Recursos

Aqui estão sugestões ou listas parciais de recursos do &chalk;.

Para o `Brush` e o `Pattern`: Poderá obter o nome e o pincel ou padrão associado do selector da barra de ferramentas do &chalk;.

Uma lista de identificadores de espaços de cores no &chalk;: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.