# Raba skriptov

## Raba skriptov v &kile;

Funkcija skriptiranja &kile; omogoča izvajanje kode ECMAScript, splošno znane kot &javascript;. Našli boste veliko učbenikov, ki nudijo informacije o objektih (spremenljivkah), funkcijah in lastnostih, ki jih podpira &javascript;.

Podporo za skripte lahko omogočite v konfiguracijskem pogovornem oknu &kile;: Nastavitve Konfiguriraj Kile... Kile Skriptiranje. Omogoči ali onemogoči podporo za skripte Omogoči ali onemogoči podporo za skripte

Če je omogočeno skriptiranje, je v stranski vrstici vidna dodatna plošča skriptov, kjer lahko upravljate skripte: Plošča skriptov v stranski vrstici Plošča skriptov v stranski vrstici

Ta gradnik vsebuje šest ikon, ki ponujajo različna opravila:

- Zaženi izbrani skript.

- Ustvari nov skript.

- Odpri izbrani skript v urejevalniku.

- Konfiguriraj zaporedje tipk za izbrani skript.

- Odstrani dodeljeno zaporedje tipk.

- Osveži seznam razpoložljivih skriptov, ki jih najdete v `$`KDEDIR`/share/apps/kile/scripts/`.

## Izvajanje skripta

Skript lahko izvedete na tri različne načine:

1. Izberite želeni skript in kliknite gumb Izvedi na levi strani pripomočka za upravljanje skriptov.

   Skriptiranje: gumb za izvajanje Skriptiranje: gumb za izvajanje

2. Uporabite bližnjico na tipkovnici.

   Skriptiranje: bližnjica na tipkovnici Skriptiranje: bližnjica na tipkovnici

   Bližnjico na tipkovnici lahko dodelite skriptu z uporabo gumba Konfiguriraj v pripomočku za upravljanje skriptov.

   Skriptiranje: pogovorno okno konfiguriranja zaporedja Skriptiranje: pogovorno okno konfiguriranja zaporedja

3. Uporabite zaporedje tipk urejevalnika. Skript se bo izvedel, če vnesetedodeljeno zaporedje tipk v urejevalniku.

   Skriptiranje: zaporedje tipk urejevalnika Skriptiranje: zaporedje tipk urejevalnika

   To metodo je mogoče razširiti na precej sofisticirano vrsto dokončanja kode. Predpostavimo, da imate napisan scenarij, ki preprosto vstavi &latex; ukaz `\textbf{}` v trenutni dokument.

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

   Če zdaj vnesete dodeljeno zaporedje tipk `bfx` v svoj besedilni dokument, bo to zaporedje tipk odstranjeno in skript izveden. Vstavil bo `\textbf{}` in kazalec je postavljen med oklepaji.

   Skriptiranje: tipkanje zaporedja tipk urejevalnika Skriptiranje: tipkanje zaporedja tipk urejevalnika

   Kako udobna in zmogljiva metoda dokončanja kode.

## Referenca API-ja

Tukaj predstavljeni skriptni API je na voljo v vseh skriptih. Pred se vsebina skripta naloži, &kile; najprej doda več prototipov in funkcij v skriptni kontekst. Ta priročen vmesnik API vsebuje prototipe kot besedilni kazalci in obsegi besedila in se nahaja v mapi `KILE_APP_DIR/script-plugins/`.

&kile; skripti se nekoliko razlikujejo od &kate; skriptov, ki uporabljajo drugačno zasnovo, kot so lahko tudizagnani iz ukazne vrstice. Toda vse funkcije &kate; skriptni API so na voljo tudi v API-ju za skripte &kile;, tako da prenos &javascript; Koda iz &kate; v &kile; mora biti zelo enostavna. Toda kot je &kile; zelo bogat predstavljen &latex; urejevalnik, njegov lastni skriptni API ponuja veliko več več možnosti kot &kate;.

Opomba: Opis klicev API-ja, ki so tudi na voljo v &kate; skript, so bili vzeti iz dokumentacije &kate;.

### Globalne funkcije

V tem razdelku so navedene globalne funkcije.

    void debug(Niz besedilo);

- Natisne `besedilo` v `stdout` v konzoli. Natisnjeno besedilo je obarvano, da se razlikuje od drugih rezultatov odpravljanja napak.

### Prototip kazalca

Kot &kile; je urejevalnik besedil, vsi skriptni API temeljijo na kazalcih in obsegih, kadar koli je to mogoče. Kazalec je preprost nabor `(vrstica, stolpec)`, ki predstavlja položaj besedila v dokumentu.

    Cursor();

- Konstruktor: vrne kazalec na položaju `(0,0)`.

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

    Cursor(int vrstica, int stolpec);

- Konstruktor: vrne kazalec na položaj (vrstica,stolpec).

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

    Cursor(Cursor other);

- Konstruktor kopiranja: vrne kopijo kazalca `other`.

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

    Cursor Cursor.clone();

- Vrne klon kazalca.

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

    bool Cursor.isValid();

- Preverite, ali je kazalec veljaven. Kazalec ni veljaven, če sta vrstica in/ali stolpec nastavljena na `-1`.

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

    Cursor Cursor.invalid();

- Vrne nov neveljaven kazalec, ki se nahaja na `(-1,-1)`.

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

    int Cursor.compareTo(Cursor other);

- Primerja ta kazalec s kazalcem `other`. Vrne

  - `-1`, če se ta kazalec nahaja pred kazalcem `other`,

  - `0`, če sta oba kazalca enaka in

  - `1`, če se ta kazalec nahaja za kazalcem `other`.

    bool Cursor.equals(Cursor other);

- Vrne `true`, če sta ta kazalec in kazalec `other` enaka, sicer `false`.

    String Cursor.toString();

- Vrne kazalec kot niz v obliki `Cursor(vrstica,stolpec)`.

### Prototip dometa

Kot &kile; je urejevalnik besedil, vsi skriptni API temeljijo na kazalcih in obsegih kadar koli je to mogoče. Ker je kazalec preprost `(vrstica, stolpec)` urejen par, ki predstavlja položaj besedila v dokumentu, obseg obsegabesedilo od začetnega položaja kazalca do končnega položaja kazalca.

    Range();

- Konstruktor: Klic `new Range()` vrne obseg na `(0,0) - (0,0)`.

    Range(Cursor start, Cursor end);

- Konstruktor: Klic `new Range(`start`, `end`)` vrne obseg od kazalca `start` do kazalca `end`.

    Range(int startLine, int startColumn, int endLine, int endColumn);

- Konstruktor: Klicanje `new Range(`startLine`,`startColumn`,`endLine`, `endColumn`)` vrne obseg od (`startLine`, `startColumn`) to (`endLine`, `endColumn`).

    Range(Range other);

- Konstruktor kopiranja: vrne kopijo Range `other`.

    Obseg Range.clone();

- Vrne klon obsega.

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

    bool Range.isValid();

- Vrne `true`, če sta začetni in končni kazalec veljavna, sicer `false`.

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

    bool Range.invalid();

- Vrne obseg od (-1,-1) do (-1,-1).

    bool Range.contains(Cursor cursor);

- Vrne `true`, če ta obseg vsebuje položaj kazalke, sicer `false`.

    bool Range.contains(Range other);

- Vrne `true`, če ta obseg vsebuje obseg `other`, sicer `false`.

    bool Range.containsColumn(int column);

- Vrne `true`, če je `stolpec` v pol odprtem intervalu `[start.column, end.column]`, sicer `false`.

    bool Range.containsLine(int line);

- Vrne `true`, če je `line` v pol odprtem intervalu `[start.line, end.line]`, sicer `false`.

    bool Range.overlaps(Range other);

- Vrne `true`, če imata ta obseg in obseg `other` skupno regijo, sicer `false`.

    bool Range.overlapsLine(int line);

- Vrne `true`, če je `line` v intervalu `[start.line, end.line]`, sicer `false`.

    bool Range.overlapsColumn(int column);

- Vrne `true`, če je `column` v intervalu `[start.column, end.column]`, sicer `false`.

    bool Range.equals(Range other);

- Vrne `true`, če sta ta obseg in obseg `other` enaka, sicer `false`.

    String Range.toString();

- Vrne obseg kot niz v obliki `Range(Cursor(line,column) - Cursor(line,column))`.

### Pogled API

Kadarkoli se izvaja skript, obstaja globalni objekt (spremenljivka) `pogled`, ki predstavlja trenutni aktivni pogled urejevalnika. Vse funkcije `pogleda` delujejo s položaji kazalca ali izbranim besedilom. Sledi seznam vseh razpoložljivih `pogledov` funkcij.

    void view.backspace();

- Programsko izvede enakovredno pritisku tipke vračalka.

    Cursor view.cursorPosition();

- Vrne trenutni položaj kazalca v pogledu.

    void view.setCursorPosition(int line, int column);
    void view.setCursorPosition(Cursor cursor);

- Nastavi trenutni položaj kazalca bodisi na `vrstico`, `stolpec` ali na dani `kurzor`.

    void view.cursorLeft();

- Premakne kazalec eno mesto nazaj v besedilu.

    void view.cursorRight();

- Premakne kazalec eno mesto naprej v besedilu.

    void view.cursorUp();

- Premakne kazalec eno vrstico navzgor v dokumentu.

    void view.cursorDown();

- Premakne kazalec eno vrstico navzdol v dokumentu.

    int view.cursorLine();

- Vrne vrstico, v kateri se trenutno nahaja kazalec.

    int view.cursorColumn();

- Vrne stolpec, v katerem se trenutno nahaja kazalec.

    void view.setCursorLine(int line);

- Nastavi vrstico kazalca na dano `vrstico`.

    void view.setCursorColumn(int column);

- Nastavi stolpec kazalca na podani `stolpec`.

    Cursor view.virtualCursorPosition();

- Pridobi trenutni virtualni položaj kazalca.Navidezno pomeni, da šteje tabulatorski znak (TAB).več znakov, kot jih konfigurira uporabnik (npr.en TAB je 8 presledkov). Položaj navideznega kazalca omogoča dostop douporabniško vidne vrednosti trenutnega položaja kazalca.

    bool view.hasSelection();

- Vrne `true`, če ima pogled izbrano besedilo, sicer `false`.

    String view.selectedText();

- Vrne izbrano besedilo. Če besedilo ni izbrano, je vrnjen prazni niz.

    Range view.selectionRange();

- Vrne izbrani obseg besedila. Vrnjeni obseg je neveljaven, če ni izbranega besedila.

    void view.setSelection(Range range);

- Nastavi izbrano besedilo na podani `obseg`.

    void view.selectAll();

- Izbere celotno besedilo v dokumentu.

    void view.clearSelection();

- Počisti izbor besedila brez odstranitve besedila.

    void view.removeSelectedText();

- Odstrani izbrano besedilo. Če pogled nima izbranega besedila, to ne naredi ničesar.

    void view.selectLine();

- Izbere besedilo v trenutni vrstici.

    void view.selectLine(int line);

- Izbere besedilo v dani `vrstici`.

    void view.selectLines(int from, int to);

- Izbere celotno besedilo od vrstice `od` do vrstice `do`.

    void view.selectWord();

- Izbere trenutno besedo. Če na trenutnem položaju kazalca ni najdene besede, ne naredi ničesar.

    void view.selectLatexCommand();

- Izbere trenutni &latex; ukaz. Če na trenutnem položaju kazalca ni nobenega ukaza, ne naredi ničesar.

    void view.selectEnvironment(bool inside = false);

- Izbere celotno besedilo trenutnega &latex; okolja. Če je `inside` `false`, bo izbrano okolje besedila, vključno z okolico &latex; oznake `\begin{...}...\end{...}`, sicer brez teh oznak. Če ni podanega parametra, `inside` je nastavljen na `false`.

    void view.selectTexgroup(bool inside = true);

- Izbere besedilo trenutne &latex; grupe. Če je `inside` `true`, bo izbrana samo besedilna skupina brezokoliških oklepajev. Če parameter ni podan, je `inside` nastavljen na `true`.

    void view.selectMathgroup();

- Izbere besedilo trenutne matematične skupine.

    void view.selectParagraph(bool wholeLines = true);

- Izbere celotno besedilo trenutnega &latex; odstavka. Če je `wholeLines` `true`, bodo prve in zadnje vrstice odstavka v celoti vključene v izbor (vključno z znakom za konec vrstice); sicer bo izbor samo vseboval znake, ki niso presledni znaki.

### API dokumenta

Kadarkoli se izvaja skript, obstaja globalni objekt (spremenljivka) `dokument`, ki predstavlja trenutni aktivni dokument. Sledi seznam vseh razpoložljivih funkcij `document`.

    void document.insertText(String text);

- Vstavi `text` na trenutni položaj kazalke.

    void document.insertText(int line, int column, String text);
    void document.insertText(Cursor cursor, String text);

- Vstavi `text` na dani položaj kazalke.

    bool document.removeText(int fromLine, int fromColumn, int toLine, int toColumn);
    bool document.removeText(Cursor from, Cursor to);
    bool document.removeText(Range range);

- Odstrani besedilo v danem obsegu. Vrne `true` pri uspehu ali `false`, če je dokument v načinu samo za branje.

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

- Zamenjaj besedilo podanega obsega s podanim besedilom.

    int document.lines();

- Vrne število vrstic v dokumentu.

    int document.length();

- Vrne število znakov v dokumentu.

    Dokument obsega.documentRange();

- Vrne obseg, ki zajema celotni dokument.

    Cursor document.documentEnd();

- Vrne trenutni položaj kazalca na koncu dokumenta.

    String document.text();

- Vrne celotno vsebino dokumenta v enem besedilnem nizu. Nove vrstice so označene z znakom za novo vrstico `\n`.

    String document.text(int fromLine, int fromColumn, int toLine, int toColumn);
    String document.text(Cursor from, Cursor to);
    String document.text(Range range);

- Vrne besedilo v danem obsegu. Priporočljivo je, da uporabite kazalec inrazličica na podlagi obsega za boljšo berljivost izvorne kode.

    bool document.setText(String text);

- Nastavi celotno besedilo dokumenta.

    bool document.clear();

- Odstrani celotno besedilo v dokumentu.

    String document.line();

- Vrne trenutno besedilno vrstico kot niz.

    String document.line(int line);

- Vrne dano besedilno vrstico kot niz. Niz je prazen, če je zahtevana vrstica izven obsega.

    int document.lineLength();

- Vrne dolžino trenutne vrstice.

    int document.lineLength(int line);

- Vrne dolžino `vrstice`.

    bool document.insertLine(String s);

- Vstavi besedilo v trenutno vrstico. Vrne `true` pri uspehu ali `false`, če je dokument v načinu samo za branje ali če vrstica ni v obsegu dokumenta.

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

- Vstavi besedilo v dano vrstico. Vrne `true` ob uspehu,ali `false`, če je dokument v načinu samo za branje alivrstica ni v obsegu dokumenta.

    bool document.removeLine();

- Odstrani trenutno vrstico besedila. Vrne `true` ob uspehu, ali `false`, če je dokument v načinu samo za branje.

    bool document.removeLine(int line);

- Odstrani dano vrstico besedila. Vrne `true` ob uspehu ali `false`, če je dokument v načinu samo za branje ali če vrstica ni v obsegu dokumenta.

    bool document.replaceLine(String text);

- Zamenjaj besedilo trenutne vrstice s podanim besedilom.

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

- Zamenjaj besedilo dane vrstice s podanim besedilom.

    bool document.truncateLine();

- Obreže trenutno vrstico na danem stolpcu ali položaju kazalca. Vrne `true` ob uspehu ali `false`, če podana vrstica ni del obsega dokumenta.

    bool document.truncate(int line, int column);
    bool document.truncate(Cursor cursor);

- Odreže dano vrstico na danem stolpcu ali položaju kazalca. Vrne `true` ob uspehu ali `false`, če podana vrstica ni del obsega dokumenta.

    String document.word();

- Vrne besedo na trenutnem položaju kazalca. Če ni najdene besede na položaju kazalca, je vrnjeni niz prazen.

    String document.wordAt(int line, int column);
    String document.wordAt(Cursor cursor);

- Vrne besedo na danem položaju kazalca. Če tam ni najdene besede na položaju kazalca, je vrnjeni niz prazen.

    Range document.wordRange();

- Vrne obseg besede na danem položaju kazalca. Če besede ni najdene, je vrnjen `Range.invalid()`, kar je mogoče preizkusiti z `Range.isValid()`.

    String document.latexCommand();

- Vrne &latex; ukaz na trenutnem položaju kazalca. Če ni najdenega ukaza na tem položaju kazalca, je vrnjeni niz prazen.

    String document.latexCommandAt(int line, int column);
    String document.latexCommandAt(Cursor cursor);

- Vrne &latex; ukaz na danem položaju kazalca. Če ni najdenega ukaza na tem položaju kazalca, je vrnjeni niz prazen.

    Range document.latexCommandRange();

- Vrne obseg &latex; ukazov na danem položaju kazalca. Če ni najdenega nobenega ukaza &latex;, je vrnjen `Range.invalid()`, ki ga je mogoče preizkusiti z `Range.isValid()`.

    String document.charAt(int line, int column);
    String document.charAt(Cursor cursor);

- Vrne znak na danem položaju kazalca.

    String document.firstChar(int line);

- Vrne prvi znak v dani `vrstici`, ki ni beli prostor. Prvi znak je v stolpcu 0. Če je vrstica prazna ali vsebuje le beli prostor, je vrnjeni niz prazen.

    String document.lastChar(int line);

- Vrne zadnji znak v dani `vrstici`, ki ni beli prostor. Če je vrstica prazna ali vsebuje samo beli prostor, je vrnjeni niz prazen.

    bool document.isSpace(int line, int column);
    bool document.isSpace(Cursor cursor);

- Vrne `true`, če je znak na danem položaju kazalca beli prostor, sicer `false`.

    void document.insertBullet();

- Vstavi &kile; oznako. Ne pozabite, da lahko preprosto skoči na naslednjo ali prejšnjo oznako. To bo tudi poudarilo to oznako, da se samodejno izbriše, ko vnesete prvo črko.

    void document.nextBullet();

- Skoči na naslednjo oznako v besedilu, če obstaja.

    void document.previousBullet();

- Skoči na prejšnjo oznako v besedilu, če obstaja.

    bool document.hasEnvironment();

- Vrne `true`, če je najdeno okolje &latex;, sicer `false`.

    String document.environment(bool inside = false);

- Vrne celotno besedilo obkrožajočega &latex; okolja. Če je `inside` `false`, bo izbrano okolje besedila, vključno z okoljem &latex; oznake `\begin{...}...\end{...}`, sicer brez teh oznak. Če ni podanega parametra, je `inside` nastavljen na `false`. Če ni najdenega nobenega okolja, je vrnjeni niz prazen.

    Range document.environmentRange(bool inside = false);

- Vrne obseg obkroženega &latex; okolja. Če je `inside` `false`, obsegvključno z okolico &latex; bodo vrnjene oznake `\begin{...}...\end{...}`, sicer brez teh oznak. Če parameter ni podan, je `inside` nastavljen na `false`. Čeni najdeno nobeno okolje, je vrnjen `Range.invalid()`, ki ga je mogoče preizkusiti z `Range.isValid()`.

    String document.environmentName();

- Vrne ime obkrožujočega &latex; okolja ali prazen niz.

    void document.removeEnvironment(bool inside = false);

- Odstrani besedilo obkrožujočega &latex; okolja. Če je `inside` `false`, bo besedilo okolja, vključno z okolico &latex; oznake `\begin{...}...\end{...}` odstranjeno, sicer brez teh oznak. Če parameter ni podan, je `inside` nastavljen na `false`.

    void document.closeEnvironment();

- Vstavite zaključno oznako okolja, če je odprt &latex; okolje se nahaja na trenutnem položaju kazalca.

    void document.closeAllEnvironments();

- Vstavi zaključne oznake okolja za vse odprte &latex; okolja, ki so bila najdena na trenutnem položaju kazalca.

    bool document.hasTexgroup();

- Vrne `true`, če okolica &latex; skupina je najdena na trenutnem položaju kazalca, sicer `false`.

    String document.texgroup(bool inside = true);

- Vrne besedilo okoliškega &latex; skupina. Če je `inside` `false`, je besedilo tega &latex; skupina, vključno z okoliškimi oklepaji `{...}`, bo vrnjena, sicer brez njih. Če parameter ni podan, je `inside` nastavljen na `false`. Vrnjeni niz je prazen, če v okolici &latex; skupina je na trenutnem položaju kazalca.

    Range document.texgroupRange(bool inside = true);

- Vrne obseg okolice &latex; skupina. Če je `inside` `false`, bo vrnjen obseg, vključno z okoliškimi oklepaji `{...}`, drugače pa brez njih. Če parameter ni podan, je `inside` nastavljen na `false`. Če ni najdena nobena skupina, je vrnjen `Range.invalid()`, ki ga je mogoče preizkusiti z `Range.isValid()`.

    void document.removeTexgroup(bool inside = true);

- Odstrani besedilo okoliškega &latex; skupina. Če je `inside` `false`, je besedilo tega &latex; skupina, vključno z okoliškimi oklepaji `{...}`, bo odstranjena, sicer brez njih. Če parameter ni podan, je `inside` nastavljen na `false`.

    bool document.hasMathgroup();

- Vrne `true`, če okolica &latex; mathgroup je najdena na trenutnem položaju kazalca, sicer `false`.

    String document.mathgroup();

- Vrne besedilo okoliškega &latex; skupina za matematiko. Vrnjeni niz je prazen, če v okolici &latex; mathgroup se nahaja na trenutnem položaju kazalca.

    Range document.mathgroupRange();

- Vrne obseg okolice &latex; skupina za matematiko. Če ni okoliške matematične skupine, se vrne `Range.invalid()`, kar je mogoče preizkusiti z `Range.isValid()`.

    void document.removeMathgroup();

- Odstrani besedilo okoliškega &latex; skupina za matematiko.

    String document.paragraph();

- Vrne besedilo trenutnega &latex; odstavek.

    Range document.paragraphRange();

- Vrne obseg okolice &latex; odstavek.

    void document.removeParagraph();

- Odstrani besedilo trenutnega &latex; odstavek.

    bool document.matchesAt(int line, int column, String text);
    bool document.matchesAt(Cursor cursor, String text);

- Vrne `true`, če se podani `besedilo` ujema na ustreznem položaju kazalke, sicer `false`.

    bool document.startsWith(int line, String pattern, bool skipWhiteSpaces = true);

- Vrne `true`, če se vrstica začne z `pattern`, sicer `false`. Argument `skipWhiteSpaces` nadzira, ali se vodilni presledki prezrejo.

    bool document.endsWith(int line, String pattern, bool skipWhiteSpaces = true);

- Vrne `true`, če se vrstica konča z `pattern`, sicer `false`. Argument `skipWhiteSpaces` nadzira, ali se končni presledki prezrejo.

    int document.firstColumn(int line);

- Vrne prvi stolpec brez presledkov v dani `vrstici`. Če je v vrstici samo beli prostor, je vrnjena vrednost `-1`.

    int document.lastColumn(int line);

- Vrne zadnji stolpec nebelega prostora v dani `vrstici`. Če so v vrstici samo beli prostor, je vrnjena vrednost `-1`.

    int document.prevNonSpaceColumn(int line, int column);
    int document.prevNonSpaceColumn(Cursor cursor);

- Vrne stolpec z znakom brez presledka, ki se začne na danem položaju kazalke in išče nazaj.

    int document.nextNonSpaceColumn(int line, int column);
    int document.nextNonSpaceColumn(Cursor cursor);

- Vrne stolpec z znakom brez presledka, ki se začne na danem položaju kazalke in išče naprej.

    int document.prevNonEmptyLine(int line);

- Vrne naslednjo neprazno vrstico, ki vsebuje znake, ki niso presledki, pri iskanju nazaj.

    int document.nextNonEmptyLine(int line);

- Vrne naslednjo neprazno vrstico, ki vsebuje znake, ki niso presledki, pri iskanju naprej.

    void document.gotoBeginEnv();

- Pojdite na začetek okoliškega &latex; okolju.

    void document.gotoEndEnv();

- Pojdite na konec okoliškega &latex; okolju.

    void document.gotoBeginTexgroup();

- Pojdite na začetek okoliškega &latex; skupina.

    void document.gotoEndTexgroup();

- Pojdite na konec okoliškega &latex; skupina.

    void document.gotoNextParagraph();

- Pojdi na naslednji &latex; odstavek.

    void document.gotoPrevParagraph();

- Pojdi na prejšnji &latex; odstavek.

    void document.gotoNextSectioning();

- Pojdi na naslednji &latex; razdelek.

    void document.gotoPrevSectioning();

- Pojdi na prejšnji &latex; razdelek.

    void document.gotoLine(int line);

- Pojdi na dano `vrstico`.

    void document.insertChapter();

- Vstavite ukaz `\chapter` (glejte tudi `document.insertSection()`).

    void document.insertSection();

- Vstavite ukaz `\section`. Tako kot pri izbiri menijskega vnosa LaTeX Sectioning section se prikaže pogovorno okno, kjer lahko izberete naslov in neobvezna oznaka za ta ukaz za razdeljevanje. Pogovorno okno: ukaz za vstavljanje poglavja Pogovorno okno: ukaz za vstavljanje poglavja

    void document.insertSubsection();

- Vstavite ukaz `\subsection` (glejte tudi `document.insertSection()`).

    void document.insertSubsubsection();

- Vstavite ukaz `\subsubsection` (glejte tudi `document.insertSection()`).

    void document.insertParagraph();

- Vstavite ukaz `\paragraph` (glejte tudi `document.insertSection()`).

    void document.insertSubparagraph();

- Vstavi ukaz `\subparagraph` (glejte tudi `document.insertSection()`).

    void document.insertLabel();

- Vstavi ukaz `\label`.

    void document.insertReference();

- Vstavite ukaz `\ref`. Tako kot pri izbiri menijskega vnosa &latex;Reference ref se prikaže pogovorno okno, kjer lahko izbirate med že definiranimi oznake, ki so navedene v kombiniranem polju. Pogovorno okno: vstavi referenčni ukaz Pogovorno okno: vstavi referenčni ukaz

    void document.insertPageref();

- Vstavite ukaz `\pageref` (glejte tudi `document.insertReference()`).

    void document.insertCitation();

- Vstavite ukaz `\cite`.

    void document.insertIndex();

- Vstavite ukaz `\index`.

    void document.insertFootnote();

- Vstavite ukaz `\footnote`.

    void document.comment();

- Vstavi označevalce komentarjev, da izbor ali trenutna vrstica postane komentar.

    void document.uncomment();

- Odstrani oznake komentarjev iz izbrane ali trenutne vrstice.

    void document.uppercase();

- Postavi izbrano besedilo ali črko za kazalcem v velike črke.

    void document.lowercase();

- Postavi izbrano besedilo ali črko za kazalcem v male črke.

    void document.capitalize();

- Napiši izbrano besedilo ali trenutno besedo z veliko začetnico.

    void document.joinLines();

- Združi vrstice trenutnega izbora. Dve zaporedni vrstici besedila sta vedno ločeni z enim presledkom.

    void document.insertIntelligentNewline();

- Vstavite pametno novo vrstico (glejte editing_smartnewline).

    void document.insertIntelligentTabulator();

- Vstavi pametni tabulator (glejte editing_tabulator).

    void document.editBegin();

- Zažene skupino za urejanje za razveljavitev/uveljavitev združevanja. Poskrbite, da vedno pokličete`editEnd()` tako pogosto, kot pokličete `editBegin()`. Interni klic `editBegin()` uporablja števec referenc, tj. ta klic je lahko ugnezden..

    void document.editEnd();

- Konča skupino za urejanje. Zadnji klic `editEnd()` (tj. tisti za prvi klic `editBegin()`) zaključi korak urejanja.

    StringList document.labelList();

- Vrne vse definirane oznake kot seznam nizov `StringList` , kar je lahko uporabljeno v &javascript; kot polje nizov.

    StringList document.bibitemList();

- Vrne vse definirane elemente bibliografije bibitems kot `StringList`, ki lahko je lahko uporabljen v &javascript; kot polje nizov.

    void document.refreshStructure();

- Osveži pogled strukture (glejte navigating).

### API za &kile;

Globalni objekt (spremenljivka) `kile` se uporablja za obdelavo interakcije na najvišji ravni z zunanjim svetom, vhodno sporočilo in vmesnike dialoga. Ti klici API-ja so razdeljeni na podobjekte, da se to strukturira kot del skriptnega API-ja. Konceptualno je `kile` malo podoben `oknu` brskalnika v API-ju.

- `kile.alert`: message boxes

- `kile.input`: get user input

- `kile.wizard`: call one of &kile;'s wizards

- `kile.script`: get info about a running script

- `kile.file`: file operations like read and write.

#### Opozorilo

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

- Prikaži pogovorno okno Informacije. `text` je niz sporočila in `caption` naslov sporočilnega polja. Privzeti naslov je ime skripta.

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

- Prikaži pogovorno okno Sorry. `text` jeniz sporočila in `caption` naslov polja za sporočila. Privzeti naslov je ime skripta.

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

- Prikaži pogovorno okno Error. `text` jeniz sporočila in `caption` naslov polja za sporočila. Privzeti naslov je ime skripta.

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

- Prikaži pogovorno okno question. `text` jeniz sporočila in `caption` naslov polja za sporočila. Privzeti naslov je ime skripta. Vrnjen niz je `yes` ali `no`.

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

- Prikaži pogovorno okno warning. `text` jeniz sporočila in `caption` naslov polja za sporočila. Privzeti naslov je ime skripta. Vrnjen niz je `continue` ali `cancel`.

#### Vnos

    String kile.input.getListboxItem(String caption, String label, StringList list);

- Funkcija, ki omogoča uporabniku, da izbere element s seznama, ki je prikazan kot seznamsko polje. `caption` je besedilo, ki je prikazano v naslovni vrstici, `label` je besedilo, ki se prikaže kot oznaka za seznam in `list` je seznam nizov, ki je vstavljen na seznam.

    String kile.input.getComboboxItem(String caption, String label, StringList list);

- Funkcija, ki omogoča uporabniku, da izbere element s seznama, ki je prikazan kot kombinirano polje. `caption` je besedilo, ki je prikazano v naslovni vrstici, `label` je besedilo, ki se prikaže kot oznaka za seznam in `list` je seznam nizov, ki je vstavljen na seznam.

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

- Funkcija za pridobitev niza od uporabnika. `caption` jebesedilo, ki je prikazano v naslovni vrstici in `label`besedilo, ki se prikaže kot oznaka za urejanje vrstice.

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

- Funkcija za pridobitev &latex; ukaz od uporabnika. To pomeni, da so dovoljene le male in velike črke. `caption` je besedilo, ki je prikazano v naslovni vrstici in `label` besedilo, ki se pojavi kot oznaka za urejanje vrstice.

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

- Funkcija za pridobitev celega števila od uporabnika. `caption` jebesedilo, ki je prikazano v naslovni vrstici. `label` jebesedilo, ki se pojavi kot oznaka vrtilnega polja. `min` in `max` sta minimum in maksimumdovoljene vrednosti, ki jih uporabnik lahko izbere. Privzete vrednosti so `INT_MIN` in `INT_MAX`.

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

- Funkcija za pridobitev pozitivnega celega števila od uporabnika. `caption` je besedilo, ki je prikazano v naslovni vrstici. `label` je besedilo, ki se pojavi kot oznaka vrtilnega polja.`min` in `max` sta minimumin največje dovoljene vrednosti, ki jih uporabnik lahko izbere. Privzete vrednosti so`1` in `INT_MAX`.

#### Čarovnik

    void kile.wizard.tabular();

- Prikliče čarovnika za tabele, ki pomaga napisati tabelarično okolje (glejte wizard_array).

    void kile.wizard.array();

- Prikliče čarovnika za matriko, ki pomaga napisati okolje matrike (glejte wizard_array).

    void kile.wizard.tabbing();

- Prikliče čarovnika za zavihke, ki pomaga napisati okolje za zavihke (glejte wizard_array).

    void kile.wizard.floatEnvironment();

- Prikliče čarovnika za lebdeče, ki pomaga pri vstavljanju plavajočih elementov (glejte wizard_float).

    void kile.wizard.mathEnvironment();

- Prikliče čarovnika za matematiko, ki pomaga pri vstavljanju matematičnih okolij (glejte wizard_math).

    void kile.wizard.postscript();

- Prikliče čarovnika za orodja Postscript, ki lahko pomaga pri manipulaciji ali preurejanju dokumentov Postscript (glejte wizard_postscript).

#### Skript

    String kile.script.name();

- Vrne osnovno ime delujočega skripta (brez poti in razširitve).

    String kile.script.caption();

- Vrne niz, ki se lahko uporabi kot napis opozorilnih polj. Videti je kot `Script: scriptname.js`.

#### Datoteka

    Object kile.file.read(String filename);

- Prebere vsebino besedilne datoteke. Uporablja se kot

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

  Povrnjena vrednost `res` je objekt (bolje: mapa) s tremi lastnostmi:

  - status: Poda statusno kodo operacije, ki je lahko 0 (ni napake), 1 (dostop ni uspel) ali 2 (dostop zavrnjen). Torej, če ni prišlo do napake, vrednost `res.status` oz.`res["status"]` bo 0.

  - result: Vsebuje besedilo dane datoteke.

  - message: Vsebuje sporočilo o napaki, če je prišlo do napake.

    Object kile.file.read();

- Enako kot `read(filename)`, vendar ime datoteke ni navedeno. Aprikaže se pogovorno okno za izbiro datoteke za branje.

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

- Zapiše dano besedilo v datoteko. Uporablja se kot

  Primer: `var res = kile.file.write("path/to/file.txt","Some text...");`

  Povratna vrednost `res` je objekt (bolje: mapa)z dvema lastnostma: `status` in `message` (za več informacij glejte `read()`).

    Object kile.file.write(String text);

- Enako kot `write(filename,text)`, vendar ni dano nobeno ime datoteke. Prikaže se pogovorno okno za izbiro imena datoteke.

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

- Ustvari modalno pogovorno okno datoteke in vrne izbrano ime datoteke ali prazen niz, če ni izbrana nobena. Upoštevajte, da mora pri tej metodi uporabnik izbratiobstoječe ime datoteke.

  Parametri:

  - startDir: Začetni imenik odprtega pogovornega okna.

  - filter: Shell glob ali filter tipa mime, ki določa, katere datoteke naj se prikažejo. Glejte dokumentacijo KFileDialog za več informacij o tem parametru.

  Oba parametra sta neobvezna. Če izpustite `filter`, bodo prikazane vse datoteke. Če je poleg tega izpuščen `startDir`, bo pogovorno okno vzelo trenutni imenik dokumentov kot začetno točko.

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

- Ustvari modalno pogovorno okno datoteke in vrne izbrano ime datoteke ali prazen niz, če ni izbran noben. Upoštevajte, da pri tej metodi uporabniku ni treba izbrati obstoječe ime datoteke. Oglejte si `getOpenFileName()` za razlago parametrov.

## Primeri

Nekateri primeri vam lahko pomagajo razumeti, kako uporabljati API za skripte. Teprimere in še nekaj več najdete v skriptnem imeniku &kile;: `KILE_APP_DIR/scripts/`. Vsak scenarij vsebuje kratek opis.

### Primer 1: zamenjajte ime okolja

Zamenjajte okolico &latex; okolja z drugo, kjer relativni položaj kazalca ne bo spremenjen. `\begin{abc}...\end{abc}` na primer lahko spremenite v `\begin{xyz}...\end{xyz}`.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Enter Environment","New environment name:");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("No surrounding LaTeX environment found.");
    }

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

### Primer 2: zamenjava &latex; ukaz pisave

Zamenjajte okolico &latex; ukaz pisave z drugim ukazom pisave, ko je kazalec postavljen znotraj besedilne skupine. Relativni položaj kazalca ne bo bo spremenjen. `\textbf{abc}` lahko na primer spremenite v `\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("No surrounding TeX group found.");
    }

    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("No surrounding font command found.");
            }
            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;
    }

### Primer 3: obdaj izbrano besedilo

Obkrožite izbrano besedilo z ukazom TeX, kjer relativni položaj kazalca ne bo spremenjen. `abc` lahko na primer spremenite v `\texcommand{abc}`.

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand("Choose","Choose surrounding LaTeX command:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("No selection found.");
    }

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