Écrit par Neil Deakin.
Traduit par Cyril Cheneson (28/07/2004).
Page originale :
http://www.xulplanet.com/tutorials/xultu/filedialog.html
Un type commun de boîtes de dialogue avec lequel un utilisateur peut sélectionner un fichier à ouvrir où à enregistrer.
Un sélecteur de fichiers est une boîte dialogue qui permet à l'utilisateur de sélectionner un fichier.
Il est le plus fréquemment utilisé pour les commandes de menu Ouvrir ou Enregistrer Sous,
mais vous pouvez l'utiliser n'importe où l'utilisateur a besoin de sélectionner un fichier.
L'interface XPCOM nsIFilePicker est utilisé pour implémenter un sélecteur de fichiers.
Vous pouvez utiliser le sélecteur de fichiers dans l'un des trois modes:
Open : On demande à l'utilisateur de sélectionner un fichier à ouvrir.GetFolder : On demande à l'utilisateur de sélectionner un répertoire.Save : On demande à l'utilisateur de sélectionner le nom sous lequel sera sauvé le fichier.L'apparence de la boîte de dialogue sera différente pour chaque type et variera selon la plate-forme. Une fois que l'utilisateur aura sélectionner le fichier ou le répertoire, 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 un certain nombre de particularités pour la boîte de dialogue en utilisant l'interface.
Quand 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é.
Pour commencer, vous avez besoin de 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électionner 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 le mode.
Le mode ici 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.
Il y a deux particularité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 par défaut qui est affiché quand la boîte de dialogue s'ouvre. Le second est un filtre qui indique la liste des types de fichiers à afficher dans la boîte de dialogue. On pourrait l'utiliser par exemple afin de tout cacher sauf les fichiers HTML.
Vous pouvez définir le répertoire par défaut en définissant la proprieté
displayDirectory de l'objet du sélecteur de fichiers.
Le répertoire devrait être un objet nslLocalFile. Si vous ne le définissez pas, un
répertoire par défaut sera sélectionné pour vous.
Pour ajouter des filtres, appelez la fonction appendFilters pour définir les types de fichier
que vous souhaitez voir afficher.
fp.appendFilters(nsIFilePicker.filterHTML | nsIFilePicker.filterImages);
fp.appendFilters(nsIFilePicker.filterText | nsIFilePicker.filterAll);
Le premier exemple ajoutera des filtres pour les fichiers HTML et images. L'utilisateur pourra uniquement sélectionner ces types de fichiers. La manière de procéder est spécifique à la plate-forme. Sur quelques plate-formes, chaque filtre sera séparé et l'utilisateur peut 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 afficher uniquement les fichiers textes ou tous les fichiers.
Vous pouvez aussi utilisez filterXML et filterXUL pour filtrer les fichiers
XML et XUL.
Si vous voulez filtrer des fichiers personalisés, vous pouvez utiliser la fonction appendFilter
pour faire cela :
fp.appendFilter("Fichiers Audio","*.wav; *.mp3");
Cette ligne ajoutera un filtre pour les fichiers audios wav et MP3. Le premier argument est le titre
du type de fichier et le second est une liste de masque de fichiers séparés par un point virgule.
Vous pouvez mettre autant de motifs 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.
Enfin, vous pouvez afficher la boîte de dialogue en appelant la fonction show.
elle ne prend aucun arguments mais retourne un code d'état qui indique ce que l'utilisateur a sélectionné.
Remarquez que la fonction ne retourne une valeur que lorsque l'utilisateur a sélectionné un fichier.
La fonction retourne une des trois constantes :
file du
sélecteur de fichiers.Vous devriez vérifier 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 ---
}
Dans la suite, nous verrons comment créer un assistant d'installation.