&Anders.Lund; &Anders.Lund.mail;
&Dominik.Haumann; &Dominik.Haumann.mail;
&traductor.Antoni.Bella;

# Eines d'edició avançades

## Comenta/descomenta

Les ordres Comenta i Descomenta, disponibles des del menú Eines us permeten afegir o eliminar marques de comentari per a la selecció, o de la línia actual si no hi ha cap selecció. El format dels comentaris dependrà del format del text que esteu editant.

Les regles que determinen com hauran de ser els comentaris s'estableixen en les definicions de sintaxi, de manera que si no s'usa el ressaltat de sintaxi, no serà possible fer això.

Alguns formats defineixen marques de comentaris d'una sola línia, d'altres de múltiples línies i d'altres usen ambdues possibilitats. Si no estan disponibles les marques de comentaris de diverses línies, no serà possible comentar una selecció en que l'última línia d'aquesta no estigui inclosa completament.

Si està disponible una marca de comentari d'una sola línia, es preferible comentar les línies individualment, atès que així s'eviten problemes de comentaris niats.

En eliminar les marques de comentari, s'haurà de seleccionar el text sense comentar. En eliminar les marques de comentari multi-línia d'una selecció, s'ignorarà qualsevol espai en blanc que quedi fora de les marques de comentari.

Per a posar marques de comentari, useu l'element del menú Eines Comenta o la drecera de teclat corresponent, per omissió és &Ctrl;D.

Per eliminar les marques de comentari, useu l'element del menú Eines Descomenta o la drecera de teclat corresponent, per omissió és &Ctrl;&Maj;D.

## El component línia d'ordres de l'editor

El component editor del &kappname; té una línia d'ordres interna, permetent-vos dur a terme vàries accions des d'una interfície gràfica mínima. La línia d'ordres és una entrada de text en la part inferior de l'àrea d'edició, i per a veure-la tan sols haureu de seleccionar Visualitza Canvia a línia d'ordres o usar la drecera (per omissió és F7). L'editor proveeix un joc d'ordres com els que es documenten a continuació, així com aquells altres que es poden proveir a partir de connectors.

Per a executar una ordre, escriviu-la i després premeu la tecla &Intro;. La línia d'ordres indicarà què ha succeït mostrant un possible missatge. Si entreu a la línia d'ordres i premeu F7 aquest missatge s'ocultarà automàticament després d'uns pocs segons. Per esborrar el missatge i introduir una ordre nova, premeu F7 altra vegada.

La línia d'ordres té un sistema d'ajuda encastat, escriviu l'ordre `help` per a iniciar-la. Per a veure una llista de tots les ordres disponibles escriviu `help list`, per a veure l'ajuda específica d'una ordre, escriviu `help ordre`.

La línia d'ordres té integrat un historial, de manera que podreu tornar a usar les ordres ja teclejades. Per a navegar a través de l'historial, useu les tecles Amunt i Avall. Quan es mostrin les ordres de l'historial, restarà seleccionada la part de l'argument, permetent-vos tornar a escriure'ls amb facilitat.

### Ordres estàndard de la línia d'ordres

#### Tipus d'arguments

BOOLEÀ

  Aquest s'usa amb ordres que activen o desactiven coses. Els valors acceptats són: `on` (activat), `off` (desactivat), `true` (verdader), `false` (fals), `1` (activat) o `0` (desactivat).

ENTER

  Un número enter.

CADENA

  Una cadena, entre cometes simples (') o cometes dobles (") si conté espais.

#### Ordres per a configurar l'editor

Aquestes ordres són les que proveeix el component editor, i us permeten configurar només la vista i el document actiu. Això és especialment pràctic si voleu usar una configuració diferent de la per omissió, per exemple per al sagnat.

    set-tab-widthENTER amplada

  Estableix l'amplada de la pestanya al número `amplada`.

    set-indent-widthENTER amplada

  Estableix l'amplada del sagnat al número `amplada`. Tan sols s'usa si esteu sagnant amb espais.

    set-word-wrap-columnENTER amplada

  Estableix l'amplada per a l'ajust de línia al número `amplada`. Tan sols s'usa si teniu l'ajust de línia automàtic.

    set-icon-borderBOOLEÀ activa

  Estableix la visibilitat de la vora d'icones.

    set-folding-markersBOOLEÀ activa

  Estableix la visibilitat del plafó de marques de plegat.

    set-line-numbersBOOLEÀ activa

  Estableix la visibilitat dels números de línia al plafó.

    set-replace-tabsBOOLEÀ activa

  Si està habilitat, se substitueixen els espais de tabulació per espais normals mentre aneu escrivint.

    set-remove-trailing-spaceBOOLEÀ activa

  Si està habilitat, els espais en blanc de marca seran eliminats en el moment en que el cursor surti d'una línia.

    set-show-tabsBOOLEÀ activa

  Si està habilitat, els caràcters de tabulació i espais en blanc de marca es veuran com un punt petit.

    set-show-indentBOOLEÀ activa

  Si està habilitat, el sagnat es veurà com una línia puntejada vertical.

    set-indent-spacesBOOLEÀ activa

  Si està habilitat, l'editor farà un sagnat amb `indent-width` espais per a cada nivell de sagnat, en comptes de amb un caràcter de tabulació.

    set-mixed-indentBOOLEÀ activa

  Si està habilitat, el &kappname; usarà una barreja de tabulacions i espais per al sagnat. Cada nivell de sagnat serà d'amplada `indent-width`, i els diferents nivells de sagnat s'optimitzaran usant el màxim de caràcters de tabulació com sigui possible.

  Quan s'executa, aquesta ordre habilita el sagnat amb espais, i si no s'especifica l'amplada se li assignarà un valor igual que la meitat de `tab-width` per al document en temps d'execució.

    set-word-wrapBOOLEÀ activa

  Habilita l'ajust de línia dinàmic d'acord amb el valor de `enable`

    set-replace-tabs-saveBOOLEÀ activa

  Quan està habilitat, les tabulacions seran substituïdes amb espais en blanc al desar el document.

    set-remove-trailing-space-saveBOOLEÀ activa

  Quan està habilitat, s'eliminen els espais de marca de cada línia en desar el document.

    set-indent-modeCADENA nom

  Estableix el mode de sagnat automàtic a `nom`. Si `nom` és desconegut, el mode seleccionat serà «none». Els modes vàlids són «none», «normal», «cstyle», «haskell», «lilypond», «lisp», «python», «ruby» i «xml».

    set-auto-identBOOLEÀ script

  Habilita o deshabilita el sagnat automàtic.

    set-highlightCADENA ressaltat

  Estableix el sistema de ressaltat de sintaxi per al document. L'argument haurà de ser un nom de ressaltat vàlid, com aquells que es poden veure en el menú Eines Ressaltat. Aquesta ordre proveeix una llista de compleció automàtica per als seus arguments.

    reload-scripts

  Torna a carregar tots els scripts de JavaScript usats per Kate, inclosos els scripts sagnadors i de línia d'ordres.

    set-modeCADENA mode

  Tria l'esquema de tipus de fitxer per al document actual.

    nn[oremap]CADENA original CADENA mapped

  Mapa de la seqüència de tecles `original` a `mapped`.

#### Ordres per a l'edició

Aquestes ordres modifiquen el document actual.

    indent

  Sagna les línies seleccionades o la línia actual.

    unindent

  Treu el sagnat de les línies seleccionades o la línia actual.

    cleanindent

  Treu el sagnat de les línies seleccionades o la línia actual d'acord amb les opcions de sagnat que tingueu establertes al document.

    comment

  Insereix marques de comentari fent que la selecció, les línies seleccionades o la línia actual siguin un comentari d'acord amb el format de text que s'hagi definit a la sintaxi de ressaltat per al document.

    uncomment

  Elimina les marques de comentari de la selecció, de les línies seleccionades o la línia actual, d'acord amb el format del text tal com és definit per la definició de ressaltat de sintaxi per al document.

    kill-line

  Elimina la línia actual.

    replaceCADENA patró CADENA substitució

  Substitueix el text en que coincideixi el `patró` amb el valor de `substitució`. Si voleu incloure espais en blanc en el `patró`, haureu de posar entre cometes tan el `patró` com la `substitució` amb cometes simples o dobles. Si els arguments no són entre cometes, la primera paraula s'usarà com a `patró` i la resta com a `substitució`. Si la `substitució` és buida, cada ocurrència de `patró` serà eliminada.

  Podeu establir etiquetes per a configurar la cerca afegint dos punts, seguits d'una o més lletres cadascuna de les quals representa una configuració, quedant de la forma `replace:opcions patró substitució`. Les opcions disponibles són:

  `b`

    Cerca enrere.

  `c`

    Cerca des de la posició del cursor.

  `e`

    Cerca tan sols en el text seleccionat.

  `r`

    Cerca usant una expressió regular. Si està establerta, podeu usar `\N` a on N serà un número per a representar captures en la cadena de substitució.

  `s`

    Cerca distingint majúscules i minúscules.

  `p`

    Demana permís per a substituir la següent ocurrència.

  `w`

    Tan sols coincidiran paraules senceres.

    dateCADENA format

  Insereix una cadena de data/hora definida d'acord al `format`, o si aquest no s'especifica s'usarà el format «aaaa-MM-dd hh:mm:ss». La interpretació del `format` serà la següent:

  `d` | El dia com a número sense zeros a l'esquerra (1-31).
  `dd` | El dia com a número amb dos dígits (01-31).
  `ddd` | L'abreujament del nom del dia segons la localització (&pex;, «Dl»..«Dg»).
  `dddd` | El nom llarg traduït del dia (&pex;, «Dilluns»..«Diumenge»).
  `M` | El mes com a número sense zeros a l'esquerra (1-31).
  `MM` | El mes com a número amb dos dígits (01-31).
  `MMMM` | El nom llarg del mes segons la localització (&pex;, «Gener»..«Desembre»).
  `MMM` | El nom abreujat del mes segons la localització (&pex;, «Gen»..«Dec»).
  `yy` | L'any amb un número de dos dígits (00-99).
  `yyyy` | L'any amb un número de quatre dígits (1752-8000).
  `h` | L'hora sense zeros a l'esquerra (0..23 o 1..12 si es mostra AM/PM).
  `hh` | L'hora amb dos dígits (00..23 o 01..12 si es mostra AM/PM).
  `m` | Els minuts sense zeros a l'esquerra (0..59).
  `mm` | Els minuts amb dos dígits (00..59).
  `s` | Els segons sense zeros a l'esquerra (0..59).
  `ss` | Els segons amb dos dígits (00..59).
  `z` | Els mil·lisegons sense zeros a l'esquerra (0..999).
  `zzz` | Els mil·lisegons amb tres dígits (000..999).
  `AP` | S'usa per a mostrar AM/PM. AP serà substituït per «AM» o «PM».
  `ap` | S'usa per a mostrar am/pm. ap serà substituït per «am» o «pm».

    charCADENA identificador

  Aquesta ordre us permet inserir caràcters literals pel seu identificador numèric, en format decimal, octal o hexadecimal. Per a usar-lo llanceu el diàleg Ordre d'edició i escriviu `char: [número]` en el quadre d'entrada, després premeu Bé.

  ##### Exemples de `char`

  Entrada: `char:234`

  Eixida: `ê`

  Entrada: `char:0x1234`

  Eixida: `ሴ`

`s///[ig]` `%s///[ig]`

  Aquesta ordre realitzarà una operació de cerca/substitució similar a les de sed sobre la línia actual o en tot el fitxer (`%s///`).

  Abreujat, se cerca en el text alguna cadena que coincideixi amb el patró de cerca, l'expressió regular entre la primera i la segona barra, i quan es troba una coincidència, la part coincident del text és substituïda per l'expressió continguda entre les barres central i última de la cadena. Els parèntesis en el patró de cerca creen referències enrere, és a dir, que l'ordre recorda quina part de la coincidència es troba entre parèntesis; aquestes cadenes es poden tornar a usar en el patró de substitució, referint-se a elles com a `\1` per al primer conjunt de parèntesis, `\2` per al segon i així successivament.

  Per a fer una cerca literal de `(` o `)`, haureu d'escapar el caràcter emprant un altre caràcter de barra invertida: `\(\)`

  Si poseu una `i` al final de l'expressió, les coincidències seran sensibles a majúscules i minúscules. Si poseu una `g` al final, se substituiran totes les ocurrències del patró, en qualsevol altre cas tan sols se substituirà la primera ocurrència.

  ##### Substitució de text en la línia actual

  El vostre bon amic l'ordinador s'ha aturat, dient que la classe `myClass` mencionada en la línia 3902 del fitxer font no està definida.

  "Llamps i trons!" Pensareu. Per descomptat és `MyClass`. Anireu fins la línia 3902 i en comptes d'intentar cercar la paraula en el text, obrireu el diàleg Ordre d'edició, introduireu `s/myclass/MyClass/i`, premereu el botó Bé, desareu el fitxer i tornareu a compilar aquesta vegada sense l'error.

  ##### Substitució de text en tot el fitxer

  Imagineu que teniu un fitxer, en el que mencioneu a «Miss Jensen» vàries vegades, quan resulta que algú ve i us diu que s'acaba de casar amb «Mr Jones». Per descomptat, voldreu substituir cada ocurrència de «Miss Jensen» per «Ms Jones».

  Entreu a la línia d'ordres, escriviu l'ordre `%s/Miss Jensen/Ms Jones/`, una vegada que premeu &Intro; ja estarà fet.

  ##### Un exemple més avançat

  Aquest exemple fa ús de referències enrere així com d'una classe de caràcter (si no sabeu què és això, si us plau, consulteu la documentació mencionada a sota).

  Suposeu que teniu la següent línia:

      void MyClass::DoStringOps( String      &foo, String &bar, String *p, int  &a, int &b )

  Però us adoneu que aquest codi no està bé i decidiu que voleu usar la paraula clau `const` per a tots els arguments «adreça de», que es caracteritzen per tenir un operador & al davant del nom de l'argument. També voldreu simplificar l'espai en blanc, de manera que només n'hi hagi un entre cada paraula.

  Obriu el diàleg Ordre d'edició i introduïu: `s/\s+(\w+)\s+(&)/ const \1 \2/g`, i després premeu el botó Bé. La `g` al final de l'expressió fa que l'expressió regular recompili cada coincidència per a desar les referències enrere.

  Eixida: `void MyClass::DoStringOps( const String &foo, const String &bar, String *p, const int &a, const int &b )`

  Missió completada! Ara, què ha passat? Vaja, hem cercat algun espai en blanc (`\s+`) seguit d'un o més caràcters alfabètics (`\w+`) seguits d'algun espai en blanc (`\s+`) seguit del símbol «&», i en el procés hem desat el bloc alfabètic i el caràcter «&» per a tornar a usar-los en l'operació de substitució. Aleshores hem substituït la part coincident de la nostra línia per un espai en blanc seguit de «const» seguit d'un espai en blanc seguit del nostre bloc alfabètic (`\1`) seguit d'un espai en blanc seguit del nostre caràcter «&» emmagatzemat (`\2`)

  En alguns casos el bloc alfabètic era «String», en d'altres «int», de manera que emprant la classe de caràcter `\w` i el quantificador `+` ens ha proveït d'un valuós actiu.

    sort

  Ordena el text seleccionat o tot el document.

    natsort

  Ordena el text seleccionat o tot el document de forma natural.

  ##### `sort` vs. `natsort`

  `sort(a10, a1, a2)` resulta en `a1, a10, a2`

  `natsort(a10, a1, a2)` resulta en `a1, a2, a10`

    moveLinesDown

  Mou cap avall les línies seleccionades.

    moveLinesUp

  Mou cap amunt les línies seleccionades.

    uniq

  Elimina les línies duplicades del text seleccionat o de tot el document.

    rtrim

  Elimina els espais finals del text seleccionat o de tot el document.

    ltrim

  Elimina els espais al començament del text seleccionat o de tot el document.

    joinseparador CADENA

  Uneix les línies seleccionades o tot el document. De manera opcional pren un paràmetre definint un separador, per exemple: ``join` ', '`

    rmblank

  Elimina tots els espais en blanc del text seleccionat o de tot el document.

    unwrap

  Ajusta les línies del text seleccionat o de tot el document.

    eachCADENA script

  Dóna una funció de JavaScript com un argument, aquesta crida a la llista de línies seleccionades i les substitueix pel valor retornat per aquesta crida.

  ##### Unir les línies seleccionades

  ``each` 'function(lines){return lines.join(", ")}'`

  O, més curt:

  ``each` 'lines.join(", ")'`

    filterCADENA script

  Dóna una funció de JavaScript com un argument, aquesta crida a la llista de línies seleccionades i elimina les que el valor retornat és «false».

  ##### Esborrar les línies buides

  ``filter` 'function(1){return 1.length > 0;}'`

  O, més curt:

  ``filter` 'line.length > 0'`

    mapCADENA script

  Dóna una funció de JavaScript com un argument, aquesta crida a la llista de línies seleccionades i substitueix la línia amb el valor de la crida.

  ##### Esborrar les línies buides

  ``map` 'function(line){return line.replace(/^s+/,"");}'`

  O, més curt:

  ``map` 'line.replace(/^s+/,"")'`

    duplicateLinesUp

  Duplica les línies seleccionades per sobre de la selecció actual.

    duplicateLinesDown

  Duplica les línies seleccionades per sota de la selecció actual.

#### Ordres per a navegar

    gotoENTER línia

  Aquesta ordre va a la línia especificada.

    grep CADENA patró

  Cercar al document per al `patró` d'expressió regular. Per a més informació, veure .

    findCADENA patró

  Aquesta ordre navega fins la primera ocurrència del `patró` d'acord amb la configuració. Les següents ocurrències es poden trobar usant Edita Cerca següent (la drecera per omissió és F3).

  L'ordre «find» pot configurar-se afegint dos punts seguits per una o més opcions, el format serà `find:opcions patró`. Estan suportades les següents opcions:

  `b`

    Cerca enrere.

  `c`

    Cerca des de la posició del cursor.

  `e`

    Cerca tan sols en el text seleccionat.

  `r`

    Cerca usant una expressió regular. Si està establerta, podeu usar `\N` a on N serà un número per a representar captures en la cadena de substitució.

  `s`

    Cerca distingint majúscules i minúscules.

  `w`

    Tan sols coincidiran paraules senceres.

    ifindCADENA patró

  Aquesta ordre proveeix cerca «quan-escriviu». Podeu configurar-ne el comportament o la cerca afegint dos punts seguits per a una o més opcions, de forma similar a: `ifind:patró d'opcions`. Les opcions permeses són:

  `b`

    Cerca enrere.

  `r`

    Cerca mitjançant expressions regulars.

  `s`

    Cerca distingint majúscules i minúscules.

  `c`

    Cerca des de la posició del cursor.

#### Ordres per a les funcions bàsiques de l'editor (aquestes dependran de l'aplicació, el component d'edició s'utilitza en)

    w

  Desa el document actual.

    wa

  Desa tots els documents actualment oberts.

    q

  Tanca el document actual.

    qa

  Tanca tots els documents oberts.

    wq

  Tanca i desa el document actualment obert.

    wqa

  Tanca i desa tots els documents actualment oberts.

    x

  Desa el document actual només si ha canviat i després el tanca.

    x

  Desa tots els documents oberts només si han canviat i després els tanca.

    bp

  Va al document anterior en la llista de documents.

    bn

  Va al document següent en la llista de documents.

    new

  Obre un nou document en una vista dividida horitzontal.

    vnew

  Obre un nou document en una vista dividida vertical.

    e

  Torna a carregar el document actual si ha canviat al disc.

    enew

  Edita un document nou.

    print

  Obre el diàleg d'impressió per imprimir el document actual.

## Usar el plegat de codi

El plegat de codi us permet ocultar parts d'un document en l'editor, facilitant la visió de documents grans. En &kappname; les regions plegables es calculen usant regles definides en les definicions de ressaltat de sintaxi, i per tant només està disponible en alguns formats (típicament codi font de programes, com ara el de marques XML i similars). La majoria de les definicions de ressaltat suporten plegat de codi i també us permeten definir manualment regions plegables, generalment usant les paraules clau `BEGIN` i `END`.

Per a usar la característica del plegat de codi, activeu els marcadors plegables usant l'element de menú Visualitza Mostra marcadors plegables si no estan visibles. El plafó de marcadors plegables a la part esquerra de la pantalla mostra una vista gràfica de les regions plegables, amb els símbols de triangle per a indicar la possible operació sobre una certa regió: Un triangle cap avall vol dir que la regió està desplegada, fent clic sobre seu es plegarà i es mostrarà un triangle apuntant cap al punt.

Es proveeixen onze ordres per a manipular l'estat de les regions plegables, consulteu la documentació del menú.

Les línies de plegat es recorden quan es tanca un fitxer, de manera que quan el torneu a obrir els nodes plegats encara ho estaran. Això també s'aplica a les operacions de torna a carregar.

Si no desitgeu usar la característica de plegat de codi, podeu deshabilitar l'opció Mostra marcadors plegables (si són disponibles) en la pàgina Aparença de configuració de l'editor.

## Ampliar el &kappname; amb scripts

Des de &kappname; 3.4 de KDE 4.4 el component d'edició de &kappname; és fàcilment extensible, escrivint scripts. El llenguatge d'script és ECMAScript (conegut com Javascript). &kappname; admet dos tipus d'script: el sagnat i els scripts de línia d'ordres.

### Scripts de sagnat

Els scripts de sagnat: També coneguts com «indenters», sagnen automàticament el codi font en escriure text. Com a exemple, després de tocar la tecla de retorn el nivell de sagnat sovint és incrementat.

En les següents seccions es descriuen pas a pas com crear l'esquelet d'un sagnat simple. Com a primer pas, creeu una nou fitxer `*.js` anomenat &pex;, `javascript.js` a la carpeta d'inici local `$KDEHOME/share/apps/katepart/script/indentation`.

#### La capçalera de l'script de sagnat

La capçalera del fitxer `javascript.js` està encastada en un comentari i és de la forma següent

    /* kate-script
     * name: JavaScript
     * author: Nom exemple <nom.exemple@alguna.adreça.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * required-syntax-style: javascript
     * indent-languages: javascript
     * priority: 0
     * i18n-catalog: mycatalog
     *
    * Una línia sense punts «:» atura l'anàlisi de la capçalera. És a dir, podeu * afegir text opcional aquí com una llicència detallada. */

Cada entrada s'explica en detall tot seguit:

- `kate-script` [requerit]: Aquesta cadena de text ha d'aparèixer a la primera línia del fitxer `*.js`, en cas contrari el &kappname; omet l'script.

- `name` [requerit]: Aquest és el nom del sagnat que apareix al menú Eines Sagnat i en el diàleg de configuració.

- `author` [opcional]: El nom de l'autor i la informació de contacte.

- `license` [opcional]: La forma curta de la llicència, com ara BSD o LGPLv3.

- `revision` [requerit]: La revisió de l'script. Aquest número ha de ser major cada vegada que l'script es modifica.

- `kate-version` [requerit]: La versió mínima requerida per &kappname;.

- `required-syntax-style` [opcional]: Llista separada per comes dels estils de ressaltat de la sintaxi. Això és important per als sagnats que es basen en la informació de ressaltat específica en el document. Si s'especifica un estil de sintaxi requerit, el sagnat només estarà disponible amb el ressaltat actiu apropiat. Això evita «comportament sense definir» causat per l'ús del sagnat sense l'esquema de ressaltat esperat. Per exemple, el sagnat de Ruby en fa ús en els fitxers `ruby.js` i `ruby.xml`.

- `indent-languages` [opcional]: Llista separada per comes dels estils de sintaxi que pot sagnar correctament, &pex;: c++, java.

- `priority` [opcional]: Si els diversos sagnats són adequats per a un determinat fitxer ressaltat, la prioritat decideix quin sagnat és triat com sagnat per omissió.

- `i18n-catalog` [opcional]: Catàleg de missatges addicionals (fitxer `po`) carregat per a la traducció de sagnats de terceres parts.

&kappname; llegeix tots els parells de la forma «clau:valor» fins que no es trobin més dos punts. Això implica que la capçalera pot contenir text arbitrari, com una llicència, com es mostra en l'exemple.

#### El codi font del sagnat

Després d'haver especificat la capçalera aquesta secció explica com funciona l'script de sagnat mateix. L'esquelet bàsic del cos s'assembla a això:

    // es necessiten les biblioteques «js» de katepart, per exemple, «range.js»
    // si utilitzeu «Range»
    require ("range.js");

    triggerCharacters = "{}/:;";
    function indent(line, indentWidth, ch)
    {
        // crida per a cada línia nova (ch == «\n») i tots els caràcters s'especifiquen en
        // la variable global triggerCharacters. Quan es crida EinesAlinea
        // la variable ch és buidada, &ead;, ch == «».
        //
        // Veure també: L'API dels scripts
        return -2;
    }

La funció `indent()` té tres paràmetres:

- `line`: La línia que ha d'estar amb sagnat.

- `indentWidth`: L'amplada del sagnat en quantitat d'espais.

- `ch`: o bé un caràcter de línia nova (`ch == '\n'`),el caràcter de tall especificat en `triggerCharacters` o buida si l'usuari invoca l'acció Eines Alinea.

El valor retornat de la funció `indent()` especifica com se sagna la línia. Si el valor retornat és un nombre enter simple, aquest s'interpreta de la següent manera:

- El valor retornat `-2`: No fa res.

- El valor retornat `-1`: Es manté el sagnat (cerca la línia anterior que no estigui en blanc).

- El valor retornat `0`: Un número >= 0 especifica la profunditat del sagnat en nombre d'espais.

Alternativament, un conjunt de dos elements es poden retornar:

- `return [ indent, align ];`

En aquest cas, el primer element és la profunditat de sagnat com anteriorment amb el mateix significat dels valors especials. No obstant, el segon element és un valor absolut que representa una columna d'«alineació». Si aquest valor és major que el valor de sagnat, la diferència representa un nombre d'espais a afegir després del sagnat del primer paràmetre. En cas contrari, el segon nombre serà ignorat. L'ús de tabulacions i espais per al sagnat sovint és referit com «mode mixt».

Considerem el següent exemple: Suposem que s'usen tabulacions per a sagnar, i l'amplada de la tabulació és 4. Aquí, <tab> representa una tabulació i «.» un espai:

    1: <tab><tab>foobar("hola",
    2: <tab><tab>......."món");

Quan se sagna la línia 2, la funció `indent()` retorna [8, 15]. Com a resultat, s'insereixen dues tabulacions per a sagnar fins a la columna 8, i s'afegeixen 7 espais per alinear el segon paràmetre a la primera, de manera que quedi alineat si el fitxer es veu amb una amplada de tabulació diferent.

Una instal·lació per omissió de KDE ens dóna el &kappname; amb diversos sagnats. El corresponent codi font de JavaScript d'origen pot trobar-se en `$KDEDIR/share/apps/katepart/script/indentation`.

El desenvolupament d'un sagnat requereix tornar a carregar els scripts per veure si els canvis es comporten adequadament. En comptes de reiniciar l'aplicació, simplement canvieu a la línia d'ordres i crideu l'ordre `reload-scripts`.

Si desenvolupeu scripts útils, si us plau, considereu el contribuir al projecte &kappname; posant-vos en contacte amb la llista de correu.

### Els scripts de la línia d'ordres

Com és difícil satisfer les necessitats de tothom, el &kappname; suporta unes quantes eines d'ajuda per a la manipulació ràpida de text a través de la línia d'ordres encastada. Per exemple, l'ordre `sort` s'implementa com script. En aquesta secció s'explica com crear fitxers `*.js` per estendre el &kappname; amb scripts d'ajuda arbitrària.

Scripts de línia d'ordres es troben en la mateixa carpeta que els scripts de sagnat. Així que com a primer pas, creeu un nou fitxer `*.js` anomenat `myutils.js` a la carpeta d'inici local `$KDEHOME/share/apps/katepart/script/commands`.

#### La capçalera de l'script de línia d'ordres

La capçalera de cada script de línia d'ordres està integrada en un comentari i és en la forma següent

    /* kate-script
     * author: Nom exemple <nom.exemple@alguna.adreça.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * functions: sort, format-paragraph
     * i18n-catalog: mycatalog
     *
     * Una línia sense dos punts «:» atura l'anàlisi de la capçalera. És a dir,
     * podeu afegir text opcional com una llicència detallada.
     */

Cada entrada s'explica en detall tot seguit:

- `kate-script` [requerit]: Aquesta cadena de text ha d'aparèixer a la primera línia del fitxer `*.js`, en cas contrari el &kappname; omet l'script.

- `author` [opcional]: El nom de l'autor i la informació de contacte.

- `license` [opcional]: La forma curta de la llicència, com ara BSD o LGPLv3.

- `revision` [requerit]: La revisió de l'script. Aquest número ha de ser major cada vegada que l'script es modifica.

- `kate-version` [requerit]: La versió mínima requerida per &kappname;.

- `functions` [requerit]: Llista separada per comes de les ordres en l'script.

- `i18n-catalog` [opcional]: Catàleg de missatges addicionals (fitxer `po`) carregat per a la traducció d'scripts de terceres parts.

&kappname; llegeix tots els parells de la forma «clau:valor» fins que no es trobin més dos punts. Això implica que la capçalera pot contenir text arbitrari, com una llicència, com es mostra en l'exemple. El valor de les funcions clau és una llista separada per comes de les ordres en la línia d'ordres. Això significa que un únic script conté una quantitat arbitrària d'ordres de la línia d'ordres. Cada funció està disponible a través de la línia d'ordres encastada de &kappname;.

#### El codi font de l'script

Totes les funcions especificades a la capçalera s'han d'implementar a l'script. Per exemple, el fitxer d'script en l'exemple anterior necessita implementar les dues funcions `sort` i `format-paragraph`. Totes les funcions tenen la següent sintaxi:

    // es necessiten les biblioteques «js» de katepart, per exemple, «range.js»
    // si utilitzeu «Range»
    require ("range.js");

    function <nom>(arg1, arg2...)
    {
        // ... implementació, veure també: L'API dels scripts.
    }

Els arguments en la línia d'ordres es passen a la funció com `arg1`, `arg2`, &etc; Per tal de proveir documentació per a cada ordre, simplement implementeu la funció «`help`» de la següent manera:

    {
        if (cmd == "sort") {
            return i18n("Ordena el text seleccionat.");
        } else if (cmd == "...") {
            // ...
        }
    }

Executar `help sort` en la línia d'ordres crida a aquesta funció d'ajuda amb l'argument `cmd` establert en l'ordre donada, &ead;, `cmd == "sort"`. &kappname; presentarà el text retornat com documentació per a l'usuari. Assegureu-vos de traduir les cadenes.

##### Vincular dreceres

Per tal de poder assignar dreceres, l'script ha de proporcionar una funció anomenada `action` de la següent manera:

    function action(cmd)
    {
        var a = new Object();
        if (cmd == "sort") {
            a.text = i18n("Ordena el text seleccionat");
            a.icon = "";
            a.category = "";
            a.interactive = false;
            a.shortcut = "";
        } else if (cmd == "moveLinesDown") {
            // El mateix per a la següent acció
        }
        return a;
    }

El paràmetre `cmd` de la funció específica l'ordre per al qual es demana una drecera. Hi ha diversos camps que heu d'especificar en l'objecte javascript retornat:

- `a.text` [requerit]: El text apareix en el menú Eines Scripts. Assegureu-vos d'utilitzar `i18n` per a la traducció.

- `a.icon` [opcional]: La icona apareix al costat del text en el menú. Aquí es poden usar tots els noms d'icones del KDE.

- `a.category` [opcional]: Si s'especifica una categoria, l'script apareixerà en un submenú. Assegureu-vos d'utilitzar `i18n` per a la traducció.

- `a.interactive` [opcional]: Si l'script necessita usar l'entrada, establiu-ho a `true` (vertader).

- `a.shortcut` [opcional]: La drecera que aquí és la drecera per omissió. Exemple: Ctrl+Alt+t. Consulteu la Documentació de Qt per més detalls.

El desenvolupament d'un script de línia d'ordres requereix tornar a carregar els scripts per veure si els canvis es comporten adequadament. En comptes de reiniciar l'aplicació, simplement canvieu a la línia d'ordres i crideu l'ordre `reload-scripts`.

Si desenvolupeu scripts útils, si us plau, considereu el contribuir al projecte &kappname; posant-vos en contacte amb la llista de correu.

### L'API dels scripts

La API per a scripts que es presenta aquí està disponible en tots els scripts, &pex;, els scripts d'exemple de sagnat i ordres de línia d'ordres. Els `Cursor` i `Range` són proporcionats pels fitxers de la biblioteca a `$KDEDIR/share/apps/katepart/libraries`. Si voleu utilitzar-los en el seu vostre script, serà necessari utilitzar algunes de les funcions `Document` o `View`, si us plau, afegiu la biblioteca necessària mitjançant:

    // es necessiten les biblioteques «js» de katepart, per exemple, «range.js»
    // si utilitzeu «Range»
    require ("range.js");

Per estendre la norma de l'API dels scripts amb les funcions i prototips propis n'hi ha prou amb crear un nou fitxer a la carpeta de configuració local del KDE `$KDEHOME/share/apps/katepart/libraries` i incloure'l en l'script utilitzant:

    require ("nom_script.js");

Per estendre els prototips com `Cursor` o `Range`, la manera més recomanable és no modificar els fitxers `*.js` globals. En el seu lloc, canvieu el prototip `Cursor` en JavaScript després afegiu el `cursor.js` al vostre script mitjançant `require`.

#### Cursors i rangs

Com &kappname; és un editor de text, tota l'API dels scripts es basa en els cursors i els rangs sempre que sigui possible. Un Cursor és una simple `(line, column)` que representa una posició del text en el document. Un Range s'estén pel text des de la posició del cursor fins a una posició final del cursor. L'API s'explica amb detall en les següents seccions.

##### El prototip de «Cursor»

    Cursor();

  Constructor. Retorna un cursor a la posició `(0, 0)`.

  Exemple: `var cursor = new Cursor();`

    Cursor(int línia, int columna);

  Constructor. Retorna un cursor a la posició (línia, columna).

  Exemple: `var cursor = new Cursor(3, 42);`

    Cursor(Cursor altra);

  El constructor de còpia. Retorna una còpia del cursor altra.

  Exemple: `var copy = new Cursor(altra);`

    Cursor Cursor.clone();

  Retorna una còpia del cursor.

  Exemple: `var clone = cursor.clone();`

    bool Cursor.isValid();

  Comproveu si el cursor és vàlid. El cursor no és vàlid, si la línia i/o la columna s'estableix a `-1`.

  Exemple: `var valid = cursor.isValid();`

    Cursor Cursor.invalid();

  Retorna un nou cursor no vàlid situat a `(-1, -1)`.

  Exemple: `var invalidCursor = cursor.invalid();`

    int Cursor.compareTo(Cursor altra);

  Compara aquest cursor al cursor altra. Retorna

  - `-1`, si el cursor està situat abans del cursor altra,

  - `0`, si tots dos cursors són iguals i

  - `+1`, si el cursor està situat després del cursor altra.

    bool Cursor.equals(Cursor altra);

  Retorna `true` (vertader), si aquest cursor i el cursor altra són iguals, en cas contrari retornarà `false` (fals).

    String Cursor.toString();

  Retorna el cursor com una cadena de la forma «`Cursor(line, column)`».

##### El prototip «Range»

    Range();

  El constructor. Crida `new Range()` retornant un rang (0, 0) - (0, 0).

    Range(Cursor inici, Cursor final);

  El constructor. Crida `new Range(inici, final)` retorna el rang (inici, final).

    Range(int líniaInici, int columnaInici, int líniaFinal, int columnaFinal);

  El constructor. Crida `new Range(líniaInici, columnaInici, líniaFinal, columnaFinal)` returna el rang de (líniaInici, columnaInici) a (líniaFinal, columnaFinal).

    Range(Range altra);

  El constructor de còpia. Retorna una còpia del rang altra.

    Range Range.clone();

  Retorna una còpia de la rang.

  Exemple: `var clone = range.clone();`

    bool Range.isValid();

  Retorna `true` (vertader), si inici i final del cursor són vàlids, en cas contrari retornarà `false` (fals).

  Exemple: `var valid = range.isValid();`

    bool Range.invalid();

  Retorna el rang de (-1, -1) a (-1, -1).

    bool Range.contains(Cursor cursor);

  Retorna `true` (vertader) si aquest rang conté la posició de cursor, en cas contrari retornarà `false` (fals).

    bool Range.contains(Range altra);

  Retorna `true` (vertader), si aquest rang conté el rang altra, en cas contrari retornarà `false` (fals).

    bool Range.containsColumn(int columna);

  Retorna `true` (vertader), si columna està en l'interval obert medi `[start.column, end.column)`, en cas contrari retornarà `false` (fals).

    bool Range.containsLine(int línia);

  Retorna `true` (vertader), si línia està en l'interval obert medi `[start.line, end.line)`, en cas contrari retornarà `false` (fals).

    bool Range.overlaps(Range altra);

  Retorna `true` (vertader), si aquest rang i el rang altra comparteixen una regió comuna, en cas contrari retornarà `false` (fals).

    bool Range.overlapsLine(int línia);

  Retorna `true` (vertader), si línia està en l'interval `[start.line, end.line]`, en cas contrari retornarà `false` (fals).

    bool Range.overlapsColumn(int columna);

  Retorna `true` (vertader), si columna està en l'interval `[start.column, end.column]`, en cas contrari retornarà `false` (fals).

    bool Range.onSingleLine();

  Retorna `true` (vertader), si el range comença i finalitza a la mateixa línia, &ead; si Línia.comença.rang == Línia.finalitza.rang.

  Des de: KDE 4.9

    bool Range.equals(Range altra);

  Retorna `true` (vertader), si aquest rang i el rang de altra són iguals, en cas contrari retornarà `false` (fals).

    String Range.toString();

  Retorna el rang com una cadena de la forma «`Rang(Cursor(line, column), Cursor(line, column))`».

#### Funcions globals

Aquesta secció llista totes les funcions globals.

##### Llegir i incloure fitxers

    String read(String fitxer);

  Cercarà el fitxer donat en relació al directori `katepart/script/files` i retorna el seu contingut com una cadena.

    void require(String fitxer);

  Cercarà el fitxer donat en relació al directori `katepart/script/libraries` i l'avaluarà. `require` està internament protegit contra inclusions múltiples del mateix fitxer.

  Des de: KDE 4.10

##### Depuració

    void debug(String text);

  Imprimeix text a `stdout` a la consola de llançament de l'aplicació.

##### Traducció

Per tal de donar suport a la completa localització, hi ha diverses funcions per convertir cadenes en l'script, anomenades `i18n`, `i18nc`, `i18np` i `i18ncp`. Aquestes funcions es comporten exactament com les funcions de traducció de KDE.

Les funcions de traducció tradueixen les cadenes embolcallades a través del sistema de traducció del KDE a la llengua utilitzada en l'aplicació. Les cadenes en els scripts es desenvolupen en les fonts oficials de &kappname; i s'extreuen i tradueixen automàticament. En altres paraules, com a desenvolupador de &kappname; no us heu de preocupar per l'extracció dels missatges i la traducció. No obstant, pels scripts de terceres parts desenvolupats fora de KDE, heu d'extreure i traduir els missatges vosaltres mateixos. Juntament amb els scripts haureu de distribuir també un catàleg de traducció, que inclou totes les cadenes traduïdes. A més, a la capçalera de l'script li heu d'introduir el catàleg a carregar especificant `i18n-catalog`.

    void i18n(String text, arg1...);

  Tradueix text a la llengua utilitzada per l'aplicació. Els arguments arg1..., són opcionals i s'utilitzen per substituir els arguments `%1`, `%2`, &etc;

    void i18nc(String context, String text, arg1...);

  Tradueix text a la llengua utilitzada per l'aplicació. A més, la cadena context és visible als traductors perquè puguin oferir una millor traducció. Els arguments arg1..., són opcionals i s'utilitzen per substituir els arguments `%1`, `%2`, &etc;

    void i18np(String singular, String plural, int número, arg1...);

  Tradueix singular o plural a la llengua utilitzada per l'aplicació, en funció del número indicat. Els arguments arg1..., són opcionals i s'utilitzen per substituir els arguments `%1`, `%2`, &etc;

    void i18ncp(String context, String singular, String plural, int número, arg1...);

  Tradueix singular o plural a la llengua utilitzada per l'aplicació, en funció del número indicat. A més, la cadena context és visible als traductors perquè puguin oferir una millor traducció. Els arguments arg1..., són opcionals i s'utilitzen per substituir els arguments `%1`, `%2`, &etc;

#### L'API de «View»

Cada vegada que s'executa un script, si no hi ha una variable global «`view`» que representa la vista actual de l'editor actiu. La següent és una llista de totes les funcions «View» disponibles.

    Cursor view.cursorPosition()

  Retorna la posició actual del cursor en la vista.

    void view.setCursorPosition(int línia, int columna);
    void view.setCursorPosition(Cursor cursor);

  Estableix la posició actual del cursor a (línia, columna) o el cursor indicat.

    Cursor view.virtualCursorPosition();

  Retorna la posició del cursor virtual amb cada tabulació comptant la corresponent quantitat d'espais depenent de l'amplada de la tabulació actual.

    void view.setVirtualCursorPosition(int línia, int columna);
    void view.setVirtualCursorPosition(Cursor cursor);

  Estableix la posició actual del cursor virtual (línia, columna) o el cursor indicat.

    String view.selectedText();

  Retorna el text seleccionat. Si no hi ha text seleccionat, la cadena retornada estarà buida.

    bool view.hasSelection();

  Retorna `true` (vertader), si la vista conté el text seleccionat, en cas contrari retornarà `false` (fals).

    Range view.selection();

  Retorna el rang de text seleccionat. El rang retornat no és vàlid si no hi ha text seleccionat.

    void view.setSelection(Range rang);

  Estableix el text seleccionat al rang indicat.

    void view.removeSelectedText();

  Elimina el text seleccionat. Si la vista no té cap text seleccionat, no fa res.

    void view.selectAll();

  Selecciona el text sencer en el document.

    void view.clearSelection();

  Neteja la selecció de text sense esborrar-lo.

#### L'API de «Document»

Cada vegada que s'executa un script, si no hi ha una variable global «`document`» que representa el document actiu actual. La següent és una llista de totes les funcions de «Document» disponibles.

    String document.fileName();

  Retorna el nom de fitxer del document o una cadena buida per a la memòria cau de text sense desar.

    String document.url();

  Retorna l'URL complet del document o una cadena buida per a la memòria cau de text sense desar.

    String document.mimeType();

  Retorna el tipus mime del document o el tipus mime `application/octet-stream` si no es pot trobar un tipus mime adequat.

    String document.encoding();

  Retorna la codificació usada actualment per a desar el fitxer.

    String document.highlightingMode();

  Retorna el mode de ressaltat global usat per a tot el document.

    String document.highlightingModeAt(Cursor pos);

  Retorna el mode de ressaltat usat a la posició indicada en el document.

    Array document.embeddedHighlightingModes();

  Retorna una cadena de modes de ressaltat inclosos en aquest document.

    bool document.isModified();

  Retorna `true` (vertader), si el document conté canvis sense desar (modificat), en cas contrari retornarà `false` (fals).

    String document.text();

  Retorna el contingut complet del document en una cadena de text única. Els salts de línia estan marcats amb el caràcter de nova línia «`\n`».

    String document.text(int desdeLínia, int desdeColumna, int alaLínia, int alaColumna);
    String document.text(Cursor des_de, Cursor a_la);
    String document.text(Range rang);

  Retorna el text en el rang donat. Es recomana utilitzar el cursor i la versió basada en el rang per a una millor lectura del codi font.

    String document.line(int línia);

  Retorna la línia de text donada com a cadena. La cadena estarà buida si la línia demanada està fora de rang.

    String document.wordAt(int línia, int columna);
    String document.wordAt(Cursor cursor);

  Retorna la paraula a la posició del cursor donada.

    Range document.wordRangeAt(int línia, int columna);
    Range document.wordRangeAt(Cursor cursor);

  Retorna el rang de la paraula a la posició del cursor donada. El rang retornat no és vàlid (veure Range.isValid()), si la posició del text és després del final d'una línia. Si no hi ha paraula al cursor donat, es retornarà un rang buit.

  Des de: KDE 4.9

    String document.charAt(int línia, int columna);
    String document.charAt(Cursor cursor);

  Retorna el caràcter a la posició del cursor donada.

    String document.firstChar(int línia);

  Retorna el primer caràcter en la línia donada que no és un espai en blanc. El primer caràcter és a la columna 0. Si la línia està buida o només conté espais en blanc, la cadena retornada estarà buida.

    String document.lastChar(int línia);

  Retorna l'últim caràcter de la línia donada que no és un espai en blanc. Si la línia està buida o només conté espais en blanc, la cadena retornada estarà buida.

    bool document.isSpace(int línia, int columna);
    bool document.isSpace(Cursor cursor);

  Retorna `true` (vertader), si el caràcter a la posició del cursor donada és un espai en blanc, en cas contrari retornarà `false` (fals).

    bool document.matchesAt(int línia, int columna, String text);
    bool document.matchesAt(Cursor cursor, String text);

  Retorna `true` (vertader), si el text donat coincideix a la posició del cursor corresponent, en cas contrari retornarà `false` (fals).

    bool document.startsWith(int línia, String text, bool skipWhiteSpaces);

  Retorna `true` (vertader), si la línia comença amb text, en cas contrari retornarà `false` (fals). L'argument skipWhiteSpaces controla si s'han d'ometre els espais en blanc al davant.

    bool document.endsWith(int línia, String text, bool skipWhiteSpaces);

  Retorna `true` (vertader), si la línia acaba amb text, en cas contrari retornarà `false` (fals). L'argument skipWhiteSpaces controla si s'han d'ometre els espais en blanc al darrere.

    bool document.setText(String text);

  Estableix el text a tot el document.

    bool document.clear();

  Esborra el text sencer en el document.

    bool document.truncate(int línia, int columna);
    bool document.truncate(Cursor cursor);

  Trunca la línia donada a la columna o la posició del cursor donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals) si la línia donada no forma part del rang document.

    bool document.insertText(int línia, int columna, String text);
    bool document.insertText(Cursor cursor, String text);

  Insereix el text en la posició donada del cursor. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura.

    bool document.removeText(int des_deLínia, int des_deColumna, int a_laLínia, int a_laColumna);
    bool document.removeText(Cursor des_de, Cursor a_la);
    bool document.removeText(Range range);

  Elimina el text dins del rang donat. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura.

    bool document.insertLine(int línia, String text);

  Insereix text en la línia donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura o la línia no està en el rang document.

    bool document.removeLine(int línia);

  Elimina la línia de text donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura o la línia no està en el rang document.

    bool document.wrapLine(int línia, int columna);
    bool document.wrapLine(Cursor cursor);

  Ajusta la línia en la posició del cursor donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), &pex; si la línia < 0.

  Des de: KDE 4.9

    void document.joinLines(int iniciLínia, int finalLínia);

  S'uneix a les línies de iniciLínia a finalLínia. Dues línies de text successives sempre estan separades per un espai.

    int document.lines();

  Retorna la quantitat de línies en el document.

    int document.length();

  Retorna el nombre de caràcters en el document.

    int document.lineLength(int línia);

  Retorna la longitud de la línia.

    void document.editBegin();

  Comença un grup d'edició per agrupar desfer/refer. Assegureu-vos de cridar sempre `editEnd()` tan aviat com crideu `editBegin()`. La crida `editBegin()` utilitza internament un comptador de referència, &ead;, aquesta crida es pot niar.

    void document.editEnd();

  Finalitza un grup d'edició. L'última crida de `editEnd()` (&ead;, una per a la primera crida de `editBegin()`) finalitza la passa d'edició.

    int document.firstColumn(int línia);

  Retorna la primera columna que no està en blanc en la línia donada. Si només hi ha espais en blanc en la línia, el valor retornat serà `-1`.

    int document.lastColumn(int línia);

  Retorna la darrera columna que no està en blanc en la línia donada. Si només hi ha espais en blanc en la línia, el valor retornat serà `-1`.

    int document.prevNonSpaceColumn(int línia, int columna);
    int document.prevNonSpaceColumn(Cursor cursor);

  Retorna la columna no buida que conté caràcters no en blanc a partir de la posició donada del cursor i cercant cap enrere.

    int document.nextNonSpaceColumn(int línia, int columna);
    int document.nextNonSpaceColumn(Cursor cursor);

  Retorna la columna no buida que conté caràcters no en blanc a partir de la posició donada del cursor i cercant cap endavant.

    int document.prevNonEmptyLine(int línia);

  Retorna la línia següent no buida que conté caràcters no en blanc a la cerca cap enrere.

    int document.nextNonEmptyLine(int línia);

  Retorna la línia següent no buida que conté caràcters no en blanc a la cerca cap endavant.

    bool document.isInWord(String caràcter, int atribut);

  Retorna `true` (vertader), si el caràcter donat amb l'atribut donat pot formar part d'una paraula, en cas contrari retornarà `false` (fals).

    bool document.canBreakAt(String caràcter, int atribut);

  Retorna `true` (vertader), si el caràcter donat amb l'atribut donat és adequat com a embolcall d'una línia, en cas contrari retornarà `false` (fals).

    bool document.canComment(int iniciAtribut, int finalAtribut);

  Retorna `true` (vertader), si un rang inicial i final amb els atributs donats es presten a ser descomentats, en cas contrari retornarà `false` (fals).

    String document.commentMarker(int atribut);

  Retorna el marcador de comentari per als comentaris de línia única per a un atribut donat.

    String document.commentStart(int atribut);

  Retorna el marcador de comentari per al començament de comentaris de múltiples línies per a un atribut donat.

    String document.commentEnd(int atribut);

  Retorna el marcador de comentari per al final de comentaris de múltiples línies per a un atribut donat.

    int document.attribute(int línia, int columna);
    int document.attribute(Cursor cursor);

  Retorna l'atribut a la posició del cursor donada.

    bool document.isAttribute(int línia, int columna, int atribut);
    bool document.isAttribute(Cursor cursor, int atribut);

  Retorna `true` (vertader), si l'atribut a la posició del cursor és igual que l'atribut, en cas contrari retornarà `false` (fals).

    String document.attributeName(int línia, int columna);
    String document.attributeName(Cursor cursor);

  Retorna el nom de l'atribut com a text llegible. Això equival al nom `itemData` en els fitxers de ressaltat de sintaxi.

    bool document.isAttributeName(int línia, int columna, String nom);
    bool document.isAttributeName(Cursor cursor, String nom);

  Retorna `true` (vertader), si el nom de l'atribut en una posició determinada del cursor coincideix amb el nom donat, en cas contrari retornarà `false` (fals).

    String document.variable(String clau);

  Retorna el valor de la variable de document demanada clau. Si la variable de document no existeix, el valor retornat serà una cadena buida.

    String document.setVariable(String clau, String valor);

  Estableix el valor de la variable de document demanada clau. Retorna el valor de la variable establerta.

  Veure també: variables de document de Kate

  Des de: KDE 4.8

    int document.firstVirtualColumn(int línia);

  Retorna la columna virtual del primer caràcter que no està en blanc en la línia donada o `-1`, si la línia està buida o només conté caràcters d'espai en blanc.

    int document.lastVirtualColumn(int línia);

  Retorna la columna virtual de l'últim caràcter que no està en blanc en la línia donada o `-1`, si la línia està buida o només conté caràcters d'espai en blanc.

    int document.toVirtualColumn(int línia, int columna);
    int document.toVirtualColumn(Cursor cursor);
    Cursor document.toVirtualCursor(Cursor cursor);

  Converteix la posició «real» donada del cursor a una posició virtual del cursor, d'altra manera retorna un int o un objecte Cursor.

    int document.fromVirtualColumn(int línia, int virtualColumna);
    int document.fromVirtualColumn(Cursor virtualCursor);
    Cursor document.fromVirtualCursor(Cursor virtualCursor);

  Converteix la posició virtual donada del cursor a una posició «real» del cursor, d'altra manera retorna un int o un objecte Cursor.

    Cursor document.anchor(int línia, int columna, Char caràcter);
    Cursor document.anchor(Cursor cursor, Char caràcter);

  Cerca enrere pel caràcter donat a partir del cursor donat. Com exemple, si es passa «(» com a caràcter, aquesta funció retornarà la posició de l'obertura «(». Això compta la referència, &ead;, els altres «(...)» seran ignorats.

    Cursor document.rfind(int línia, int columna, String text, int atribut = -1);
    Cursor document.rfind(Cursor cursor, String text, int atribut = -1);

  Cercar cap enrere el text donat amb l'atribut adequat. L'argument atribut s'ignorarà si s'estableix a `-1`. El cursor retornat no serà vàlid, si el text no s'ha pogut trobar.

    int document.defStyleNum(int línia, int columna);
    int document.defStyleNum(Cursor cursor);

  Retorna l'estil per omissió utilitzat a la posició donada del cursor.

    bool document.isCode(int línia, int columna);
    bool document.isCode(Cursor cursor);

  Retorna `true` (vertader), si l'atribut a la posició donada del cursor no és igual per a tots els següents estils: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int línia, int columna);
    bool document.isComment(Cursor cursor);

  Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsComment`, en cas contrari retornarà `false` (fals).

    bool document.isString(int línia, int columna);
    bool document.isString(Cursor cursor);

  Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsString`, en cas contrari retornarà `false` (fals).

    bool document.isRegionMarker(int línia, int columna);
    bool document.isRegionMarker(Cursor cursor);

  Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsRegionMarker`, en cas contrari retornarà `false` (fals).

    bool document.isChar(int línia, int columna);
    bool document.isChar(Cursor cursor);

  Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsChar`, en cas contrari retornarà `false` (fals).

    bool document.isOthers(int línia, int columna);
    bool document.isOthers(Cursor cursor);

  Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsOthers`, en cas contrari retornarà `false` (fals).