QFileSelector Class

Description détaillée

QFileSelector est un outil pratique permettant de sélectionner des variantes de fichiers en fonction des caractéristiques de la plateforme ou du périphérique. Cela vous permet de développer et de déployer plus facilement une base de code unique contenant toutes les différentes variantes dans certaines circonstances, par exemple lorsque la variante correcte ne peut pas être déterminée lors de l'étape de déploiement.

Utilisation de QFileSelector

Si vous utilisez toujours le même fichier, vous n'avez pas besoin d'utiliser QFileSelector.

Prenons l'exemple suivant, dans lequel vous souhaitez utiliser différents fichiers de paramètres selon les paramètres régionaux. Vous pouvez sélectionner le code en fonction des paramètres régionaux comme suit :

QString defaultsBasePath = "data/";
QString defaultsPath = defaultsBasePath + "defaults.conf";
QString localizedPath = defaultsBasePath
        + QString("%1/defaults.conf").arg(QLocale().name());
if (QFile::exists(localizedPath))
    defaultsPath = localizedPath;
QFile defaults(defaultsPath);

De même, si vous souhaitez choisir un fichier de données différent en fonction de la plateforme cible, votre code pourrait ressembler à ceci :

    QString defaultsPath = "data/defaults.conf";
#if defined(Q_OS_ANDROID)
    defaultsPath = "data/android/defaults.conf";
#elif defined(Q_OS_IOS)
    defaultsPath = "data/ios/defaults.conf";
#endif
    QFile defaults(defaultsPath);

QFileSelector offre une alternative pratique à l’écriture de ce type de code standard, et dans ce dernier cas, il vous permet de commencer à utiliser une configuration spécifique à la plateforme sans avoir à recompiler. QFileSelector permet également d’enchaîner plusieurs sélecteurs de manière pratique, par exemple pour sélectionner un fichier différent uniquement selon certaines combinaisons de plate-forme et de paramètres régionaux. Par exemple, pour effectuer une sélection en fonction de la plate-forme et/ou des paramètres régionaux, le code est le suivant :

QFileSelector selector;
QFile defaultsFile(selector.select("data/defaults.conf"));

Les fichiers à sélectionner sont placés dans des répertoires nommés d’après une « '+' » et un nom de sélecteur. Dans l’exemple ci-dessus, vous pourriez faire en sorte que les configurations de plate-forme soient sélectionnées en les plaçant aux emplacements suivants :

data/defaults.conf
data/+android/defaults.conf
data/+ios/+en_GB/defaults.conf

Pour trouver les fichiers sélectionnés, QFileSelector recherche dans le même répertoire que le fichier de base. S’il existe des répertoires de la forme +<sélecteur> avec un sélecteur actif, QFileSelector privilégiera un fichier portant le même nom provenant de ce répertoire plutôt que le fichier de base. Ces répertoires peuvent être imbriqués pour effectuer une vérification par rapport à plusieurs sélecteurs, par exemple :

images/background.png
images/+android/+en_GB/background.png

Avec ces fichiers disponibles, vous sélectionneriez un fichier différent sur la plateforme Android, mais uniquement si la locale était en_GB.

Pour la gestion des erreurs en l’absence de sélecteurs valides, il est recommandé de disposer d’un fichier par défaut ou de gestion des erreurs à l’emplacement du fichier de base, même si vous vous attendez à ce que des sélecteurs soient présents pour tous les déploiements.

Dans une future version, certains pourraient être marqués comme « statiques au moment du déploiement » et être déplacés lors de l’étape de déploiement à des fins d’optimisation. Les sélecteurs ayant un coût en termes de performances, il est recommandé d’éviter leur utilisation dans des contextes impliquant du code pour lequel les performances sont critiques.

Ajout de sélecteurs

Les sélecteurs normalement disponibles sont

• platform, l’une des chaînes suivantes correspondant à la plateforme sur laquelle l’application s’exécute (liste non exhaustive) : android, harmonyos, ios, osx, darwin, mac, macos, linux, qnx, unix, windows. Sous Linux, s’il est possible de le déterminer, le nom de la distribution est également pris en compte, par exemple debian, fedora ou opensuse.
• locale, identique à QLocale().name().

D'autres sélecteurs seront ajoutés à partir de la variable d'environnement ` QT_FILE_SELECTORS `, qui, lorsqu'elle est définie, doit contenir un ensemble de sélecteurs séparés par des virgules. Notez que cette variable n'est lue qu'une seule fois ; les sélecteurs peuvent ne pas être mis à jour si la variable change pendant l'exécution de l'application. L'ensemble initial de sélecteurs n'est évalué qu'une seule fois, lors de la première utilisation.

Vous pouvez également ajouter des sélecteurs supplémentaires lors de l’exécution pour un comportement personnalisé. Ceux-ci seront utilisés dans tous les futurs appels à ` select()`. Si la liste des sélecteurs supplémentaires a été modifiée, les appels à ` select()` utiliseront la nouvelle liste et pourront renvoyer des résultats différents.

Résolution des conflits lorsque plusieurs sélecteurs s’appliquent

Lorsque plusieurs sélecteurs peuvent s’appliquer à un même fichier, le premier sélecteur correspondant est retenu. L’ordre dans lequel les sélecteurs sont vérifiés est le suivant :

1. Les sélecteurs définis via setExtraSelectors(), dans l’ordre où ils apparaissent dans la liste
2. Les sélecteurs de la variable d’environnement ` QT_FILE_SELECTORS `, de gauche à droite
3. Locale
4. Plateforme

Voici un exemple impliquant plusieurs sélecteurs correspondant simultanément. Il utilise des sélecteurs de plateforme, ainsi qu’un sélecteur supplémentaire nommé « admin » défini par l’application en fonction des identifiants de l’utilisateur. L’exemple est classé de manière à ce que le fichier correspondant le moins prioritaire soit choisi si tous les sélecteurs étaient présents :

images/background.png
images/+linux/background.png
images/+windows/background.png
images/+admin/background.png
images/+admin/+linux/background.png

Comme les sélecteurs supplémentaires sont vérifiés avant ceux de la plateforme, le fichier +admin/background.png sera choisi sous Windows lorsque le sélecteur « admin » est défini, et le fichier +windows/background.png sera choisi sous Windows lorsque le sélecteur « admin » n’est pas défini. Sous Linux, le fichier +admin/+linux/background.png sera choisi lorsque « admin » est défini, et le fichier +linux/background.png lorsqu’il ne l’est pas.