# Écrire des scripts

## Écrire des scripts dans &kile;

Le module d'écriture de script de &kile; permet l'exécution de code ECMAScript, largement connu sous le nom de &javascript;. Vous trouverez beaucoup de tutoriels, fournissant des informations sur les objets (variables), fonctions et propriétés gérés par &javascript;.

La prise en charge des scripts peut être activée dans la boîte de configuration de &kile; : Configuration Configurer Kile… Kile Scripts. Activer ou désactiver la prise en charge des scripts Activer ou désactiver la prise en charge des scripts

Si la prise en charge des scripts est activée, un panneau supplémentaire dédié aux scripts apparaît dans le panneau latéral, où les scripts peuvent être gérés : Panneau dédié aux scripts dans le panneau latéral Panneau dédié aux scripts dans le panneau latéral

Ce composant graphique contient six icônes proposant différentes fonctions :

- Exécuter le script sélectionné.

- Créer un nouveau script.

- Ouvrir le script sélectionné dans l'éditeur.

- Configurer une séquence de touches (raccourci) pour le script sélectionné.

- Supprimer une séquence de touches affectée (raccourci).

- Rafraîchir la liste des scripts disponibles qui ont été trouvés dans `$`KDEDIR`/share/apps/kile/scripts/`.

## Exécution d'un script

Vous pouvez exécuter un script de trois façons différentes :

1. Sélectionner le script désiré et cliquer sur le bouton Exécuter sur le côté gauche du composant graphique de gestion de scripts.

   Scripts : bouton « Exécuter » Scripts : bouton « Exécuter »

2. Utiliser un raccourci clavier.

   Scripts : raccourci clavier Scripts : raccourci clavier

   Vous pouvez assigner un raccourci clavier à un script en utilisant le bouton Configurer dans le panel de gestion des scripts.

   Scripts : boîte de dialogue pour la configuration de séquences Scripts : boîte de dialogue pour la configuration de séquences

3. Utilisez un éditeur de séquences clavier. Le script sera exécuté, si vous saisissez la séquence qui lui a été assignée dans l'éditeur.

   Scripts : éditeur de séquence de caractère Scripts : éditeur de séquence de caractère

   Cette méthode peut être étendue à un type plutôt compliqué de complètement de code. Supposons que vous ayez à écrire un script qui insère simplement la commande &latex; `\textbf{}` dans le document actuel.

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

   Si vous saisissez maintenant la séquence associée de caractère `bfx` dans votre document, cette séquence sera supprimée et le script sera exécuté. Il insérera `\textbf{}` et le curseur sera placé automatiquement entre les accolades.

   Scripts : saisie d'une séquence de caractère pour l'éditeur Scripts : saisie d'une séquence de caractère pour l'éditeur

   Quelle méthode confortable et puissante de complètement de code.

## Référence de l'API

L'API de scripts présenté ici est disponible dans tous les scripts. Avant le chargement du contenu d'un script, &kile; ajoute d'abord plusieurs prototypes et fonctions dans le contexte du script. Cet API pratique, fournit des prototypes comme les curseurs de texte et les champs de texte. Il est disponible dans le dossier `KILE_APP_DIR/script-plugins/`.

Les scripts de &kile; diffèrent légèrement des scripts de &kate;, qui utilisent un autre modèle de conception, car ils sont conçus pour être aussi lancés en ligne de commande. Mais toutes les fonctions de l'API des scripts de &kate; sont aussi disponibles dans l'API des scripts &kile;. Par conséquent, le portage d'un code &javascript; de &kate; à &kile; devrait être extrêmement simple. Mais comme &kile; est un éditeur &latex; riche en fonctionnalités, ses scripts offrent bien plus de possibilités que ceux de &kate;.

Remarque : La description des appels API, qui sont aussi disponibles pour les scripts de &kate; est déjà fournie dans la documentation de &kate;.

### Fonctions générales

Cette section liste les fonctions générales.

    void debug(Chaîne texte);

- Imprime `texte` sur `stdout` dans la console. Le texte imprimé est coloré pour le distinguer des autres sorties de débogage.

### Le prototype « Cursor »

Comme &kile; est un éditeur de texte, toute l'API de scripts est fondée sur les curseurs et les champs aussi souvent que possible. Un « curseur » est un simple couple `(ligne, colonne)` représentant la position d'un texte dans le document.

    Cursor();

- Constructeur : renvoie un curseur à la position `(0 , 0)`.

  Exemple : `var curseur = new Cursor();`

    Cursor(int ligne, int colonne);

- Constructeur : retourne un curseur à la position (ligne, colonne).

  Exemple : `var curseur = new Cursor(3,42);`

    Cursor(Cursor autre);

- Constructeur de copie : renvoie une copie du curseur `autre`.

  Exemple : `var copie = new Cursor(autre) ;`

    Cursor Cursor.clone();

- Renvoie un clone du curseur.

  Exemple : `var clone = curseur.clone();`

    bool Cursor.isValid();

- Vérifie la validité du curseur. Le curseur est non valable si la ligne et / ou la colonne valent `-1`.

  Exemple : `var validité = curseur.isValid();`

    Cursor Cursor.invalid();

- Renvoie une nouvelle position de curseur non valable à la position `(-1, -1)`.

  Exemple : `var curseur-non-valable = curseur.invalid();`

    int Cursor.compareTo(Cursor autre);

- Compare ce curseur avec le curseur `autre`. Renvoie

  - `-1` si ce curseur est positionné avant le curseur `autre`,

  - `0` si les deux curseurs sont à la même position et

  - `+1` si le curseur est positionné après le curseur `autre`.

    bool Cursor.equals(Cursor autre);

- Renvoie `vrai` si le curseur appelant et le curseur `autre` sont égaux, autrement renvoie `faux`.

    String Cursor.toString();

- Renvoie le curseur comme une chaîne de caractères sous la forme `Cursor(ligne, colonne)`.

### Le prototype « Range »

Comme &kile; est un éditeur de texte, l'ensemble des API de scripts est fondée sur des curseurs et des zones lorsque cela est possible. Comme Cursor est un simple couple `(ligne, colonne)` représentant une position d'un texte dans un document, un « Range » encadre un texte entre une position de départ d'un curseur à une position de fin d'un curseur.

    Range();

- Constructeur : un appel à `new Range()` renvoie un intervalle (Range) en `(0,0) - (0,0)`.

    Range(Cursor début, Cursor fin);

- Constructeur : un appel à `new Range(`début`, `fin`)`, renvoie la plage à partir du curseur `début` au curseur `fin`.

    Range(int début-Ligne, int début-Colonne, int fin-Ligne, int fin-Colonne);

- Constructeur : un appel à `new Range(`début-Ligne`,`début-Ligne`,`début-Colonne`, `fin-Colonne`)` renvoie le Range à partir de (`début-Ligne`, `début-Colonne`) à (`fin-Ligne`, `fin-Colonne`).

    Range(Range autre);

- Constructeur de copie : renvoie une copie de l'intervalle `autre`.

    Range Range.clone();

- Renvoie un clone de l'intervalle.

  Exemple : `var clone = intervalle.clone();`

    bool Range.isValid();

- Renvoie `vrai` si les deux curseurs « début » et « fin » sont valables, sinon `faux`.

  Exemple : `var valid = intervalle.isValid();`

    bool Range.invalid();

- Renvoie le Range de (-1, -1) à (-1, -1).

    bool Range.contains(Cursor curseur);

- Renvoie `vrai` si cette plage contient la position du curseur, sinon `faux`.

    bool Range.contains(Range autre);

- Renvoie `vrai` si la plage contient Range `autre`, sinon `faux`.

    bool Range.containsColumn(entier colonne);

- Renvoie `vrai` si `colonne` est à la moitié de l'intervalle ouvert `[début.column, fin.column]`, sinon `faux`.

    bool Range.containsLine(intligne);

- Renvoie `vrai` si `ligne` est à la moitié de l'intervalle ouvert `[début.line, fin.line]`, sinon `faux`.

    bool Range.overlaps(Range autre);

- Renvoie `vrai` si cette plage et la plage `autre` partagent une région commune, sinon `faux`.

    bool Range.overlapsLine(int ligne);

- Renvoie `vrai` si `ligne` est dans l'intervalle`[début.line, fin.line]`, sinon `faux`.

    bool Range.overlapsColumn(int colonne);

- Renvoie `vrai` si `colonne` est dans l'intervalle `[début.column, fin.column]`, sinon `faux`.

    bool Range.equals(Range autre);

- Renvoie `vrai` si cette plage et la plage `autre` sont égales, sinon `faux`.

    String Range.toString();

- Renvoie la plage comme une chaîne de caractères de la forme`Range(Cursor(ligne, colonne) - Cursor(ligne, colonne))`.

### L'API d'affichage

À chaque fois qu'un script est exécuté, il y a un objet global (variable) `view` représentant la vue de l'actuel éditeur actif. Toutes les fonction de `view` fonctionnent avec les positions d'un curseur ou du texte sélectionné. La liste de toutes les fonctions disponibles de `view` est donnée ci-dessous.

    void view.backspace();

- Réalise l'équivalent à un appui sur la touche « Retour arrière ».

    Cursor view.cursorPosition();

- Retourne la position du curseur courant dans la vue.

    void view.setCursorPosition(int ligne, int colonne);
    void view.setCursorPosition(Cursor curseur);

- Définit la position du curseur courant en position `ligne`, `colonne` ou à la position donnée par `curseur`.

    void view.cursorLeft();

- Déplace le curseur d'une position en arrière du texte.

    void view.cursorRight();

- Déplace le curseur d'une position vers l'avant dans le texte.

    void view.cursorUp();

- Déplace le curseur d'une ligne vers le haut dans le document.

    void view.cursorDown();

- Déplace le curseur d'une ligne vers le bas dans le document.

    int view.cursorLine();

- Renvoie la ligne où se trouve actuellement le curseur.

    int view.cursorColumn();

- Renvoie la colonne de la position du curseur courant.

    void view.setCursorLine(int ligne);

- Définit la ligne du curseur à la valeur `ligne`.

    void view.setCursorColumn(int colonne);

- Définit la colonne du curseur à la valeur `colonne`.

    Cursor view.virtualCursorPosition();

- Lit la position courante du curseur virtuel. Virtuel signifie que le caractère de tabulation (TAB) compte pour plusieurs caractères, selon la configuration choisie par l'utilisateur (par exemple une tabulation (TAB) vaut 8 espaces). La position du curseur virtuel permet l'accès aux valeurs visibles par l'utilisateur de la position du curseur courant.

    bool view.hasSelection();

- Renvoie `vrai`, si la vue possède du texte sélectionné, auquel cas `faux`.

    String view.selectedText();

- Renvoie le texte sélectionné. Si aucun texte n'est sélectionné, la chaîne de caractères vide est renvoyée.

    Range view.selectionRange();

- Renvoie la plage de texte sélectionné. La plage renvoyée n'est pas valable si aucun texte n'est sélectionné.

    void view.setSelection(Range intervalle);

- Définit le texte sélectionné comme valant `intervalle`.

    void view.selectAll();

- Sélectionne la totalité du texte du document.

    void view.clearSelection();

- Efface la sélection sans supprimer le texte.

    void view.removeSelectedText();

- Supprime le texte sélectionné. Si la vue ne posséde aucun texte sélectionné, rien n'est fait.

    void view.selectLine();

- Sélectionne le texte dans la ligne courante.

    void view.selectLine(int ligne);

- Sélectionne le texte à la ligne donnée par `ligne`.

    void view.selectLines(int partir-de, int jusqu-a);

- Sélectionne tout le texte de la ligne `partir-de` jusqu'à la ligne `jusqu-a`.

    void view.selectWord();

- Sélectionne le mot courant. Si aucun mot n'a été trouvé à la position du curseur courant, rien n'est fait.

    void view.selectLatexCommand();

- Sélectionne la commande &latex; courante. Si aucune commande n'a été trouvée à la position du curseur courant, rien n'est fait.

    void view.selectEnvironment(bool inside = false);

- Sélectionne la totalité du texte de l'environnement &latex; courant. Si `dedans` est à `faux`, le texte de l'environnement, y compris les balises &latex; d'encadrement, `\begin{…}… \end{…}` sera sélectionné ; sinon seule le texte sans ces balises sera sélectionné. Si aucun paramètre n'est donné, `dedans` est positionné à `faux`.

    void view.selectTexgroup(bool dedans = true);

- Sélectionnez le texte du groupe &latex; courant. Si `dedans` est `vrai`, seul le groupe texte sans les accolades qui autour sera sélectionné. Si aucun paramètre n'est renseigné, `inside` est à `vrai`.

    void view.selectMathgroup();

- Sélectionne le texte de l'actuel groupe mathématique.

    void view.selectParagraph(bool wholeLines = true);

- Sélectionnez la totalité du texte du paragraphe &latex; courant. Si `Lignes-entières` est `vrai`, seules les première et dernière lignes du paragraphe seront prises en compte comme sélection (y compris le caractère de fin de ligne). Dans le cas contraire, la sélection ne contiendra que les caractères différents d'une espace.

### La documentation de l'API

Lorsqu'un script est en exécution, il y a un objet global (variable) `document` représentant le document actif courant. La liste de toutes fonctions disponibles de `document` est fournie ci-dessous.

    void document.insertText(String texte);

- Insère le `texte` à la position courante du curseur.

    void document.insertText(int ligne, int colonne, String texte);
    void document.insertText(Cursor curseur, String texte);

- Insère le `texte` à la position donnée du curseur.

    bool document.removeText(int de-La-Ligne, int de-La-Colonne, int a-La-Ligne, int a-La-Colonne);
    bool document.removeText(Cursor a-partir-de, Cursor jusqu-a);
    bool document.removeText(Range plage);

- Supprime le texte contenu dans la plage spécifiée. Renvoie `vrai` en cas de succès ou `faux`, si le document est en lecture seule.

    bool document.replaceText(Range plage, String texte);

- Remplace le texte de la plage donnée avec le texte spécifié.

    int document.lines();

- Renvoie le nombre total de lignes du document.

    int document.length();

- Retourne le nombre de caractères dans le document.

    Range document.documentRange();

- Renvoie la plage qui encapsule la totalité du document.

    Cursor document.documentEnd();

- Renvoie la position courante du curseur de fin de document.

    String document.text();

- Renvoie la totalité du contenu du document dans une seule chaîne de caractères. Les nouvelles lignes sont indiqué par le caractère de nouvelle ligne `\n`.

    String document.text(int de-Ligne, int de-Colonne, int a-Ligne, int a-Colonne);
    String document.text(Cursor a-partir-de, Cursor jusqu-a);
    String document.text(Range plage);

- Renvoie le texte contenu dans la plage donnée. Il est recommandé d'utiliser la version utilisant un curseur et une plage pour avoir une meilleure lisibilité du code source.

    bool document.setText(String texte);

- Définit le texte pour la totalité du document.

    bool document.clear();

- Supprime la totalité du texte dans le document.

    String document.line();

- Renvoie le texte de la ligne courante comme une chaîne de caractères.

    String document.line(int ligne);

- Renvoie le texte de la ligne donnée comme une chaîne de caractères. La chaîne de caractères vide est renvoyée si la ligne demandée est en dehors de la plage.

    int document.lineLength();

- Renvoie la longueur de la ligne courante.

    int document.lineLength(int ligne);

- Renvoie la longueur de `ligne`.

    bool document.insertLine(String chaîne);

- Insère « texte » dans la ligne courante. Retourne `vrai` en cas de succès ou `faux`, si le document est en lecture seul ou sila ligne n'est pas dans la plage du document.

    bool document.insertLine(int ligne, String chaîne);

- Insère « texte » dans la ligne spécifiée. Retourne `vrai` en cas de succès ou `faux`, si le document est en lecture seule ou la ligne n'est pas dans la plage du document.

    bool document.removeLine();

- Supprime la ligne courante. Renvoie `vrai` en cas de succès ou `faux`, si le document est en lecture seule.

    bool document.removeLine(int ligne);

- Supprime la ligne spécifiée. Retourne `vrai` en cas de succès ou `faux`, si le document est en lecture seule ou la ligne n'est pas dans la plage du document.

    bool document.replaceLine(String texte);

- Remplace le texte de la ligne courante avec le texte spécifié.

    bool document.replaceLine(int ligne, String texte);

- Remplace le texte de la ligne donnée avec le texte spécifié.

    bool document.truncateLine();

- Tronque la ligne courante à la colonne spécifiée ou à la position du curseur. Renvoie `vrai` en cas de succès ou `faux`, si la ligne donnée n'appartient pas à la plage du document.

    bool document.truncate(int ligne, int colonne);
    bool document.truncate(Cursorcurseur);

- Tronque la ligne spécifiée à la colonne spécifiée ou à la position du curseur. Renvoie `vrai` en cas de succès ou `faux` si la ligne spécifiée ne fait pas partie du document

    String document.word();

- Renvoie le mot à la position du curseur courant. Si aucun mot n'est trouvé à la position du curseur, la chaîne de caractères vide est retournée.

    String document.wordAt(int ligne, int colonne);
    String document.wordAt(Cursor curseur);

- Renvoie le mot à la position spécifiée du curseur. Si aucun mot n'est trouvé à cette position, la chaîne de caractère vide est retournée.

    Range document.wordRange();

- Renvoie la plage de mot à la position donnée du curseur. Si aucun mot n'est trouvé, `Range.invalid()` est retourné, qui peut être testé avec `Range.isValid()`.

    String document.latexCommand();

- Renvoie la commande &latex; à la position courante du curseur. Si aucune commande n'est trouvée à la position du curseur, la chaîne vide est retournée.

    String document.latexCommandAt(int ligne, int colonne);
    String document.latexCommandAt(Cursor curseur);

- Renvoie la commande &latex; à la position donnée du curseur. Si aucune commande n'est trouvée à cette position du curseur, la chaîne vide est retournée.

    Range document.latexCommandRange();

- Renvoie la plage de la commande &latex; à la position spécifiée du curseur. Si aucune commande &latex; n'est trouvée, `Range.invalid()` est retourné, qui peut être testé avec `Range.isValid()`.

    String document.charAt(int ligne, int colonne);
    String document.charAt(Cursor curseur);

- Renvoie le caractère à la position donnée du curseur.

    String document.firstChar(int ligne);

- Renvoie le premier caractère différent d'un espace blanc de la `ligne` donnée. Le premier caractère est à la colonne 0. Si la ligne est vide ou ne contient que des espaces blancs, la chaîne de caractère vide est retournée.

    String document.lastChar(int ligne);

- Renvoie le dernier caractère différent d'un espace blanc de la `ligne` donnée. Si la ligne est vide ou ne contient que des espaces blancs, la chaîne de caractère vide est retournée.

    bool document.isSpace(int ligne, int colonne);
    bool document.isSpace(Cursor curseur);

- Renvoie `vrai`, si le caractère à la position donnée du curseur est un espace blanc, sinon retourne `faux`.

    void document.insertBullet();

- Insert une puce &kile;. Se rappeler que vous pouvez facilement sauter à la puce suivante ou précédente. Ceci devrait aussi mettre en valeur cette puce et cet effet sera automatiquement supprimé dès la saisie de votre premier caractère.

    void document.nextBullet();

- Passer à la prochaine puce dans le texte s'il y en a une.

    void document.previousBullet();

- Passer à la puce précédente dans le texte s'il y en a eu une.

    bool document.hasEnvironment();

- Renvoie `vrai` si un environnement &latex; englobant est trouvé sinon renvoie `faux`.

    String document.environment(bool inside = false);

- Renvoie la totalité du texte dans l'environnement englobant &latex;. Si `inside` vaut `faux`, le texte de l'environnement, y compris les balises &latex; englobantes `\begin{...}...\end{...}` sera renvoyé, dans l'autre cas, les balises ne seront pas incluses. Si aucun paramètre n'est donné, `inside` est mis à `faux`. Si aucun environnement n'est trouvé, la chaîne vide est retournée.

    Range document.environmentRange(bool dedans = faux);

- Retourne la plage de l'environnement &latex; englobant. Si `dedans` est `faux`, la plage incluant les balises &latex; englobantes, `\begin{…}…\end{…}` sera retournée, sinon ce qui sera retourné sera sans ces tags. Si aucun paramètre n'est fourni, `dedans` est mis à `faux`. Si aucun environnement n'est trouvé, `Range.invalid()` est retourné, pouvant être testé avec `Range.isValid()`.

    String document.environmentName();

- Renvoie le nom de l'environnement &latex; englobant ou une chaîne vide de caractères.

    void document.removeEnvironment(bool dedans = faux);

- Supprime le texte de l'environnement &latex; englobant. Si `dedans` est `faux`, l'environnement texte incluant les balises &latex; englobantes, `\begin{…}…\end{…}` sera enlevé, sinon celui-ci sera renvoyé sans balise. Si aucun paramètre n'est fourni, `dedans` est mis à `faux`.

    void document.closeEnvironment();

- Insère une balise d'environnement de fermeture, si un environnement &latex; d'ouverture est trouvé à la position du curseur courante.

    void document.closeAllEnvironments();

- Insert des balises de fermeture de l'environnement pour tous les environnements &latex; ouverts trouvés à la position du curseur courant.

    bool document.hasTexgroup();

- Renvoie `vrai`, si un groupe &latex; englobant est trouvé à la position du curseur courant, sinon `faux`.

    String document.texgroup(bool dedans = vrai);

- Renvoie le texte du groupe &latex; englobant. Si `dedans` est `faux`, le texte de ce groupe &latex; incluant les accolades, `{…}`, sera retourné, sinon ce sera sans accolade. Si aucun paramètre n'est indiqué, `dedans` est mis à `faux`. La chaîne vide est retournée, si aucun groupe &latex; englobant n'est trouvé à la position courante du curseur.

    Range document.texgroupRange(bool dedans = vrai);

- Renvoie la plage du groupe &latex; englobant. Si `dedans` est `faux`, la plage incluant les accolades englobantes, `{…}`, sera retournée, sinon la place sera retournée sans accolade. Si aucun paramètre n'est fourni, `dedans` est mis à `faux`. Si aucun groupe n'est trouvé, `Range.invalid()` est retourné, pouvant être testé avec `Range.isValid()`.

    void document.removeTexgroup(bool dedans = vrai);

- Supprime le texte du groupe &latex; englobant. Si `dedans` est `faux`, le texte de ce groupe &latex;, y compris les accolades englobantes, `{…}`, sera enlevé, sinon ce sera sans les accolades. Si aucun paramètre n'est donné, `dedans` est mis à `faux`.

    bool document.hasMathgroup();

- Renvoie `vrai` si un groupe mathématique &latex; englobant est trouvé à la position courante du curseur, sinon `faux`.

    String document.mathgroup();

- Renvoie le texte du groupe mathématique &latex; englobant. La chaîne de caractère vide est retournée, si aucun groupe mathématique &latex; englobant n'est trouvé à la position courante du curseur.

    Range document.mathgroupRange();

- Renvoie la plage du groupe mathématique &latex; englobant. S'il n'y a aucun groupe englobant de type mathématique, `Range.invalid()` est retourné ; pouvant être testé avec `Range.isValid()`.

    void document.removeMathgroup();

- Supprime le texte du bloc mathématique &latex; englobant.

    String document.paragraph();

- Renvoie le texte du paragraphe &latex; courant.

    Range document.paragraphRange();

- Renvoie la plage du paragraphe &latex; englobant.

    void document.removeParagraph();

- Supprime le texte du paragraphe &latex; courant.

    bool document.matchesAt(int ligne, int colonne, String texte);
    bool document.matchesAt(Cursor curseur, String texte);

- Renvoie `vrai`, si le paramètre `texte` correspond à la position correspondant du curseur, sinon renvoie `faux`.

    bool document.startsWith(int ligne, String expression, bool Sauter-Espaces-Blancs = vrai);

- Renvoie `vrai` si une ligne commence avec `motif`, dans les autres cas `faux`. L'argument `Sauter-Espaces-Blancs` indique si les espaces blancs en tête sont à ignorer.

    bool document.endsWith(int ligne, String forme, bool Sauter-Espaces-Blancs = vrai);

- Renvoie `vrai`, si la ligne se termine avec `motif`, dans les autres cas `faux`. L'argument `Sauter-Espaces-Blancs` indique si les espaces blancs en fin de ligne sont à ignorer.

    int document.firstColumn(int ligne);

- Renvoie la première position d'un caractère différent d'un espace blanc dans la ligne spécifiée par le paramètre `ligne`. S'il n'y a que des espaces blancs dans la ligne, la valeur retournée est `-1`.

    int document.lastColumn(int ligne);

- Renvoie la dernière position d'un caractère différent d'un espace blanc dans la ligne spécifiée par le paramètre `ligne`. S'il n'y a que des espaces blancs dans la ligne, la valeur retournée est `-1`.

    int document.prevNonSpaceColumn(int ligne, int colonne);
    int document.prevNonSpaceColumn(Curseur cursor);

- Renvoie la position contenant un caractère différent d'un espace blanc à partir d'une position donnée du curseur et en recherchant en l'arrière.

    int document.nextNonSpaceColumn(int ligne, int colonne);
    int document.nextNonSpaceColumn(Cursor curseur);

- Renvoie la position contenant un caractère différent d'un espace blanc à partir de la position spécifiée du curseur et en recherchant vers l'avant.

    int document.prevNonEmptyLine(int ligne);

- Renvoie la ligne suivante non vide contenant un caractère différent d'un espace blanc et en recherchant vers l'arrière.

    int document.nextNonEmptyLine(int ligne);

- Retourne la prochaine ligne non vide contenant un caractère différent d'un espace blanc et en recherchant vers l'avant.

    void document.gotoBeginEnv();

- Aller au début de l'environnement &latex; englobant.

    void document.gotoEndEnv();

- Aller à la fin de l'environnement &latex; englobant.

    void document.gotoBeginTexgroup();

- Aller au début du groupe &latex; englobant.

    void document.gotoEndTexgroup();

- Aller à la fin du groupe &latex; englobant.

    void document.gotoNextParagraph();

- Aller au paragraphe &latex; suivant.

    void document.gotoPrevParagraph();

- Aller au paragraphe &latex; précédent.

    void document.gotoNextSectioning();

- Aller à la section &latex; suivante.

    void document.gotoPrevSectioning();

- Aller à la section &latex; précédente.

    void document.gotoLine(int ligne);

- Aller à la `ligne` indiquée.

    void document.insertChapter();

- Insérez une commande de `\chapter` (voir aussi `document.insertSection()`).

    void document.insertSection();

- Insérez une commande de `\section`. Comme pour choisir l'entrée du menu LaTeX Sectionnement section, une boîte de dialogue apparaîtra, où vous pourrez choisir le titre et une étiquette optionnelle pour cette commande de sectionnement. Boîte de dialogue : insérez une commande de chapitre Boîte de dialogue : insérez une commande de chapitre

    void document.insertSubsection();

- Insérez une commande `\subsection` (voir aussi `document.insertSection()`).

    void document.insertSubsubsection();

- Insérez une commande `\subsubsection` (voir aussi `document.insertSection()`).

    void document.insertParagraph();

- Insérez une commande `\paragraph` (voir aussi `document.insertSection()`).

    void document.insertSubparagraph();

- Insérez une commande `\subparagraph` (voir aussi `document.insertSection()`).

    void document.insertLabel();

- Insérez une commande `\label`.

    void document.insertReference();

- Insérez une commande de `\ref`. Comme pour choisir l'entrée du menu &latex;Références ref, une boîte de dialogue apparaîtra, où vous pourrez choisir un des labels déjà définis dans une liste déroulante. Boîte de dialogue : insérez une commande de référence Boîte de dialogue : insérez une commande de référence

    void document.insertPageref();

- Insérez une commande `\pageref` (voir aussi `document.insertReference()`).

    void document.insertCitation();

- Insérez une commande `\cite`.

    void document.insertIndex();

- Insérez une commande `\index`.

    void document.insertFootnote();

- Insérez une commande `\footnote`.

    void document.comment();

- Insère des marqueurs de commentaires pour transformer la sélection ou la ligne courante en commentaires.

    void document.uncomment();

- Supprime les marqueurs de commentaires de la sélection ou de la ligne courante.

    void document.uppercase();

- Met en majuscule le texte sélectionné ou la lettre après le curseur.

    void document.lowercase();

- Met en minuscule le texte sélectionné ou la lettre après le curseur.

    void document.capitalize();

- Met en majuscule le texte sélectionné ou le mot courant.

    void document.joinLines();

- Regroupe les lignes de la sélection courante. Deux lignes successives de texte sont toujours séparées avec un seul espace.

    void document.insertIntelligentNewline();

- Insère une nouvelle ligne élégante (voir editing_smartnewline).

    void document.insertIntelligentTabulator();

- Insère un tabulation élégante (voir editing_tabulator).

    void document.editBegin();

- Démarre un groupe d'édition pour annuler / refaire le regroupement. Veuillez vous assurer de toujours appeler `editEnd()` autant de fois que vous appellerez `editBegin()`. L'appel de `editBegin()` utilise en interne un compteur de référence, par conséquent, cet appel peut être imbriqué.

    void document.editEnd();

- Termine un groupe d'édition. Le dernier appel de `editEnd()` (c'est-à-dire, celui pour le premier appel de `editBegin()`) termine l'étape de modification.

    StringList document.labelList();

- Renvoie tous les labels définis comme un `StringList`, qui peuvent être utilisés dans &javascript; comme tableau de chaînes de caractères.

    StringList document.bibitemList();

- Renvoie tous les éléments « bib » comme un `StringList`, qui peuvent être utilisés dans &javascript; comme tableau de chaînes de caractères.

    void document.refreshStructure();

- Rafraîchit l'affichage de la structure (voir navigating).

### L'API de &kile;

L'objet global (variable) `kile` est utilisé pour gérer des opérations de haut niveau avec le monde extérieur, des messages en entrée et des interfaces de boîtes de dialogue. Ces appels API sont divisés en sous objet pour structurer cette partie de l'API du langage de scripts. Conceptuellement `kile` est un peu comme `fenêtre` dans une API d'un navigateur.

- `kile.alert`: boîtes de messages

- `kile.input`: lit les entrées de l'utilisateur

- `kile.wizard`: appelle l'un des assistants de &kile;

- `kile.script`: obtient des informations sur le script en exécution.

- `kile.file`: enregistre des opérations comme la lecture et l'écriture.

#### Alerte

    void kile.alert.information(String texte, String légende);

- Afficher un boîte de dialogue d'Informations. `texte` est un message de type chaîne de caractères et `titre` le titre de la boîte de messages. Le titre par défaut est le nom du script.

    void kile.alert.sorry(String texte, String légende);

- Afficher un boîte de dialogue d'Excuses. `texte` est un message de type chaîne de caractères et `titre` est le titre de la boîte de messages. Le titre par défaut est le nom du script.

    void kile.alert.error(String texte, String légende);

- Afficher une boîte de dialogue d'Erreur. `texte` est un message de type chaîne de caractères et `titre` est le titre de la boîte de messages. Le titre par défaut est le nom du script.

    String kile.alert.question(String texte, String légende);

- Afficher une boîte de dialogue Question. `texte` est un message de type chaîne de caractères et `titre` est le titre de la boîte de messages. Le titre par défaut est le nom du script. La chaîne retournée est soit `Oui` soit `Non`.

    String kile.alert.warning(String texte, String légende);

- Afficher une boîte de dialogue d'Alerte. `texte` est un message de type chaîne de caractères et `titre` est le titre de la boîte de messages. Le titre par défaut est le nom du script. La chaîne retournée est soit `Continuer` soit `Annuler`.

#### Entrée

    String kile.input.getListboxItem(String légende, String étiquette, StringList liste);

- Fonction laissant l'utilisateur sélectionner un élément à partir d'une liste de type choix unique.`légende` est le texte affiché dans le barre de titre,`étiquette` est le texte apparaissant comme étiquette de la liste et `liste` est la chaîne de caractères insérée dans la liste.

    String kile.input.getComboboxItem(String légende, String étiquette, StringList liste);

- Fonction laissant l'utilisateur sélectionner un élément à partir d'une liste à choix multiple.`légende` est le texte affiché dans le barre de titre, `étiquette` est le texte apparaissant comme étiquette de la liste et `liste` est la chaîne de caractères insérée dans la liste.

    String kile.input.getText(String légende, String étiquette);

- Fonction pour saisir une chaîne de caractères par l'utilisateur. `légende` est le texte affiché dans la barre de titre et `étiquette` est le texte apparaissant comme étiquette de la zone de saisie de texte.

    String kile.input.getLatexCommand(String légende, String étiquette);

- Fonction pour saisir une commande &latex; par l'utilisateur. Ceci ignifie que seuls les caractères (minuscules et majuscules) sont autorisés.`légende` est le texte affiché dans la barre de titre et `étiquette` est le texte apparaissant comme étiquette de la zone d'édition de texte.

    int kile.input.getInteger(String légende, String étiquette, int min = INT-MIN, int max = INT-MAX);

- Fonction pour saisir un nombre par l'utilisateur.`légende` est le texte affiché dans la barre de titre et `étiquette` est le texte apparaissant comme étiquette de la boîte à sélection multiple. `min` et `max` sont les valeurs minimum et maximum autorisées choisies par l'utilisateur. Les valeurs par défaut sont `INT_MIN` et `INT-MAX`.

    int kile.input.getPosInteger(String légende, String étiquette, int min = 1, int max = INT-MAX);

- Fonction pour saisir un nombre positif par l'utilisateur.`légende` est le texte affiché dans la barre de titre et `étiquette` est le texte apparaissant comme étiquette de la boîte de sélections multiples. `min` et `max` sont les valeurs minimum et le maximum autorisées choisies par l'utilisateur. Les valeurs par défaut sont `INT-MIN` et `INT-MAX`.

#### Assistant

    void kile.wizard.tabular();

- Appelle l'Assistant de tableau, qui aide à écrire un environnement de tableau (voir wizard_array).

    void kile.wizard.array();

- Appelle l'Assistant de table, qui aide à écrire un environnement de tableau (voir wizard_array).

    void kile.wizard.tabbing();

- Appelle l'Assistant de tabulation, qui aide à écrire un environnement de tabulation (voir wizard_array).

    void kile.wizard.floatEnvironment();

- Appelle l'Assistant de nombres à virgule, qui aide à insérer un nombre à virgule flottante (voir wizard_float).

    void kile.wizard.mathEnvironment();

- Appelle l'Assistant Maths, qui aide à insérer des environnements mathématiques (voir wizard_math).

    void kile.wizard.postscript();

- Appelle l'Assistant Outils PostScript, qui pourrait vous aider à manipuler ou ré-organiser des documents PostScript (voir wizard_postscript).

#### Script

    String kile.script.name();

- Renvoie le nom racine du script en cours d'exécution (sans l'emplacement et l'extension).

    String kile.script.caption();

- Renvoie une chaîne de caractères pouvant être utilisée comme titre des boîtes d'alerte. Cela ressemble à `Script: scriptname.js`.

#### Fichier

    Object kile.file.read(String Nom-Fichier);

- Lit le contenu d'un fichier texte. Utilisé comme

  Exemple : `var res = kile.file.read("emplacement/vers/fichier.txt");`

  La valeur de retour `res` est un objet (mieux, une carte) possédant trois propriétés :

  - état : Donne les codes d'état de l'opération, pouvant être 0 (pas d'erreur), 1 (échec de l'accès) ou 2 (accès refusé). Ainsi, si aucune erreur n'est survenue, la valeur de `res.état` ou `res[ « état » ]` sera 0.

  - résultat : Contient le texte du fichier spécifié.

  - message : Contient un message d'erreur, si une erreur est survenue.

    Object kile.file.read();

- Tout comme `read(nom-fichier)`, mais sans qu'un nom de fichier ne soit fourni. Une boîte de dialogue apparaîtra pour sélectionner le fichier à lire.

    Object kile.file.write(String nom-fichier, String texte);

- Écrit le texte donné dans un fichier. C'est utilisé comme

  Exemple : `var des = kile.file.write("emplacement/de/fichier.txt","Du texte…");`

  La valeur de retour `res` est un objet (mieux : une carte) possédant deux propriétés : `état` et `message` (voir `read()` pour plus d'informations).

    Object kile.file.write(String texte);

- Tout comme `write(nom-fichier,texte)`, mais sans qu'aucun nom de fichier ne soit fourni. Une boîte de dialogue apparaîtra pour choisir un nom de fichier.

    String kile.file.getOpenFileName(String Dossier-Départ, String filtre);

- Crée une boîte de dialogue de sélection de fichier et renvoie le nom du ficher sélectionné ou une chaîne vide si aucun fichier n'est choisi. Veuillez noter qu'avec cette méthode, l'utilisateur doit sélectionner un nom de fichier existant.

  Paramètres :

  - Dossier-Départ : Dossier de base pour la boîte de dialogue d'ouverture de fichier.

  - filtre : Un shell global ou un filtre de type MIME spécifiant quel fichier à afficher. Veuillez vous référer à la documentation de KFileDialog pour plus d'informations sur ce paramètre.

  Les deux paramètres sont optionnels. Si vous ne renseignez pas `filtre`, tous les fichiers seront affichés. Si en plus `Dossier-Départ` est omis, la boîte de dialogue prendra le dossier du document courant comme point de départ.

    String kile.file.getSaveFileName(String Dossier-Départ, String filtre);

- Crée une boîte de dialogue de sélection de fichier et renvoie le nom du ficher sélectionné ou une chaîne vide si aucun fichier n'est choisi. Veuillez noter qu'avec cette méthode, l'utilisateur n'a besoin de sélectionner un nom de fichier existant. Veuillez consulter `getOpenFileName()` pour plus d'explications concernant ces paramètres.

## Exemples

Quelques exemples pourraient vous aider à comprendre comment utiliser l'API d'écriture de scripts. Ces exemples et bien d'autres sont disponibles dans le dossier de scripts de &kile; : `KILE-APP-DIR/scripts/`. Chaque script contient une description succincte.

### Exemple 1 : remplacer le nom de l'environnement

Remplace l'environnement &latex; englobant avec un autre, où la position relative du curseur ne sera pas modifiée. `\begin{abc}…\end{abc}`, par exemple, peut être changé en `\begin{xyz}…\end{xyz}`.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Saisissez l'environnement","Nouveau nom d'environnement : ");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("Aucun environnement LaTeX englobant trouvé.");
    }

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

### Exemple 2 : remplacer une commande &latex; de polices de caractères

Remplace la commande &latex; de police englobante avec une autre commande, quand le curseur est placé à l'intérieur du groupe de texte. La position relative du curseur ne sera pas changée. Par exemple, `\textbf{abc}` peut être changé en `\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("Aucun groupe LaTeX englobant.");
    }

    function replaceFontCommand®
    {
            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 ( new command != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - newcommand.length);
                            }
                    }
    /                view.setCursorPosition©;
            }
            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;
    }

### Exemple 3: entourer le texte sélectionné

Entourer le texte sélectionné à l'aide commande TeX, où la position relative du curseur ne pourra plus être changée. Par exemple, `abc` peut être changé en `\texcommand{abc}`.

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand(« Choisir », « Choisir la commande LaTeX englobante :  »);
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("Aucune sélection trouvée.");
    }

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