12.3 Boîte de dialogue de fichiers

Attention : Ce tutoriel est ancien et n'est pas mis à jour. Bien que beaucoup d'informations soient encore valables pour les dernières versions de gecko, beaucoup sont aussi obsolètes. Il est préférable d'aller consulter cette page sur la version française de ce tutoriel sur developer.mozilla.org.

Un type commun de boîtes de dialogue est celui avec lequel un utilisateur peut sélectionner un fichier à ouvrir où à enregistrer.

Sélecteurs de fichiers

Un sélecteur de fichiers est une boîte dialogue qui permet à l'utilisateur de sélectionner un fichier. Il est fréquemment utilisé pour les commandes de menu « Ouvrir... » ou « Enregistrer sous... », mais vous pouvez l'utiliser dès que l'utilisateur a besoin de sélectionner un fichier. L'appel à l'interface XPCOM nsIFilePicker est nécessaire pour implémenter un sélecteur de fichiers.

Notez que le sélecteur de fichiers ne fonctionne qu'avec des URLs chrome.

Vous pouvez utiliser le sélecteur de fichiers dans l'un de ces trois modes :

• Open : Il est demandé à l'utilisateur de sélectionner un fichier à ouvrir.
• GetFolder : Il est demandé à l'utilisateur de sélectionner un répertoire/dossier.
• Save : Il est demandé à l'utilisateur de sélectionner le nom sous lequel sera sauvegardé le fichier.

L'apparence de la boîte de dialogue sera différente pour chaque type et variera selon la plateforme. Une fois que l'utilisateur aura sélectionné le fichier ou le répertoire/dossier, celui-ci pourra être lu ou enregistré.

L'interface du sélecteur de fichiers nsIFilePicker est responsable de l'affichage de la boîte de dialogue dans l'un des trois modes. Vous pouvez définir plusieurs fonctionnalités de la boîte de dialogue en utilisant cette interface. Une fois que la boîte de dialogue est fermée, vous pouvez utiliser les fonctions de l'interface pour obtenir le fichier qui a été sélectionné.

Création d'un sélecteur de fichier

Pour commencer, vous devez créer un composant du sélecteur de fichiers et l'initialiser.

var nsIFilePicker = Components.interfaces.nsIFilePicker;
var fp = Components.classes["@mozilla.org/filepicker;1"]
        .createInstance(nsIFilePicker);
fp.init(window, "Sélectionnez un fichier", nsIFilePicker.modeOpen);

Tout d'abord, un nouvel objet sélecteur de fichiers est créé et stocké dans une variable fp. La fonction init est utilisée pour initialiser le sélecteur de fichiers. Cette fonction prend trois arguments : la fenêtre qui ouvre la boîte de dialogue, le titre de la boîte de dialogue et son mode. Ici, le mode est modeOpen qui est utilisé pour une boîte de dialogue Ouvrir. Vous pouvez aussi utiliser modeGetFolder et modeSave pour les deux autres modes. Ces modes sont des constantes de l'interface nsIFilePicker.

Répertoire par défaut et filtres

Il y a deux fonctionnalités que vous pouvez définir pour la boîte de dialogue avant qu'elle ne soit affichée.

• La première est le répertoire/dossier par défaut qui est affiché à l'ouverture de la boîte de dialogue.
• La seconde est un filtre indiquant la liste des types de fichiers à afficher dans la boîte de dialogue. Elle pourrait être utilisée, par exemple, pour ne lister que les fichiers .html.

Vous pouvez définir le répertoire par défaut en renseignant la proprieté displayDirectory de l'objet du sélecteur de fichiers. Le répertoire doit être un objet nslLocalFile. Si vous ne le définissez pas, un répertoire par défaut sera sélectionné pour vous. Pour appliquer des filtres, appelez la fonction appendFilters() pour définir les types de fichiers que vous souhaitez voir s'afficher.

fp.appendFilters(nsIFilePicker.filterHTML | nsIFilePicker.filterImages);
fp.appendFilters(nsIFilePicker.filterText | nsIFilePicker.filterAll);

• Le premier exemple ajoutera des filtres pour les fichiers HTML et les images. L'utilisateur ne pourra sélectionner que ces types de fichiers. La manière de procéder est spécifique à la plateforme. Sur quelques plateformes, chaque filtre sera séparé et l'utilisateur pourra choisir entre les fichiers HTML et les fichiers images.
• Le second exemple ajoutera des filtres pour les fichiers textes et pour tous les fichiers. L'utilisateur a ainsi une option pour n'afficher que les fichiers textes ou tous les fichiers.

Vous pouvez aussi utiliser filterXML et filterXUL pour filtrer les fichiers XML et XUL. Si vous voulez filtrer des fichiers personnalisés, vous pouvez utiliser la fonction appendFilter() :

fp.appendFilter("Fichiers Audio","*.wav; *.mp3");

Cette ligne ajoutera un filtre pour les fichiers audio Wav et MP3. Le premier argument est le titre du type de fichier et le second est une liste de masques de fichiers séparés par un point virgule. Vous pouvez mettre autant de masques que vous le souhaitez. Vous pouvez appeler appendFilter autant de fois que nécessaire pour ajouter les filtres supplémentaires. L'ordre dans lequel vous les ajoutez détermine leur priorité. Habituellement, le premier ajouté est sélectionné par défaut.

Obtention du fichier sélectionné

Enfin, vous pouvez afficher la boîte de dialogue en appelant la fonction show(). Elle ne prend aucun argument mais retourne un code d'état qui indique ce que l'utilisateur a sélectionné. Notez que la fonction ne retourne aucune valeur tant que l'utilisateur n'a pas sélectionné un fichier. La fonction retourne une des trois constantes suivantes :

returnOK :

l'utilisateur a sélectionné un fichier et a pressé le bouton « OK ». Le fichier que l'utilisateur a sélectionné sera stocké dans la propriété file du sélecteur de fichiers.

returnCancel :

l'utilisateur a pressé le bouton « Annuler ».

returnReplace :

dans le mode enregistrement, cette valeur de retour signifie que l'utilisateur a sélectionné un fichier à remplacer (returnOK sera retournée lorsque l'utilisateur aura rentré le nom d'un nouveau fichier).

Vous devrez tester la valeur de retour et ensuite utiliser l'objet file du sélecteur de fichiers en utilisant la propriété file.

var res = fp.show();
if (res == nsIFilePicker.returnOK){
  var thefile = fp.file;
  // --- faire quelque chose avec le fichier ici ---
}

---

Par la suite, nous verrons comment créer un assistant.