QDesktopServices Class Reference

The QDesktopServices class provides methods for accessing common desktop services. More...

#include <qdesktopservices.h>

Collaboration diagram for QDesktopServices:

Static Public Member Functions
static bool	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.
static void	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.
static void	unsetUrlHandler (const QString &scheme)
	Removes a previously set URL handler for the specified scheme.

Detailed Description

The QDesktopServices class provides methods for accessing common desktop services.

Since

4.2

\inmodule QtGui

Many desktop environments provide services that can be used by applications to perform common tasks, such as opening a web page, in a way that is both consistent and takes into account the user's application preferences.

This class contains functions that provide simple interfaces to these services that indicate whether they succeeded or failed.

The openUrl() function is used to open files located at arbitrary URLs in external applications. For URLs that correspond to resources on the local filing system (where the URL scheme is "file"), a suitable application will be used to open the file; otherwise, a web browser will be used to fetch and display the file.

The user's desktop settings control whether certain executable file types are opened for browsing, or if they are executed instead. Some desktop environments are configured to prevent users from executing files obtained from non-local URLs, or to ask the user's permission before doing so.

Definition at line 18 of file qdesktopservices.h.

Member Function Documentation

openUrl()

bool QDesktopServices::openUrl ( const QUrl &  url )

static

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@.nosp@m.foo..nosp@m.com}), a subject ({Test}), and a message body ({Just a test}):

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

Warning

Although many e-mail clients can send attachments and are Unicode-aware, the user may have configured their client without these features. Also, certain e-mail clients (e.g., Lotus Notes) have problems with long URLs.

A return value of true indicates that the application has successfully requested the operating system to open the URL in an external application. The external application may still fail to launch or fail to open the requested URL. This result will not be reported back to the application.

URLs passed to this function on iOS will not load unless their schemes are listed in the LSApplicationQueriesSchemes key of the application's Info.plist file. For more information, see the Apple Developer Documentation for \l {iOS: canOpenURL:}{canOpenURL:}. For example, the following lines enable URLs with the HTTPS scheme:

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

Note

For Android Nougat (SDK 24) and above, URLs with a file scheme are opened using \l {Android: FileProvider}{FileProvider} which tries to obtain a shareable content scheme URI first. For that reason, Qt for Android defines a file provider with the authority ${applicationId}.qtprovider, with applicationId being the app's package name to avoid name conflicts. For more information, also see \l {Android: Setting up file sharing}{Setting up file sharing}.

See also

setUrlHandler()

Definition at line 174 of file qdesktopservices.cpp.

References QHash< Key, T >::constEnd(), QHash< Key, T >::constFind(), Qt::DirectConnection, QOpenUrlHandlerRegistry::handlers, QUrl::hasFragment(), QCoreApplication::instance(), QMetaObject::invokeMethod(), QUrl::isLocalFile(), QUrl::isValid(), QOpenUrlHandlerRegistry::mutex, QPlatformServices::openDocument(), QPlatformServices::openUrl(), QGuiApplicationPrivate::platformIntegration(), Q_ARG, Q_UNLIKELY, qWarning, QUrl::scheme(), QPlatformIntegration::services(), and url.

Referenced by QTextBrowserPrivate::_q_activateAnchor(), QWidgetTextControlPrivate::activateLinkUnderCursor(), QAndroidPlatformServices::handleNewIntent(), QIOSServices::handleUrl(), QQuickGuiProvider::openUrlExternally(), and src_gui_util_qdesktopservices::wrapper1().

Here is the call graph for this function:

Here is the caller graph for this function:

setUrlHandler()

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

static

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.

Definition at line 297 of file qdesktopservices.cpp.

References QObject::connect(), QObject::destroyed(), Qt::DirectConnection, QOpenUrlHandlerRegistry::handlers, QHash< Key, T >::insert(), method, QOpenUrlHandlerRegistry::mutex, QHash< Key, T >::remove(), and QString::toLower().

Referenced by unsetUrlHandler(), and src_gui_util_qdesktopservices::wrapper0().

Here is the call graph for this function:

Here is the caller graph for this function:

unsetUrlHandler()

void QDesktopServices::unsetUrlHandler ( const QString &  scheme )

static

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

Definition at line 325 of file qdesktopservices.cpp.

References setUrlHandler().

Here is the call graph for this function:

---

The documentation for this class was generated from the following files:

• qtbase/src/gui/util/qdesktopservices.h
• qtbase/src/gui/util/qdesktopservices.cpp