Skip to content

PythonQt.Qt.QDesktopServices

QDesktopServices

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

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.

URL Handlers

The behavior of the openUrl() function can be customized for individual URL schemes to allow applications to override the default handling behavior for certain types of URLs.

The dispatch mechanism allows only one custom handler to be used for each URL scheme; this is set using the setUrlHandler() function. Each handler is implemented as a slot which accepts only a single QUrl argument.

The existing handlers for each scheme can be removed with the unsetUrlHandler() function. This returns the handling behavior for the given scheme to the default behavior.

This system makes it easy to implement a help system, for example. Help could be provided in labels and text browsers using help://myapplication/mytopic URLs, and by registering a handler it becomes possible to display the help text inside the application:

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

QDesktopServices::setUrlHandler("help", helpInstance, "showHelp");

If inside the handler you decide that you can't open the requested URL, you can just call QDesktopServices::openUrl() again with the same argument, and it will try to open the URL using the appropriate mechanism for the user's desktop environment.

Combined with platform specific settings, the schemes registered by the openUrl() function can also be exposed to other applications, opening up for application deep linking or a very basic URL-based IPC mechanism.

Note: Since Qt 5, storageLocation() and displayName() are replaced by functionality provided by the QStandardPaths class.

Source: https://doc.qt.io/archives/qt-5.15/qdesktopservices.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
openUrl function (self, url: Any) -> bool X.openUrl(url) -> bool (shared captured text)
setUrlHandler function (self, scheme: str, receiver: Any, method: str) -> None X.setUrlHandler(scheme, receiver, method) (shared captured text)
unsetUrlHandler function (self, scheme: str) -> None Removes a previously set URL handler for the specified scheme. (shared captured text)