# Outils d'édition avancée

## Commenter / Décommenter

Les commandes Commenter et Décommenter, disponibles dans le menu Outils, permettent d'ajouter ou de supprimer des indicateurs de commentaire à la sélection ou à la ligne actuelle, s'il n'y a pas de texte sélectionné et si le format du texte qu'on modifie prend en charge les commentaires.

Les règles qui régissent la façon de créer des commentaires étant établies dans les définitions de syntaxe, l'ajout / la suppression de commentaires n'est pas possible si la coloration syntaxique n'est pas activée.

Certains formats définissent des indicateurs de commentaire sur une seule ligne, d'autres sur plusieurs lignes et d'autres encore, les deux. Si les indicateurs sur plusieurs lignes ne sont pas disponibles, on ne pas décommenter une sélection qui ne contient pas la totalité de sa dernière ligne.

Si un indicateur de commentaire sur une seule ligne est disponible, le commentaire ligne par ligne aura la préférence là où il est applicable, car ce comportement contribue à éviter des problèmes avec les commentaires imbriqués.

Lorsqu'on supprime des indicateurs de commentaire, il ne faut sélectionner aucun texte non commenté. Lorsqu'on supprime des indicateurs de commentaire sur plusieurs lignes d'une sélection, tout espace en dehors des indicateurs de commentaire est ignoré.

Pour placer des indicateurs de commentaire, utilisez la ligne de menu Outils Commenter ou le raccourci clavier correspondant, par défaut &Ctrl;#.

Pour supprimer des indicateurs de commentaire, utilisez la ligne de menu Outils Décommenter ou le raccourci clavier correspondant, par défaut &Ctrl;&Maj;#.

## La ligne de commande du composant Éditeur

Le composant éditeur de Kate offre une ligne de commande interne permettant d'effectuer diverses actions à partir d'une interface graphique minimale. La ligne de commande est un élément de texte situé au bas de la zone d'édition. Pour la voir, cliquez sur Affichage Afficher la ligne de commande ou utilisez le raccourci clavier (par défaut, F7). L'éditeur fournit un ensemble de commandes comme décrit ci-dessous. Des commandes additionnelles peuvent être fournies par des modules externes.

Pour exécuter une commande, saisissez cette dernière, puis appuyez sur la touche Entrée. La ligne de commande indique si elle a abouti et affiche éventuellement un message. Si vous avez saisi la ligne de commande en appuyant sur F7, elle disparaît automatiquement au bout de quelques secondes. Pour effacer le message et saisir une nouvelle commande, appuyez sur F7 à nouveau.

La ligne de commande est dotée d'un système d'aide intégré : exécutez la commande `help` pour démarrer. Pour afficher une liste de toutes les commandes disponibles, saisissez `help list`. Pour afficher l'aide concernant une commande donnée, saisissez `help `commande``.

Comme la ligne de commande comporte un historique intégré, vous pouvez réutiliser les commandes déjà saisies. Pour parcourir l'historique, utilisez les touches Haut et Bas. Lorsque vous affichez l'historique des commandes, la partie argument de la commande est sélectionnée, ce qui vous permet d'écraser aisément les arguments.

### Commandes standard de la ligne de commande

#### Commandes pour configurer l'éditeur

Ces commandes sont fournies par le composant éditeur et permettent de configurer le document actif et son affichage uniquement. Ce comportement est pratique si vous voulez employer un autre paramètre que ceux par défaut, par exemple pour l'indentation.

#### Types d'arguments

BOOLÉEN

- On emploie cet argument avec les commandes qui servent à (dés)activer tel ou tel élément. Les valeurs admises sont `on`, `off`, `true`, `false`, `1` ou `0`

ENTIER

- Un nombre entier

CHAÎNE

- Une chaîne de caractères

    set-tab-widthENTIER largeur

- Définit la largeur de tabulation au nombre `largeur`

    set-indent-widthENTIER largeur

- Définit la largeur d'indentation au nombre `largeur`. Utilisée seulement si vous indentez avec des espaces.

    set-word-wrap-columnENTIER largeur

- Définit la largeur de ligne pour le retour à la ligne forcé à `largeur`. Utilisé si vous avez choisi le retour à la ligne automatique pour votre texte.

    set-icon-borderBOOLÉEN activer

- Définit la visibilité de la bordure d'icônes.

    set-folding-markersBOOLÉEN activer

- Définit la visibilité de la bordure des indicateurs de pliage.

    set-line-numbersBOOLÉEN activer

- Définit la visibilité du panneau des numéros de ligne.

    set-replace-tabsBOOLÉEN activer

- Si cette option est cochée, les tabulations sont remplacées par des espaces au fur et à mesure que vous saisissez au clavier.

    set-remove-trailing-spaceBOOLÉEN activer

- Si cette option est cochée, les espaces de fin sont supprimés chaque fois que le curseur change de ligne.

    set-show-tabsBOOLÉEN activer

- Si cette option est cochée, les caractères de tabulation et l'espace de fin de ligne seront représentés par un petit point.

    set-indent-spacesBOOLÉEN activer

- Si cette option est cochée, l'éditeur indente avec des espaces `indentation-largeur` pour chaque niveau d'indentation plutôt qu'avec un caractère de tabulation.

    set-mixed-indentBOOLÉEN activer

- Si cette option est cochée, Kate utilise un mélange de tabulations et d'espaces pour l'indentation. Chaque niveau d'indentation aura une largeur `indentation-largeur` et d'autres niveaux d'indentation seront optimisés pour pouvoir utiliser autant de caractères de tabulation que possible.

  Lorsqu'elle est exécutée, cette commande définit en outre l'indentation avec des espaces activée et, si la largeur d'indentation n'est pas spécifiée, elle est définie à la moitié de la `tab-width` du document au moment de l'exécution.

    set-word-wrapBOOLÉEN largeur

- Active le retour à la ligne dynamique en fonction de `activer`

    set-replace-tabs-saveBOOLÉEN activer

- Si cette option est cochée, les tabulations sont remplacées par un blanc chaque fois que le document est enregistré.

    set-remove-trailing-space-saveBOOLÉEN activer

- Lorsque cette option est cochée, l'espace de fin est supprimé de chaque ligne chaque fois que le document est enregistré.

    set-indent-modenom

- Définit le mode d'indentation automatique à `nom`. Si `nom` n'est pas connu, le mode est défini à 'none'. Les modes autorisés sont 'cstyle', 'csands', 'xml', 'python', 'varindent' et 'none'.

    set-highlightcoloration syntaxique

- Définit le système de coloration syntaxique pour le document. L'argument doit être un nom de coloration syntaxique autorisé, comme on le voit dans le menu Outils Coloration syntaxique. Cette commande fournit une liste d'autocomplétement pour son argument.

#### Commandes d'édition

Ces commandes modifient le document actuel.

    indent

- Indente les lignes sélectionnées ou la ligne actuelle.

    unindent

- Désindente les lignes sélectionnées ou la ligne actuelle.

    cleanindent

- Nettoie l'indentation des lignes sélectionnées ou de la ligne actuelle en fonction des paramètres d'indentation du document.

    comment

- Insère des indicateurs de commentaire pour créer sur la sélection, les lignes sélectionnées ou la ligne actuelle un commentaire en fonction du format du texte, comme défini par la coloration syntaxique concernant le document.

    uncomment

- Supprime les indicateurs de commentaires de la sélection, des lignes sélectionnées ou de la ligne actuelle en fonction du format du texte, comme défini par la définition de la coloration syntaxique concernant le document.

    kill-line

- Supprime la ligne actuelle.

    replacemotifremplacement

- Remplace le texte correspondant à `motif` par `remplacement`. Si vous voulez ajouter un blanc dans le `motif`, vous devez entourer d'apostrophes ou de guillemets à la fois le `motif` et le `remplacement`. Si les arguments n'ont pas de guillemets, le premier mot sert de `motif` et le reste de `remplacement`. Si `remplacement` est vide, chaque occurrence de `motif` est supprimée.

  Vous pouvez définir des drapeaux pour configurer la recherche, en ajoutant un caractère « : » (deux points), suivi d'une ou plusieurs lettres représentant une configuration, ce qui donne la forme `replace:options motif remplacement`. Les options disponibles sont les suivantes :

  `b`

- Recherche arrière.

`c`

- Recherche à partir de la position du curseur.

`e`

- Recherche dans la sélection uniquement.

`r`

- Recherche sur des expressions rationnelles. Si défini, vous pouvez utiliser `\N`, où N est un nombre réprésentant des captures dans la chaîne de remplacement.

`s`

- Recherche sensible à la casse.

`p`

- Invite de permission pour remplacer la prochaine occurrence.

`w`

- Correspondance de mots entiers uniquement.

    dateformat

- Insère une chaîne date/time comme défini par le format spécifié `format` ou le format « aaaa-MM-jj hh:mm:ss », si aucun n'est indiqué. Les traductions suivantes sont effectuées lors de l'interprétation de `format` :

  `d` | Le jour sous la forme d'un nombre sans zéro de début (1-31).
  `dd` | Le jour sous la forme d'un nombre avec un zéro de début (01-31).
  `ddd` | Le nom abrégé du jour localisé (par exemple 'Lun'..'Dim').
  `dddd` | Le nom entier du jour localisé (par exemple 'Lundi'..'Dimanche').
  `M` | Le mois sous la forme d'un nombre sans zéro de début (1-12).
  `MM` | Le mois sous la forme d'un nombre avec un zéro de début (01-12).
  `MMM` | Le nom abrégé du mois localisé (par exemple 'Jan'..'Déc').
  `aa` | L'année sous la forme d'un nombre à deux chiffres (00-99).
  `aaaa` | L'année sous la forme d'un nombre à quatre chiffres (1752-8000).
  `h` | L'heure sans zéro de début (0..23 ou 1..12 en cas d'affichage AM/PM).
  `hh` | L'heure avec un zéro de début (00..23 ou 01..12 en cas d'affichage AM/PM).
  `m` | La minute sans zéro de début (0..59).
  `mm` | La minute avec un zéro de début (00..59).
  `s` | La seconde sans zéro de début (0..59).
  `ss` | La seconde avec un zéro de début (00..59).
  `z` | Les millisecondes sans zéro de début (0..999).
  `zzz` | Les millisecondes des zéros de début (000..999).
  `AP` | Utiliser l'affichage AM/PM. AP sera remplacé soit par « AM », soit par « PM ».
  `ap` | Utiliser l'affichage. ap sera remplacé soit par « am », soit par « pm ».

    charidentifiant

- Cette commande permet d'insérer des caractères spéciaux par leur identifiant numérique, sous forme décimale, octale ou hexadécimale. Pour l'utiliser, ouvrez la boîte de dialogue Commandes d'édition, et saisissez `char: [numéro]` dans la zone de saisie, puis cliquez sur OK.

  ##### Exemples avec `char`

  Entrée : `char:234`

  Sortie : `ê`

  Entrée : `char:0x1234`

  Sortie : `ሴ`

`s///[ig]` `%s///[ig]`

- Cette commande effectue une opération de recherche / remplacement comme sed dans la ligne actuelle, ou dans tout le fichier (`%s///`).

  En bref, on recherche dans le texte une expression qui correspond au texte recherché, l'expression rationnelle entre la première et la deuxième barre oblique. Lorsqu'une correspondance est trouvée, la part de texte correspondant est remplacée par l'expression entre la partie du milieu et la dernière partie de la chaîne. Les parenthèses dans le motif de recherche créent des références arrière, c'est-à-dire que la commande se souvient quelle part du motif correspondait dans les parenthèses ; ces chaînes peuvent être réutilisées dans le motif de remplacement, référencées par `\1` pour la première paire de parenthèses, `\2` pour la deuxième, etc.

  Pour rechercher une `(` ou une `)`, vous devez la faire précéder d'un antislash, qui joue le rôle de caractère d'échappement : `\(\)`.

  Si vous placez un `i` à la fin de l'expression, l'expression correspondante sera insensible à la casse. Si vous placez un `g` à la fin, toutes les occurrences du motif seront remplacées, sinon seule la première occurrence est remplacée.

  ##### Remplacer du texte dans la ligne actuelle

  Votre compilateur préféré vient de s'arrêter en vous indiquant que la classe `maClasse` mentionnée à la ligne 3902 de votre fichier source n'est pas définie.

  C'est évidemment `MaClasse` ! Vous allez à la ligne 3902 et, au lieu d'essayer de trouver le mot dans le texte, vous ouvrez la boîte de dialogue Commande d'édition, saisissez `s/maClasse/MaClasse/i`, cliquez sur le bouton OK, enregistrez le fichier et compilez – avec succès, sans l'erreur.

  ##### Remplacer du texte dans le fichier entier

  Imaginez que vous avez un fichier dans lequel vous mentionnez plusieurs fois « Mlle Dupont » lorsque quelqu'un entre et vous dit qu'elle vient de se marier avec « M. Martin ». Vous voulez, bien évidemment, remplacer chaque occurrence de « Mlle Dupont » par « Mme Martin ».

  Sur la ligne de commande, saisissez `%s/Melle Dupont/Mme Martin/` et appuyez sur Entrée. Vous avez terminé.

  ##### Un exemple plus avancé

  Cet exemple utilise les références arrière ainsi qu'une classe de caractères (si vous ne savez pas de quoi il s'agit, reportez-vous à la documentation relative à ce sujet mentionnée ci-dessous).

  Supposons que vous ayez la ligne suivante :

      void MyClass::DoStringOps( String      &foo, String &bar String *p, int  &a, int &b )

  Maintenant, vous vous rendez compte que ce n'est pas du code élégant et décidez que vous voulez utiliser le mot-clé `const` pour tous les arguments « adresse de », ceux caractérisés par l'opérateur & avant le nom d'argument. Vous voulez aussi simplifier les espaces, de sorte qu'il n'y a qu'un caractère d'espace entre les mots.

  Ouvrez la boîte de dialogue « Commande d'édition » et saisissez : `s/\s+(\w+)\s+(&)/ const \1 \2/g`, puis cliquez sur le bouton OK. Le `g` à la fin de l'expression fait recompiler l'expression rationnelle pour chaque occurrence, pour enregistrer les références arrière.

  Sortie : `void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )`

  Mission réussie ! Mais que s'est-il passé ? Nous avons recherché des blancs (`\s+`), suivis d'un ou plusieurs caractères alphabétiques (`\w+`), eux-mêmes suivis d'un autre blanc (`\s+`) suivi d'une esperluette. Le processus a enregistré le fragment alphanumérique et l'esperluette pour le réutiliser lors de l'opération de remplacement. Puis, nous avons remplacé la partie correspondante de la ligne par un blanc suivi de « const », suivi d'un blanc, suivi de notre fragment alphanumérique enregistré (`\1`), lui-même suivi d'un blanc et de notre esperluette enregistrée (`\2`).

  Maintenant, comme dans certains cas, le fragment alphanumérique était « String » et dans d'autres « int », l'utilisation de la classe de caractères `//w` et du quantificateur `+` a été un grand avantage.

#### Commandes de navigation

    gotoENTIER ligne

- Cette commande permet d'aller jusqu'à la ligne spécifiée.

    findmotif

- Cette commande permet d'aller à la première occurrence de `motif`, en fonction de la configuration. Vous pouvez trouver les occurrences suivantes à l'aide de Édition Poursuivre la recherche (le raccourci par défaut est F3).

  Il est possible de configurer la commande Chercher en ajoutant à la fin un caractère « : », suivi d'une ou plusieurs options. La forme est `find:options motif`. Les options suivantes sont prises en charge :

  `b`

- Recherche arrière.

`c`

- Recherche à partir de la position du curseur.

`e`

- Recherche dans la sélection uniquement.

`r`

- Recherche sur des expressions rationnelles. Si défini, vous pouvez utiliser `\N`, où N est un nombre réprésentant des captures dans la chaîne de remplacement.

`s`

- Recherche sensible à la casse.

`w`

- Correspondance de mots entiers uniquement.

    ifindmotif

- Cette commande fournit une recherche au fur et à mesure de la saisie (« as-you-type »). Vous pouvez configurer le comportement ou la recherche en ajoutant à la fin un caractère « : », suivi d'une ou plusieurs options, comme suit : `ifind:options motif`. Les options autorisées sont les suivantes :

  `b`

- Recherche arrière.

`r`

- Effectue une recherche sur des expressions rationnelles.

`s`

- Recherche sensible à la casse.

`c`

- Recherche à partir de la position du curseur.

## Utiliser le pliage du code

Le pliage du code permet de cacher des parties d'un document dans l'éditeur, ce qui facilite l'affichage de la vue d'ensemble de documents volumineux. Dans &kate; les régions pliables sont calculées à l'aide de règles définies dans les définitions de coloration syntaxique, et le pliage du code n'est donc disponible que dans certains formats - en général le code source du programme, le marquage XML et similaires. La plupart des définitions de coloration syntaxique prenant en charge le pliage du code permet également de définir manuellement des régions pliables, en général à l'aide des mots-clés `DEBUT` et `FIN`.

Pour utiliser la fonctionnalité de pliage du code, activez les marqueurs suivants à l'aide de l'élément de menu Affichage Afficher les indicateurs de pliage s'ils ne sont pas déjà visibles. Le panneau des indicateurs de pliage du côté gauche de l'écran affiche une vue graphique des régions pliables, avec des signes +/- pour indiquer l'opération possible sur une région donnée : un - signifie que la région est dépliée. Un clic sur - replie la région et sur + sera affiché à la place.

Quatre commandes sont prévues pour manipuler l'état des régions de pliage. Consultez la documentation du menu.

Si vous ne voulez pas employer la fonctionnalité de pliage du code, vous pouvez désactiver l'option Afficher les indicateurs de pliage (si cette option est activée) dans la page Apparence de la configuration de l'éditeur.

## Scriptage du composant éditeur avec Javascript

### Introduction

À partir de la version 2.5, le composant éditeur de &kate; prend en charge le scriptage avec le script ECMA, également connu sous le nom de JavaScript.

Les scripts peuvent être utilisés à l'aide de la ligne de commande intégrée uniquement. La condition requise est que le script est placé dans un dossier où &kate; peut le trouver, ainsi qu'un fichier .desktop optionnel qui définit les propriétés associées. Le dossier pertinent est nommé `katepart/scripts` dans les dossiers de données de &kde;. Vous trouverez les dossiers de données en exécutant la commande `kde-config `--path` `data``. Vous aurez le plus souvent un système et un dossier de données personnel. Naturellement, les scripts contenus dans le dossier de données du système sont à la disposition de tous les utilisateurs sur le système, alors que ceux qui sont dans le dossier personnel ne sont accessibles qu'à vous.

Cette fonctionnalité est expérimentale et il est fort probable qu'elle subisse des changements au cours du développement futur.

Nous savons que beaucoup d'entre vous seront déçus car vous ne pouvez pas ajouter vos scripts au menu ou leur affecter des raccourcis clavier. Désolé. Il se peut que dans le futur ce soit possible.

Il n'est également pas encore possible de passer des arguments à vos scripts. Soyez patient, ce sera peut-être ajouté dans un futur proche !

### L'API JavaScript de Kate

Est listée ici l'ensemble complet des fonctions et propriétés disponibles dans les objets `document` et `view`. De plus, vous pouvez naturellement utiliser tous les objets standard tels que `Math`, `String` `Regex`, etc.

Lorsqu'on exécute un script, l'objet `document` est le document actuel, et l'objet `view` est la vue actuelle.

Les types des arguments ne sont bien entendu pas utilisés en JavaScript à ce moment, ils ne servent qu'à indiquer quel sorte de valeur les fonctions attendent.

### Fonctions globales

`debug( ``chaîne``) [fonction]`

- ### paramètres

  - `chaîne` : la chaîne à produire en sortie.

  Sort la chaîne dans STDERR à l'aide de `kdDebug()`. On utilise une zone de sortie dédiée pour la sortie, qui sera préfixée par `Kate (KJS Scripts)`.

### L'API `document`

`document.attribute( ``ligne`` , ``colonne``) ; [fonction]`

- ### Paramètres

  - `uint ligne` : la ligne de la position pour laquelle trouver l'attribut.

  - `uint colonne` : la colonne de la position pour laquelle trouver l'attribut.

  Ce paramètre retourne l'ID numérique de l'attribut concernant la position du document [`ligne`,`colonne`]. L'attribut représente l'apparence visuelle ou le style du texte, et sert également à calculer la coloration syntaxique pour une partie donnée du texte dans des formats mélangés comme HTML ou PHP.

`document.canBreakAt( `caractère c`, `uint attribut`); [fonction]`

- ### Paramètres

  - `c` : le caractère à tester.

  - `attribut` : l'attribut à la position de `c`.

  La valeur restituée indique s'il est permis d'interrompre la ligne à un caractère c avec l'attribut attribut. Le résultat est décidé en demandant la coloration syntaxique possédant l'attribut pour lequel les caractères permettent d'interrompre la ligne.

`document.canComment( `uint attribut_début`, `uint attribut_fin` ); [fonction]`

- ### Paramètres

  - `attribut_début` : l'attribut au début de l'intervalle à transformer en commentaire.

  - `attribut_fin` : l'attribut à la fin de l'intervalle à transformer en commentaire.

  La valeur restituée indique si attribut_début et attribut_fin appartiennent au même système de coloration syntaxique. Si tel est le cas, c'est correct.

  #### Utiliser canComment

      if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
          // 1,0 et 5,0 appartiennent au même système de coloration syntaxique
      }

`document.clear(); [fonction]`

- Efface le document.

`document.commentStart( `uint attribut` ); [fonction]`

- ### Paramètres

  - `attribut` : l'attribut du texte pour lequel obtenir la chaîne commentStart.

  La valeur restituée indique la chaîne requise pour démarrer un commentaire multiligne pour un texte avec attribut, ou une chaîne vide si les commentaires multiligne ne sont pas pris en charge pour ce texte.

`document.commentMarker( `uint attribut` ); [fonction]`

- ### Paramètres

  - `attribut` : l'attribut du texte pour lequel obtenir la chaîne commentMarker.

  La valeur restituée indique la chaîne utilisée pour marquer le reste de la ligne en tant que commentaire pour un texte avec attribut ou une chaîne vide si les commentaires à une seule ligne ne sont pas pris en charge pour ce texte.

`document.commentEnd( `uint attribut` ); [fonction]`

- ### Paramètres

  - `attribut` : l'attribut du texte pour lequel obtenir la chaîne commentEndg.

  La valeur restituée indique la chaîne requise pour terminer un commentaire multiligne pour un texte avec attribut, ou une chaîne vide si les commentaires multilignes ne sont pas pris en charge pour ce texte.

`document.editBegin(); [fonction]`

- Démarre un groupe d'édition. Toutes les actions effectuées jusqu'à l'appel de editEnd() seront groupées en une action d'annulation.

`document.editEnd(); [fonction]`

- Termine un groupe d'édition.

`document.highlightMode; [propriété:lecture seule]`

- Le nom du mode de coloration syntaxique du document, tel que JavaScript ou C++. Si aucun mode de coloration syntaxique n'est défini pour le document, la valeur est None (Aucune). Notez que vous devez utiliser le nom anglais au cas où il diffère de celui du nom traduit.

`document.indentMode; [propriété:lecture seule]`

- Le nom du mode d'indentation du document, tel que `normal` ou `cstyle`. n'oubliez pas que si aucun mode d'indentation n'est défini, la valeur est `aucun`.

`document.indentWidth; [propriété:lecture seule]`

- La largeur d'indentation définie pour le document. Cette valeur est utilisée si l'indentation par espaces est activée.

`document.insertLine( `uint ligne`, `chaîne texte` ); [fonction]`

- ### Paramètres

  - `ligne` : numéro de ligne du document.

  - `texte` : texte à insérer.

  Insère une nouvelle ligne avec le texte `texte` à la ligne `ligne`.

`document.insertText( `uint ligne`, `uint colonne`, `chaîne texte` ); [fonction]`

- ### Paramètres

  - `ligne` le numéro de la ligne

  - `colonne` la colonne

  - `texet` le texte qui doit être inséré

  Insère le texte `texte` dans la llgne `ligne` et la colonne `colonne`.

document.length(); [fonction]

- La valeur restituée indique la taille du document en octets.

`document.lines(); [fonction]`

- La valeur restituée indique le nombre de lignes dans le document.

document.mixedIndent; [propriété:lecture seule]

- Une propriété booléenne indiquant si le paramètre mixed-indent est activé pour le document. Si oui, l'indentation est optimisée de façon à contenir un mélange de caractères de tabulation et d'espaces comme l'utilise l'éditeur Emacs.

document.removeLine( `uint ligne` ); [fonction]

- ### Paramètres

  - `ligne` numéro de la ligne

  Supprime la ligne ligne du document.

`document.removeText( `uint débutLigne`, `uint débutColonne`, `uint finLigne`, `uint finColonne` ); [fonction]`

- ### Paramètres

  - `débutLigne` : spécifie la ligne de début.

  - `débutColonne` : spécifie la colonne de début.

  - `finLigne` : spécifie la ligne de fin.

  - `finColonne` : spécifie la colonne de fin.

  Supprime l'intervalle de texte depuis la ligne `débutLigne` et la colonne `débutColonne` jusqu'à la ligne `finLigne` et la colonne `finColonne`.

`document.setText( `chaîne texte` ); [fonction]`

- ### Paramètres

  - `texte` : texte du document.

  Affecte au contenu du document entier un `texte`.

`document.spaceIndent; [propriété:lecture seule]`

- Une propriété booléenne indiquant si le paramètre space-indent est activé pour le document. Si oui, le document est indenté avec des espaces indentWidth par niveau, sinon l'indentation est un caractère de tabulation par niveau.

`document.textFull(); [fonction]`

- La valeur restituée indique le texte complet du document. Si le texte s'étend sur plusieurs lignes, le caractère de saut de ligne est `\n`.

`document.textLine( uint ligne ); [fonction]`

- ### Paramètres

  - `ligne` : la ligne.

  La valeur restituée indique le texte de la ligne `ligne`.

`document.textRange( `uint débutLigne`, `uint débutColonne`, `uint finLigne`, `uint finColonne` ); [fonction]`

- ### Paramètres

  - `débutLigne` : spécifie la ligne de début.

  - `débutColonne` : spécifie la colonne de début.

  - `finLigne` : spécifie la ligne de fin.

  - `finColonne` : spécifie la colonne de fin.

  La valeur restituée indique l'intervalle de texte spécifié. Si l'intervalle s'étend sur plusieurs lignes, le caractère de saut de ligne est `\n`.

### L'API `view`

`view.clearSelection(); [fonction]`

- Désélectionne tout le texte.

`view.cursorColumn(); [fonction]`

- La valeur restituée indique la colonne actuelle du curseur (les caractères de tabulation sont étendus).

`view.cursorColumnReal(); [fonction]`

- La valeur restituée indique la colonne actuelle réelle du curseur (les caractères de tabulation comptent pour une colonne).

`view.cursorLine(); [fonction]`

- La valeur restituée indique la ligne actuelle du curseur.

`view.hasSelection(); [fonction]`

- La valeur restituée indique `true` si la vue contient le texte sélectionné, sinon `false`.

`view.removeSelectedText(); [fonction]`

- Supprime le texte sélectionné, si la vue contient une sélection.

`view.selectAll(); [fonction]`

- Sélectionne tout le texte.

`view.selection(); [fonction]`

- La valeur restituée indique le texte sélectionné. Si la sélection s'étend sur plusieurs lignes, le caractère de saut de ligne est `\n`.

`view.selectionEndColumn; [propriété:lecture seule]`

- La valeur restituée indique la colonne de fin de la sélection.

`view.selectionEndLine; [propriété:lecture seule]`

- La valeur restituée indique la ligne de fin de la sélection.

`view.selectionStartColumn; [propriété:lecture seule]`

- La valeur restituée indique la colonne de début de la sélection.

`view.selectionStartLine; [propriété:lecture seule]`

- La valeur restituée indique la ligne de début de la sélection.

`view.setCursorPosition( `uint ligne`, `uint colonne` ); [fonction]`

- ### Paramètres

  - `ligne` : spécifie la ligne pour le curseur.

  - `colonne` : spécifie la colonne pour le curseur.

  Définit la position du curseur d'entrée dans la vue selon [`ligne`, `col`]. Ce paramètre fixe la position du curseur de manière visuelle, c'est-à-dire que le caractère de tabulation compte jusqu'à `largeur tabulation` en fonction de la position à l'intérieur de la ligne. La position du curseur es rendue visible. La ligne ainsi que la colonne commencent à partir de zéro.

`view.setCursorPositionReal( `uint ligne`, `uint colonne` ); [fonction]`

- ### Paramètres

  - `ligne` : spécifie la ligne pour le curseur.

  - `colonne` : spécifie la colonne pour le curseur.

  Définit la position du curseur d'entrée selon [`ligne`, `col`]. Ce paramètre définit la position de la chaîne, c'est-à-dire qu'un caractère de tabulation compte un caractère. La position du curseur est rendue visible. La ligne ainsi que la colonne commencent à partir de zéro.

`view.setSelection( `uint débutLigne`, `uint débutColonne`, `uint finLigne`, `uint finColonne` ); [fonction]`

- ### Paramètres

  - `débutLigne` : spécifie la ligne de début.

  - `débutColonne` : spécifie la colonne de début.

  - `finLigne` : spécifie la ligne de fin.

  - `finColonne` : spécifie la colonne de fin.

  Définit une sélection à partir de la ligne `débutLigne` et de la colonne `débutColonne` jusqu'à la ligne `finLigne` et la colonne `finColonne`.

#### Un exemple de script

À titre d'exemple, nous allons créer un petit script qui met en majuscules la sélection. Il est évident que nous devons d'abord déterminer si une sélection existe, et si tel est le cas, il faut obtenir le texte, changer la casse puis le remplacer par le nouveau. Voici ce pourrait donner la mise en œuvre :

    if ( view.hasSelection() )
    {
      // sélection en majuscules
      column = view.selectionStartColumn;
      line = view.selectionStartLine;

      selection = view.selection().toUpperCase();

      document.editBegin();
      view.removeSelectedText();
      document.insertText( ligne, colonne, sélection );
      document.editEnd();
    }

Pour grouper cette action, de façon à ce qu'elle soit inversée par une seule activation de la fonction Annuler, on encapsule les lignes

    view.removeSelectedText()

et

    document.insertText()

avec un

    document.editBegin()

et un

    document.editEnd()

#### Un exemple de fichier `.desktop`

Voici un exemple de fichier .desktop qui accompagne le script ci-dessus :

    # Exemple de fichier .desktop
    [Desktop Entry]
    Encoding=UTF-8
    Name=Mettre en majuscules JavaScript Kate Part
    Comment=Script pour convertir en majuscules la sélection
    X-Kate-Command=uppercase-selection
    X-Kate-Help=<p>Utilisation : <code>uppercase-selection</code></p>

Comme vous le constatez, vous pouvez définir l'encodage, définir un nom, un commentaire, un texte d'aide à l'aide de X-Kate-Help et le nom de la ligne de commande à l'aide de X-Kate-Command. Les éléments « Name », « Comment » et « X-Kate-Help » sont automatiquement traduits en d'autres langues par les équipes de traduction de KDE, si les fichiers sont dans le référentiel SVN de KDE.

#### En assemblant tout cela

&kate; recherchera les dossiers de script (voir ci-dessus) pour les fichiers `*.js`. Pour chaque fichier, l'application vérifie s'il existe un fichier `.desktop` correspondant : pour uppercase.js, ce pourrait être uppercase.desktop.

S'il n'est pas possible de trouver un fichier `.desktop`, le script sera enregistré dans la ligne de commande de katepart, avec le nom de fichier sans le .js de fin. Ainsi, dans notre exemple, ce serait `uppercase`. Si le nom de la commande est correct et que vous n'avez pas besoin des fonctionnalités supplémentaires, qu'offre un fichier `.desktop`, vous n'avez absolument pas besoin d'un fichier `.desktop`.

S'il existe un fichier `.desktop`, katepart lit le nom sous lequel le script sera enregistré à partir de l'élément .desktop-entry de X-Kate-Command, par exemple X-Kate-Command=uppercase-selection.