http://docs.kde.org/
AnteriorEstendre la KatePartSegüent

Crear scripts en JavaScript

El component d'edició de la KatePart és fàcilment extensible, escrivint scripts. El llenguatge per a crear scripts és ECMAScript (conegut com a JavaScript). La KatePart admet dos tipus de script: scripts de sagnat i de línia d'ordres. El connector de retalls també proporciona una funcionalitat semblant als scripts de línia d'ordres.

Scripts de sagnat

Els scripts de sagnat: També coneguts com a «indenters», sagnen automàticament el codi font en escriure text. Com a exemple, després de prémer 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 un fitxer *.js nou anomenat, p. ex., javascript.js a la carpeta d'inici local $XDG_DATA_HOME/katepart5/script/indentation. En aquest sentit, la variable d'entorn XDG_DATA_HOME normalment s'expandeix a ~/.local o ~/.local/share.

Al Windows® aquests fitxers es troben a %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% que generalment s'expandeix a C:\\Users\\usuari.

La capçalera de l'script de sagnat

La capçalera del fitxer javascript.js està incrustada com un JSON al començament del document de la forma següent: 

var katescript = {
    "name": "JavaScript",
    "author": "Nom exemple <nom.exemple@alguna.adreça.org>",
    "license": "BSD License",
    "revision": 1,
    "kate-version": "5.1",
    "required-syntax-style": "javascript",
    "indent-languages": ["javascript"],
    "priority": 0,
}; // kate-script-header, haurà d'estar al començament del fitxer sense comentaris

Cada entrada s'explica en detall tot seguit:

  • 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 es modifica l'script.

  • kate-version [requerit]: La versió mínima requerida per la KatePart.

  • required-syntax-style [opcional]: L'estil de la sintaxi requerida, el qual coincideix amb style especificat als fitxers 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 la 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 del ressaltat esperat. Per exemple, el sagnat de Ruby en fa ús en els fitxers ruby.js i ruby.xml.

  • indent-languages [opcional]: Una matriu JSON dels estils de la sintaxi que pot sagnar correctament, p. ex.: ["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 a sagnat predeterminat.

El codi font del sagnat

Després d'haver especificat la capçalera aquesta secció explica com funciona la creació de scripts de sagnat. 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 Eines → Format del sagnat
    // la variable ch és buidada, és a dir, ch == «».
    //
    // Vegeu també: L'API per a crear 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 nombre 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 manera següent:

  • 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 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 això, 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'utilitzen 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 a 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ó predeterminada del KDE ens dona la KatePart amb diversos sagnats. El corresponent codi font de JavaScript d'origen pot trobar-se en $XDG_DATA_DIRS/katepart5/script/indentation.

Al Windows® aquests fitxers es troben a %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% que generalment s'expandeix a C:\\Users\\usuari.

El desenvolupament d'un sagnat requereix tornar a carregar els scripts per a 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, considereu contribuir al projecte KatePart proporcionant una petició de fusió al nostre projecte de GitLab.

Els scripts de la línia d'ordres

Nota

Una funcionalitat similar als scripts de línia d'ordres també es proporciona al connector de retalls. Aquest connector pot proporcionar un punt de partida més fàcil, especialment per a scripts personalitzats petits.

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

Els scripts de línia d'ordres es troben a la mateixa carpeta que els scripts de sagnat. Així que com a primer pas, creeu un fitxer *.js nou anomenat myutils.js a la carpeta d'inici local $XDG_DATA_HOME/katepart5/script/commands. En aquest sentit, la variable d'entorn XDG_DATA_HOME normalment s'expandeix a ~/.local o ~/.local/share.

Al Windows® aquests fitxers es troben a %USERPROFILE%\AppData\Local\katepart5\script\commands. %USERPROFILE% que generalment s'expandeix a C:\\Users\\usuari.

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

La capçalera de cada script de la línia d'ordres està incrustada en el JSON al començament de l'script de la forma següent: 

var katescript = {
    "author": "Nom exemple <nom.exemple@alguna.adreça.org>",
    "license": "LGPLv2+",
    "revision": 1,
    "kate-version": "5.1",
    "functions": ["sort", "moveLinesDown"],
    "actions": [
        {   "function": "sort",
            "name": "Sort Selected Text",
            "category": "Editing",
            "interactive": "false"
        },
        {   "function": "moveLinesDown",
            "name": "Move Lines Down",
            "category": "Editing",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
}; // kate-script-header, haurà d'estar al començament del fitxer sense comentaris

Cada entrada s'explica en detall tot seguit:

  • 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 LGPLv2.

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

  • kate-version [requerit]: La versió mínima requerida per la KatePart.

  • functions [requerit]: Matriu JSON de les ordres a l'script.

  • actions [opcional]: La matriu JSON dels objectes JSON que defineixen les accions que apareixen al menú de l'aplicació. Es proporciona informació detallada a la secció Vincular dreceres.

Atès que el valor de functions és una matriu JSON, un únic script és capaç de contenir un nombre arbitrari d'ordres de la línia d'ordres. Cada funció està disponible a través de la línia d'ordres integrada a la KatePart.

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 de script en l'exemple anterior necessita implementar les dues funcions sort i moveLinesDown. Totes les funcions tenen la següent sintaxi: 

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

function <nom>(arg1, arg2...)
{
    // «...» implementació, vegeu també: L'API de creació de 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 manera següent: 

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

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

El desenvolupament d'un script de línia d'ordres requereix tornar a carregar els scripts per a 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.

Vincular les dreceres

Per tal de fer que els scripts siguin accessibles al menú de l'aplicació i assignar dreceres, l'script ha de proporcionar una capçalera de script adequada. En l'exemple anterior, ambdues funcions sort i moveLinesDown apareixen al menú per la següent part a la capçalera de l'script: 

var katescript = {
    ...
    "actions": [
        {   "function": "sort",
            "name": "Sort Selected Text",
            "icon": "",
            "category": "Editing",
            "interactive": "false"
        },
        {   "function": "moveLinesDown",
            "name": "Move Lines Down",
            "icon": "",
            "category": "Editing",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
};

Els camps per a una acció són els següents:

  • function [requerit]: La funció que ha d'aparèixer al menú Eines → Scripts.

  • name [requerit]: El text apareix al menú de l'script.

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

  • category [opcional]: Si s'especifica una categoria, l'script apareixerà en un submenú.

  • shortcut [opcional]: La drecera indicada serà la drecera predeterminada. Exemple: Ctrl+Alt+t. Per a més detalls, vegeu la Documentació de les Qt™.

  • interactive [opcional]: Si l'script necessita utilitzar l'entrada a la línia d'ordres, establiu-ho a true (cert).

Si desenvolupeu scripts útils, considereu contribuir al projecte KatePart proporcionant una petició de fusió al nostre projecte de GitLab.

L'API de creació de scripts

L'API per a crear scripts que es presenta aquí està disponible per a tots els scripts, p. ex., els scripts de sagnat i una ordre de línia d'ordres. Les classes Cursor i Range són proporcionades pels fitxers de la biblioteca a $XDG_DATA_DIRS/katepart5/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 la katepart, p. ex., «range.js»
// si utilitzeu «Range»
require ("range.js");

Per a estendre la norma de l'API per a crear scripts amb les vostres pròpies funcions i prototips n'hi ha prou amb crear un fitxer nou a la carpeta de configuració local del KDE $XDG_DATA_HOME/katepart5/libraries i incloure'l a l'script utilitzant: 

require ("nom_script.js");

Al Windows® aquests fitxers es troben a %USERPROFILE%\AppData\Local\katepart5\libraries. %USERPROFILE% que generalment s'expandeix a C:\\Users\\usuari.

Per a 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 intervals

Com la KatePart és un editor de text, tota l'API per a la creació de scripts es basa en els cursors i els intervals 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(); 

Cursor.setPosition(int línia, int columna);

Estableix la posició del cursor a línia i columna.

Des del: KDE 4.11 

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 cursor nou 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 (cert), 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 interval (0, 0) - (0, 0). 

Range(Cursor inici, Cursor final);

El constructor. Crida new Range(inici, final) retorna l'interval de (inici, final). 

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

El constructor. Crida new Range(líniaInici, columnaInici, líniaFinal, columnaFinal) retorna l'interval de (líniaInici, columnaInici) a (líniaFinal, columnaFinal). 

Range(Range altra);

El constructor de còpia. Retorna una còpia de l'interval altra. 

Range Range.clone();

Retorna una còpia de l'interval.

Exemple: var clone = range.clone(); 

bool Range.isEmpty();

Retorna true (cert), si inici i final del cursor són iguals.

Exemple: var empty = range.isEmpty();

Des del: KDE 4.11 

bool Range.isValid();

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

Exemple: var valid = range.isValid(); 

Range Range.invalid();

Retorna l'interval de (-1, -1) a (-1, -1). 

bool Range.contains(Cursor cursor);

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

bool Range.contains(Range altra);

Retorna true (cert), si aquest interval conté l'interval altra, en cas contrari retornarà false (fals). 

bool Range.containsColumn(int columna);

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

bool Range.containsLine(int línia);

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

bool Range.overlaps(Range altre);

Retorna true (cert), si aquest interval i l'interval altre comparteixen una regió comuna, en cas contrari retornarà false (fals). 

bool Range.overlapsLine(int línia);

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

bool Range.overlapsColumn(int columna);

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

bool Range.onSingleLine();

Retorna true (cert), si l'interval comença i finalitza a la mateixa línia, és a dir si Línia.comença.interval == Línia.finalitza.interval.

Des del: KDE 4.9 

bool Range.equals(Range altra);

Retorna true (cert), si aquest interval i l'interval altra són iguals, en cas contrari retornarà false (fals). 

String Range.toString();

Retorna l'interval 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ó amb el directori katepart5/script/files i retorna el seu contingut com una cadena. 

void require(String fitxer);

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

Des del: 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 a convertir cadenes en els scripts, anomenades i18n, i18nc, i18np i i18ncp. Aquestes funcions es comporten exactament com les funcions de traducció del KDE.

Les funcions de traducció tradueixen les cadenes embolcallades a través del sistema de traducció del KDE per a l'idioma utilitzat en l'aplicació. Les cadenes als scripts es desenvolupen a les fonts oficials de la KatePart i s'extrauen de forma automàtica i traduïble. En altres paraules, com a desenvolupador de la KatePart no haureu de preocupar-vos per l'extracció dels missatges i la traducció. Però cal assenyalar que la traducció només funciona dins de la infraestructura del KDE, és a dir, les cadenes noves als scripts de terceres parts desenvolupats fora del KDE no seran traduïbles. Per tant, considereu en contribuir els vostres scripts al Kate, de tal manera que sigui possible una traducció apropiada. 

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

Tradueix text a l'idioma emprat per l'aplicació. Els arguments arg1..., són opcionals i s'utilitzen per a substituir els arguments %1, %2, etc.

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

Tradueix text a l'idioma emprat per l'aplicació. A més, la cadena context és visible a l'equip de traducció perquè puguin oferir una millor traducció. Els arguments arg1..., són opcionals i s'utilitzen per a substituir els arguments %1, %2, etc.

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

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

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

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

L'API de «View»

Cada vegada que s'executa un script, si 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. 

void view.copy()

Copia la selecció si n'hi ha una, en cas contrari la línia actual si s'ha establert l'opció [] Copia/retalla la línia actual si no hi ha cap selecció.

Des del: Frameworks del KDE™ 5.79

void view.cut()

Retalla la selecció si n'hi ha una, en cas contrari la línia actual si s'ha establert l'opció [ ] Copia/retalla la línia actual si no hi ha cap selecció.

Des del: Frameworks del KDE™ 5.79

void view.paste()

Enganxa el contingut del porta-retalls.

Des del: Frameworks del KDE™ 5.79

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 column);
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 (cert), si la vista conté el text seleccionat, en cas contrari retornarà false (fals). 

Range view.selection();

Retorna l'interval de text seleccionat. L'interval retornat no serà vàlid si no hi ha text seleccionat. 

void view.setSelection(Range rang);

Estableix el text seleccionat a l'interval indicat. 

void view.removeSelectedText();

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

void view.selectAll();

Selecciona el text sencer en el document. 

void view.clearSelection();

Neteja la selecció de text sense eliminar-lo. 

void view.setBlockSelection(bool on);

Activa o desactiva el mode de selecció de blocs («on» o «off»). 

bool view.blockSelection();

Retorna true (cert), si el mode de selecció de blocs està activat, en cas contrari retornarà false (fals). 

void view.align(Range interval);

Torna a sagnar correctament les línies dins de l'interval segons els paràmetres actuals del sagnat. 

void view.alignOn(Range interval, String patró = "");

Alinea les línies de l'interval a la columna indicada pel patró de l'expressió regular. Amb un patró buit s'alinearà amb el primer caràcter no blanc de manera predeterminada. Si el patró té una captura, se sagnarà a la coincidència capturada.

Exemples:

view.alignOn(document.documentRange(), '-'); inserirà espais abans del primer - de cada línia per a alinear-les totes a la mateixa columna.

>view.alignOn(document.documentRange(), ':\\s+(.)'); inserirà espais abans del primer caràcter no blanc que hi hagi després de dos punts (:) per a alinear-les totes a la mateixa columna.

object view.executeCommand(String ordre,
                           String args,
                           Range interval);

Executa l'ordredes de la línia d'ordres amb els arguments args opcionals i l'interval opcional. L'objecte retornat tindrà una propietat booleana object.ok, la qual indica que l'execució de l'ordre ha tingut èxit. En cas d'error, la cadena object.status contindrà un missatge d'error.

Des del: Frameworks del KDE™ 5.0

Range view.searchText(Range interval,
                      String patró,
                      bool enrere = false);

Cerca la primera ocurrència de patró a l'interval i retorna l'interval coincident. La cerca es porta a terme cap enrere si el paràmetre booleà opcional enrere s'estableix a cert.

L'interval retornat no és vàlid (vegeu Range.isValid()) si el patró no s'ha trobat en l'interval.

Des del: Frameworks del KDE™ 5.97

L'API de «Document»

Cada vegada que s'executa un script, si 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 del text sense desar. 

String document.url();

Retorna l'URL complet del document o una cadena buida per a la memòria cau del 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ó emprada actualment per a desar el fitxer. 

String document.highlightingMode();

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

String document.highlightingModeAt(Cursor pos);

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

Array document.embeddedHighlightingModes();

Retorna una cadena dels modes de ressaltat incrustats en aquest document. 

bool document.isModified();

Retorna true (cert), 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 desDe, Cursor a);
String document.text(Range rang);

Retorna el text en l'interval donat. Es recomana utilitzar el cursor i la versió basada en l'interval 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 l'interval. 

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 l'interval de la paraula a la posició del cursor donada. L'interval retornat no serà vàlid (vegeu 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 interval buit.

Des del: 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 (cert), 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 (cert), 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 (cert), 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 (cert), 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 finals. 

bool document.setText(String text);

Estableix el text a tot el document. 

bool document.clear();

Elimina tot el text 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ó donada del cursor. Retorna true (cert) en cas d'èxit, o false (fals) si la línia donada no forma part de l'interval del document. 

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

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

bool document.removeText(int desDeLínia, int desDeColumna, int alaLínia, int alaColumna);
bool document.removeText(Cursor desDe, Cursor a);
bool document.removeText(Range rang);

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

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

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

bool document.removeLine(int línia);

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

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

Ajusta la línia a la posició del cursor donada. Retorna true (cert) en cas d'èxit, o false (fals), p. ex. si la línia < 0.

Des del: 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 el nombre de línies en el document. 

bool document.isLineModified(int línia);

Retorna true (cert), si la línia actual conté dades sense desar.

Des del: KDE 5.0 

bool document.isLineSaved(int línia);

Retorna true (cert), si la línia ha canviat, però el document ha estat desat. Per tant, la línia actual no conté cap dada sense desar.

Des del: KDE 5.0 

bool document.isLineTouched(int línia);

Retorna true (cert), si la línia actual conté dades sense desar o que s'han canviat abans.

Des del: KDE 5.0 

bool document.findTouchedLine(int iniciLínia, bool avall);

Cerca la següent línia tocada començant per la línia. La cerca es realitza amunt o avall depenent de la direcció especificada en avall.

Des del: KDE 5.0 

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 a agrupar desfer/refer. Assegureu-vos de cridar sempre editEnd() tan aviat com crideu editBegin(). La crida editBegin() utilitza internament un comptador de referència, és a dir, aquesta crida es pot imbricar. 

void document.editEnd();

Finalitza un grup d'edició. L'última crida de editEnd() (és a dir, una per a la primera crida de editBegin()) finalitza el pas 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 a 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 a 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é un caràcter 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é un caràcter 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 (cert), 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 (cert), 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 (cert), si un interval 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. 

Range document.documentRange();

Retorna un interval que abasta tot el document. 

Cursor documentEnd();

Retorna un cursor situat a l'última columna de l'última línia al document. 

bool isValidTextPosition(int línia, int columna);
bool isValidTextPosition(Cursor cursor);

Retorna true (cert), si la posició indicada del cursor està situada a una posició vàlida del text. Una posició de text només és vàlida si es localitza al començament, al mig o al final d'una línia vàlida. A més, una posició de text no serà vàlida si es troba en un substitut Unicode.

Des del: KDE 5.0 

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 (cert), 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 la sintaxi. 

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

Retorna true (cert), 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. 

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

Estableix el valor de la variable de document demanada clau.

Vegeu també: variables de document del Kate

Des del: KDE 4.8 

int document.firstVirtualColumn(int línia);

Retorna la columna virtual del primer caràcter que no està en blanc a 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 a 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 a exemple, si es passa «(» com a caràcter, aquesta funció retornarà la posició de l'obertura «(». Això compta la referència, és a dir, 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);

Cerca 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 predeterminat utilitzat a la posició donada del cursor. 

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

Retorna true (cert), 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 (cert), 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 (cert), 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 (cert), 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 (cert), 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 (cert), si l'atribut del caràcter a la posició del cursor és dsOthers, en cas contrari retornarà false (fals). 

void document.indent(Range interval, int canvi);

Sagna totes les línies de l'interval canviant les tabulacions o canviant tabSize vegades els espais depenent de les preferències dels usuaris. El paràmetre canvi pot ser negatiu.

L'API de l'editor

A més de l'API del document i la visualització, hi ha una API general de l'editor que proporciona funcions per a la funcionalitat per a crear scripts general de l'editor. 

Cadena editor.clipboardText();

Retorna el text que es troba actualment al porta-retalls global.

Des del: Frameworks del KDE™ 5.0

Cadena editor.clipboardHistory();

L'editor manté un historial del porta-retalls que conté fins a 10 entrades. Aquesta funció retorna totes les entrades que actualment es troben a l'historial del porta-retalls.

Des del: Frameworks del KDE™ 5.0

void editor.setClipboardText(String text);

Estableix el contingut del porta-retalls al text. El text serà afegit a l'historial del porta-retalls.

Des del: Frameworks del KDE™ 5.0