QDesktopServices Class

Member Function Documentation

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

Opens the given url in the appropriate Web browser for the user's desktop environment, and returns true if successful; otherwise returns false.

If the URL is a reference to a local file (i.e., the URL scheme is "file") then it will be opened with a suitable application instead of a Web browser.

The following example opens a file on the Windows file system residing on a path that contains spaces:

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

If a mailto URL is specified, the user's e-mail client will be used to open a composer window containing the options specified in the URL, similar to the way mailto links are handled by a Web browser.

For example, the following URL contains a recipient (user@foo.com), a subject (Test), and a message body (Just a test):

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

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

See also setUrlHandler().

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

Sets the handler for the given scheme to be the handler method provided by the receiver object.

This function provides a way to customize the behavior of openUrl(). If openUrl() is called with a URL with the specified scheme then the given method on the receiver object is called instead of QDesktopServices launching an external application.

The provided method must be implemented as a slot that only accepts a single QUrl argument.

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

If setUrlHandler() is used to set a new handler for a scheme which already has a handler, the existing handler is simply replaced with the new one. Since QDesktopServices does not take ownership of handlers, no objects are deleted when a handler is replaced.

Note that the handler will always be called from within the same thread that calls QDesktopServices::openUrl().

You must call unsetUrlHandler() before destroying the handler object, so the destruction of the handler object does not overlap with concurrent invocations of openUrl() using it.

iOS

To use this function for receiving data from other apps on iOS you also need to add the custom scheme to the CFBundleURLSchemes list in your Info.plist file:

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

For more information, see the Apple Developer Documentation for Defining a Custom URL Scheme for Your App.

To claim support for http and https the above entry in the Info.plist file is not allowed. This is only possible when you add your domain to the Entitlements file:

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

iOS will search for /.well-known/apple-app-site-association on your domain, when the application is installed. If you want to listen to https://your.domain.com/help?topic=ABCDEF you need to provide the following content there:

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

For more information, see the Apple Developer Documentation for Supporting Associated Domains.

Android

To use this function for receiving data from other apps on Android, you need to add one or more intent filter to the activity in your app manifest:

<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>

For more information, see the Android Developer Documentation for Create Deep Links to App Content.

To immediately open the corresponding content in your Android app, without requiring the user to select the app, you need to verify your link. To enable the verification, add an additional parameter to your intent filter:

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

Android will look for https://your.domain.com/.well-known/assetlinks.json, when the application is installed. If you want to listen to https://your.domain.com:1337/help, you need to provide the following content there:

[{
  "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"]
  }
}]

For more information, see the Android Developer Documentation for Verify Android App Links.

See also openUrl() and unsetUrlHandler().

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

Removes a previously set URL handler for the specified scheme.

Call this function before the handler object that was registered for scheme is destroyed, to prevent concurrent openUrl() calls from continuing to call the destroyed handler object.

See also setUrlHandler().