http://docs.kde.org/
IndietroEstensione di KatePartAvanti

Scripting con JavaScript

Il componente editor di KatePart è facilmente estendibile attraverso degli script. Il linguaggio di script è ECMAScript (comunemente noto come JavaScript). KatePart supporta due tipi di script: script di rientro e a riga di comando. Una funzionalità simile per comandare gli script da riga di comando viene anche fornita dall'estensione dei frammenti.

Script di rientro

Gli script di rientro, noti anche come rientratori, fanno rientrare automaticamente il codice sorgente mentre si scrive. Per esempio, spesso il livello di rientro aumenta dopo aver premuto Invio.

Le sezioni seguenti descrivono passo-passo come creare la struttura di un semplice rientratore. Come primo passo crea un nuovo file *.js chiamato ad es. javascript.js nella cartella home locale $XDG_DATA_HOME/katepart5/script/indentation. Al suo interno la variabile di ambiente XDG_DATA_HOME viene tipicamente espansa sia in ~/.local che in ~/.local/share.

In Windows® questi file si trovano in %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% viene generalmente espanso in C:\\Utenti\\utente.

L'intestazione dello script di rientro

L'intestazione del file javascript.js è incorporata come JSON all'inizio del documento, e ha la forma seguente: 

var katescript = {
    "name": "JavaScript",
    "author": "Pippo <pippo@topolinia.it>"
    "license": "BSD License",
    "revision": 1,
    "kate-version": "5.1",
    "required-syntax-style":"javascript",
    "indent-languages": ["javascript"],
    "priority": 0,
}; // kate-script-header, deve essere all'inizio della riga senza commenti

Ogni voce viene ora spiegata in dettaglio:

  • name [obbligatorio]: questo è il nome del rientratore che appare nel menu Strumenti → Rientro e nella finestra di configurazione.

  • author [facoltativo]: il nome dell'autore e informazioni per contattarlo.

  • license [facoltativo]: forma breve della licenza, come Licenza BSD o LGPLv3.

  • revision [obbligatorio]: la revisione dello script. Questo numero va aumentato ad ogni sua modifica.

  • kate-version [obbligatorio]: versione minima di KatePart richiesta.

  • required-syntax-style [facoltativo]: lo stile della sintassi richiesto, se soddisfa lo stile specificato nei file di evidenziazione della sintassi. È importante per i rientratori che richiedono informazioni di evidenziazione specifiche nel documento. Se uno stile di sintassi richiesto viene specificato, il rientratore è disponibile solo quando è attivo l'evidenziatore appropriato. Ciò impedisce il «comportamento non definito» causato dall'uso del rientratore senza lo schema di evidenziazione atteso. Per esempio, il rientratore di Ruby lo usa nei file ruby.js e ruby.xml.

  • indent-languages [facoltativo]: elenco JSON di stili di sintassi che il rientratore può far rientrare correttamente, ad es.: ["c++", "java"].

  • priority [facoltativo]: se ci sono più rientratori che si adattano a un certo file evidenziato la priorità decide quale viene scelto come predefinito.

Il codice sorgente del rientratore

Dopo aver specificato l'intestazione, questa sezione spiega come funziona lo script di rientro vero e proprio. La struttura fondamentale ha questo aspetto: 

// librerie katepart js necessarie, ad es. range.js se usi Range
require ("range.js");
  
triggerCharacters = "{}/:;";
function indent(riga, larghezza_rientro, carattere)
{
    // richiamato a ogni ritorno a capo (carattere == '\n') e per tutti i caratteri
    // specificati nella in variabile globale triggerCharacters. Quando si chiama
    // Strumenti → Rientro formato
    // la variabile carattere è vuota, cioè caratteri == ''.
    //
    // Vedi anche: API di scripting
    return -2;
}

La funzione indent() ha tre argomenti:

  • riga: la riga da far rientrare;

  • larghezza_rientro: la larghezza del rientro espressa come numero di spazi;

  • carattere: un carattere di ritorno a capo (carattere == '\n'), un carattere di attivazione specificato in triggerCharacters, o vuota se l'utente ha attivato l'azione Strumenti → Rientro formato.

Il valore restituito dalla funzione indent() specifica come far rientrare la riga. Se il valore è un semplice numero intero, viene interpretato come segue:

  • Valore restituito -2: non fare nulla;

  • Valore restituito -1: mantieni il rientro (cerca una riga non vuota precedente)

  • Valore restituito 0: I numeri numbers ≥ 0 specificano il rientro in spazi

In alternativa, si può restituire un array di due elementi:

  • return [ indent, align ];

In questo caso, il primo elemento è il rientro, con lo stesso significato di cui sopra. Il secondo elemento, invece, è un valore assoluto che rappresenta una colonna di «allineamento». Se questo valore è maggiore del valore di rientro, la differenza rappresenta un numero di spazi da aggiungere dopo il rientro della prima variabile. Altrimenti, il secondo numero viene ignorato. Usare sia tabulatori che spazi per il rientro viene spesso indicato come «modalità mista».

Considera il seguente esempio: supponiamo di usare le tabulazioni per il rientro, e la loro ampiezza è impostata a 4. Qui, <tab> indica una tabulazione e «.» uno spazio: 

1: <tab><tab>pippo("ciao",
2: <tab><tab>......"mondo");

Quando si fa rientrare la seconda riga, la funzione indent() restituisce [8, 15]. Perciò, si inseriscono due tabulazioni per far rientrare fino alla colonna 8, e vengono aggiunti sette spazi per allineare il secondo argomento al primo, in modo che rimanga allineato se il file viene visualizzato con un'ampiezza di tabulazione diversa.

Un'installazione predefinita di KDE include KatePart con diversi rientratori. Il codice JavaScript corrispondente si può trovare in $XDG_DATA_DIRS/katepart5/script/indentation.

In Windows® questi file si trovano in %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% viene generalmente espanso in C:\\Utenti\\utente.

Lo sviluppo di un rientratore richiede il ricaricamento gli script, per testare le modifiche. Invece di riavviare l'applicazione puoi però passare alla riga di comando, e digitare il comando reload-scripts.

Se sviluppi degli script utili, per piacere considera la possibilità di contribuire al progetto KatePart creando una richiesta di integrazione nel nostro progetto GitLab.

Script da riga di comando

Nota

Una funzionalità simile per comandare gli script da riga di comando viene anche fornita dall'estensione dei frammenti. Questa può essere un punto di partenza più semplice, specialmente per i piccoli script personalizzati.

Essendo difficile soddisfare le necessità di tutti, KatePart supporta dei piccoli strumenti di supporto per manipolare velocemente il testo attraverso la riga di comando integrata. Per esempio, il comando sort è implementato come uno script. Questa sezione spiega come creare file *.js per estendere KatePart con script di supporto a piacere.

Gli script da riga di comando si trovano nella stessa cartella degli script di rientro. Come primo passo, crea un nuovo file *.js chiamato myutils.js nella home locale $XDG_DATA_HOME/katepart5/script/commands. Al suo interno la variabile di ambiente XDG_DATA_HOME viene tipicamente espansa sia in ~/.local che in ~/.local/share.

In Windows® questi file si trovano in %USERPROFILE%\AppData\Local\katepart5\script\commands. %USERPROFILE% viene generalmente espanso in C:\\Utenti\\utente.

L'intestazione dello script per la riga di comando

L'intestazione di ciascuno script da riga di comando è incorporata in JSON all'inizio dello script come segue: 

var katescript = {
    "author": "Example Name <example.name@some.address.org>",
    "license": "LGPLv2+",
    "revision": 1,
    "kate-version": "5.1",
    "functions": ["sort", "moveLinesDown"],
    "actions": [
        {   "function": "sort",
            "name": "Ordina il testo selezionato",
            "category": "Editing",
            "interactive": "false"
        },
        {   "function": "moveLinesDown",
            "name": "Sposta le righe in basso",
            "category": "Editing",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
}; // l'intestazione dello script di kate deve essere all'inizio del file senza commento

Ciascuna voce è spiegata ora in dettaglio:

  • author [facoltativo]: il nome dell'autore e informazioni per contattarlo.

  • license [facoltativo]: forma breve della licenza, come Licenza BSD o LGPLv2.

  • revision [obbligatorio]: la revisione dello script. Questo numero va aumentato ad ogni sua modifica.

  • kate-version [obbligatorio]: versione minima di KatePart richiesta.

  • functions [obbligatorio]: vettore JSON di comandi nello script.

  • actions [opzionale]: un vettore JSON di oggetti JSON che definiscono le azioni che appaiono nel menu dell'applicazione. Informazioni dettagliate sono fornite nella sezione Stabilire le scorciatoie.

Dal momento che il valore di functions è un vettore JSON, un singolo script può contenere un numero arbitrario di comandi per la riga di comando. Ciascuna funzione è disponibile attraverso il menu riga di comando integrata di KatePart.

Il codice sorgente dello script

Tutte le funzioni specificate nell'intestazione devono essere implementate nello script. Lo script nell'esempio qui sopra deve implementare le due funzioni sort e moveLinesDown. Tutte le funzioni hanno la sintassi seguente: 

// librerie katepart js necessarie, ad es. range.js se usi Range
require ("range.js");

function <nome>(argomento_1, argomento_2, ...)
{
    // ... implementazione, vedi anche: API per gli script
}

Gli argomenti nella riga di comando vengono passati alla funzione come argomento_1, argomento_2, ecc. Per poter documentare ogni comando, basta implementare la funzione help come segue: 

function help(comando)
{
    if (comando == "sort") {
        return i18n("Ordina il testo selezionato.");
    } else if (comando == "...") {
        // ...
    }
}

Eseguire quindi help sort nella riga di comando chiamerà questa funzione ausiliaria con l'argomento comando impostato al comando dato, cioè comando == "sort". KatePart presenterà quindi il testo risultante come documentazione per l'utente. Assicurati di tradurre le stringhe.

Lo sviluppo di uno script da riga di comando richiede il ricaricamento gli script stesso, per testare le modifiche. Invece di riavviare l'applicazione puoi però passare alla riga di comando, e digitare il comando reload-scripts.

Stabilire le scorciatoie

Per rendere gli script accessibili nel menu dell'applicazione e per potergli assegnare delle scorciatoie, gli script devono fornire un'appropriata intestazione. Nell'esempio sottostante entrambe le funzioni sort e moveLinesDown appaiono nel menu grazie alla seguente parte dell'intestazione dello script: 

var katescript = {
    ...
    "actions": [
        {   "function": "sort",
            "name": "Ordina il testo selezionato",
            "icon": "",
            "category": "Editing",
            "interactive": "false"
        },
        {   "function": "moveLinesDown",
            "name": "Sposta le righe in basso",
            "icon": "",
            "category": "Editing",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
};

I campi necessari sono i seguenti:

  • function [obbligatorio]: la funzione che dovrebbe comparire nel menu Strumenti → Script.

  • name [obbligatorio]: il testo che compare nel menu script.

  • icon [facoltativo]: l'icona che appare di fianco al testo nel menu. Qui si possono usare tutti i nomi delle icone di KDE.

  • category [facoltativo]: se si specifica una categoria, lo script compare in un sottomenu.

  • shortcut [facoltativo]: la scorciatoia qui data è la predefinita, per esempio Ctrl+Alt+t. Vedi la documentazione di Qt™ per maggiori dettagli.

  • interactive [facoltativo]: impostalo a true se allo script serve che l'utente faccia qualcosa.

Se sviluppi degli script utili, per piacere considera la possibilità di contribuire al progetto KatePart creando una richiesta di integrazione nel nostro progetto GitLab.

API per gli script

L'API per script qui presentata è disponibile in tutti gli script, cioè gli script di rientro e i comandi da riga di comando. Le classi Cursor e Range sono fornite dalle librerie presenti in $XDG_DATA_DIRS/katepart5/libraries. Se le vuoi usare nel tuo script, il che è necessario per usare alcune delle funzioni di Document o View, includi la libreria necessaria con: 

// librerie katepart js necessarie, ad es. range.js se usi Range
require ("range.js");

Per estendere l'API standard per gli script con funzioni e prototipi propri basta creare un nuovo file nella cartella di configurazione locale di KDE, $XDG_DATA_HOME/katepart5/libraries, e includerlo nel tuo script con: 

require ("nome_del_mio_script.js");

In Windows® questi file si trovano in %USERPROFILE%\AppData\Local\katepart5\libraries. %USERPROFILE% viene generalmente espanso in C:\\Utenti\\utente.

Per estendere i prototipi preesistenti, come Cursor o Range, il modo raccomandato di procedere non è di modificare i file *.js globali. Cambia piuttosto il prototipo Cursor in JavaScript dopo aver incluso cursor.js nello script con require.

Cursori e intervalli

Essendo KatePart un editor di testo, tutta l'API per gli script si basa, ovunque sia possibile, su cursori e intervalli. Un cursore (Cursor) è una semplice tupla del tipo (riga, colonna) che rappresenta una posizione nel testo del documento. Un intervallo (Range) si estende sul testo a partire da una posizione di partenza a una finale del cursore. L'API viene spiegata in dettaglio nelle sezioni seguenti.

Il prototipo dei cursori
Cursor();

Costruttore. Restituisce un cursore alla posizione (0, 0).

Esempio: var cursore = new Cursor(); 

Cursor(int riga, int colonna);

Costruttore. Restituisce un cursore alla posizione (riga, colonna).

Esempio: var cursore = new Cursor(3, 42); 

Cursor(Cursor altro);

Costruttore di copia. Restituisce una copia dell'altro cursore.

Esempio: var copia = new Cursor(altro); 

Cursor Cursor.clone();

Restituisce un clone del cursore.

Esempio: var clone = cursor.clone(); 

Cursor.setPosition(int riga, int colonna);

Imposta la posizione del cursore a riga e colonna.

Da: KDE 4.11 

bool Cursor.isValid();

Controlla se il cursore è valido. Non lo è se la riga o la colonna sono impostate a -1.

Esempio: var valido = cursor.isValid(); 

Cursor Cursor.invalid();

Restituisce un nuovo cursore non valido posizionato a (-1, -1).

Esempio: var cursoreNonValido = cursor.invalid(); 

int Cursor.compareTo(Cursor altro);

Confronta un cursore con un altro. Restituisce:

  • -1, se il cursore è posizionato prima dell'altro,

  • 0, se sono uguali, e

  • +1, se il cursore è posizionato dopo l'altro.

bool Cursor.equals(Cursor altro);

Restituisce true se il cursore e l'altro sono uguali, altrimenti false. 

String Cursor.toString();

Restituisce un cursore sotto forma di stringa nella forma «Cursor(riga, colonna)».

Il prototipo degli intervalli
Range();

Costruttore. Chiamare new Range() restituisce un intervallo tra (0, 0) e (0, 0). 

Range(Cursor inizio, Cursor fine);

Costruttore. Chiamare new Range(inizio, fine) restituisce l'intervallo (inizio, fine). 

Range(int riga_inizio, int colonna_inizio, int riga_fine, int colonna_fine);

Costruttore. Chiamare new Range(riga_inizio, colonna_inizio, riga_fine, colonna_fine) restituisce l'intervallo da (riga_inizio, colonna_inizio) a (riga_fine, colonna_fine). 

Range(Range altro);

Costruttore di copia. Restituisce una copia dell'altro intervallo. 

Range Range.clone();

Restituisce un clone dell'intervallo.

Esempio: var clone = range.clone(); 

bool Range.isEmpty();

Restituisce true se i cursori di inizio e fine sono uguali.

Esempio: var empty = range.isEmpty();

Da: KDE 4.11 

bool Range.isValid();

Restituisce true se entrambi i cursori, iniziale e finale, sono validi, altrimenti false.

Esempio: var valido = range.isValid(); 

Range Range.invalid();

Restituisce l'intervallo da (-1, -1) a (-1, -1). 

bool Range.contains(Cursor cursore);

Restituisce true se l'intervallo contiene la posizione del cursore, altrimenti false. 

bool Range.contains(Range altro);

Restituisce true se l'intervallo contiene l'altro, altrimenti false. 

bool Range.containsColumn(int colonna);

Restituisce true se la colonna è nell'intervallo semiaperto [inizio.colonna, fine.colonna), altrimenti false. 

bool Range.containsLine(int riga);

Restituisce true se la riga è nell'intervallo semiaperto [inizio.riga, fine.riga), altrimenti false. 

bool Range.overlaps(Range altro);

Restituisce true se l'intervallo e l'altro hanno una regione in comune, altrimenti false. 

bool Range.overlapsLine(int riga);

Restituisce true se la riga è nell'intervallo [inizio.riga, fine.riga], altrimenti false. 

bool Range.overlapsColumn(int colonna);

Restituisce true se la colonna è nell'intervallo [inizio.colonna, fine.colonna], altrimenti false. 

bool Range.onSingleLine();

Restituisce true se l'intervallo comincia e finisce sulla stessa riga, cioè se Range.start.line == Range.end.line.

Da: KDE 4.9 

bool Range.equals(Range altro);

Restituisce true se l'intervallo e l'altro sono uguali, altrimenti false. 

String Range.toString();

Restituisce un intervallo sotto forma di stringa nella forma «Range(Cursor(riga, colonna), Cursor(riga, colonna))».

Funzioni globali

Questa sezione elenca tutte le funzioni globali.

Leggere e includere file
String read(String file);

Cercherà nel file dato, relativamente alla cartella katepart5/script/files, e ne restituirà i contenuti in forma di stringa. 

void require(String file);

Cercherà nel file dato, relativamente alla katepart5/script/libraries, e lo valuterà. require è già programmato per evitare inclusioni multiple dello stesso file.

Da: KDE 4.10

Debug
void debug(String testo);

Stampa il testo su stdout nella console che ha avviato l'applicazione.

Traduzione

Per supportare una localizzazione completa ci sono diverse funzioni per tradurre le stringhe negli script, cioè i18n, i18nc, i18np e i18ncp. Queste funzioni si comportano esattamente come le funzioni di traduzione di KDE.

Le funzioni traducono le stringhe incluse con il sistema di traduzione di KDE nella lingua usata nell'applicazione. Le stringhe negli script sviluppati nel codice sorgente ufficiale di KatePart sono automaticamente estratte e traducibili: in altre parole gli sviluppatori di KatePart non devono preoccuparsi di estrarre e tradurre i messaggi. Va anche notato, però, che la traduzione funziona solo all'interno dell'infrastruttura di KDE: cioè nuove stringhe negli script di terze parti sviluppati al di fuori di KDE non sarebbero tradotte. Tuttavia prendi in considerazione l'idea di contribuire con i tuoi script a Kate, in modo che sia possibile una traduzione appropriata. 

void i18n(String testo, argomento_1, ... );

Traduce testo nella lingua usata dall'applicazione. Gli argomenti argomento_1 e seguenti sono facoltativi e vengono usati per sostituire i segnaposti %1, %2, ecc..

void i18nc(String contesto, String testo, argomento_1, ... );

Traduce testo nella lingua usata dall'applicazione. Inoltre, la stringa contesto viene resa visibile ai traduttori, per chiarire eventuali equivoci e produrre una traduzione migliore. Gli argomenti argomento_1 e seguenti sono facoltativi, e vengono usati per sostituire i segnaposti %1, %2 ecc..

void i18np(String singolare, String plurale, int numero, argomento_1, ... );

Traduce singolare o plurale nella lingua usata dall'applicazione, a seconda del numero dato. Gli argomenti argomento_1 e seguenti sono facoltativi, e vengono usati per sostituire i segnaposti %1, %2 ecc..

void i18ncp(String contesto, String singolare, String plurale, int numero, argomento_1, ... );

Traduce singolare o plurale nella lingua usata dall'applicazione, a seconda del numero dato. Inoltre la stringa contesto viene resa visibile ai traduttori, per chiarire eventuali equivoci e produrre una traduzione migliore. Gli argomenti argomento_1 e seguenti sono facoltativi, e vengono usati per sostituire i segnaposti %1, %2 ecc..

API della vista

Ogni volta che uno script viene eseguito è presente una variabile globale, «view», che rappresenta la vista attiva dell'editor. Segue un elenco di tutte le funzioni di vista disponibili. 

void view.copy()

Taglia la selezione, se ce n'è una, altrimenti l'intera riga se è stata spuntata l'opzione [ ] Copia o taglia la riga attuale se non c'è una selezione.

Da: KDE Frameworks™ 5.79

void view.cut()

Taglia la selezione, se ce n'è una, altrimenti l'intera riga se è stata spuntata l'opzione [ ] Copia o taglia la riga attuale se non c'è una selezione.

Da: KDE Frameworks™ 5.79

void view.paste()

Incolla il contenuto degli appunti.

Da: KDE Frameworks™ 5.79

Cursor view.cursorPosition()

Restituisce la posizione attuale del cursore nella vista.

void view.setCursorPosition(int riga, int colonna);
void view.setCursorPosition(Cursor cursore);

Imposta la posizione attuale del cursore a (riga, colonna) o al cursore dato. 

Cursor view.virtualCursorPosition();

Restituisce la posizione virtuale del cursore con ogni tabulazione che conta una quantità di spazi dipendente dall'attuale ampiezza di tabulazione. 

void view.setVirtualCursorPosition(int riga, int colonna);
void view.setVirtualCursorPosition(Cursor cursore);

Imposta la posizione virtuale attuale del cursore a (riga, colonna) o al cursore dato. 

String view.selectedText();

Restituisce il testo selezionato. Se non c'è del testo selezionato, la stringa restituita è vuota. 

bool view.hasSelection();

Restituisce true se la vista contiene del testo selezionato, altrimenti false. 

Range view.selection();

Restituisce l'intervallo di testo selezionato. L'intervallo di testo non è valido se non c'è testo selezionato. 

void view.setSelection(Range intervallo);

Imposta il testo selezionato all'intervallo dato. 

void view.removeSelectedText();

Rimuove il testo selezionato. Se la vista non ne ha non fa nulla. 

void view.selectAll();

Seleziona tutto il testo del documento. 

void view.clearSelection();

Pulisce la selezione di testo senza rimuoverlo. 

void view.setBlockSelection(bool on);

Attiva o disattiva la modalità di selezione a blocchi. 

bool view.blockSelection();

Restituisce true se la modalità di selezione a blocchi è attivata, altrimenti false. 

void view.align(Range intervallo);

Fa rientrare nuovamente le righe che si trovano nell'intervallo in base alle impostazioni di rientro correnti. 

void view.alignOn(Range intervallo, String modello = "");

Allinea le righe in intervallo alla colonna data dall'espressione regolare modello. Con un modello vuoto, per impostazione predefinita allineerà al primo carattere non di spazio. Se il modello ha una cattura, rientrerà

Esempi:

view.alignOn(document.documentRange(), '-'); inserirà degli spazi prima del primo - di ogni riga per allinearle nella stessa colonna.

view.alignOn(document.documentRange(), ':\\s+(.)'); inserirà degli spazi prima del primo carattere non di spazio che ricorre dopo i due punti per allinearle nella stessa colonna.

object view.executeCommand(String comando,
                           String argomenti,
                            intervallo);

Esegue il comando per la riga di comando comando con gli argomenti opzionali argomenti e con l'opzionale intervallo. L'oggetto restituito ha la proprietà booleana oggetto.ok, che indica che l'esecuzione del comando ha avuto successo. In caso di errori, la stringa oggetto.status contiene un messaggio di errore.

Da: KDE Frameworks™ 5.50

Range view.searchText(Range intervallo,
                      String modello,
                      bool backwards = false);

Cerca la prima occorrenza di modello in intervallo e restituisce l'intervallo corrispondente. La ricerca viene eseguita all'indietro se il parametro booleano backwards è impostato a true.

L'intervallo restituito non è valido (vedi Range.isValid()) se modello non viene trovato in intervallo.

Da: KDE Frameworks™ 5.97

API del documento

Ogni volta che uno script viene eseguito è presente una variabile globale, «document», che rappresenta il documento attivo. Segue un elenco di tutte le funzioni del documento disponibili. 

String document.fileName();

Restituisce il nome del file del documento o una stringa vuota per i documenti non salvati. 

String document.url();

Restituisce l'URL completo del documento, o una stringa vuota per i documenti non salvati. 

String document.mimeType();

Restituisce il tipo di file MIME del documento, o il tipo MIME del file application/octet-stream se non se ne può trovare uno appropriato. 

String document.encoding();

Restituisce la codifica attualmente usata per salvare il file. 

String document.highlightingMode();

Restituisce la modalità di evidenziazione globale usata per tutto il documento. 

String document.highlightingModeAt(Cursor posizione);

Restituisce la modalità di evidenziazione usata alla posizione nel documento. 

Array document.embeddedHighlightingModes();

Restituisce un array di modalità di evidenziazione incorporate in questo documento. 

bool document.isModified();

Restituisce true se il documento ha modifiche non salvate, altrimenti false. 

String document.text();

Restituisce tutto il contenuto del documento in una sola stringa di testo. I ritorni a capo sono indicati con il carattere «\n». 

String document.text(int da_riga, int da_colonna, int a_riga, int a_colonna);
String document.text(Cursor da, Cursor a);
String document.text(Range intervallo);

Restituisce il testo nell'intervallo dato. Per migliorare la leggibilità del codice si raccomanda di usare le versioni con cursori o intervalli. 

String document.line(int riga);

Restituisce la riga di testo richiesta come stringa. La stringa è vuota se la riga richiesta è oltre i limiti. 

String document.wordAt(int riga, int colonna);
String document.wordAt(Cursor cursore);

Restituisce la parola alla posizione del cursore data. 

Range document.wordRangeAt(int riga, int colonna);
Range document.wordRangeAt(Cursor cursore);

Restituisce l'intervallo di una parola alla posizione del cursore data. L'intervallo restituito non è valido (vedi Range.isValid()) se la posizione è oltre la fine di una riga. Se non c'è una parola alla fine del cursore viene restituito un intervallo vuoto.

Da: KDE 4.9 

String document.charAt(int riga, int colonna);
String document.charAt(Cursor cursore);

Restituisce il carattere alla posizione del cursore data. 

String document.firstChar(int riga);

Restituisce il primo carattere nella riga data che non sia uno spazio. Il primo carattere è alla colonna 0. Se la riga è vuota o contiene solo spazi la stringa restituita è vuota. 

String document.lastChar(int riga);

Restituisce l'ultimo carattere nella riga data che non sia uno spazio. Se la riga è vuota o contiene solo spazi la stringa restituita è vuota. 

bool document.isSpace(int riga, int colonna);
bool document.isSpace(Cursor cursore);

Restituisce true se il carattere alla posizione del cursore data è uno spazio, altrimenti false. 

bool document.matchesAt(int riga, int colonna, String testo);
bool document.matchesAt(Cursor cursore, String testo);

Restituisce true se il testo corrisponde a quello presente alla posizione del cursore, altrimenti false. 

bool document.startsWith(int riga, String testo, bool salta_spazi);

Restituisce true se la riga comincia con il testo, altrimenti false. L'argomento salta_spazi decide se gli spazi iniziali vanno ignorati. 

bool document.endsWith(int riga, String testo, bool salta_spazi);

Restituisce true se la riga finisce con il testo, altrimenti false. L'argomento salta_spazi decide se gli spazi finali vanno ignorati. 

bool document.setText(String testo);

Imposta tutto il testo del documento. 

bool document.clear();

Rimuove tutto il testo del documento. 

bool document.truncate(int riga, int colonna);
bool document.truncate(Cursor cursore);

Tronca la riga alla colonna. Restituisce true se funziona, o false se la riga non fa parte dell'intervallo del documento. 

bool document.insertText(int riga, int colonna, String testo);
bool document.insertText(Cursor cursore, String testo);

Inserisce il testo alla posizione del cursore data. Restituisce true se funziona, o false se il documento è in modalità a sola lettura. 

bool document.removeText(int da_riga, int da_colonna, int a_riga, int a_colonna);
bool document.removeText(Cursor da, Cursor a);
bool document.removeText(Range intervallo);

Rimuove il testo nell'intervallo dato. Restituisce true se funziona, o false se il documento è in modalità di sola lettura. 

bool document.insertLine(int riga, String testo);

Inserisce il testo nella riga data. Restituisce true se funziona, o false se il documento è in modalità di sola lettura oppure la riga non è nell'intervallo del documento. 

bool document.removeLine(int riga);

Rimuove la riga di testo data. Restituisce true se funziona, o false se il documento è in modalità di sola lettura oppure la riga non è nell'intervallo del documento. 

bool document.wrapLine(int riga, int colonna);
bool document.wrapLine(Cursor cursore);

Manda a capo la riga alla posizione del cursore data. Restituisce true se funziona, altrimenti false, ad es. se la riga < 0.

Da: KDE 4.9 

void document.joinLines(int riga_inizio, int riga_fine);

Unisce le righe da riga_inizio a riga_fine. Due righe di testo consecutive sono sempre separate da un solo spazio. 

int document.lines();

Restituisce il numero di righe nel documento. 

bool document.isLineModified(int riga);

Restituisce true se la riga attuale contiene dati non salvati.

Da: KDE 5.0 

bool document.isLineSaved(int riga);

Restituisce true se la riga è cambiata ma il documento è stato salvato, e quindi la riga corrente non contiene dati non salvati.

Da: KDE 5.0 

bool document.isLineTouched(int riga);

Restituisce true se la riga contiene dati non salvati o è stata cambiata in precedenza.

Da: KDE 5.0 

bool document.findTouchedLine(int startLine, bool giù);

Cerca la successiva riga modificata, a partire da riga. La ricerca è eseguita verso l'alto o verso il basso, a seconda della direzione specificata in giù.

Da: KDE 5.0 

int document.length();

Restituisce il numero di caratteri nel documento. 

int document.lineLength(int riga);

Restituisce la lunghezza della riga. 

void document.editBegin();

Avvia un gruppo di modifica per un raggruppamento di azioni annullabili. Assicurati di chiamare sempre editEnd() con la stessa frequenza di editBegin(). Chiamando editBegin viene usato internamente un contatore di riferimenti, cioè, questa chiamata può essere annidata. 

void document.editEnd();

Chiude un gruppo di modifica. L'ultima chiamata di editEnd() (cioè quella corrispondente alla prima chiamata a editBegin()) conclude il passo di modifica. 

int document.firstColumn(int riga);

Restituisce la prima colonna non di spazi nella riga. Se nella riga ci sono solo spazi, viene restituito -1. 

int document.lastColumn(int riga);

Restituisce l'ultima colonna non di spazi nella riga. Se nella riga ci sono solo spazi, viene restituito -1. 

int document.prevNonSpaceColumn(int riga, int colonna);
int document.prevNonSpaceColumn(Cursor cursore);

Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data, cercando indietro. 

int document.nextNonSpaceColumn(int riga, int colonna);
int document.nextNonSpaceColumn(Cursor cursore);

Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data, cercando in avanti. 

int document.prevNonEmptyLine(int riga);

Restituisce la prossima riga non vuota con caratteri non di spaziatura, cercando indietro. 

int document.nextNonEmptyLine(int riga);

Restituisce la prossima riga non vuota con caratteri non di spaziatura, cercando in avanti. 

bool document.isInWord(String carattere, int attributo);

Restituisce true se il carattere con l'attributo può far parte di una parola, altrimenti false. 

bool document.canBreakAt(String carattere, int attributo);

Restituisce true se il carattere con l'attributo può essere mandato a capo, altrimenti false. 

bool document.canComment(int attributo_inizio, int attributo_fine);

Restituisce true se un intervallo che inizia e finisce con gli attributi dati può essere fatto diventare un commento, altrimenti false. 

String document.commentMarker(int attributo);

Restituisce l'indicatore di commento per i commenti di una sola riga per un attributo. 

String document.commentStart(int attributo);

Restituisce l'indicatore di commento per l'inizio di commenti multi-riga per un attributo. 

String document.commentEnd(int attributo);

Restituisce l'indicatore di commento per la fine di commenti multi-riga per un attributo. 

Range document.documentRange();

Restituisce un intervallo che comprende tutto il documento. 

Cursor documentEnd();

Restituisce un cursore posizionato nell'ultima colonna dell'ultima riga del documento. 

bool isValidTextPosition(int riga, int colonna);
bool isValidTextPosition(Cursor cursore);

Restituisce true se la posizione del cursore ricade in una posizione di testo valida, cioè se è localizzata all'inizio, nel mezzo o alla fine di una riga valida. Una posizione di testo non è valida se si trova in un surrogato Unicode.

Da: KDE 5.0 

int document.attribute(int riga, int colonna);
int document.attribute(Cursor cursore);

Restituisce l'attributo alla posizione del cursore data. 

bool document.isAttribute(int riga, int colonna, int attributo);
bool document.isAttribute(Cursor cursore, int attributo);

Restituisce true se l'attributo alla posizione del cursore data è uguale a attributo, altrimenti false. 

String document.attributeName(int riga, int colonna);
String document.attributeName(Cursor cursore);

Restituisce il nome dell'attributo in testo leggibile. È uguale al nome itemData nei file di evidenziazione della sintassi. 

bool document.isAttributeName(int riga, int colonna, String nome);
bool document.isAttributeName(Cursor cursore, String nome);

Restituisce true se il nome dell'attributo a una certa posizione del cursore corrisponde al nome, altrimenti false. 

String document.variable(String chiave);

Restituisce il valore della variabile del documento chiave. Se la variabile non esiste il valore restituito è una stringa vuota. 

void document.setVariable(String chiave, String valore);

Imposta il valore della variabile del documento richiesta chiave.

Vedi anche: le variabili nei documenti di Kate.

Da: KDE 4.8 

int document.firstVirtualColumn(int riga);

Restituisce la colonna virtuale del primo carattere non di spaziatura nella riga indicata, o -1 se la riga è vuota oppure contiene solo caratteri di spaziatura. 

int document.lastVirtualColumn(int riga);

Restituisce la colonna virtuale dell'ultimo carattere non di spaziatura nella riga indicata, o -1 se la riga è vuota oppure contiene solo caratteri di spaziatura. 

int document.toVirtualColumn(int riga, int colonna);
int document.toVirtualColumn(Cursor cursore);
Cursor document.toVirtualCursor(Cursor cursore);

Converte la posizione «reale» del cursore in una virtuale, restituendo un oggetto int o Cursor. 

int document.fromVirtualColumn(int riga, int colonna_virtuale);
int document.fromVirtualColumn(Cursor cursore_virtuale);
Cursor document.fromVirtualCursor(Cursor cursore_virtuale);

Converte la posizione virtuale data del cursore in una «reale», restituendo un oggetto int o Cursor. 

Cursor document.anchor(int riga, int colonna, Char carattere);
Cursor document.anchor(Cursor cursore, Char carattere);

Cerca indietro il carattere partendo dal cursore dato. Per esempio, se si passa «(» come carattere, la funzione restituirà la posizione dell'apertura «(». Questo conteggio dei riferimenti, cioè altri «(...)», vengono ignorati. 

Cursor document.rfind(int riga, int colonna, String testo, int attributo = -1);
Cursor document.rfind(Cursor cursore, String testo, int attributo = -1);

Cerca all'indietro il testo con l'attributo appropriato. L'attributo viene ignorato se è impostato a -1. Il cursore restituito non è valido se non si trova il testo. 

int document.defStyleNum(int riga, int colonna);
int document.defStyleNum(Cursor cursore);

Restituisce lo stile predefinito usato alla posizione data del cursore. 

bool document.isCode(int riga, int colonna);
bool document.isCode(Cursor cursore);

Restituisce true se l'attributo alla posizione data del cursore non è uguale a tutti i seguenti stili: dsComment, dsString, dsRegionMarker, dsChar, dsOthers. 

bool document.isComment(int riga, int colonna);
bool document.isComment(Cursor cursore);

Restituisce true se l'attributo del carattere alla posizione del cursore data è dsComment, altrimenti false. 

bool document.isString(int riga, int colonna);
bool document.isString(Cursor cursore);

Restituisce true se l'attributo del carattere alla posizione del cursore data è dsString, altrimenti false. 

bool document.isRegionMarker(int riga, int colonna);
bool document.isRegionMarker(Cursor cursore);

Restituisce true se l'attributo del carattere alla posizione del cursore data è dsRegionMarker, altrimenti false. 

bool document.isChar(int riga, int colonna);
bool document.isChar(Cursor cursore);

Restituisce true se l'attributo del carattere alla posizione del cursore data è dsChar, altrimenti false. 

bool document.isOthers(int riga, int colonna);
bool document.isOthers(Cursor cursore);

Restituisce true se l'attributo del carattere alla posizione del cursore data è dsOthers, altrimenti false. 

void document.indent(Range intervallo, int modifica);

Fa rientrare tutte le righe nell'intervallo con la modifica delle schede o del numero delle volte degli spazi tabSize, a seconda delle preferenze dell'utente. Il parametro di modifica può essere negativo.

L'API dell'editor

Oltre alle API per documento e vista c'è un'API generale per editor, che fornisce delle funzioni per le funzionalità di script generali per editor. 

String editor.clipboardText();

Restituisce il testo che c'è attualmente negli appunti globali.

Da: KDE Frameworks™ 5.50

String editor.clipboardHistory();

L'editor mantiene una cronologia degli appunti che contiene fino a 10 voci di appunti. Questa funzione restituisce tutte le voci che ci sono attualmente nella cronologia degli appunti.

Da: KDE Frameworks™ 5.50

void editor.setClipboardText(String testo);

Imposta il contenuto degli appunti a testo. il testo sarà aggiunto alla cronologia degli appunti.

Da: KDE Frameworks™ 5.50