# Skript

## Skript i &kile;

Skriptfunktionaliteten i &kile; gör det möjligt att köra Ecmascript-kod, allmänt känt som &javascript;. Det finns en mängd handledningar som ger information om objekt (variabler), funktioner och egenskaper som stöds av &javascript;.

Skriptstöd kan aktiveras i &kile;s inställningsdialogruta: Inställningar Anpassa Kile... Kile Skript. Aktivera eller inaktivera skriptstöd Aktivera eller inaktivera skriptstöd

Om skript är aktiverade, visas en ytterligare skriptpanel i sidoraden där skript kan hanteras: Skriptpanelen i sidoraden Skriptpanelen i sidoraden

Komponenten innehåller sex ikoner som tillhandahåller olika aktiviteter:

- Kör det markerade skriptet.

- Skapa ett nytt skript.

- Öppna det markerade skriptet i editorn.

- Anpassa en tangentsekvens för det markerade skriptet.

- Ta bort en tilldelad tangentsekvens.

- Uppdatera listan med tillgängliga skript, som alla finns i `$`KDEDIR`/share/apps/kile/scripts/`.

## Köra ett skript

Du kan köra ett skript på tre olika sätt:

1. Markera önskat skript och klicka på knappen Kör på vänster sida i skripthanteringskomponenten.

   Skript: Körknappen Skript: Körknappen

2. Använda en snabbtangent.

   Skript: Snabbtangent Skript: Snabbtangent

   Du kan tilldela en snabbtangent till ett skript genom att använda knappen Anpassa i skripthanteringskomponenten.

   Skript: Dialogrutan anpassa sekvens Skript: Dialogrutan anpassa sekvens

3. Använda en tangentsekvens i editorn. Skriptet körs när den tilldelade tangentsekvensen skrivs in i editorn.

   Skript: Tangentsekvens i editorn Skript: Tangentsekvens i editorn

   Metoden kan utökas till en ganska sofistikerad sorts kodkomplettering. Låt oss anta att du har skrivit ett skript som helt enkelt infogar &latex;-kommandot `\textbf{}` i det nuvarande dokumentet.

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

   Om du nu skriver den tilldelade tangentsekvensen `bfx` i textdokumentet, tas tangentsekvensen bort och skriptet körs. Det kommer att infoga `\textbf{}` och markören placeras mellan krullparenteserna.

   Skript: Skriva in en tangentsekvens i editorn Skript: Skriva in en tangentsekvens i editorn

   Vilken bekväm och kraftfull metod för kodkomplettering.

## Referens till programmeringsgränssnittet

Programmeringsgränssnittet för skript som beskrivs här är tillgängligt i alla skript. Innan skriptets innehåll läses in, lägger &kile; först till en mängd prototyper och funktioner i skriptsammanhanget. Detta bekväma programmeringsgränssnitt innehåller prototyper som textmarkörer och textintervall och finns i katalogen `KILE_APP_DIR/script-plugins/`.

Skript i &kile; skiljer sig något från skript i &kate;, som använder en annan konstruktion eftersom de också kan startas från kommandoraden. Men alla funktioner i &kate;s programmeringsgränssnitt för skript är också tillgängliga i &kile;s programmeringsgränssnitt för skript, så att flytta &javascript;-kod från &kate; till &kile; bör vara mycket enkelt. Men eftersom &kile; är en &latex;-editor med mycket omfattande funktioner, erbjuder dess egna programmeringsgränssnitt för skript många fler möjligheter än det i &kate;.

Anmärkning:Beskrivningen av anrop i programmeringsgränssnittet, som också är tillgängliga i &kate;s skript, är hämtade från &kate;s dokumentation.

### Globala funktioner

Det här avsnittet listar globala funktioner.

    void debug(String text);

- Skriver ut `text` på `standardutmatningen` i terminalen. Den utskrivna texten är färglagd för att skilja den från annan felsökningsutmatning.

### Prototypen för Cursor

Eftersom &kile; är en texteditor är alla programmeringsgränssnitt baserade på markörer och intervall om det är möjligt. En markör (Cursor) ärett enkelt par `(rad, kolumn)`, som representerar en textposition i dokumentet.

    Cursor();

- Konstruktor. Returnerar en markör på position `(0, 0)`.

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

    Cursor(int rad, int kolumn);

- Konstruktor. Returnerar en markör på position (rad, kolumn).

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

    Cursor(Cursor annan);

- Kopieringskonstruktor. Returnerar en kopia av markören `annan`.

  Exempel: `var copy = new Cursor(other);`

    Cursor Cursor.clone();

- Returnerar en klon av markören.

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

    bool Cursor.isValid();

- Kontrollera om markören är giltig. Markören är ogiltig om rad och/eller kolumn har värdet `-1`.

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

    Cursor Cursor.invalid();

- Returnerar en ny ogiltig markör placerad på `(-1, -1)`.

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

    int Cursor.compareTo(Cursor annan);

- Jämför den här markören med markören `annan`. Returnerar

  - `-1`, om den här markören är placerad innan markören `annan`,

  - `0`, om båda markörerna är lika, och

  - `+1`, om den här markören är placerad efter markören `annan`.

    bool Cursor.equals(Cursor annan);

- Returnerar `sant` om den här markören och markören `annan` är lika, annars `falskt`.

    String Cursor.toString();

- Returnerar markören som en sträng på formen `Cursor(rad, kolumn)`.

### Prototyp för Range

Eftersom &kile; är en texteditor är alla programmeringsgränssnitt baserade på markörer och intervall om det är möjligt En markör (Cursor) är ett enkelt par `(rad, kolumn)`, som representerar en textposition i dokumentet. Ett intervall (Range) omfattar text från en markörs startposition till en markörs slutposition.

    Range();

- Konstruktor. Att anropa `new Range()` returnerar intervallet `(0, 0) - (0, 0)`.

    Range(Cursor start, Cursor slut);

- Konstruktor: Anrop av `new Range(`start`, `slut`)` returnerar intervallet från markören `start` till markören `slut`.

    Range(int startrad, int startkolumn, int slutrad, int slutkolumn);

- Konstructor: Anrop av `new Range(`startrad`, `startkolumn`, `slutrad`, `slutkolumn`)` returnerar intervallet från (`startrad`, `startkolumn`) till (`slutrad`, `slutkolumn`).

    Range(Range annan);

- Kopieringskonstruktor: Returnerar en kopia av intervallet `annan`.

    Range Range.clone();

- Returnerar en klon av intervallet.

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

    bool Range.isValid();

- Returnerar `sant` om både start- och slutmarkörerna är giltiga, annars `falskt`.

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

    bool Range.invalid();

- Returnerar intervallet från (-1, -1) till (-1, -1).

    bool Range.contains(Cursor markör);

- Returnerar `true` om intervallet innehåller markörpositionen, annars `false`.

    bool Range.contains(Range annan);

- Returnerar `sant` om det här intervallet innehåller intervallet `annat`, annars `falskt`.

    bool Range.containsColumn(int kolumn);

- Returnerar `sant` om `kolumn` är i det halvöppna intervallet `[startkolumn, slutkolumn)`, annars `falskt`.

    bool Range.containsLine(int rad);

- Returnerar `sant` om `rad` är i det halvöppna intervallet `[startrad, slutrad)`, annars `falskt`.

    bool Range.overlaps(Range annan);

- Returnerar `sant` om det här intervallet och intervallet `annat` delar ett gemensamt område, annars `falskt`.

    bool Range.overlapsLine(int rad);

- Returnerar `sant` om `rad` är i intervallet `[startrad, slutrad]`, annars `falskt`.

    bool Range.overlapsColumn(int kolumn);

- Returnerar `sant` om `kolumn` är i intervallet `[startkolumn, slutkolumn]`, annars `falskt`.

    bool Range.equals(Range annan);

- Returnerar `sant` om det här intervallet och intervallet `annat` är lika, annars `falskt`.

    String Range.toString();

- Returnerar intervallet som en sträng på formen `Range(Cursor(rad, kolumn), Cursor(rad, kolumn))`.

### Programmeringsgränssnittet för vyn

När ett skript håller på att köras, finns det ett globalt objekt (variabel) `view` som representerar den för närvarande aktiva editorvyn. Alla funktioner i `view` arbetar med markörpositioner eller markerad text. Det följande är en lista med alla tillgängliga funktioner i `view`.

    void view.backspace();

- Utför motsvarigheten till att trycka på backstegstangenten programmatiskt.

    Cursor view.cursorPosition();

- Returnerar den nuvarande markörpositionen i vyn.

    void view.setCursorPosition(int rad, int kolumn);
    void view.setCursorPosition(Cursor markör);

- Ställ in den nuvarande markörpositionen till antingen `rad`, `kolumn` eller till angiven `markör`.

    void view.cursorLeft();

- Flyttar markören en position bakåt i texten.

    void view.cursorRight();

- Flyttar markören en position framåt i texten.

    void view.cursorUp();

- Flyttar markören en rad uppåt i dokumentet.

    void view.cursorDown();

- Flyttar markören en rad neråt i dokumentet.

    int view.cursorLine();

- Returnerar raden där markören för närvarande är placerad.

    int view.cursorColumn();

- Returnerar kolumnen där markören för närvarande är placerad.

    void view.setCursorLine(int rad);

- Ändra markörens rad till angiven `rad`.

    void view.setCursorColumn(int kolumn);

- Ändra markörens kolumn till angiven `kolumn`.

    Cursor view.virtualCursorPosition();

- Hämta den nuvarande virtuella markörpositionen. Virtuell betyder att tabulatortecknet (TAB) räknas som flera tecken, enligt vad som är inställt av användaren (t.ex. en tabulator är 8 mellanslag). Den virtuella markörpositionen ger tillgång till den nuvarande markörpositionens värde som användaren ser.

    bool view.hasSelection();

- Returnerar `true` om vyn har markerad text, annars `false`.

    String view.selectedText();

- Returnerar den markerade texten. Om ingen text är markerad, är den returnerade strängen tom.

    Range view.selectionRange();

- Returnerar det markerade textintervallet. Det returnerade intervallet är ogiltigt om det inte finns någon markerad text.

    void view.setSelection(Range intervall);

- Ställer in markerad text till angivet `intervall`.

    void view.selectAll();

- Markerar hela texten i dokumentet.

    void view.clearSelection();

- Rensar textmarkeringen utan att ta bort texten.

    void view.removeSelectedText();

- Tar bort den markerade texten. Om vyn inte har någon markerad text, händer ingenting.

    void view.selectLine();

- Markerar texten på nuvarande rad.

    void view.selectLine(int rad);

- Markerar texten på angiven `rad`.

    void view.selectLines(int från, int till);

- Markerar hela texten från rad `från` till rad `till`.

    void view.selectWord();

- Markerar aktuellt ord. Om inget ord hittas vid markörens position händer ingenting.

    void view.selectLatexCommand();

- Markerar aktuellt &latex;-kommando. Om inget kommando hittas vid markörens position händer ingenting.

    void view.selectEnvironment(bool inuti = false);

- Markerar hela texten i den nuvarande &latex;-omgivningen. Om`inuti` är `false`, markeras omgivningstexten inklusive &latex;-taggarna `\begin{...}...\end{...}`, annars ingår inte taggarna. Om ingen parameter anges, sätts `inuti` till `false`.

    void view.selectTexgroup(bool inuti = true);

- Markerar texten i den nuvarande &latex;-omgivningen. Om`inuti` är `true`, markeras bara textgruppen utan omgivande krullparenteser. Om ingen parameter anges, sätts `inuti` till `true`.

    void view.selectMathgroup();

- Markerar texten i aktuell matematikgrupp.

    void view.selectParagraph(bool wholeLines = true);

- Markerar hela texten i det nuvarande &latex;-stycket. Om `wholeLines` är `true`, ingår styckets första och sista rader helt och hållet (inklusive radslutstecken), annars innehåller markeringen bara tecken som inte är blanktecken.

### Programmeringsgränssnittet för dokumentet

Så snart ett skript körs, finns ett globalt objekt (variabel) `document` som representerar det nuvarande aktiva dokumentet. Det följande är en lista över tillgängliga funktioner för `document`.

    void document.insertText(String text);

- Infogar `text` vid aktuell markörposition.

    void document.insertText(int rad, int kolumn, String text);
    void document.insertText(Cursor markör, String text);

- Infogar `text` vid angiven markörposition.

    bool document.removeText(int frånrad, int frånkolumn, int tillrad, int tillkolumn);
    bool document.removeText(Cursor från, Cursor till);
    bool document.removeText(Range intervall);

- Tar bort text i det givna intervallet. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat.

    bool document.replaceText(Range intervall, String text);

- Ersätter texten i det givna intervallet med den angivna texten.

    int document.lines();

- Returnerar antal rader i dokumentet.

    int document.length();

- Returnerar antal tecken i dokumentet.

    Range document.documentRange();

- Returnerar ett intervall som omfattar hela dokumentet.

    Cursor document.documentEnd();

- Returnerar aktuell markörposition för dokumentets slut.

    String document.text();

- Returnerar dokumentets hela innehåll i en enda textsträng. Nya rader är markerade med nyradstecknet `\n`.

    String document.text(int frånrad, int frånkolumn, int tillrad, int tillkolumn);
    String document.text(Cursor från, Cursor till);
    String document.text(Range intervall);

- Returnerar texten i det angivna intervallet. Det rekommenderas att använda markör- och intervallbaserade versioner för bättre läsbarhet hos källkoden.

    bool document.setText(String text);

- Anger hela dokumentets text.

    bool document.clear();

- Tar bort hela texten i dokumentet.

    String document.line();

- Returnerar aktuell textrad som en sträng.

    String document.line(int rad);

- Returnerar den givna textraden som en sträng. Strängen är tom om den begärda raden är utanför tillgängligt intervall.

    int document.lineLength();

- Returnerar den aktuella radens längd.

    int document.lineLength(int rad);

- Returnerar längden på `rad`.

    bool document.insertLine(String s);

- Infogar text på den nuvarande raden. Returnerar `true` om det lyckas, eller `false` om dokumentet är skrivskyddat eller raden inte ingår i dokumentets intervall.

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

- Infogar text på den givna raden. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat eller raden inte ingår i dokumentets intervall.

    bool document.removeLine();

- Tar bort den nuvarande textraden. Returnerar `true` om det lyckas, eller `false` om dokumentet är skrivskyddat.

    bool document.removeLine(int rad);

- Tar bort den givna textraden. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat eller raden inte ingår i dokumentets intervall.

    bool document.replaceLine(String text);

- Ersätter texten på aktuell rad med den angivna texten.

    bool document.replaceLine(int rad, String text);

- Ersätter texten på den givna raden med angiven text.

    bool document.truncateLine();

- Avkorta den nuvarande raden från angiven kolumn eller markörposition. Returnerar `true` om det lyckas, eller `false` om den angivna raden inte ingår i dokumentets intervall.

    bool document.truncate(int rad, int kolumn);
    bool document.truncate(Cursor markör);

- Avkortar den givna raden på den givna kolumnen eller markörpositionen. Returnerar `sant` om det lyckas, eller `falskt` om den givna raden inte ingår i dokumentets intervall.

    String document.word();

- Returnerar ordet på den nuvarande markörpositionen. Om inget ord hittas på markörpositionen, är den returnerade strängen tom.

    String document.wordAt(int rad, int kolumn);
    String document.wordAt(Cursor markör);

- Returnerar ordet på den angivna markörpositionen. Om inget ord hittas på markörpositionen, är den returnerade strängen tom.

    Range document.wordRange();

- Returnerar intervallet för ordet vid den angivna markörpositionen. Om inget ord hittas, returneras `Range.invalid()`, vilket kan kontrolleras med `Range.isValid()`.

    String document.latexCommand();

- Returnerar &latex;-kommandot på den nuvarande markörpositionen. Om inget kommando hittas vid markörpositionen är den returnerade strängen tom.

    String document.latexCommandAt(int rad, int kolumn);
    String document.latexCommandAt(Cursor markör);

- Returnerar &latex;-kommandot på den angivna markörpositionen. Om inget kommando hittas på markörpositionen, är den returnerade strängen tom.

    Range document.latexCommandRange();

- Returnerar intervallet för &latex;-kommandot vid den angivna markörpositionen. Om inget kommando hittas, returneras `Range.invalid()`, vilket kan kontrolleras med `Range.isValid()`.

    String document.charAt(int rad, int kolumn);
    String document.charAt(Cursor markör);

- Returnerar tacknet på den angivna markörpositionen.

    String document.firstChar(int rad);

- Returnerar det första tecknet på angiven `rad` som inte är ett blanktecken. Det första tecknet finns på kolumn 0. Om raden är tom, eller bara innehåller blanktecken, är den returnerade strängen tom.

    String document.lastChar(int rad);

- Returnerar det sista tecknet på angiven `rad` som inte är ett blanktecken. Om raden är tom, eller bara innehåller blanktecken, är den returnerade strängen tom.

    bool document.isSpace(int rad, int kolumn);
    bool document.isSpace(Cursor markör);

- Returnerar `sant` om tecknet på den givna markörpositionen är ett blanktecken, annars `falskt`.

    void document.insertBullet();

- Infoga en &kile; punkt. Kom ihåg att du enkelt kan gå till nästa eller föregående punkt. Detta markerar också punkten så att den automatiskt tas bort när den första bokstaven skrivs in.

    void document.nextBullet();

- Gå till nästa punkt i texten om det finns någon.

    void document.previousBullet();

- Gå till föregående punkt i texten om det finns någon.

    bool document.hasEnvironment();

- Returnerar `true` om en omgivande &latex;-omgivning hittas, annars `false`.

    String document.environment(bool inuti = false);

- Returnerar hela texten i den nuvarande &latex;-omgivningen. Om`inuti` är `false`, returneras omgivningstexten inklusive &latex;-taggarna `\begin{...}...\end{...}`, annars ingår inte taggarna. Om ingen parameter anges, sätts `inuti` till `false`. Om ingen omgivning hittas är den returnerade strängen tom.

    Range document.environmentRange(bool inuti = false);

- Returnerar intervallet i den nuvarande &latex;-omgivningen. Om`inuti` är `false`, returneras intervallet inklusive &latex;-taggarna `\begin{...}...\end{...}`, annars ingår inte taggarna. Om ingen parameter anges, sätts `inuti` till `false`. Om inget kommando hittas, returneras `Range.invalid()`, vilket kan kontrolleras med `Range.isValid()`.

    String document.environmentName();

- Returnerar namnet på den omgivande &latex;-omgivningen eller en tom sträng.

    void document.removeEnvironment(bool inuti = false);

- Tar bort texten i den nuvarande &latex;-omgivningen. Om`inuti` är `false`, tas omgivningstexten inklusive &latex;-taggarna `\begin{...}...\end{...}` bort, annars ingår inte taggarna. Om ingen parameter anges, sätts `inuti` till `false`.

    void document.closeEnvironment();

- Infoga en avslutande omgivningstagg, om en öppen &latex;-omgivning hittas på markörens nuvarande position.

    void document.closeAllEnvironments();

- Infoga avslutande omgivningstaggar, för alla öppna &latex;-omgivningar som hittades på markörens nuvarande position.

    bool document.hasTexgroup();

- Returnerar `true` om en omgivande &latex;-grupp hittas vid markörens nuvarande position, annars `false`.

    String document.texgroup(bool inuti = true);

- Returnerar texten i den omgivande &latex;-gruppen. Om`inuti` är `false`, returneras texten i &latex;-gruppen inklusive omgivande krullparenteser `{...}`, annars ingår de inte. Om ingen parameter anges, sätts `inuti` till `false`. Den returnerade strängen tom om ingen omgivande &latex;-grupp hittas på markörens nuvarande position.

    Range document.texgroupRange(bool inuti = true);

- Returnerar intervallet i den omgivande &latex;-gruppen. Om`inuti` är `false`, returneras intervallet inklusive omgivande krullparenteser `{...}`, annars ingår de inte. Om ingen parameter anges, sätts `inuti` till `false`. Om ingen grupp hittas, returneras `Range.invalid()`, vilket kan kontrolleras med `Range.isValid()`.

    void document.removeTexgroup(bool inuti = true);

- Tar bort texten i den omgivande &latex;-gruppen. Om`inuti` är `false`, tas texten i &latex;-gruppen inklusive omgivande krullparenteser `{...}` bort, annars ingår de inte. Om ingen parameter anges, sätts `inuti` till `false`.

    bool document.hasMathgroup();

- Returnerar `true` om en omgivande &latex;-matematikgrupp hittas, annars `false`.

    String document.mathgroup();

- Returnerar den omgivande &latex;-matematikgruppens text. Den returnerade strängen är tom om ingen omgivande &latex;-matematikgrupp hittas vid markörens nuvarande position.

    Range document.mathgroupRange();

- Returnerar intervallet för den omgivande &latex;-matematikgruppen. Om ingen matematikgrupp hittas, returneras `Range.invalid()`, vilket kan kontrolleras med `Range.isValid()`.

    void document.removeMathgroup();

- Tar bort den omgivande &latex;-matematikgruppens text.

    String document.paragraph();

- Returnerar det nuvarande &latex;-styckets text.

    Range document.paragraphRange();

- Returnerar intervallet för det omgivande &latex;-stycket.

    void document.removeParagraph();

- Tar bort det nuvarande &latex;-styckets text.

    bool document.matchesAt(int rad, int kolumn, String text);
    bool document.matchesAt(Cursor markör, String text);

- Returnerar `sant` om given `text` matchar på den motsvarande markörpositionen, annars `falskt`.

    bool document.startsWith(int rad, String mönster, bool hoppa-över-blanktecken = true);

- Returnerar `true` om raden börjar med `mönster`, annars `false`. Parametern `hoppa-över-blanktecken` bestämmer om inledande blanktecken ignoreras.

    bool document.endsWith(int rad, String mönster, bool hoppa-över-blanktecken = true);

- Returnerar `true` om raden slutar med `mönster`, annars `false`. Parametern `hoppa-över-blanktecken` bestämmer om avslutande blanktecken ignoreras.

    int document.firstColumn(int rad);

- Returnerar det första tecknet som inte är ett blanktecken på given `rad`. Om det bara finns blanktecken på raden, är returvärdet `-1`.

    int document.lastColumn(int rad);

- Returnerar det sista tecknet som inte är ett blanktecken på given `rad`. Om det bara finns blanktecken på raden, är returvärdet `-1`.

    int document.prevNonSpaceColumn(int rad, int kolumn);
    int document.prevNonSpaceColumn(Cursor markör);

- Returnerar kolumnen med ett tecken som inte är ett blanktecken med början på given markörposition genom att söka bakåt.

    int document.nextNonSpaceColumn(int rad, int kolumn);
    int document.nextNonSpaceColumn(Cursor markör);

- Returnerar kolumnen med ett tecken som inte är ett blanktecken med början på given markörposition genom att söka framåt.

    int document.prevNonEmptyLine(int rad);

- Returnerar nästa rad som inte är tom och som innehåller tecken som inte är blanktecken, genom att söka bakåt.

    int document.nextNonEmptyLine(int rad);

- Returnerar nästa rad som inte är tom och som innehåller tecken som inte är blanktecken, genom att söka framåt.

    void document.gotoBeginEnv();

- Gå till början av en omgivande &latex;-omgivning.

    void document.gotoEndEnv();

- Gå till slutet av en omgivande &latex;-omgivning.

    void document.gotoBeginTexgroup();

- Gå till början av en omgivande &latex;-grupp.

    void document.gotoEndTexgroup();

- Gå till slutet av en omgivande &latex;-grupp.

    void document.gotoNextParagraph();

- Gå till nästa &latex;-stycke.

    void document.gotoPrevParagraph();

- Gå till föregående &latex;-stycke.

    void document.gotoNextSectioning();

- Gå till nästa &latex;-avsnitt.

    void document.gotoPrevSectioning();

- Gå till föregående &latex;-avsnitt.

    void document.gotoLine(int rad);

- Gå till angiven `rad`.

    void document.insertChapter();

- Infoga kommandot `\chapter` (se också `document.insertSection()`).

    void document.insertSection();

- Infoga kommandot `\section`. Som när menyalternativet Latex Sektioner section används, dyker en dialogruta upp där du kan välja rubrik och en valfri etikett för det här sektionskommandot. Dialogruta: Kommandot Infoga kapitel Dialogruta: Kommandot Infoga kapitel

    void document.insertSubsection();

- Infoga kommandot `\subsection` (se också `document.insertSection()`).

    void document.insertSubsubsection();

- Infoga kommandot `\subsubsection` (se också `document.insertSection()`).

    void document.insertParagraph();

- Infoga kommandot `\paragraph` (se också `document.insertSection()`).

    void document.insertSubparagraph();

- Infoga kommandot `\subparagraph` (se också `document.insertSection()`).

    void document.insertLabel();

- Infoga kommandot `\label`.

    void document.insertReference();

- Infoga kommandot `\ref`. Som när menyalternativet &latex;Referenser ref används, dyker en dialogruta upp där du kan välja bland redan definierade etiketter som listas i en kombinationsruta. Dialogruta: Infoga ett hänvisningskommando Dialogruta: Infoga ett hänvisningskommando

    void document.insertPageref();

- Infoga kommandot `\pageref` (se också `document.insertReference()`).

    void document.insertCitation();

- Infoga kommandot `\cite`.

    void document.insertIndex();

- Infoga kommandot `\index`.

    void document.insertFootnote();

- Infoga kommandot `\footnote`.

    void document.comment();

- Infogar kommentarmarkörer så att markeringen eller nuvarande rad blir en kommentar.

    void document.uncomment();

- Tar bort kommentarmarkörer från markeringen eller nuvarande rad.

    void document.uppercase();

- Ändra den markerade texten eller bokstaven efter markören till stora bokstäver.

    void document.lowercase();

- Ändra den markerade texten eller bokstaven efter markören till små bokstäver.

    void document.capitalize();

- Ändra den inledande bokstaven för orden i den markerade texten eller i aktuellt ord till stor bokstav.

    void document.joinLines();

- Sammanfogar raderna i den nuvarande markeringen. Två textrader i följd åtskiljs alltid av ett enda mellanslag.

    void document.insertIntelligentNewline();

- Infoga en smart nyrad (se editing_smartnewline).

    void document.insertIntelligentTabulator();

- Infoga en smart tabulator (se editing_tabulator).

    void document.editBegin();

- Startar en redigeringsgrupp för gruppering av ångra/gör om. Försäkra dig om att alltid anropa `editEnd()` lika många gånger som du anropar `editBegin()`. Att anropa `editBegin()` använder en referensräknare internt, dvs. anropet kan nästlas.

    void document.editEnd();

- Avslutar en redigeringsgrupp. Det sista anropet av `editEnd()` (dvs. det för det första anropet till `editBegin()`) avslutar redigeringssteget.

    StringList document.labelList();

- Returnerar alla definierade etiketter som en `StringList`, vilken kan användas i &javascript; som ett fält av strängar.

    StringList document.bibitemList();

- Returnerar alla definierade bibitems som en `StringList`, vilken kan användas i &javascript; som ett fält av strängar.

    void document.refreshStructure();

- Uppdaterar strukturvyn (se navigating).

### Programmeringsgränssnittet för &kile;

Det globala objektet (variabeln) `kile` används för att hantera interaktion på toppnivå med den omgivande världen, indatameddelanden och dialogrutegränssnitt. Dessa anrop till programmeringsgränssnittet är uppdelade i delobjekt för att strukturera den här delen av skriptgränssnittet. Begreppsmässigt påminner `kile` något om `window` i ett programmeringsgränssnitt för webbläsare.

- `kile.alert`: Meddelanderutor

- `kile.input`: Hämta inmatning från användaren

- `kile.wizard`: Anropa en av guiderna i &kile;

- `kile.script`: Hämta information om ett skript som kör

- `kile.file`: Åtgärder med filer, som läs och skriv.

#### Meddelanden

    void kile.alert.information(String text, String rubrik);

- Visa en informationsdialogruta. `text` är meddelandets sträng och `rubrik` är meddelanderutans namn. Standardnamnet är skriptets namn.

    void kile.alert.sorry(String text, String rubrik);

- Visa dialogrutan Tyvärr. `text` är meddelandets sträng och `rubrik` är meddelanderutans namn. Standardnamnet är skriptets namn.

    void kile.alert.error(String text, String rubrik);

- Visa en feldialogruta. `text` är meddelandets sträng och `rubrik` är meddelanderutans namn. Standardnamnet är skriptets namn.

    String kile.alert.question(String text, String rubrik);

- Visa en enkel frågedialogruta. `text` är meddelandets sträng och `rubrik` är meddelanderutans namn. Standardnamnet är skriptets namn. Den returnerade strängen är antingen `yes` eller `no`.

    String kile.alert.warning(String text, String rubrik);

- Visa en enkel varningsdialogruta. `text` är meddelandets sträng och `rubrik` är meddelanderutans namn. Standardnamnet är skriptets namn. Den returnerade strängen är antingen `continue` eller `cancel`.

#### Inmatning

    String kile.input.getListboxItem(String rubrik, String etikett, StringList lista);

- Funktion för att låta användaren välja ett objekt i en lista, som visas som en listruta. `rubrik` är texten som visas i namnlisten, `etikett` är texten som syns som etikett för listan och `lista` är stränglistan som infogas i rutan.

    String kile.input.getComboboxItem(String rubrik, String etikett, StringList lista);

- Funktion för att låta användaren välja ett objekt i en lista, som visas som en kombinationsruta. `rubrik` är texten som visas i namnlisten, `etikett` är texten som syns som etikett för listan och `lista` är stränglistan som infogas i rutan.

    String kile.input.getText(String rubrik, String etikett);

- Funktion för att hämta en sträng från användaren. `rubrik` är texten som visas i namnlisten, `etikett` är texten som syns som etikett för radeditorn.

    String kile.input.getLatexCommand(String rubrik, String etikett);

- Funktion för att hämta ett &latex;-kommando från användaren. Det betyder att bara små och stora bokstäver tillåts. `rubrik` är texten som visas i namnlisten, `etikett` är texten som syns som etikett för radeditorn.

    int kile.input.getInteger(String rubrik, String etikett, int min = INT_MIN, int max = INT_MAX);

- Funktion för att hämta ett heltal från användaren. `rubrik` är texten som visas i namnlisten, `etikett` är texten som syns som etikett för nummerrutan. `min` och `max` är det minsta och största tillåtna värdet som användaren kan välja. Förvalda värden är `INT_MIN` och `INT_MAX`.

    int kile.input.getPosInteger(String rubrik, String etikett, int min = 1, int max = INT_MAX);

- Funktion för att hämta ett positivt heltal från användaren. `rubrik` är texten som visas i namnlisten, `etikett` är texten som syns som etikett för nummerrutan. `min` och `max` är det minsta och största tillåtna värdet som användaren kan välja. Förvalda värden är `1` och `INT_MAX`.

#### Guider

    void kile.wizard.tabular();

- Anropar tabellguiden som hjälper till att skriva en tabellomgivning (se wizard_array).

    void kile.wizard.array();

- Anropar fältguiden som hjälper till att skriva en fältomgivning (se wizard_array).

    void kile.wizard.tabbing();

- Anropar tabulatorguiden som hjälper till att skriva en tabulatoromgivning (se wizard_array).

    void kile.wizard.floatEnvironment();

- Anropar flytguiden som hjälper till att infoga flytande element (se wizard_float).

    void kile.wizard.mathEnvironment();

- Anropar matematikguiden som hjälper till att infoga matematikomgivningar (se wizard_math).

    void kile.wizard.postscript();

- Anropar Postscript-verktygsguiden som kan hjälpa till att hantera eller arrangera om Postscript-dokument (se wizard_postscript).

#### Skript

    String kile.script.name();

- Returnerar basnamnet på ett skript som kör (utan sökväg och filändelse).

    String kile.script.caption();

- Returnerar en sträng som kan användas som rubrik i underrättelserutor. Det ser ut som `Script: scriptname.js`.

#### Fil

    Object kile.file.read(String filnamn);

- Läser innehållet i en textfil. Det används på följande sätt:

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

  Returvärdet `res` är ett objekt (eller bättre: en avbildning) med tre egenskaper:

  - status: Anger åtgärdens statuskod, som kan vara 0 (inget fel), 1 (åtkomst misslyckades) eller 2 (åtkomst nekades). Så om inget fel uppstod är värdet av `res.status` eller `res["status"]` 0.

  - result: Innehåller den angivna filens text.

  - message: Innehåller ett felmeddelande om ett fel uppstod.

    Object kile.file.read();

- Samma sak som `read(filnamn)`, men inget filnamn anges. En dialogruta kommer att visas för att välja filen att läsa.

    Object kile.file.write(String filnamn, String text);

- Skriv den angivna texten till en fil. Det används på följande sätt:

  Exempel: `var res = kile.file.write("sökväg/till/fil.txt","Någon text...");`

  Returvärdet `res` är ett objekt (eller bättre: en avbildning) med två egenskaper: `status` och `message` (se `read()` för mer information).

    Object kile.file.write(String text);

- Samma sak som `write(filename,text)` men inget filnamn anges. En dialogruta dyker upp för att välja ett filnamn.

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

- Skapar en fildialogruta och returnerar det valda filnamnet eller en tom sträng om inget väljes. Observera att med den här metoden måste användaren välja ett befintligt filnamn.

  Parametrar:

  - startkatalog: Den öppnade dialogrutans startkatalog.

  - filter: En sträng med jokertecken för skalet eller ett Mime-typfilter som anger vilka filer som ska visas. Se dokumentationen av KFileDialog för mer information om parametern.

  Båda parametrar är valfria. Om `filter` utelämnas visas alla filer. Om dessutom `startkatalog` utelämnas använder dialogrutan det nuvarande dokumentets katalog som startpunkt.

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

- Skapar en fildialogruta och returnerar det valda filnamnet eller en tom sträng om inget väljes. Observera att med den här metoden behöver användaren inte välja ett befintligt filnamn. Se `getOpenFileName()` för en förklaring av parametrarna.

## Exempel

Några exempel kan hjälpa till att förstå hur skriptgränssnittet används. Dessa exempel och ytterligare några finns i &kile;s skriptkatalog: `KILE_APP_DIR/scripts/`. Varje skript innehåller en kortfattad beskrivning.

### Exempel 1: Ersätt omgivningsnamn

Ersätt en omgivande &latex;-omgivning med en annan, där den relativa markörpositionen inte ändras. `\begin{abc}...\end{abc}` kan exempelvis ändras till `\begin{xyz}...\end{xyz}`.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Ange omgivning","Nytt omgivningsnamn:");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("Ingen omgivande Latex-omgivning hittades.");
    }

    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();
            }
    }

### Exempel 2: Ersätt ett &latex; teckensnittskommando

Ersätt ett omgivande &latex;-teckensnittkommando med ett annat teckensnittkommando där markören är placerad inne i tex-gruppen. Den relativa markörpositionen ändras inte. `\textbf{abc}` kan exempelvis ändras till `\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("Ingen omgivande Tex-grupp hittades.");
    }

    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("Choose",
                                                        "Choose font command:",buildCmdList(cmd));
                            if ( newcommand != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - newcommand.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("Inget omgivande teckensnittkommando hittades.");
            }
            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;
    }

### Exempel 3: Omge markerad text

Omge markerad text med ett Tex-kommando där den relativa markörpositionen inte ändras. `abc` kan exempelvis ändras till `\texkommando{abc}`.

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand("Välj","Välj omgivande Latex-kommando:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("Ingen markering hittades.");
    }

    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();
    }