# Scripter

I &chalk; kan du skrive scripter med Ruby eller Python (tilgængeligheden af disse fortolkere kan afhænge af hvad din distribution eller administratoren af din maskine installerede). Her finder du en beskrivelse af programmeringsgrænsefladen for scripter.

Visse eksempler leveres med &chalk;, og du kan finde dem i `/usr/share/apps/chalk/scripts` (eller `/opt/kde/share/apps/chalk/scripts`).

## Variabler i modulet `Krosschalkcore`

- `ChalkDocument` returnerer et `Document`-objekt

- `ChalkScript` returnerer et `ScriptProgress`-objekt

Du kan hente et objekt med funktionen `get` i modulet `Krosschalkcore`. I Ruby skal du skrive noget i retning af dette:

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

## Funktioner i modulet `Krosschalkcore`

- Funktion: `getBrush`

  Denne funktion returnerer en pensel (`Brush`) som tages fra listen med &chalk;s ressourcer. Den har et argument: penslens navn. For eksempel (i Ruby):

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

- Funktion: `getFilter`

  Denne funktion returnerer et filter (`Filter`) som tages fra listen med &chalk;s ressourcer. Den har et argument: filtrets navn. For eksempel (i Ruby):

      Krosschalkcore::getFilter("invert")

- Funktion: `getPattern`

  Denne funktion returnerer et mønster (`Pattern`) som tages fra listen med &chalk;s ressourcer. Den har et argument: mønstrets navn. For eksempel (i Ruby):

      Krosschalkcore::getPattern("Bricks")

- Funktion: `loadBrush`

  Denne funktion indlæser en pensel (`Brush`) og returnerer den derefter. Den har et argument: penslens filnavn.

- Funktion: `loadPattern`

  Denne funktion indlæser et mønster (`Pattern`) og returnerer det derefter. Den har et argument: mønstrets filnavn.

- Funktion: `newCircleBrush`

  Denne funktion returnerer en pensel (`Brush`) med en cirkulær form. Den har mindst to argumenter: bredde og højde. Den kan også have to yderligere argumenter: skyggens bredde og højde. Hvis skyggen ikke angives, bruges ingen. For eksempel (i Ruby):

      Krosschalkcore::newCircleBrush(10,20) # opret en almindelig cirkel
      Krosschalkcore::newCircleBrush(10,20,5,10) # oprette en overgang

- Funktion: `newHSVColor`

  Denne funktion returnerer en ny farve (`Color`) med den angivne HSV-trippel. Den har tre argumenter: farvetonekomponenten (0 til 255), farvemætningskomponenten (0 til 255), og værdikomponenten (0 til 255). For eksempel (i Ruby):

      Krosschalkcore::newHSVColor(255,125,0)

- Funktion: `newImage`

  Denne funktion returnerer et nyt billede (`Image`). Den har fire argumenter: bredde, højde, farverumsidentifikation, billedets navn. Den returnerer objektet `Image`. For eksempel (i Ruby):

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

- Funktion: `newRectBrush`

  Denne funktion returnerer en pensel (`Brush`) med en rektangulær form. Den har mindst to argumenter: bredde og højde. Den kan også have to yderligere argumenter: skyggens bredde og højde. Hvis skyggen ikke angives, bruges ingen. For eksempel (i Ruby):

      Krosschalkcore::newRectBrush(10,20) # opret et almindeligt rektangel
       Krosschalkcore::newRectBrush(10,20,5,10) # opret en overgang

- Funktion: `newRGBColor`

  Denne funktion returnerer en ny farve (`Color`) med den angivne RGB-trippel. Den har tre argumenter: den røde komponent (0 til 255), den blå komponent (0 til 255), og den grønne komponent (0 til 255). For eksempel (i Ruby):

      Krosschalkcore::newRGBColor(255,0,0) # opret en rød farve
      Krosschalkcore::newRGBColor(255,255,255) # opret en hvid farve

## Beskrivelser og funktionslister for diverse objekter i `Krosschalkcore`

- Objekt: PaintLayer

  - Funktion: `beginPainting`

  - Funktion: `convertToColorspace`

    Konvertér billedet til et farverum. Denne funktion har et argument: navnet på det resulterende farverum. For eksempel (i Ruby):

        image.convertToColorspace("CMYK")

  - Funktion: `createHistogram`

    Denne funktion laver et histogram for dette lag. Den har to argumenter: histogramtypen ("RGB8HISTO"), og 0 hvis histogrammet er lineært eller 1 hvis det er logaritmisk.

  - Funktion: `createHLineIterator`

    Opret en iterator over et lag, som iterere på en række. Denne funktion har tre argumenter: `x` (start i rækken), `y` (rækkens lodrette position), rækkens bredde.

  - Funktion: `createPainter`

    Denne funktion laver en (`Painter`) som lader dig male på laget.

  - Funktion: `createRectIterator`

    Opret en iterator for et lag, som itererer i et rektangulært område. Denne funktion har fire argumenter: `x`, `y`, rektanglets bredde, rektanglets højde.

  - Funktion: `createVLineIterator`

    Opret en iterator for et lag, som itererer gennem en søjle. Denne funktion har tre argumenter: `x` (søjlens vandrette position), `y` (start i søjlen), søjlens højde.

  - Funktion: `endPainting`

    Denne funktion lukker nuværende fortrydelsesindgang og tilføje den til historikken.

  - Funktion: `fastWaveletTransformation`

    Returnerer lagets hurtige wavelet-transformering.

  - Funktion: `fastWaveletUntransformation`

    Annullér fortryd transformering af en hurtig wavelet af laget. Den har et argument: et wavelet-objekt. For eksempel (i Ruby):

        wavelet = layer.fastWaveletTransformation()
        layer.fastWaveletUntransformation(wavelet)

  - Funktion: `getHeight`

    Returnér lagets højde.

  - Funktion: `getWidth`

    Returnér lagets bredde.

- Objekt: `Filter`

  - Funktion: `getFilterConfiguration`

    Denne funktion returnerer filterindstillingen (`FilterConfiguration`) som hører sammen med dette filter.

  - Funktion: `process`

    Denne funktion udfører filtret. Den har mindst et argument: kildelaget. Du kan også bruge disse fire argumenter: `x`, `y`, `bredde`, `højde`. (`x`, `y`, `bredde`,`højde`) definerer det rektangulære område hvor filtret beregnes. Hvis rektanglet ikke er defineret, bruges filtret på hele laget. For eksempel (i Ruby)

        doc = Krosschalkcore::get("ChalkDocument")
        image = doc.getImage()
        layer = image.getActivePaintLayer()
        width = layer.getWidth()
        height = layer.getHeight()
        filter = Krosschalkcore::getFilter("invert")
        filter.process(layer, layer)
        filter.process(layer, layer, 10, 10, 20, 20 )

- Objekt: `FilterConfiguration`

  - Funktion: `getProperty`

    Denne funktion returnerer en parameterværdi for tilhørende filter (`Filter`). Den har et argument: parameterens navn.

  - Funktion: `setProperty`

    Denne funktion definerer en parameter for tilhørende filter (`Filter`). Den har to argumenter: parameterens navn og værdi, hvis type afhænger af filtret.

- Objekt: `Histogram`

  Denne klasse lader dig få adgang til histogrammet for et malelag (`PaintLayer`). Eksempel (i Ruby):

      doc = krosschalkcore::get("ChalkDocument")
       image = doc.getImage()
       layer = image.getActiveLayer()
       histo = layer.createHistogram("RGB8HISTO",0)
       min = layer.getMin() * 255
       max = layer.getMax() * 255
       for i in min..max
         print layer.getValue(i)
         print "\n"
       end

  - Funktion: `getChannel`

    Returnér den valgte kanal.

  - Funktion: `getCount`

    Denne funktion returnerer antal billedpunkter som bruges af histogrammet.

  - Funktion: `getHighest`

    Denne funktion returnerer histogrammets største værdi.

  - Funktion: `getLowest`

    Denne funktion returnerer histogrammets mindste værdi.

  - Funktion: `getMax`

    Denne funktion returnerer histogrammets maksimale grænseværdi (værdier på større afstand end den maksimale værdi er nul). Værdien er i intervallet 0.0 – 1.0.

  - Funktion: `getMean`

    Denne funktion returnerer histogrammets middelværdi.

  - Funktion: `getMin`

    Denne funktion returnerer histogrammets minimale grænseværdi (værdier på mindre afstand end den minimale værdi er nul). Værdien er i intervallet 0.0 – 1.0.

  - Funktion: `getNumberOfBins`

    Returnerer antal bjælker i histogrammet.

  - Funktion: `getTotal`

    Denne funktion returnerer summen af alle værdier i histogrammet.

  - Funktion: `getValue`

    Returnerer værdien for en bjælke i histogrammet. Denne funktion har et argument: indekset i intervallet [0..255].

  - Funktion: `setChannel`

    Vælg kanal i laget som resultatet i histogrammet skal hentes fra. Denne funktion har et argument: kanalnummeret.

- Objekt: `ScriptProgress`

  `ScriptProgress` bruges til at håndtere fremgangslinjen i &chalk;s statuslinje. For eksempel (i Ruby):

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

  - Funktion: `incProgress`

    Denne funktion øger fremgangsindikeringen med et skridt.

  - Funktion: `setProgress`

    Denne funktion indstiller fremgangsindikeringens værdi. Den har et argument: fremgangsindikeringens værdi.

  - Funktion: `setProgressStage`

    Denne funktion indstiller fremgangsindikeringens værdi og viser teksten.

  - Funktion: `setProgressTotalSteps`

    Denne funktion indstiller antal skridt som scriptet vil kræve. Den har et argument: den maksimale værdi af fremgangsindikeringen

- Objekt: `Wavelet`

  Dette objekt indeholder koefficienterne for en wavelet-transformering af et malelag (`PaintLayer`).

  - Funktion: `getDepth`

    Returnerer lagets dybde.

  - Funktion: `getNCoeff`

    Returnerer værdien af den N'te koefficient. Funktionen har et argument: koefficientens indeks.

  - Funktion: `getNumCoeffs`

    Returnerer antal koefficienter i denne wavelet-transformering (= størrelse * størrelse * dybde).

  - Funktion: `getSize`

    Returnerer wavelet-transformeringens størrelse (størrelse = bredde * højde).

  - Funktion: `getXYCoeff`

    Returnerer en koefficients værdi. Funktionen har to argumenter: `x` og `y`.

  - Funktion: `setNCoeff`

    Indstiller værdien for den N'te koefficient. Funktionen har to argumenter: koefficientens indeks og koefficientens nye værdi.

  - Funktion: `setXYCoeff`

    Indstiller værdien for en koefficient. Funktionen har tre argumenter: `x`, `y` og koefficientens nye værdi.

- Objekt: `Painter`

  - Funktion: `convolve`

    Denne funktion anvender en foldningskerne på et billede. Den har mindst tre argumenter: en liste af kerner (alle lister skal have samme størrelse), faktor og forskydning.

    Værdien af et billedpunkt angives af følgende funktion: K * P / faktor + forskydning, hvor K er kernen og P er naboomgivelsen.

    Den kan have følgende valgfrie argument: `kantoperation` (styrwe hvordan billedpunkterne i kanten på et billede skal foldes: 0 = brug standardfarve, 1 = brug billedpunktet på billedets modsatte side, 2 = brug kantens billedpunkt, 3 = undgå billedpunkter ved kanten), `kanal` (1 for farve, 2 for alfa, 3 for begge), `x`, `y`, `bredde`, `højde`.

  - Funktion: `setFillThreshold`

    Indstiller udfyldningstærsklen. Den har et argument: tærsklen.

  - Funktion: `fillColor`

    Begynder at udfylde med en farve. Den har to argumenter: `x` og `y`.

  - Funktion: `fillPattern`

    Begynder at udfylde med et mønster. Den har to argumenter: `x` og `y`.

  - Funktion: `paintPolyline`

    Denne funktion tegner en polylinje. Den har to argumenter: en liste med x-positioner og en liste med y-positioner.

  - Funktion: `paintLine`

    Denne funktion tegner en linje. Den har fem argumenter: `x1`, `y1`, `x2`, `y2`, og `tryk`.

  - Funktion: `paintBezierCurve`

    Denne funktion tegner en Bezier-kurve. Den har ti argumenter: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2`, `p2`, hvor (`x1`,`y1`) er startpositionen, `p1` er trykket ved start, (`x2`,`y2`) er slutpositionen, `p2` er trykket ved slutningen. (`cx1`,`cy1`) og (`cx2`,`cy2`) er positionerne for kontrolpunkterne.

  - Funktion: `paintEllipse`

    Denne funktion tegner en ellipse. Den har fem argumenter: `x1`, `y1`, `x2`, `y2`, `tryk`, hvor (`x1`,`y1`) og (`x2`,`y2`) er positionerne for de to centre.

  - Funktion: `paintPolygon`

    Denne funktion tegner en polygon. Den har to argumenter: en liste med x-positioner og en liste med y-positioner.

  - Funktion: `paintRect`

    Denne funktion tegner et rektangel. Den har fem argumenter: `x`, `y`, `bredde` `højde`, `tryk`.

  - Funktion: `paintAt`

    Denne funktion maler en given position. Den har tre argumenter: `x`, `y`, `tryk`.

  - Funktion: `setPaintColor`

    Denne funktion indstiller malerfarven (også kaldet forgrundsfarven). Den har et argument: en farve (`Color`).

  - Funktion: `setBackgroundColor`

    Denne funktion indstiller baggrundsfarven. Den har et argument: en farve (`Color`).

  - Funktion: `setPattern`

    Denne funktion indstiller mønstret som bruges at fylde ud med. Den har et argument: et mønsterobjekt (`Pattern`).

  - Funktion: `setBrush`

    Denne funktion indstiller penslen som bruges at male med. Den har et argument: et penselobjekt (`Brush`).

  - Funktion: `setPaintOp`

    Denne funktion definerer en maleoperation. Den har et argument: maleoperationens navn.

  - Funktion: `setDuplicateOffset`

    Denne funktion definerer duplikatets forskydning. Den har to argumenter: vandret forskydning og lodret forskydning.

  - Funktion: `setOpacity`

    Denne funktion indstiller maleriets ugennemsigtighed. Den har et argument: ugennemsigtigheden i intervallet 0 til 255.

  - Funktion: `setStrokeStyle`

    Denne funktion indstiller stregens stil. Den har et argument: 0 for ingen, eller 1 for pensel.

  - Funktion: `setFillStyle`

    Denne funktion indstiller udfyldningsstilen for maleobjektet (`Painter`). Den har et argument: 0 for ingen, 1 for fyld ud med forgrundsfarve, 2 for fyld ud med baggrundsfarve, 3 for fyld ud med mønster.

- Objekt: `Iterator`

  Dette objekt lader dig ændre billedpunktsværdier et af gangen. Navnet på visse funktioner afhænger af farverummet, om lagets farverum for eksempel er RGB, findes `setR`, `setG` og `setB`, og for CMYK, `setC`, `setM`, `setY` og `setK`. I dokumentationen antager vi at farverummet kaldes ABC, med tre kanaler: A, B, C.

  - Funktioner: `setA`, `setB`, `setC`

    Disse funktioner har et argument: den nye værdi for et af billedpunktets kanaler.

  - Funktion: `setABC`

    Indstiller alle kanalers værdi. Denne funktion har et argument: et felt med de nye værdier for alle kanaler.

  - Funktioner `getA`, `getB`, `getC`

    Returnér værdien for en af kanalerna i dette billedpunkt.

  - Funktion: `getABC`

    Returnér et felt med alle kanalers værdier.

  - Funktion: `darken`

    Gør et billedpunkt mørkere. Denne funktion har mindst et argument: `shade` (værdien som bruges til at gøre alle farvekanaler mørkere). Denne funktion kan have følgende valgfrie argument: `compensation` (for at begrænse mørkningen).

  - Funktion: `invertColor`

    Invertér farven for et billedpunkt.

  - Funktion: `next`

    Øg positionen, og gå til næste billedpunkt.

  - Funktion: `isDone`

    Returnér sand hvis iteratoren er i slutningen (ikke flere billedpunkter er tilgængelige).

## Ressourcer

Her er vink eller partielle lister med ressourcer for &chalk;.

For pensel (`Brush`) og mønster (`Pattern`): Du kan hente navne og tilhørende pensler eller mønstre fra markeringsværktøjet i &chalk;s værktøjslinje.

En liste med id'er af farverum i &chalk; : LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.