QDesktopServices Class

Documentation des fonctions membres

[static] bool QDesktopServices::openUrl(const QUrl &url)

Ouvre l'adresse url dans le navigateur Web approprié à l'environnement de bureau de l'utilisateur et renvoie true en cas de succès ; sinon, renvoie false.

Si l'URL est une référence à un fichier local (c'est-à-dire que le schéma de l'URL est "file"), il sera ouvert avec une application appropriée au lieu d'un navigateur Web.

L'exemple suivant ouvre un fichier sur le système de fichiers Windows résidant sur un chemin d'accès contenant des espaces :

QDesktopServices::openUrl(QUrl("file:///C:/Program Files", QUrl::TolerantMode));

Si une URL mailto est spécifiée, le client de messagerie de l'utilisateur sera utilisé pour ouvrir une fenêtre de composition contenant les options spécifiées dans l'URL, de la même manière que les liens mailto sont traités par un navigateur Web.

Par exemple, l'URL suivante contient un destinataire (user@foo.com), un objet (Test) et un corps de message (Just a test) :

mailto:user@foo.com?subject=Test&body=Just a test

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>https</string>
</array>

Voir aussi setUrlHandler().

[static] void QDesktopServices::setUrlHandler(const QString &scheme, QObject *receiver, const char *method)

Définit le gestionnaire pour l'objet scheme donné comme étant le gestionnaire method fourni par l'objet receiver.

Cette fonction permet de personnaliser le comportement de openUrl(). Si openUrl() est appelé avec une URL contenant l'adresse scheme spécifiée, l'adresse method de l'objet receiver est appelée au lieu de QDesktopServices pour lancer une application externe.

La méthode fournie doit être implémentée comme un slot qui n'accepte qu'un seul argument QUrl.

class MyHelpHandler : public QObject
{
    Q_OBJECT
public:
    // ...
public slots:
    void showHelp(const QUrl &url);
};

Si setUrlHandler() est utilisé pour définir un nouveau gestionnaire pour un schéma qui a déjà un gestionnaire, le gestionnaire existant est simplement remplacé par le nouveau. Comme QDesktopServices n'est pas propriétaire des gestionnaires, aucun objet n'est supprimé lorsqu'un gestionnaire est remplacé.

Notez que le gestionnaire sera toujours appelé par le même thread qui appelle QDesktopServices::openUrl().

Vous devez appeler unsetUrlHandler() avant de détruire l'objet gestionnaire, de sorte que la destruction de l'objet gestionnaire n'empiète pas sur les invocations concurrentes de openUrl() qui l'utilisent.

iOS et macOS

Pour utiliser cette fonction afin de recevoir des données d'autres applications sous iOS/macOS, vous devez également ajouter le schéma personnalisé à la liste CFBundleURLSchemes dans votre fichier Info.plist :

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

Pour plus d'informations, consultez la documentation Apple Developer sur la définition d'un schéma d'URL personnalisé pour votre application.

Pour revendiquer la prise en charge de http et https, l'entrée ci-dessus dans le fichier Info.plist n'est pas autorisée. Cela n'est possible que lorsque vous ajoutez votre domaine au fichier Entitlements :

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:your.domain.com</string>
</array>

iOS/macOS recherchera /.well-known/apple-app-site-association sur votre domaine, lorsque l'application sera installée. Si vous souhaitez écouter https://your.domain.com/help?topic=ABCDEF, vous devez fournir le contenu suivant dans ce fichier :

{
    "applinks": {
        "apps": [],
        "details": [{
            "appIDs" : [ "ABCDE12345.com.example.app" ],
            "components": [{
                "/": "/help",
                "?": { "topic": "?*"}
            }]
        }]
    }
}

Pour plus d'informations, voir la documentation Apple Developer Documentation for Supporting Associated Domains.

Android

Pour utiliser cette fonction afin de recevoir des données d'autres applications sur Android, vous devez ajouter un ou plusieurs filtres d'intention à l'adresse activity dans le manifeste de votre application :

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="your.domain.com" android:port="1337" android:path="/help"/>
</intent-filter>

Pour plus d'informations, voir la documentation du développeur Android pour Créer des liens profonds vers le contenu de l'application.

Pour ouvrir immédiatement le contenu correspondant dans votre application Android, sans demander à l'utilisateur de sélectionner l'application, vous devez vérifier votre lien. Pour activer la vérification, ajoutez un paramètre supplémentaire à votre filtre d'intention :

<intent-filter android:autoVerify="true">

Android recherchera https://your.domain.com/.well-known/assetlinks.json, lorsque l'application sera installée. Si vous souhaitez écouter https://your.domain.com:1337/help, vous devez fournir le contenu suivant à cet endroit :

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Pour plus d'informations, voir la documentation du développeur Android pour Vérifier les liens de l'application Android.

Voir également openUrl() et unsetUrlHandler().

[static] void QDesktopServices::unsetUrlHandler(const QString &scheme)

Supprime un gestionnaire d'URL précédemment défini pour l'adresse scheme spécifiée.

Appelez cette fonction avant que l'objet gestionnaire enregistré pour scheme ne soit détruit, afin d'éviter que des appels simultanés à openUrl() ne continuent d'appeler l'objet gestionnaire détruit.

Voir aussi setUrlHandler().