# Scripting

## Scripting in &kile; gebruiken

De scripting functie van &kile; staat het uitvoeren van code volgens ECMAScript toe, beter bekend als &javascript;. U zult heel wat inleidingen vinden, die informatie bieden over objects (variabelen), functies en eigenschappen ondersteund door &javascript;.

Ondersteuning kan ingeschakeld worden in de instellingendialoog van &kile;: Instellingen Kile instellen... Kile Scripting. Ondersteuning voor scripting inschakelen Ondersteuning voor scripting inschakelen

Als scripting is ingeschakeld zal een extra paneel voor scripting zichtbaar worden in de zijbalk, waar scripts beheerd kunnen worden: Paneel voor scripting in de zijbalk Paneel voor scripting in de zijbalk

Dit widget bevat zes pictogrammen, die verschillende taken bieden:

- Het geselecteerd script uitvoeren.

- Een nieuw script aanmaken.

- Het geselecteerd script in de editor openen.

- Stel toetsenreeks in voor het geselecteerde script.

- Verwijder een toegekende toetsenreeks.

- Ververs de lijst met beschikbare scripts, die allemaal zijn gevonden in `$`KDEDIR`/share/apps/kile/scripts/`.

## Een script uitvoeren

U kunt een script op drie verschillende manieren uitvoeren:

1. Selecteer het gewenste script en klik op de knop Uitvoeren aan de linker kant van het widget voor beheer van scripts.

   Scripting: knop Uitvoeren Scripting: knop Uitvoeren

2. Een sneltoets gebruiken.

   Scripting: sneltoets Scripting: sneltoets

   U kunt een sneltoets aan een script toekennen met de knop Instellen in het widget voor beheer van scripts.

   Scripting: stel dialoog voor toetsenreeks in Scripting: stel dialoog voor toetsenreeks in

3. Een toetsenreeks voor de bewerker gebruiken. Het script zal uitgevoerd worden als u de toegekende toetsenreeks in de bewerker intypt.

   Scripting: toetsenreeks voor de bewerker Scripting: toetsenreeks voor de bewerker

   Deze methode kan uitgebreid worden tot een tamelijk geavanceerde soort van aanvullen van code. Nemen we aan dat u een script hebt geschreven, die eenvoudig het &latex;-commando `\textbf{}` in het huidige document invoegt.

       document.insertText("\\textbf{%C}");

   Als u nu de toegekende toetsenreeks `bfx` in uw tekstdocument intypt, dan zal deze toetsenreeks verwijderd worden en zal het script worden uitgevoerd. Het zal `\textbf{}` invoegen en de cursor zal tussen de accolades worden geplaatst.

   Scripting: intypen van een sneltoetsvoor de bewerker Scripting: intypen van een sneltoetsvoor de bewerker

   Wat een comfortabele en krachtige methode van aanvullen van code.

## API-referentie

De hier gepresenteerde API voor scripts is beschikbaar in alle scripts. Voordat de inhoud van een script wordt geladen zal &kile; eerst verschillende prototypen en functies aan de context van het script toevoegen. Deze API voor het gemak bevat prototypes zoals tekstcursors en tekstreeksen en is gelokaliseerd in de map `KILE_APP_DIR/script-plugins/`.

De scripts van &kile; verschillen enigszins van scripts van &kate;, die een ander ontwerp gebruiken, omdat ze ook vanaf de opdrachtregel gestart kunnen worden. Maar alle functies van de API voor scripts van &kate; zijn ook beschikbaar in de API voor scripts van &kile;, dus porteren van &javascript;-code van &kate; naar &kile; zou erg gemakkelijk moeten zijn. Maar omdat &kile; een erg rijk van functies voorziene &latex;-bewerker is, biedt zijn eigen API voor scripts veel meer mogelijkheden dan die van &kate;.

Opmerking: Beschrijvingen van API aanroepen, die ook beschikbaar zijn in de scripts van &kate;, zijn overgenomen uit de documentatie van &kate;.

### Globale functies

Deze sectie geeft een lijst met globale functies.

    void debug(String tekst);

- Stuurt `tekst` naar `stdout` in de console. De gestuurde tekst is gekleurd om het te onderscheiden van andere debuguitvoer.

### Het prototype van cursor

Omdat &kile; een tekstbewerker is, is, waar mogelijk, alles van de scripting-API gebaseerd op cursors en reeksen. Een cursor is een eenvoudig paar `(regel, kolom)` die een tekstpositie in het document representeert.

    Cursor();

- Constructor: levert een cursor terug op positie `(0, 0)`.

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

    Cursor(int regel, int kolom);

- Constructor: levert een cursor terug op positie (regel, kolom).

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

    Cursor(Cursor andere);

- Constructor kopiëren: geeft een kopie van de cursor `andere` terug.

  Voorbeeld: `var copy = new Cursor(andere);`

    Cursor Cursor.clone();

- Geeft een kloon van de cursor terug.

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

    bool Cursor.isValid();

- Controleert of de cursor geldig is. De cursor is ongeldig indien lijn en/of kolom ingesteld zijn op `-1`.

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

    Cursor Cursor.invalid();

- Geeft een nieuwe ongeldige cursor op locatie `(-1, -1)`.

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

    int Cursor.compareTo(Cursor andere);

- Vergelijkt deze cursor met de cursor `andere`. Geeft terug

  - `-1`, indien deze cursor zich bevindt voor de cursor `andere`,

  - `0`, indien beide cursors gelijk zijn

  - `+1`, als deze cursor gelokaliseerd is na de cursor `andere`.

    bool Cursor.equals(Cursor andere);

- Geeft `true` terug, als deze cursor en de cursor `andere` gelijk zijn, anders `false`.

    String Cursor.toString();

- Geeft de cursor terug als een tekenreeks met de vorm `Cursor(regel, kolom)`.

### Het prototype Bereik

Omdat &kile; een tekstbewerker is, is, waar mogelijk, alles van de scripting-API gebaseerd op cursors en reeksen. Omdat Cursor een eenvoudig paar `(regel, kolom)` is, die een tekstpositie in het document representeert, omspant een Bereik tekst vanaf een beginpositie van de cursor tot een eindpositie.

    Range();

- Constructor: Aanroepen van `new Range()` geeft een Bereik op `(0, 0) - (0, 0)` terug.

    Range(Cursor begin, Cursor eind);

- Constructor: Aanroepen van `new Range(`begin`, `eind`)` geeft het bereik terug van de `begin`-cursor naar de `eind`-cursor.

    Range(int beginRegel, int beginKolom, int eindRegel, int eindKolom);

- Constructor: Aanroepen van `new Range(`beginRegel`, `beginKolom`, `eindeRegel`, `eindKolom`)` geeft het Bereik van (`beginRegel`, `beginKolom`) tot (`eindRegel`, `eindKolom`).

    Range(Range andere);

- Constructor kopiëren. Geeft een kopie terug van Bereik `andere`.

    Reeks Range.clone();

- Geeft een kloon van de reeks terug.

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

    bool Range.isValid();

- Geeft `true` terug, als zowel begin als einde cursor geldig zijn, anders `false`.

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

    bool Range.invalid();

- Geeft het Bereik van (-1,-1) tot (-1,-1) terug.

    bool Range.contains(Cursor cursor);

- Geeft `true` terug, als dit bereik de cursorpositie bevat, anders `false`.

    bool Range.contains(Range andere);

- Geeft `true` terug, als dit bereik het Bereik `andere` bevat, anders `false`.

    bool Range.containsColumn(int kolom);

- Geeft `true` terug, als `kolom` zich in het half open interval `[start.column, end.column]` bevindt, anders `false`.

    bool Range.containsLine(int regel);

- Geeft `true` terug, als `regel` zich in het half open interval `[start.line, end.line]` bevindt, anders `false`.

    bool Range.overlaps(Range overig);

- Geeft `true` terug, als dit bereik en het Bereik `overig` een gebied delen, anders `false`.

    bool Range.overlapsLine(int regel);

- Geeft `true` terug, als `regel` zich in het interval `[start.line, end.line)` bevindt, anders `false`.

    bool Range.overlapsColumn(int kolom);

- Geeft `true` terug, als `kolom` zich in het interval `[start.column, end.column)` bevindt, anders `false`.

    bool Range.equals(Range overig);

- Geeft `true` terug, als dit bereik en het Bereik `andere` gelijk zijn, anders `false`.

    String Range.toString();

- Geeft het bereik terug als een tekenreeks van de vorm `Range(Cursor(regel, kolom) - Cursor(regel,kolom))`.

### De API voor weergave

Wanneer een script wordt uitgevoerd, dan is er een globaal object (variabele) `view` die de huidige actieve editor-view representeert. Alle functies van `view` werken met de cursorposities of de geselecteerde tekst. Het volgende is een lijst met alle beschikbare `view`-functies.

    void view.backspace();

- Voert programmatisch het equivalent van het indrukken van de backspace-toets.

    Cursor view.cursorPosition();

- Geeft de huidige cursorpositie in het beeld terug.

    void view.setCursorPosition(int lijn, int kolom);
    void view.setCursorPosition(Cursor cursor);

- Stelt de huidige cursorpositie in op ofwel`lijn`, `kolom` of op de gegeven `cursor`.

    void view.cursorLeft();

- Verplaatst de cursor één positie achterwaarts in de tekst.

    void view.cursorRight();

- Verplaatst de cursor één positie voorwaarts in de tekst.

    void view.cursorUp();

- Verplaatst de cursor één regel omhoog in het document.

    void view.cursorDown();

- Verplaatst de cursor één regel omlaag in het document.

    int view.cursorLine();

- Geeft de regel terug waar de cursor zich op dat moment bevindt.

    int view.cursorColumn();

- Geeft de kolom terug waar de cursor zich op dat moment bevindt.

    void view.setCursorLine(int regel);

- Stelt de cursor-regel in op de gegeven `regel`.

    void view.setCursorColumn(int kolom);

- Stelt de cursor-kolom in op de gegeven `kolom`.

    Cursor view.virtualCursorPosition();

- Haalt de huidige virtuele cursor-positie op. Virtual betekent dat het tabulatorteken (TAB) meerdere tekens telt, zoals ingesteld door de gebruiker (bijv. één TAB is 8 spaties). De virtuele cursor-positie levert toegang tot de voor de gebruiker zichtbare waarden van de huidige cursor-positie.

    bool view.hasSelection();

- Geeft `true` terug, als het beeld geselecteerde tekst heeft, anders `false`.

    String view.selectedText();

- Geeft de geselecteerde tekst terug. Als er geen tekst is geselecteerd dan is de tekenreeks leeg.

    Range view.selectionRange();

- Geeft de geselecteerde tekstreeks terug. Als er geen tekst is geselecteerd dan is het teruggegeven bereik ongeldig.

    void view.setSelection(Range reeks);

- Stelt de geselecteerde tekst in op de gegeven `reeks`.

    void view.selectAll();

- Selecteert de gehele tekst in het document.

    void view.clearSelection();

- Wist de tekstselectie zonder de tekst te verwijderen.

    void view.removeSelectedText();

- Verwijder de geselecteerde tekst. Als het beeld geen geselecteerde tekst bevat, dan doet dit niets.

    void view.selectLine();

- Selecteert de tekst in de huidige regel.

    void view.selectLine(int regel);

- Selecteert de tekst in de huidige `regel`.

    void view.selectLines(int van, int tot);

- Selecteert de gehele tekst van regel `vanaf` tot regel `tot`.

    void view.selectWord();

- Selecteert het huidige woord. Als er geen woord is gevonden op de huidige cursorpositie, dan gebeurt er niets.

    void view.selectLatexCommand();

- Selecteert het huidige &latex;-commando. Als er geen commando is gevonden op de huidige cursorpositie, dan gebeurt er niets.

    void view.selectEnvironment(bool inside = false);

- Selecteert de gehele tekst van de huidige &latex;-omgeving. Als `inside` de waarde `false` krijgt zal de omgevingstekst inclusief de omgevende &latex;-tags `\begin{...}...\end{...}` worden geselecteerd, anders zonder deze tags. Als er geen parameter is gegeven, krijgt `inside` de waarde `false`.

    void view.selectTexgroup(bool inside = true);

- Selecteert de tekst van de huidige &latex;-groep. Als `inside` de waarde `true` krijgt, zal alleen de tekstgroep zonder de omgevende accolades geselecteerd worden. Als geen parameter is gegeven, krijgt `inside` de waarde `true`.

    void view.selectMathgroup();

- Selecteert de tekst van de huidige math-groep.

    void view.selectParagraph(bool wholeLines = true);

- Selecteert de gehele tekst van de huidige &latex;-paragraaf. Als `wholeLines` de waarde `true` heeft zullen de eerste en laatste regels van de paragraaf geheel meegenomen worden in de selectie (inclusief het einde-regel-teken); anders zal de selectie alleen niet-witruimte tekens bevatten.

### De API van Document

Wanneer een script wordt uitgevoerd is er een globaal object (variabele) `document` die het huidige actieve document representeert. Het volgende is een lijst van alle beschikbare `document`-functies.

    void document.insertText(String tekst);

- Voegt de `tekst` in op de huidige cursorpositie.

    void document.insertText(int regel, int kolom, String tekst);
    bool document.insertText(Cursor cursor, String tekst);

- Voegt de `tekst` in op de gegeven cursorpositie.

    bool document.removeText(int vanafRegel, int vanafKolom, int totRegel, int totKolom);
    bool document.removeText(Cursor vanaf, Cursor tot);
    bool document.removeText(Range reeks);

- Verwijdert de tekst in het gegeven bereik. Geeft `true` terug bij succes of `false`, als het document alleen-lezen is.

    bool document.replaceText(Range reeks, String tekst);

- Vervangt de tekst van de gegeven reeks door de gespecificeerde tekst.

    int document.lines();

- Geeft het aantal regels in het document terug.

    int document.length();

- Geeft het aantal tekens in het document terug.

    Range document.documentRange();

- Geeft een reeks terug die het gehele document omvat.

    Cursor document.documentEnd();

- Geeft de huidige cursorpositie in het beeld terug.

    String document.text();

- Geef de gehele inhoud van het document terug in een enkele tekenreeks. Nieuwe regels zijn gemarkeerd met het teken nieuw-regel `\n`.

    String document.text(int vanafRegel, int vanafKolom, int totRegel, int totKolom);
    String document.text(Cursor vanaf, Cursor tot);
    String document.text(Range reeks);

- Geeft de tekst terug in het gegeven bereik. Het is aanbevolen de cursor te gebruiken en een versie gebaseerd op bereik voor betere leesbaarheid van de broncode.

    bool document.setText(String tekst);

- Stelt de gehele documenttekst in.

    bool document.clear();

- Verwijdert de gehele tekst uit het document.

    String document.line();

- Geeft de huidige tekstregel terug als tekenreeks.

    String document.line(int regel);

- Geeft de gegeven tekstregel terug als tekenreeks. De tekenreeks is leeg als de gevraagde regel buiten het bereik ligt.

    int document.lineLength();

- Geeft de lengte van de huidige regel terug.

    int document.lineLength(int regel);

- Geeft de lengte van de `regel` terug.

    bool document.insertLine(String s);

- Voegt tekst toe in de huidige regel. Geeft `true` terug bij success of `false`, als het document alleen-lezen is of de regel bevindt zich niet in de het documentbereik.

    bool document.insertLine(int regel, String s);

- Voegt tekst in de gegeven regel in. Geeft `true` terug bij succes of `false`, als het document alleen-lezen is of de regel niet in het documentbereik ligt.

    bool document.removeLine();

- Verwijdert de huidige tekstregel. Geeft `true` terug bij succes of `false`, als het document alleen-lezen is.

    bool document.removeLine(int regel);

- Verwijdert de gegeven tekstregel. Geeft `true` terug bij succes of `false`, als het document alleen-lezen is of de regel niet in het documentbereik ligt.

    bool document.replaceLine(String tekst);

- Vervang de tekst van de huidige regel door de gespecificeerde tekst.

    bool document.replaceLine(int regel, String tekst);

- Vervangt de tekst van de gegeven regel door de gespecificeerde tekst.

    bool document.truncateLine();

- Kap de huidige regel op de gegeven kolom of cursorpositie af. Geeft `true` terug bij succes of `false` als de gegeven regel geen deel is van het documentbereik.

    bool document.truncate(int regel, int kolom);
    bool document.truncate(Cursor cursor);

- Kap de gegeven regel op de gegeven kolom of cursorpositie af. Geeft `true` terug bij succes of `false` als de gegeven regel geen deel is van het documentbereik.

    String document.word();

- Geeft het woord terug op de huidige cursorpositie. Als er geen woord op deze cursorpositie wordt gevonden, dan is de teruggegeven tekenreeks leeg.

    String document.wordAt(int regel, int kolom);
    String document.wordAt(Cursor cursor);

- Geeft het woord terug op de gegeven cursorpositie. Als er geen woord op deze cursorpositie wordt gevonden, dan is de teruggegeven tekenreeks leeg.

    Range document.wordRange();

- Geeft het bereik van het woord terug op de gegeven cursorpositie. Als geen woord is gevonden wordt `Range.invalid()` teruggegeven, die getest kan worden met `Range.isValid()`.

    String document.latexCommand();

- Geeft het &latex;-commando terug op de huidige cursorpositie. Als er geen commando op deze cursorpositie wordt gevonden, dan is de teruggegeven tekenreeks leeg.

    String document.latexCommandAt(int regel, int kolom);
    String document.latexCommandAt(Cursor cursor);

- Geeft het &latex;-commando terug op de gegeven cursorpositie. Als er geen commando op deze cursorpositie wordt gevonden, dan is de teruggegeven tekenreeks leeg.

    Range document.latexCommandRange();

- Geeft het bereik van het &latex;-commando terug op de gegeven cursorpositie. Als geen &latex;-commando is gevonden wordt `Range.invalid()` teruggegeven, die getest kan worden met `Range.isValid()`.

    String document.charAt(int regel, int kolom);
    String document.charAt(Cursor cursor);

- Geeft het teken terug op de gegeven cursorpositie.

    String document.firstChar(int regel);

- Geeft het eerste teken in de gegeven `regel` terug die geen witruimte is. Het eerste teken is in kolom 0. Als de regel leeg of alleen witruimte bevat, dan is de teruggegeven tekenreeks leeg.

    String document.lastChar(int regel);

- Geeft het laatste teken in de gegeven `regel` terug die geen witruimte is. Als de regel leeg of alleen witruimte bevat, dan is de teruggegeven tekenreeks leeg.

    bool document.isSpace(int regel, int kolom);
    bool document.isSpace(Cursor cursor);

- Geeft `true` terug, als het teken op de gegeven cursorpositie gelijk is aan een witruimte, anders `false`.

    void document.insertBullet();

- Voeg een opsomteken van &kile; in. Denk er aan dat u gemakkelijk naar het volgende of vorige opsomteken kunt springen. Dit zal dit opsomteken ook accentueren zodat het automatisch verwijderd zal worden wanneer u de eerste letter invoert.

    void document.nextBullet();

- Ga naar het volgende opsomteken in de tekst als er een is.

    void document.previousBullet();

- Ga naar het vorige opsomteken in de tekst als er een is.

    bool document.hasEnvironment();

- Geeft `true` terug als een omgevende &latex;-omgeving is gevonden, anders `false`.

    String document.environment(bool inside = false);

- Geeft de gehele tekst van de omgevende &latex;-omgeving terug. Als `inside` de waarde `false` krijgt, zal de omgevende tekst worden teruggegeven inclusief de omgevende &latex;-tags `\begin{...}...\end{...}`, anders zonder deze tags. Als geen parameter is gegeven, zal `inside` de waarde `false` krijgen. Als geen omgeving is gevonden, dan wordt een lege tekenreeks teruggegeven.

    Range document.environmentRange(bool inside = false);

- Geeft het bereik terug van de omgevende &latex;-omgeving. Als `inside` de waarde `false` krijgt zal het bereik inclusief de omgevende &latex;-tags `\begin{...}...\end{...}` teruggegeven worden, anders zonder deze tags. Als geen parameter is gegeven zal `inside` de waarde `false` krijgen. Als er geen omgeving is gevonden zal `Range.invalid()` teruggegeven worden, wat getest kan worden met `Range.isValid()`.

    String document.environmentName();

- Geeft de naam van de omgevende &latex;-omgeving terug of een lege tekenreeks.

    void document.removeEnvironment(bool inside = false);

- Verwijdert de tekst van de omgevende &latex;-omgeving. Als `inside` de waarde `false` krijgt zal de omgevingstekst inclusief de omgevende &latex;-tags `\begin{...}...\end{...}` worden verwijderd, anders zonder deze tags. Als er geen parameter is gegeven, krijgt `inside` de waarde `false`.

    void document.closeEnvironment();

- Voegt een sluittag van een omgeving in, als een geopende &latex;-omgeving is gevonden op de huidige cursorpositie.

    void document.closeAllEnvironments();

- Voegt een sluitomgevingstag in voor alle geopende &latex;-omgevingen, die zijn gevonden op de huidige cursorpositie.

    bool document.hasTexgroup();

- Geeft `true` terug als een omgevende &latex;-groep is gevonden op de huidige cursorpositie, anders `false`.

    String document.texgroup(bool inside = true);

- Geeft de tekst van de omgevende &latex;groep terug. Als `inside` de waarde `false` krijgt zal de tekst van deze &latex;-groep inclusief de omgevende accolades `{...}` terug worden gegeven, anders zonder deze. Als geen parameter is gegeven zal `inside` de waarde `false` krijgen. De teruggegeven tekenreeks is leeg, als geen omgevende &latex;-groep gevonden wordt op de huidige cursorpositie.

    Range document.texgroupRange(bool inside = true);

- Geeft het bereik terug van de omgevende &latex;-groep. Als `inside` de waarde `false` krijgt zullen omgevende accolades `{...}` teruggegeven worden, anders zonder deze. Als geen parameter is gegeven zal `inside` de waarde `false` krijgen. Als er geen groep is gevonden zal `Range.invalid()` teruggegeven worden, wat getest kan worden met `Range.isValid()`.

    void document.removeTexgroup(bool inside = true);

- Geeft de tekst van de omgevende &latex;groep terug. Als `inside` de waarde `false` krijgt, zal de tekst van deze &latex;-groep inclusief de omgevende accolades `{...}` teruggegeven worden, anders zonder deze. Als geen parameter is gegeven zal `inside` de waarde `false` krijgen.

    bool document.hasMathgroup();

- Geeft `true` terug als een omgevende &latex;-mathgroep is gevonden op de huidige cursorpositie, anders `false`.

    String document.mathgroup();

- Geeft de tekst van de omgevende &latex;-mathgroep terug. De teruggegeven tekenreeks is leeg als er geen omgevende &latex; mathgroep is gevonden op de huidige cursorpositie.

    Range document.mathgroupRange();

- Geeft het bereik van de omgevende &latex;-mathgroep terug. Als er geen omgevende mathgroep is, wordt `Range.invalid()` teruggegeven, die getest kan worden met `Range.isValid()`.

    void document.removeMathgroup();

- Verwijdert de tekst uit de omgevende &latex;-mathgroep.

    String document.paragraph();

- Geeft de tekst van de huidige &latex;-paragraaf terug.

    Range document.paragraphRange();

- Geeft het bereik van de omgevende &latex;-paragraaf terug.

    void document.removeParagraph();

- Verwijdert de tekst van de huidige &latex;-paragraaf.

    bool document.matchesAt(int regel, int kolom, String tekst);
    bool document.matchesAt(Cursor cursor, String tekst);

- Geeft `true` terug, als de gegeven `tekst` overeenkomt met de overeenkomstige cursorpositie, anders `false`.

    bool document.startsWith(int regel, String patroon, bool skipWhiteSpaces = true);

- Geeft `true` terug als de regel begint met `patroon`, anders `false`. Het argument `skipWhiteSpaces` bepaalt of voorloopwitruimte genegeerd worden.

    bool document.endsWith(int regel, String patroon, bool skipWhiteSpaces = true);

- Geeft `true` terug als de regel eindigt met `patroon`, anders `false`. Het argument `skipWhiteSpaces` bepaalt of witruimte achteraan genegeerd wordt.

    int document.firstColumn(int regel);

- Geeft de eerste niet-witruimte kolom in de gegeven `regel` terug. Als er alleen witruimte in de regel bevindt, dan is de terugkeerwaarde `-1`.

    int document.lastColumn(int regel);

- Geeft de laatste niet-witruimte kolom in de gegeven `regel` terug. Als er alleen witruimte in de regel bevindt, dan is de terugkeerwaarde `-1`.

    int document.prevNonSpaceColumn(int regel, int kolom);
    int document.prevNonSpaceColumn(Cursor cursor);

- Geeft de kolom terug met een niet-witruimte teken beginnend bij de gegeven cursorpositie en achterwaarts zoeken.

    int document.nextNonSpaceColumn(int regel, int kolom);
    int document.nextNonSpaceColumn(Cursor cursor);

- Geeft de kolom terug met een niet-witruimte teken beginnend bij de gegeven cursorpositie en voorwaarts zoeken.

    int document.prevNonEmptyLine(int regel);

- Geeft de volgende niet-lege regel terug met een niet-witruimte teken en achterwaarts zoeken.

    int document.nextNonEmptyLine(int regel);

- Geeft de volgende niet-lege regel terug met een niet-witruimte teken en voorwaarts zoeken.

    void document.gotoBeginEnv();

- Ga naar het begin van de omringende &latex;-omgeving.

    void document.gotoEndEnv();

- Ga naar het einde van de omringende &latex;-omgeving.

    void document.gotoBeginTexgroup();

- Ga naar het begin van de omringende &latex;-groep.

    void document.gotoEndTexgroup();

- Ga naar het einde van de omringende &latex;-groep.

    void document.gotoNextParagraph();

- Ga naar de volgende &latex;-paragraaf.

    void document.gotoPrevParagraph();

- Ga naar de vorige &latex;-paragraaf.

    void document.gotoNextSectioning();

- Ga naar de volgende &latex;-sectie.

    void document.gotoPrevSectioning();

- Ga naar de vorige &latex;-sectie.

    void document.gotoLine(int regel);

- Ga naar de gegeven `regel`.

    void document.insertChapter();

- Voeg een commando `\chapter` in (zie ook `document.insertSection()`).

    void document.insertSection();

- Voegt een commando `\section` in. Zoals met het kiezen van het menu-item LaTeX Opdeling in secties sectie zal een dialoogvenster verschijnen, waar u de titel en een optioneel label kunt kiezen voor dit commando voor een sectie. Dialoog: voeg commando hoofdstuk in Dialoog: voeg commando hoofdstuk in

    void document.insertSubsection();

- Voeg een commando `\subsection` in (zie ook `document.insertSection()`).

    void document.insertSubsubsection();

- Voeg een commando `\subsection` in (zie ook `document.insertSection()`).

    void document.insertParagraph();

- Voeg een commando `\paragraph` in (zie ook `document.insertSection()`).

    void document.insertSubparagraph();

- Voeg een commando `\subparagraph` in (zie ook `document.insertSection()`).

    void document.insertLabel();

- Voeg een commando `\label` in.

    void document.insertReference();

- Voegt een commando `\ref` in. Zoals met het kiezen van het menu-item &latex;Referenties ref zal een dialoogvenster verschijnen, waar u uit al gedefinieerde labels kunt kiezen, die beschikbaar zijn in een keuzelijst. Dialoog: voeg commando referenties in Dialoog: voeg commando referenties in

    void document.insertPageref();

- Voeg een commando `\pageref` in (zie ook `document.insertReference()`).

    void document.insertCitation();

- Voeg een commando `\cite` in.

    void document.insertIndex();

- Voeg een commando `\index` in.

    void document.insertFootnote();

- Voeg een commando `\footnote` in.

    void document.comment();

- Voegt commentaarmarkeringen in om de selectie of de huidige regel commentaar te maken.

    void document.uncomment();

- Verwijdert commentaarmarkeringen uit de selectie of de huidige regel.

    void document.uppercase();

- Zet de geselecteerde tekst of de letter na de cursor om in hoofdletters.

    void document.lowercase();

- Zet de geselecteerde tekst of de letter na de cursor om in kleine letters.

    void document.capitalize();

- Laat de geselecteerde tekst of het huidige woord met een hoofdletter beginnen.

    void document.joinLines();

- Voegt de regels in de huidige selectie samen. Twee opeen volgende regels worden altijd gescheiden door een enkele spatie.

    void document.insertIntelligentNewline();

- Voegt een slimme nieuweregel in (zie editing_smartnewline).

    void document.insertIntelligentTabulator();

- Voegt een slimme tab in (zie editing_tabulator).

    void document.editBegin();

- Begint een bewerkingsgroep voor groepering van ongedaan maken/opnieuw doen. Controleer altijd of `editEnd()` is aangeroepen als u `editBegin()` aanroept. Aanroepen van `editBegin()` gebruikt intern een referentieteller, let op deze aanroep kan genest worden.

    void document.editEnd();

- Beëindigt een bewerkingsgroep. De laatst aanroep van `editEnd()` (dwz. diegene voor de eerste aanroep van `editBegin()`) beëindigt de bewerkingsstap.

    StringList document.labelList();

- Geeft alle gedefinieerde labels als een `StringList` terug, die in &javascript; kan worden gebruikt als een array van tekenreeksen.

    StringList document.bibitemList();

- Geeft alle gedefinieerde bibitems als een `StringList` terug, die in &javascript; kan worden gebruikt als een array van tekenreeksen.

    void document.refreshStructure();

- Ververs de structuurweergave (zie navigating).

### De API van &kile;

Het globale object (variabele) `kile` wordt gebruikt om interacties op topniveau met de buitenwereld te behandelen, invoerberichten en interfaces voor een dialoog. Deze API-aanroepen worden verdeeld in subobjecten om deze delen van de API voor scripts te structureren. Conceptueel lijkt `kile` een beetje op een `venster` in een API voor een browser.

- `kile.alert`: berichtvakken

- `kile.input`: krijgt de invoer van de gebruiker

- `kile.wizard`: roept een van de assistenten van &kile; aan

- `kile.script`: krijgt informatie over een script in uitvoering

- `kile.file`: bestandsbewerkingen zoals lezen en schrijven.

#### Waarschuwing

    void kile.alert.information(String tekst, String opschrift);

- Toon een Informatie-dialoog. `tekst` is tekenreeks van het bericht en `opschrift` is de titel van het berichtvak. De standaard titel is de naam van het script.

    void kile.alert.sorry(String tekst, String opschrift);

- Toon een Sorry-dialoog. `tekst` is tekenreeks van het bericht en `opschrift` is de titel van het berichtvak. De standaard titel is de naam van het script.

    void kile.alert.error(String tekst, String opschrift);

- Toon een Fout-dialoog. `tekst` is tekenreeks van het bericht en `opschrift` is de titel van het berichtvak. De standaard titel is de naam van het script.

    String kile.alert.question(String tekst, String opschrift);

- Toon een eenvoudige dialoog met een vraag. `tekst` is tekenreeks van het bericht en `opschrift` is de titel van het berichtvak. De standaard titel is de naam van het script. De teruggegeven tekenreeks is ofwel `ja` of `nee`.

    String kile.alert.warning(String tekst, String opschrift);

- Toon een eenvoudige dialoog met een waarschuwing. `tekst` is tekenreeks van het bericht en `opschrift` is de titel van het berichtvak. De standaard titel is de naam van het script. De teruggegeven tekenreeks is ofwel `doorgaan` of `annuleren`.

#### Invoer

    String kile.input.getListboxItem(String opschrift, String label, StringList lijst);

- Functie om de gebruiker een item uit een lijst te laten selecteren, die getoond wordt als een keuzelijst. `opschrift` is de tekst die in de titelbalk wordt getoond, `label` is de tekst die verschijnt als het label voor de lijst en `lijst` is de lijst met tekenreeksen die in de lijst wordt gezet.

    String kile.input.getComboboxItem(String opschrift, String label, StringList lijst);

- Functie om de gebruiker een item uit een lijst te laten selecteren, die getoond wordt als een keuzelijst. `opschrift` is de tekst die in de titelbalk wordt getoond, `label` is de tekst die verschijnt als het label voor de lijst en `lijst` is de lijst met tekenreeksen die in de lijst wordt gezet.

    String kile.input.getText(String opschrift, String label);

- Functie om een tekenreeks van de gebruiker te krijgen. `opschrift` is de tekst die wordt getoond in de titelbalk en `label` de tekst die verschijnt als een label voor de te bewerken regel.

    String kile.input.getLatexCommand(String opschrift, String label);

- Functie om een &latex;-opdracht van de gebruiker te krijgen. Dit houdt in dat alleen gewone en hoofdletters zijn toegestaan. `opschrift` is de tekst die wordt getoond in de titelbalk en `label` de tekst die verschijnt als een label voor de te bewerken regel.

    int kile.input.getInteger(String opschrift, String label, int min = INT_MIN, int max = INT_MAX);

- Functie om een integer van de gebruiker te krijgen. `caption` s de tekst die wordt getoond in de titelbalk. `opschrift` is de tekst die wordt getoond in de spin box. `min` en `max` zijn de minimum en maximum toegestanewaarden die de gebruiker mag kiezen. De standaardwaarden zijn `INT_MIN` en `INT_MAX`.

    int kile.input.getPosInteger(String opschrift, String label, int min = 1, int max = INT_MAX);

- Functie om een positieve integer van de gebruiker te krijgen. `opschrift` is de tekst die wordt getoond in de titelbalk. `opschrift` is de tekst die wordt getoond in de spin box. `min` en `max` zijn de minimum en maximum toegestanewaarden die de gebruiker mag kiezen. De standaardwaarden zijn `1` en `INT_MAX`.

#### Assistent

    void kile.wizard.tabular();

- Start de Tabel assistent, die helpt bij het aanmaken van een tabel (lees wizard_array).

    void kile.wizard.array();

- Start de Array assistent, die helpt bij het aanmaken van een array (lees wizard_array).

    void kile.wizard.tabbing();

- Start de Tabbing assistent, die helpt bij het aanmaken van de instellingen voor tabs (lees wizard_array).

    void kile.wizard.floatEnvironment();

- Start de Floats assistent, die helpt bij het aanmaken van zwevende elementen (lees wizard_float).

    void kile.wizard.mathEnvironment();

- Start de Math assistent, die helpt bij het aanmaken van de instellingen voor wiskundige omgeving (lees wizard_math).

    void kile.wizard.postscript();

- Start de Postscript hulpmiddel assistent, die hulp kan geven bij het organiseren van Postscript documenten (lees wizard_postscript).

#### Script

    String kile.script.name();

- Geeft de bestandsnaam van het gestarte script (zonder pad en zonder extensie).

    String kile.script.caption();

- Geeft een tekenreeks, dat gebruikt kan worden als opschrift voor een alert box. Dat zal er uit zien zoals `Script: scriptname.js`.

#### Bestand

    Object kile.file.read(String bestandsnaam);

- Leest de inhoud van een tekstbestand. Het gebruik is als volgt

  Voorbeeld: `var res = kile.file.read("path/to/file.txt");`

  De teruggegeven waarde `res` is een object (beter: een map) met drie eigenschappen:

  - status: Geeft de status code van de bewerking, dit kan zijn 0 (geen fout), 1 (toegang mislukt) of 2 (toegang geweigerd). Dus, als er geen fout optrad, dan zal de waarde van `res.status` of `res["status"]` 0 zijn.

  - result: Bevat de tekst van het opgegeven bestand.

  - message: Bevat een foutmelding, als een fout is opgetreden.

    Object kile.file.read();

- Hetzelfde als `read(bestandsnaam)`, maar er is geen bestandsnaam opgegeven. Een dialoogvenster opent voor het selecteren van het bestand.

    Object kile.file.write(String bestandsnaam, String tekst);

- Schrijft de opgegeven tekst naar een bestand. Het gebruik is als volgt

  Voorbeeld: `var res = kile.file.write("path/to/file.txt","Wat tekst...");`

  De teruggegeven waarde `res` is een object (beter: een map) met twee eigenschappen: `status` en `message` (lees `read()` voor meer informatie).

    Object kile.file.write(String tekst);

- Hetzelfde als `write(bestandsnaam,text)`, maar er is geen bestandsnaam opgegeven. Een dialoogvenster opent voor het selecteren van een bestand.

    String kile.file.getOpenFileName(String startDir, String filter);

- Creëert een algemeen dialoogvenster voor bestanden en geeft de gekozen bestandsnaam of een lege tekenreeks als niets is gekozen. Merk op dat bij deze methode de gebruiker een bestaand bestandsnaam moet kiezen.

  Parameters:

  - startDir: De map waarmee het dialoogvenster opent.

  - filter: Een shell glob of een mime-type-filter dat instelt welke bestanden te zien zijn. Lees de informatie over KFileDialog voor meer informatie over deze parameter.

  Beide parameters zijn optioneel. Als u `filter` weglaat, dan zijn alle bestanden zichtbaar. Als bovendien `startDir` weggelaten is, dan start het dialoogvenster in de huidige document-map.

    String kile.file.getSaveFileName(String startDir, String filter);

- Creëert een algemeen dialoogvenster voor bestanden en geeft de gekozen bestandsnaam of een lege tekenreeks als niets is gekozen. Merk op dat bij deze methode de gebruiker geen bestaand bestandsnaam hoeft te kiezen. Lees `getOpenFileName()` voor een uitleg van de parameters.

## Voorbeelden

Enige voorbeelden die u kunnen helpen bij het begrijpen van het gebruik van de scripting API. Deze voorbeelden en nog enige andere kunt u vinden in de map voor scripts van &kile;: `KILE_APP_DIR/scripts/`. In elk script is een korte beschrijving aanwezig.

### Voorbeeld 1: vervang omgevingsnaam

Vervang een omgevende &latex; omgeving door een andere, waar de relatieve cursorpositie niet zal worden gewijzigd. `\begin{abc}...\end{abc}` kan bijvoorbeeld gewijzigd worden in `\begin{xyz}...\end{xyz}`.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Voer omgeving in","Nieuwe naam omgeving:");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("Geen omgevende LaTeX-omgeving gevonden.");
    }

    function replaceEnvCommand(newEnv,r)
    {
            var c = view.cursorPosition();

            var envname = document.environmentName();

            if ( envname != "" ) {
                    var beginRange = new Range(r.start,new Cursor(r.start.line,r.start.column+8+envname.length));
                    var endRange = new Range(new Cursor(r.end.line,r.end.column-6-envname.length),r.end);

                    document.editBegin();
                    document.replaceText(endRange,"\\end{"+newEnv+"}");
                    document.replaceText(beginRange,"\\begin{"+newEnv+"}");
                    document.editEnd();
            }
    }

### Voorbeeld 2: vervang een &latex; lettertypecommando

Vervang een omgevend &latex;-lettertypecommando door een ander lettertypecommando, wanneer de cursor zich in de texgroup bevindt. De relatieve cursorpositie zal niet gewijzigd worden. `\textbf{abc}` kan bijvoorbeeld vervangen worden door `\textit{abc}`.

    var fontCommands = new Array("\\textbf","\\textit","\\textsl","\\texttt",
                                 "\\textsc","\\textrm","\\textsf","\\emph");

    var range = document.texgroupRange(false);
    if ( range.isValid() ) {
            replaceFontCommand(range);
    }
    else {
            kile.alert.sorry("Geen omgevende TeX-groep gevonden.");
    }

    function replaceFontCommand(r)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.setCursorPosition(r.start);
            var cmd = document.latexCommand();
            var index = fontCommands.indexOf(cmd);
            if ( index
    >= 0 ) {
                    var cmdRange = document.latexCommandRange();
                    if ( cmdRange.isValid() ) {
                            var newcommand = kile.input.getListboxItem("Maak keuze",
                                                        "Kies lettertypecommando:",buildCmdList(cmd));
                            if ( newcommand != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - newcommand.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("Geen omgevende lettertypecommando gevonden.");
            }
            document.editEnd();
    }

    function buildCmdList(current)
    {
            var result = new Array();
            for ( i=0; i<fontCommands.length; ++i ) {
                    if ( fontCommands[i] != current ) {
                            result.push(fontCommands[i]);
                    }
            }
            return result;
    }

### Voorbeeld 3: zet iets om geselecteerde tekst

Zet om geselecteerde tekst een TeX-commando, waar de relatieve cursorpositie niet zal worden gewijzigd. Bijvoorbeeld `abc` kan worden gewijzigd in `\texcommand{abc}`.

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand("Maak keuze","Kies omgevende LaTeX-commando:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("Geen selectie gevonden.");
    }

    function surroundTexCommand(cmd,r)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.clearSelection();
            document.insertText(r.end,"}");
            document.insertText(r.start,cmd+"{");

            c.column = c.column + cmd.length + 2;
            view.setCursorPosition(c);
            document.editEnd();
    }