KDE API Reference

KDE API Reference
KIOGui
ApplicationLauncherJob

KIO::ApplicationLauncherJob Class

ApplicationLauncherJob runs an application and watches it while running. More...

Header:	`#include <KIO/ApplicationLauncherJob>`
CMake:	`find_package(KF6 REQUIRED COMPONENTS KIO)` `target_link_libraries(mytarget PRIVATE KIOGui)`
Since:	KDE Frameworks 5.69
Inherits:	KJob

List of all members, including inherited members

Public Types

enum	RunFlag { DeleteTemporaryFiles }
flags	RunFlags

Public Functions

	ApplicationLauncherJob(QObject *parent = nullptr)
	ApplicationLauncherJob(const KDesktopFileAction &desktopFileAction, QObject *parent = nullptr)
	ApplicationLauncherJob(const KService::Ptr &service, QObject *parent = nullptr)
	ApplicationLauncherJob(const KServiceAction &serviceAction, QObject *parent = nullptr)
virtual	~ApplicationLauncherJob() override
qint64	pid() const
QList<qint64>	pids() const
void	setRunFlags(KIO::ApplicationLauncherJob::RunFlags runFlags)
void	setStartupId(const QByteArray &startupId)
void	setSuggestedFileName(const QString &suggestedFileName)
void	setUrls(const QList<QUrl> &urls)

Reimplemented Public Functions

virtual void start() override

Detailed Description

It creates a startup notification and finishes it on success or on error (for the taskbar). It also emits an error message if necessary (e.g. "program not found").

When passing multiple URLs to an application that doesn't support opening multiple files, the application will be launched once for each URL.

The job finishes when the application is successfully started. At that point you can query the PID(s).

For error handling, either connect to the result() signal, or for a simple messagebox on error, you can use:

// Since 5.98 use:
job->setUiDelegate(KIO::createDefaultJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));
// For older releases use:
job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));

Using JobUiDelegate (which is widgets based) also enables the feature of asking the user in case the executable or desktop file isn't marked as executable. Otherwise the job will just refuse executing such files.

To invoke the open-with dialog (from KIOWidgets), construct an ApplicationLauncherJob without any arguments or with a null KService.

Member Type Documentation

enum ApplicationLauncherJob::RunFlag
flags ApplicationLauncherJob::RunFlags

@see RunFlag

The RunFlags type is a typedef for QFlags<RunFlag>. It stores an OR combination of RunFlag values.

Member Function Documentation

`[explicit]` ApplicationLauncherJob::ApplicationLauncherJob(QObject **parent* = nullptr)

Creates an ApplicationLauncherJob which will prompt the user for which application to use (via the open-with dialog from KIOWidgets). @param parent the parent QObject @since 5.71

`[explicit]` ApplicationLauncherJob::ApplicationLauncherJob(const KDesktopFileAction &desktopFileAction, QObject **parent* = nullptr)

@overload @since 6.0

`[explicit]` ApplicationLauncherJob::ApplicationLauncherJob(const KService::Ptr &service, QObject **parent* = nullptr)

Creates an ApplicationLauncherJob. @param service the service (application desktop file) to run @param parent the parent QObject

`[explicit]` ApplicationLauncherJob::ApplicationLauncherJob(const KServiceAction &serviceAction, QObject **parent* = nullptr)

Creates an ApplicationLauncherJob. @param serviceAction the service action to run @param parent the parent QObject

`[override virtual noexcept]` ApplicationLauncherJob::~ApplicationLauncherJob()

Destructor

Note that jobs auto-delete themselves after emitting result. Deleting/killing the job will not stop the started application.

qint64 ApplicationLauncherJob::pid() const

@return the PID of the application that was started

Convenience method for pids().at(0). You should only use this when specifying zero or one URL, or when you are sure that the application supports opening multiple files. Otherwise use pids(). Available after the job emits result().

QList<qint64> ApplicationLauncherJob::pids() const

@return the PIDs of the applications that were started

Available after the job emits result().

void ApplicationLauncherJob::setRunFlags(KIO::ApplicationLauncherJob::RunFlags runFlags)

Specifies various flags. @param runFlags the flags to be set. For instance, whether the URLs are temporary files that should be deleted after execution.

void ApplicationLauncherJob::setStartupId(const QByteArray &startupId)

Sets the platform-specific startup id of the application launch. @param startupId startup id, if any (otherwise ""). For X11, this would be the id for the Startup Notification protocol. For Wayland, this would be the token for the XDG Activation protocol.

void ApplicationLauncherJob::setSuggestedFileName(const QString &suggestedFileName)

Sets the file name to use in the case of downloading the file to a tempfile in order to give to a non-URL-aware application. Some apps rely on the extension to determine the MIME type of the file. Usually the file name comes from the URL, but in the case of the HTTP Content-Disposition header, we need to override the file name. @param suggestedFileName the file name

void ApplicationLauncherJob::setUrls(const QList<QUrl> &urls)

Specifies the URLs to be passed to the application. @param urls list of files (local or remote) to open

Note that when passing multiple URLs to an application that doesn't support opening multiple files, the application will be launched once for each URL.

`[override virtual]` void ApplicationLauncherJob::start()

Reimplements: KJob::start().

Starts the job. You must call this, after having done all the setters. This is (potentially) a GUI job, never use exec(), it would block user interaction.