#include <ktoolinvocation.h>

Inheritance diagram for KToolInvocation:

Public Slots
static void	invokeBrowser (const QString &url, const QByteArray &startup_id=QByteArray())

static void	invokeHelp (const QString &anchor=QString(), const QString &appname=QString(), const QByteArray &startup_id=QByteArray())

static void	invokeMailer (const QString &address, const QString &subject, const QByteArray &startup_id=QByteArray())

static void	invokeMailer (const KUrl &mailtoURL, const QByteArray &startup_id=QByteArray(), bool allowAttachments=false)

static void	invokeMailer (const QString &to, const QString &cc, const QString &bcc, const QString &subject, const QString &body, const QString &messageFile=QString(), const QStringList &attachURLs=QStringList(), const QByteArray &startup_id=QByteArray())

static void	invokeTerminal (const QString &command, const QString &workdir=QString(), const QByteArray &startup_id="")

Signals
void	kapplication_hook (QStringList &env, QByteArray &startup_id)

Public Member Functions
	~KToolInvocation ()

Static Public Member Functions
static int	kdeinitExec (const QString &name, const QStringList &args=QStringList(), QString error=0, int pid=0, const QByteArray &startup_id=QByteArray())

static int	kdeinitExecWait (const QString &name, const QStringList &args=QStringList(), QString error=0, int pid=0, const QByteArray &startup_id=QByteArray())

static OrgKdeKLauncherInterface *	klauncher ()

static KToolInvocation *	self ()

static int	startServiceByDesktopName (const QString &_name, const QString &URL, QString error=0, QString serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false)

static int	startServiceByDesktopName (const QString &_name, const QStringList &URLs=QStringList(), QString error=0, QString serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false)

static int	startServiceByDesktopPath (const QString &_name, const QString &URL, QString error=0, QString serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false)

static int	startServiceByDesktopPath (const QString &_name, const QStringList &URLs=QStringList(), QString error=0, QString serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false)

static int	startServiceByName (const QString &_name, const QString &URL, QString error=0, QString serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false)

static int	startServiceByName (const QString &_name, const QStringList &URLs=QStringList(), QString error=0, QString serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false)

Detailed Description

KToolInvocation: for starting other programs.

Desktop files for startServiceBy

The way a service gets started depends on the 'X-DBUS-StartupType' entry in the desktop file of the service:

There are three possibilities:

X-DBUS-StartupType=None (default) Always start a new service, don't wait till the service registers with D-Bus.
X-DBUS-StartupType=Multi Always start a new service, wait until the service has registered with D-Bus.
X-DBUS-StartupType=Unique Only start the service if it isn't already running, wait until the service has registered with D-Bus. The .desktop file can specify the name that the application will use when registering using X-DBUS-ServiceName=org.domain.mykapp. Otherwise org.kde.binaryname is assumed.

Multi-threading

The static members (apart from self()), have to be called from the QApplication main thread. Calls to members are only allowed if there is a Q(Core)Application object created If you call the members with signal/slot connections across threads, you can't use the return values If a function is called from the wrong thread and it has a return value -1 is returned Investigate if this is really needed or if D-Bus is threadsafe anyway

For more details see techbase.

Definition at line 71 of file ktoolinvocation.h.

Constructor & Destructor Documentation

KToolInvocation::~KToolInvocation ( )

Definition at line 51 of file ktoolinvocation.cpp.

Member Function Documentation

void KToolInvocation::invokeBrowser	(	const QString &	url,
		const QByteArray &	startup_id = `QByteArray()`
	)

staticslot

Invokes the user's preferred browser.

Note that you should only do this when you know for sure that the browser can handle the URL (i.e. its mimetype). In doubt, if the URL can point to an image or anything else than HTML, prefer to use new KRun( url ).

See also <a href="http://techbase.kde.org/Development/Architecture/KDE4/Starting_Other_Programs#KToolInvocation::invokeBrowser>techbase for a discussion of invokeBrowser vs KRun.

Parameters

url	The destination address
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default

Definition at line 37 of file ktoolinvocation_win.cpp.

void KToolInvocation::invokeHelp	(	const QString &	anchor = `QString()`,
		const QString &	appname = `QString()`,
		const QByteArray &	startup_id = `QByteArray()`
	)

staticslot

Invokes the KHelpCenter HTML help viewer from docbook sources.

Parameters

anchor	This has to be a defined anchor in your docbook sources. If empty the main index is loaded
appname	This allows you to show the help of another application. If empty the current name() is used
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default

Definition at line 250 of file ktoolinvocation.cpp.

void KToolInvocation::invokeMailer	(	const QString &	address,
		const QString &	subject,
		const QByteArray &	startup_id = `QByteArray()`
	)

staticslot

Convenience method; invokes the standard email application.

Parameters

address	The destination address
subject	Subject string. Can be QString().
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default

Definition at line 319 of file ktoolinvocation.cpp.

void KToolInvocation::invokeMailer	(	const KUrl &	mailtoURL,
		const QByteArray &	startup_id = `QByteArray()`,
		bool	allowAttachments = `false`
	)

staticslot

Invokes the standard email application.

Parameters

mailtoURL	A mailto URL.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default
allowAttachments	whether attachments specified in mailtoURL should be honoured. The default is false; do not honor requests for attachments.

Definition at line 328 of file ktoolinvocation.cpp.

void KToolInvocation::invokeMailer	(	const QString &	to,
		const QString &	cc,
		const QString &	bcc,
		const QString &	subject,
		const QString &	body,
		const QString &	messageFile = `QString()`,
		const QStringList &	attachURLs = `QStringList()`,
		const QByteArray &	startup_id = `QByteArray()`
	)

staticslot

Convenience method; invokes the standard email application.

All parameters are optional.

Parameters

to	The destination address.
cc	The Cc field
bcc	The Bcc field
subject	Subject string
body	A string containing the body of the mail (exclusive with messageFile)
messageFile	A file (URL) containing the body of the mail (exclusive with body) - currently unsupported
attachURLs	List of URLs to be attached to the mail.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default

Definition at line 54 of file ktoolinvocation_win.cpp.

void KToolInvocation::invokeTerminal	(	const QString &	command,
		const QString &	workdir = `QString()`,
		const QByteArray &	startup_id = `""`
	)

staticslot

Invokes the standard terminal application.

Parameters

command	the command to execute, can be empty.
workdir	the initial working directory, can be empty.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default

Since: 4.1

Definition at line 82 of file ktoolinvocation_win.cpp.

void KToolInvocation::kapplication_hook	(	QStringList &	env,
		QByteArray &	startup_id
	)

signal

Hook for KApplication in kdeui.

int KToolInvocation::kdeinitExec	(	const QString &	name,
		const QStringList &	args = `QStringList()`,
		QString *	error = `0`,
		int *	pid = `0`,
		const QByteArray &	startup_id = `QByteArray()`
	)

static

Starts a program via kdeinit.

program name and arguments are converted to according to the local encoding and passed as is to kdeinit.

Parameters

name	Name of the program to start
args	Arguments to pass to the program
error	On failure, `error` contains a description of the error that occurred. If the pointer is 0, the argument will be ignored
pid	On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default

Returns: an error code indicating success (== 0) or failure (> 0).

Definition at line 228 of file ktoolinvocation.cpp.

int KToolInvocation::kdeinitExecWait	(	const QString &	name,
		const QStringList &	args = `QStringList()`,
		QString *	error = `0`,
		int *	pid = `0`,
		const QByteArray &	startup_id = `QByteArray()`
	)

static

Starts a program via kdeinit and wait for it to finish.

Like kdeinitExec(), but it waits till the program is finished. As such it behaves similar to the system(...) function.

Parameters

name	Name of the program to start
args	Arguments to pass to the program
error	On failure, `error` contains a description of the error that occurred. If the pointer is 0, the argument will be ignored
pid	On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default

Returns: an error code indicating success (== 0) or failure (> 0).

Definition at line 240 of file ktoolinvocation.cpp.

static OrgKdeKLauncherInterface* KToolInvocation::klauncher ( )

static

Returns the D-Bus interface of the service launcher.

The returned object is owned by KApplication, do not delete it!

KToolInvocation * KToolInvocation::self ( )

static

Definition at line 41 of file ktoolinvocation.cpp.

int KToolInvocation::startServiceByDesktopName	(	const QString &	_name,
		const QString &	URL,
		QString *	error = `0`,
		QString *	serviceName = `0`,
		int *	pid = `0`,
		const QByteArray &	startup_id = `QByteArray()`,
		bool	noWait = `false`
	)

static

Starts a service based on the desktop name of the service.

E.g. "konqueror"

Parameters

_name	the desktop name of the service
URL	if not empty this URL is passed to the service
error	On failure, `error` contains a description of the error that occurred. If the pointer is 0, the argument will be ignored
serviceName	On success, `serviceName` contains the D-Bus service name under which this service is available. If empty, the service does not provide D-Bus services. If the pointer is 0 the argument will be ignored
pid	On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default
noWait	if set, the function does not wait till the service is running.

Returns: an error code indicating success (== 0) or failure (> 0).

Definition at line 201 of file ktoolinvocation.cpp.

int KToolInvocation::startServiceByDesktopName	(	const QString &	_name,
		const QStringList &	URLs = `QStringList()`,
		QString *	error = `0`,
		QString *	serviceName = `0`,
		int *	pid = `0`,
		const QByteArray &	startup_id = `QByteArray()`,
		bool	noWait = `false`
	)

static

Starts a service based on the desktop name of the service.

E.g. "konqueror"

Parameters

_name	the desktop name of the service
URLs	if not empty these URLs will be passed to the service
error	On failure, `error` contains a description of the error that occurred. If the pointer is 0, the argument will be ignored
serviceName	On success, `serviceName` contains the D-Bus service name under which this service is available. If empty, the service does not provide D-Bus services. If the pointer is 0 the argument will be ignored
pid	On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default
noWait	if set, the function does not wait till the service is running.

Returns: an error code indicating success (== 0) or failure (> 0).

Definition at line 216 of file ktoolinvocation.cpp.

int KToolInvocation::startServiceByDesktopPath	(	const QString &	_name,
		const QString &	URL,
		QString *	error = `0`,
		QString *	serviceName = `0`,
		int *	pid = `0`,
		const QByteArray &	startup_id = `QByteArray()`,
		bool	noWait = `false`
	)

static

Starts a service based on the desktop path of the service.

E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"

Parameters

_name	the path of the desktop file
URL	if not empty this URL is passed to the service
error	On failure, `error` contains a description of the error that occurred. If the pointer is 0, the argument will be ignored
serviceName	On success, `serviceName` contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored
pid	On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default
noWait	if set, the function does not wait till the service is running.

Returns: an error code indicating success (== 0) or failure (> 0).

Definition at line 174 of file ktoolinvocation.cpp.

int KToolInvocation::startServiceByDesktopPath	(	const QString &	_name,
		const QStringList &	URLs = `QStringList()`,
		QString *	error = `0`,
		QString *	serviceName = `0`,
		int *	pid = `0`,
		const QByteArray &	startup_id = `QByteArray()`,
		bool	noWait = `false`
	)

static

Starts a service based on the desktop path of the service.

E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"

Parameters

_name	the path of the desktop file
URLs	if not empty these URLs will be passed to the service
error	On failure, `error` contains a description of the error that occurred. If the pointer is 0, the argument will be ignored *
serviceName	On success, `serviceName` contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored
pid	On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default
noWait	if set, the function does not wait till the service is running.

Returns: an error code indicating success (== 0) or failure (> 0).

Definition at line 189 of file ktoolinvocation.cpp.

int KToolInvocation::startServiceByName	(	const QString &	_name,
		const QString &	URL,
		QString *	error = `0`,
		QString *	serviceName = `0`,
		int *	pid = `0`,
		const QByteArray &	startup_id = `QByteArray()`,
		bool	noWait = `false`
	)

static

Starts a service based on the (translated) name of the service.

E.g. "Web Browser"

Parameters

_name	the name of the service
URL	if not empty this URL is passed to the service
error	On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored
serviceName	On success, serviceName contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored
pid	On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default
noWait	if set, the function does not wait till the service is running.

Returns: an error code indicating success (== 0) or failure (> 0).

Deprecated:: Use startServiceByDesktopName or startServiceByDesktopPath

Definition at line 144 of file ktoolinvocation.cpp.

int KToolInvocation::startServiceByName	(	const QString &	_name,
		const QStringList &	URLs = `QStringList()`,
		QString *	error = `0`,
		QString *	serviceName = `0`,
		int *	pid = `0`,
		const QByteArray &	startup_id = `QByteArray()`,
		bool	noWait = `false`
	)

static

Starts a service based on the (translated) name of the service.

E.g. "Web Browser"

Parameters

_name	the name of the service
URLs	if not empty these URLs will be passed to the service
error	On failure, `error` contains a description of the error that occurred. If the pointer is 0, the argument will be ignored
serviceName	On success, `serviceName` contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored
pid	On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.
startup_id	for app startup notification, "0" for none, "" ( empty string ) is the default
noWait	if set, the function does not wait till the service is running.

Returns: an error code indicating success (== 0) or failure (> 0).

Deprecated:: Use startServiceByDesktopName or startServiceByDesktopPath

Definition at line 161 of file ktoolinvocation.cpp.

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

KDECore

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Detailed Description

Desktop files for startServiceBy

Multi-threading

Constructor & Destructor Documentation

Member Function Documentation

KDECore

kdelibs API Reference

Search