QDesktopServices Class

Documentation des fonctions membres

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

Ouvre l'url indiquée dans le navigateur Web adapté à l'environnement de bureau de l'utilisateur et renvoie true en cas de réussite ; sinon, renvoie false.

Si l'URL fait référence à un fichier local (c'est-à-dire si le schéma d'URL est « file »), celui-ci sera ouvert avec une application adaptée plutôt qu'avec un navigateur Web.

L'exemple suivant ouvre un fichier du système de fichiers Windows situé dans un chemin d'accès contenant des espaces :

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

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

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

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

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

Voir également setUrlHandler().

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

Définit le gestionnaire de l'scheme on indiquée comme étant le gestionnaire method fourni par l'objet receiver.

Cette fonction permet de personnaliser le comportement de ` openUrl()`. Si ` openUrl()` est appelée avec une URL contenant l'` scheme ` spécifié, alors la méthode ` method ` de l'objet ` receiver ` est appelée à la place de ` QDesktopServices `, qui lance une application externe.

La méthode fournie doit être implémentée sous la forme d’un slot n’acceptant 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 disposant déjà d'un gestionnaire, le gestionnaire existant est simplement remplacé par le nouveau. Étant donné qu'QDesktopServices ne prend pas possession des gestionnaires, aucun objet n'est supprimé lorsqu'un gestionnaire est remplacé.

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

Vous devez appeler ` unsetUrlHandler()` avant de détruire l'objet gestionnaire, afin que la destruction de cet objet ne chevauche pas les invocations simultanées de ` openUrl()` qui l'utilisent.

iOS et macOS

Pour utiliser cette fonction afin de recevoir des données provenant d’autres applications sous iOS/macOS, vous devez également ajouter le schéma personnalisé à la liste des « 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 des développeurs Apple intitulée « Définir un schéma d’URL personnalisé pour votre application ».

Pour déclarer 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 si 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 le fichier /.well-known/apple-app-site-association sur votre domaine lors de l’installation de l’application. Si vous souhaitez être accessible via https://your.domain.com/help?topic=ABCDEF, vous devez y fournir le contenu suivant :

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

Pour plus d’informations, consultez la documentation Apple pour les développeurs consacrée à la prise en charge des domaines associés.

Android

Pour utiliser cette fonctionnalité afin de recevoir des données provenant d’autres applications sur Android, vous devez ajouter un ou plusieurs filtres d’intention à la balise « 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, consultez la documentation des développeurs Android consacrée à la création de liens profonds vers le contenu d’une application.

Pour ouvrir immédiatement le contenu correspondant dans votre application Android, sans que l’utilisateur ait à 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 y fournir le contenu suivant :

[{
  "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, consultez la documentation des développeurs Android consacrée à la vérification des liens vers les applications 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'scheme spécifié.

Appelez cette fonction avant que l’objet gestionnaire enregistré pour scheme ne soit détruit, afin d’empêcher que des appels simultanés à openUrl() ne continuent à faire appel à l’objet gestionnaire détruit.

Voir également setUrlHandler().