Sur cette page

QStandardPaths Class

La classe QStandardPaths fournit des méthodes d'accès aux chemins standard. Plus d'informations...

En-tête : #include <QStandardPaths>
CMake : find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake : QT += core

Types publics

enum LocateOption { LocateFile, LocateDirectory }
flags LocateOptions
enum StandardLocation { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, MusicLocation, …, GenericStateLocation }

Membres publics statiques

QString displayName(QStandardPaths::StandardLocation type)
QString findExecutable(const QString &executableName, const QStringList &paths = QStringList())
QString locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
QStringList locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
void setTestModeEnabled(bool testMode)
QStringList standardLocations(QStandardPaths::StandardLocation type)
QString writableLocation(QStandardPaths::StandardLocation type)

Description détaillée

Cette classe contient des fonctions permettant d'interroger des emplacements standard sur le système de fichiers local, pour des tâches courantes telles que les répertoires spécifiques à l'utilisateur ou les répertoires de configuration à l'échelle du système.

Documentation des types de membres

enum QStandardPaths::LocateOption
flags QStandardPaths::LocateOptions

Cette énumération décrit les différents drapeaux qui peuvent être utilisés pour contrôler le comportement de QStandardPaths::locate et QStandardPaths::locateAll.

ConstanteValeurDescription de l'option
QStandardPaths::LocateFile0x0ne renvoie que les fichiers
QStandardPaths::LocateDirectory0x1ne renvoie que les répertoires

Le type LocateOptions est un typedef pour QFlags<LocateOption>. Il stocke une combinaison OU de valeurs LocateOption.

enum QStandardPaths::StandardLocation

Cette liste décrit les différents emplacements qui peuvent être interrogés à l'aide de méthodes telles que QStandardPaths::writableLocation, QStandardPaths::standardLocations, et QStandardPaths::displayName.

Certaines des valeurs de cette énumération représentent une configuration de l'utilisateur. Ces valeurs renverront les mêmes chemins dans différentes applications, de sorte qu'elles pourraient être utilisées pour partager des données avec d'autres applications. D'autres valeurs sont spécifiques à cette application. Dans le tableau ci-dessous, chaque valeur de l'énumération indique si elle est spécifique à l'application ou générique.

Les répertoires spécifiques à une application doivent être considérés comme inaccessibles aux autres applications. Par conséquent, les fichiers qui y sont placés peuvent ne pas être lisibles par d'autres applications, même si elles sont exécutées par le même utilisateur. En revanche, les répertoires génériques sont censés être accessibles à toutes les applications exécutées par cet utilisateur, mais ils sont toujours censés être inaccessibles aux applications d'autres utilisateurs.

L'échange de données avec d'autres utilisateurs n'entre pas dans le champ d'application de QStandardPaths.

ConstanteValeurDescription de la constante
QStandardPaths::DesktopLocation0Renvoie le répertoire du bureau de l'utilisateur. Il s'agit d'une valeur générique. Sur les systèmes qui n'ont pas de concept de bureau, elle est identique à QStandardPaths::HomeLocation.
QStandardPaths::DocumentsLocation1Renvoie le répertoire contenant les fichiers de documents de l'utilisateur. Il s'agit d'une valeur générique. Le chemin retourné n'est jamais vide.
QStandardPaths::FontsLocation2Renvoie le répertoire contenant les polices de l'utilisateur. Il s'agit d'une valeur générique. Notez que l'installation des polices peut nécessiter des opérations supplémentaires spécifiques à la plate-forme.
QStandardPaths::ApplicationsLocation3Renvoie le répertoire contenant les applications de l'utilisateur (soit des exécutables, soit des paquets d'applications, soit des raccourcis vers ces applications). Il s'agit d'une valeur générique. L'installation d'applications peut nécessiter des opérations supplémentaires spécifiques à la plate-forme. Les fichiers, dossiers ou raccourcis de ce répertoire sont spécifiques à la plate-forme.
QStandardPaths::MusicLocation4Renvoie le répertoire contenant la musique ou d'autres fichiers audio de l'utilisateur. Il s'agit d'une valeur générique. S'il n'existe pas de répertoire spécifique pour les fichiers musicaux, une solution de rechange raisonnable pour le stockage des documents de l'utilisateur est renvoyée.
QStandardPaths::MoviesLocation5Renvoie le répertoire contenant les films et les vidéos de l'utilisateur. Il s'agit d'une valeur générique. S'il n'existe pas de répertoire spécifique pour les fichiers de films, une solution de repli raisonnable pour le stockage des documents de l'utilisateur est renvoyée.
QStandardPaths::PicturesLocation6Renvoie le répertoire contenant les images ou les photos de l'utilisateur. Il s'agit d'une valeur générique. S'il n'existe pas de répertoire spécifique pour les fichiers d'images, une solution de repli raisonnable pour le stockage des documents de l'utilisateur est renvoyée.
QStandardPaths::TempLocation7Renvoie un répertoire dans lequel les fichiers temporaires peuvent être stockés. La valeur renvoyée peut être spécifique à une application, partagée par d'autres applications pour cet utilisateur, ou même par l'ensemble du système. Le chemin renvoyé n'est jamais vide.
QStandardPaths::HomeLocation8Renvoie le répertoire personnel de l'utilisateur (identique à QDir::homePath()). Sur les systèmes Unix, cette valeur est égale à la variable d'environnement HOME. Cette valeur peut être générique ou spécifique à une application, mais le chemin renvoyé n'est jamais vide.
QStandardPaths::AppLocalDataLocation9Renvoie le chemin d'accès aux paramètres locaux sur le système d'exploitation Windows. Sur toutes les autres plateformes, il renvoie la même valeur que AppDataLocation. Cette valeur d'énumération a été ajoutée dans Qt 5.4.
QStandardPaths::CacheLocation10Renvoie l'emplacement d'un répertoire où les données non essentielles (mises en cache) propres à l'utilisateur doivent être écrites. Il s'agit d'un répertoire spécifique à l'application. Le chemin retourné n'est jamais vide.
QStandardPaths::GenericCacheLocation15Renvoie un répertoire où les données non essentielles (mises en cache) spécifiques à l'utilisateur, partagées entre les applications, doivent être écrites. Il s'agit d'une valeur générique. Notez que le chemin renvoyé peut être vide si le système n'a pas de concept de cache partagé.
QStandardPaths::GenericDataLocation11Renvoie un répertoire où les données persistantes partagées entre les applications peuvent être stockées. Il s'agit d'une valeur générique. Le chemin renvoyé n'est jamais vide.
QStandardPaths::RuntimeLocation12Renvoie un répertoire où les fichiers de communication d'exécution doivent être écrits, comme les sockets locaux Unix. Il s'agit d'une valeur générique. Le chemin retourné peut être vide sur certains systèmes.
QStandardPaths::ConfigLocation13Renvoie un répertoire où les fichiers de configuration spécifiques à l'utilisateur doivent être écrits. Il peut s'agir d'une valeur générique ou spécifique à une application, et le chemin renvoyé n'est jamais vide.
QStandardPaths::DownloadLocation14Renvoie un répertoire pour les fichiers téléchargés par l'utilisateur. Il s'agit d'une valeur générique. S'il n'existe pas de répertoire spécifique aux téléchargements, une solution de repli raisonnable pour le stockage des documents de l'utilisateur est renvoyée.
QStandardPaths::GenericConfigLocation16Renvoie un répertoire dans lequel les fichiers de configuration spécifiques à l'utilisateur et partagés entre plusieurs applications doivent être écrits. Il s'agit d'une valeur générique et le chemin renvoyé n'est jamais vide.
QStandardPaths::AppDataLocation17Renvoie un répertoire où les données persistantes de l'application peuvent être stockées. Il s'agit d'un répertoire spécifique à l'application. Pour obtenir un chemin permettant de stocker des données à partager avec d'autres applications, utilisez QStandardPaths::GenericDataLocation. Le chemin renvoyé n'est jamais vide. Sur le système d'exploitation Windows, cette valeur renvoie le chemin d'accès itinérant. Cette valeur enum a été ajoutée dans Qt 5.4.
QStandardPaths::AppConfigLocation18Renvoie un répertoire où les fichiers de configuration spécifiques à l'utilisateur doivent être écrits. Il s'agit d'un répertoire spécifique à l'application, et le chemin renvoyé n'est jamais vide. Cette valeur a été ajoutée dans Qt 5.5.
QStandardPaths::PublicShareLocation19Renvoie un répertoire où les fichiers et répertoires partagés publiquement et spécifiques à l'utilisateur peuvent être stockés. Il s'agit d'une valeur générique. Notez que le chemin retourné peut être vide si le système n'a pas de concept d'emplacement partagé publiquement. Cette valeur d'énumération a été ajoutée dans Qt 6.4.
QStandardPaths::TemplatesLocation20Renvoie un répertoire où les fichiers de modèles spécifiques à l'utilisateur peuvent être stockés. Il s'agit d'une valeur générique. Notez que le chemin retourné peut être vide si le système n'a pas de concept d'emplacement pour les modèles. Cette valeur d'énumération a été ajoutée dans Qt 6.4.
QStandardPaths::StateLocation (since Qt 6.7)21Renvoie un répertoire où les fichiers de données d'état d'application spécifiques à l'utilisateur doivent être écrits. Il s'agit d'un répertoire spécifique à l'application, et le chemin retourné n'est jamais vide.
QStandardPaths::GenericStateLocation (since Qt 6.7)22Renvoie un répertoire où les fichiers de données d'état partagés entre les applications doivent être écrits. Cette valeur peut être générique ou spécifique à une application, mais le chemin renvoyé n'est jamais vide.

Le tableau suivant donne des exemples de chemins sur différents systèmes d'exploitation. Le premier chemin est le chemin accessible en écriture (sauf indication contraire). Les autres chemins supplémentaires, le cas échéant, représentent des emplacements non inscriptibles.

Type de cheminmacOSWindows
Emplacement du bureau"~/Desktop"C:/Users/<USER>/Desktop"
Emplacement des documents"~/Documents"C:/Users/<USER>/Documents"
FontsLocation"/System/Library/Fonts" (non accessible en écriture)"C:/Windows/Fonts" (non accessible en écriture)
ApplicationsLocation"/Applications" (non accessible en écriture)"C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Menu de démarrage/Programmes" (pas d'écriture)
Emplacement de la musique"~/Musique"C:/Users/<USER>/Music"
Emplacement des films"~/Movies""C:/Users/<USER>/Vidéos
PicturesLocation"~/Pictures""C:/Users/<USER>/Pictures"
Emplacement temporairegénéré aléatoirement par le système d'exploitation"C:/Users/<USER>/AppData/Local/Temp"
Emplacement de la maison"~""C:/Users/<USER>"
AppLocalDataLocation"~/Bibliothèque/Application Support/<APPNAME>", "/Bibliothèque/Application Support/<APPNAME>". "<APPDIR>/../Resources""C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>".
CacheLocation"~/Bibliothèque/Caches/<APPNAME>", "/Bibliothèque/Caches/<APPNAME>""C:/Users/<USER>/AppData/Local/<APPNAME>/cache"
Emplacement de l'état"~/Bibliothèque/Préférences/<APPNAME>/State""C:/Users/<USER>/AppData/Local/<APPNAME>/State", "C:/ProgramData/<APPNAME>/State"
GenericDataLocation"~/Bibliothèque/Application Support", "/Bibliothèque/Application Support""C:/Users/<USER>/AppData/Local", "C:/ProgramData", "<APPDIR>", "<APPDIR>/data"
Emplacement de l'exécution"~/Bibliothèque/Application Support""C:/Users/<USER>"
ConfigLocation"~/Bibliothèque/Préférences"C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>"
GenericConfigLocation"~/Bibliothèque/Préférences"C:/Users/<USER>/AppData/Local", "C:/ProgramData"
DownloadLocation"~/Téléchargements""C:/Users/<USER>/Downloads"
GenericCacheLocation"~/Bibliothèque/Caches", "/Bibliothèque/Caches""C:/Users/<USER>/AppData/Local/cache".
GenericStateLocation"~/Bibliothèque/Préférences/État""C:/Users/<USER>/AppData/Local/State", "C:/ProgramData/State"
AppDataLocation"~/Bibliothèque/Application Support/<APPNAME>", "/Bibliothèque/Application Support/<APPNAME>". "<APPDIR>/../Resources""C:/Users/<USER>/AppData/Roaming/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>".
AppConfigLocation"~/Bibliothèque/Préférences/<APPNAME>""C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>"
PublicShareLocation"~/PublicC:/Users/Public", "C:/ProgramData/<APPNAME>", "~/Public".
TemplatesLocation"~/Templates""C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Templates"
Type de cheminLinux et autres systèmes d'exploitation UNIX
Emplacement du bureau"~/Desktop
Emplacement des documents"~/Documents
FontsLocation"~/.fonts", "~/.local/share/fonts", "/usr/local/share/fonts", "/usr/share/fonts".
Emplacement des applications"~/.local/share/applications", "/usr/local/share/applications", "/usr/share/applications"
Emplacement de la musique"~/Musique
Emplacement des films"~/Vidéos
PicturesLocation"~/Pictures
Emplacement Temp"/tmp
HomeLocation"~"
AppLocalDataLocation"~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>"
Emplacement du cache"~/.cache/<APPNAME>"
StateLocation"~/.local/state/<APPNAME>"
GenericDataLocation"~/.local/share", "/usr/local/share", "/usr/share"
RuntimeLocation"/run/user/<USER>"
ConfigLocation"~/.config", "/etc/xdg"
GenericConfigLocation"~/.config", "/etc/xdg"
DownloadLocation"~/Downloads
GenericCacheLocation"~/.cache
GenericStateLocation"~/.local/state"
AppDataLocation"~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>"
AppConfigLocation"~/.config/<APPNAME>", "/etc/xdg/<APPNAME>"
PublicShareLocation"~/Public
TemplatesLocation"~/Templates
Type de cheminAndroidiOS
Emplacement du bureau"<APPROOT>/files"<APPROOT>/Documents/Desktop"
Emplacement des documents"<USER>/Documents" [*], "<USER>/<APPNAME>/Documents"<APPROOT>/Documents> [*], "<USER>/<APPNAME>/Documents"
FontsLocation"/system/fonts" (non accessible en écriture)"<APPROOT>/Library/Fonts" (non accessible en écriture)
Emplacement des applicationsnon pris en charge (répertoire non lisible)non pris en charge
Emplacement de la musique"<USER>/Musique" [*], "<USER>/<APPNAME>/Musique""<APPROOT>/Documents/Musique
Emplacement des films"<USER>/Movies" [*], "<USER>/<APPNAME>/Movies""<APPROOT>/Documents/Movies"
Emplacement des images"<USER>/Pictures" [*], "<USER>/<APPNAME>/Pictures""<APPROOT>/Documents/Pictures", "assets-library://"
Emplacement temporaire"<APPROOT>/cache"<APPROOT>/tmp"
HomeLocation"<APPROOT>/filesdéfini par le système
AppLocalDataLocation"<APPROOT>/files", "<USER>/<APPNAME>/files""<APPROOT>/Library/Application Support", <APPROOT>/<APPNAME>/files
CacheLocation"<APPROOT>/cache", "<USER>/<APPNAME>/cache""<APPROOT>/Bibliothèque/Caches"
Emplacement de l'état"<APPROOT>/files/state"
GenericStateLocation (il y a un état partagé)"<APPROOT>/files/state"
Emplacement des données génériques"<USER>" [*] ou "<USER>/<APPNAME>/files""<APPROOT>/Library/Application Support"
RuntimeLocation"<APPROOT>/cachenon pris en charge
Emplacement de la configuration"<APPROOT>/files/settings""<APPROOT>/Library/Preferences"
GenericConfigLocation"<APPROOT>/files/settings" (il n'y a pas de paramètres partagés)<APPROOT>/Library/Preferences> "<APPROOT>/files/settings" (il n'y a pas de paramètres partagés)
Emplacement du téléchargement"<USER>/Downloads" [*], "<USER>/<APPNAME>/Downloads"<APPROOT>/Documents/Downloads" [*], "<USER>/<APPNAME>/Downloads".
Emplacement du cache générique"<APPROOT>/cache" (il n'y a pas de cache partagé)"<APPROOT>/Library/Caches" (il n'y a pas de cache partagé)
AppDataLocation"<APPROOT>/files", "<USER>/<APPNAME>/files""<APPROOT>/Library/Application Support"
AppConfigLocation"<APPROOT>/files/settings""<APPROOT>/Library/Preferences/<APPNAME>"
PublicShareLocationnon pris en chargenon supporté
TemplatesLocationnon pris en chargenon pris en charge

Dans le tableau ci-dessus, <APPNAME> est généralement le nom de l'organisation, le nom de l'application, ou les deux, ou un nom unique généré lors de l'emballage. De même, <APPROOT> est l'emplacement où cette application est installée (souvent un bac à sable). <APPDIR> est le répertoire contenant l'exécutable de l'application.

Il ne faut pas se fier aux chemins ci-dessus, car ils peuvent changer en fonction de la configuration du système d'exploitation, de la locale, ou ils peuvent changer dans les futures versions de Qt.

Note : Sur Android, les applications avec des fichiers ouverts sur le stockage externe (emplacements <USER>), seront tuées si le stockage externe est démonté.

Remarque : sur Android 6.0 (API 23) ou plus, l'autorisation "WRITE_EXTERNAL_STORAGE" doit être demandée au moment de l'exécution lors de l'utilisation de QStandardPaths::writableLocation ou QStandardPaths::standardLocations.

Note : Sous Android, la lecture/écriture dans GenericDataLocation nécessite l'autorisation READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE.

Note : [*] Sur Android 11 et plus, les répertoires publics ne sont plus directement accessibles en mode "scoped storage". Par conséquent, les chemins de la forme "<USER>/DirName" ne sont pas renvoyés. Au lieu de cela, vous pouvez utiliser QFileDialog qui utilise le Storage Access Framework (SAF) pour accéder à ces répertoires.

Note : Sur iOS, si vous passez QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last() comme argument à QFileDialog::setDirectory(), une boîte de dialogue native de sélection d'images sera utilisée pour accéder à l'album photo de l'utilisateur. Le nom du fichier renvoyé peut être chargé à l'aide de QFile et des API correspondantes. Cette fonctionnalité a été ajoutée dans Qt 5.5.

Voir aussi writableLocation(), standardLocations(), displayName(), locate() et locateAll().

Documentation des fonctions membres

[static] QString QStandardPaths::displayName(QStandardPaths::StandardLocation type)

Renvoie un nom d'affichage localisé pour l'emplacement donné type ou un QString vide si aucun emplacement pertinent ne peut être trouvé.

[static] QString QStandardPaths::findExecutable(const QString &executableName, const QStringList &paths = QStringList())

Recherche l'exécutable nommé executableName dans le répertoire paths spécifié, ou dans le chemin d'accès au système si paths est vide.

Sur la plupart des systèmes d'exploitation, le chemin d'accès au système est déterminé par la variable d'environnement PATH. Les répertoires dans lesquels l'exécutable doit être recherché peuvent être définis dans l'argument paths. Pour rechercher à la fois dans vos propres chemins et dans les chemins du système, appelez findExecutable deux fois, une fois avec chemins définis et une fois avec chemins vides. Les liens symboliques ne sont pas résolus afin de préserver le comportement des exécutables dont le comportement dépend du nom avec lequel ils sont invoqués.

Remarque : sous Windows, les extensions habituelles des exécutables (provenant de la variable d'environnement PATHEXT) sont automatiquement ajoutées. Par exemple, l'appel findExecutable("foo") trouve foo.exe ou foo.bat s'il est présent.

Renvoie le chemin d'accès absolu à l'exécutable, ou une chaîne vide s'il n'est pas trouvé.

Si l'adresse executableName est un chemin absolu menant à un exécutable, son chemin propre est renvoyé.

[static] QString QStandardPaths::locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)

Recherche un fichier ou un répertoire appelé fileName dans les emplacements standard de type.

L'option options vous permet de spécifier si vous devez rechercher des fichiers ou des répertoires. Par défaut, cet indicateur est défini sur LocateFile.

Renvoie le chemin d'accès absolu au premier fichier ou répertoire trouvé, sinon il renvoie une chaîne vide.

[static] QStringList QStandardPaths::locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)

Recherche tous les fichiers ou répertoires portant le nom fileName dans les emplacements standard de type.

L'indicateur options vous permet de spécifier s'il faut rechercher des fichiers ou des répertoires. Par défaut, cet indicateur est défini sur LocateFile.

Renvoie la liste de tous les fichiers trouvés.

[static] void QStandardPaths::setTestModeEnabled(bool testMode)

Si testMode est true, cela active un "mode test" spécial dans QStandardPaths, qui modifie les emplacements accessibles en écriture pour qu'ils pointent vers des répertoires de test. Cela empêche les tests automatiques de lire ou d'écrire dans la configuration de l'utilisateur actuel.

Cela affecte les emplacements dans lesquels les programmes de test peuvent écrire des fichiers : GenericDataLocation, AppDataLocation, ConfigLocation, GenericConfigLocation, AppConfigLocation, StateLocation, GenericStateLocation, GenericCacheLocation, et CacheLocation. Les autres emplacements ne sont pas concernés.

Sous Unix, XDG_DATA_HOME correspond à ~/.qttest/share, XDG_CONFIG_HOME correspond à ~/.qttest/config, XDG_STATE_HOME correspond à ~/.qttest/state et XDG_CACHE_HOME correspond à ~/.qttest/cache.

Sous macOS, les données vont à ~/.qttest/Application Support, le cache à ~/.qttest/Cache et la configuration à ~/.qttest/Preferences.

Sous Windows, tout va dans un répertoire "qttest" sous %APPDATA%.

[static] QStringList QStandardPaths::standardLocations(QStandardPaths::StandardLocation type)

Renvoie tous les répertoires auxquels appartiennent les fichiers de type.

La liste des répertoires est triée de la plus haute à la plus basse priorité, en commençant par writableLocation() s'il est possible de le déterminer. Cette liste est vide si aucun emplacement pour le type n'est défini.

Voir aussi writableLocation().

[static] QString QStandardPaths::writableLocation(QStandardPaths::StandardLocation type)

Renvoie le répertoire dans lequel les fichiers de type doivent être écrits, ou une chaîne vide si l'emplacement ne peut être déterminé.

Remarque : l'emplacement de stockage renvoyé peut ne pas exister, c'est-à-dire qu'il peut devoir être créé par le système ou l'utilisateur.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.