KDE 4.5 PyKDE API Reference

• KDE's Python API

• Overview
• PyKDE Home
• Sitemap
• Contact Us

 

KToolInvocation Class Reference

from PyKDE4.kdecore import *

Inherits: QObject

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 <a href="http://techbase.kde.org/Development/Architecture/KDE4/Starting_Other_Programs#KToolInvocation.startServiceByDesktopPath">techbase.

Signals
	kapplication_hook (QStringList env, QByteArray startup_id)
Methods
	__init__ (self)
Static Methods
	invokeBrowser (QString url, QByteArray startup_id=QByteArray())
	invokeHelp (QString anchor=QString(), QString appname=QString(), QByteArray startup_id=QByteArray())
	invokeMailer (QString address, QString subject, QByteArray startup_id=QByteArray())
	invokeMailer (KUrl mailtoURL, QByteArray startup_id=QByteArray(), bool allowAttachments=0)
	invokeMailer (QString to, QString cc, QString bcc, QString subject, QString body, QString messageFile=QString(), QStringList attachURLs=QStringList(), QByteArray startup_id=QByteArray())
	invokeTerminal (QString command, QString workdir=QString(), QByteArray startup_id="")
int, int pid	kdeinitExec (QString name, QStringList args=QStringList(), QString error=0, QByteArray startup_id=QByteArray())
int, int pid	kdeinitExecWait (QString name, QStringList args=QStringList(), QString error=0, QByteArray startup_id=QByteArray())
KToolInvocation	self ()
int, int pid	startServiceByDesktopName (QString _name, QString URL, QString error=0, QString serviceName=0, QByteArray startup_id=QByteArray(), bool noWait=0)
int, int pid	startServiceByDesktopName (QString _name, QStringList URLs=QStringList(), QString error=0, QString serviceName=0, QByteArray startup_id=QByteArray(), bool noWait=0)
int, int pid	startServiceByDesktopPath (QString _name, QString URL, QString error=0, QString serviceName=0, QByteArray startup_id=QByteArray(), bool noWait=0)
int, int pid	startServiceByDesktopPath (QString _name, QStringList URLs=QStringList(), QString error=0, QString serviceName=0, QByteArray startup_id=QByteArray(), bool noWait=0)
int, int pid	startServiceByName (QString _name, QString URL, QString error=0, QString serviceName=0, QByteArray startup_id=QByteArray(), bool noWait=0)
int, int pid	startServiceByName (QString _name, QStringList URLs=QStringList(), QString error=0, QString serviceName=0, QByteArray startup_id=QByteArray(), bool noWait=0)

---

Signal Documentation

kapplication_hook	(	QStringList	env,
		QByteArray	startup_id
	)

Hook for KApplication in kdeui

Internal:

Signal syntax:

QObject.connect(source, SIGNAL("kapplication_hook(QStringList&, QByteArray&)"), target_slot)

---

Method Documentation

__init__

(

self )

---

Static Method Documentation

invokeBrowser	(	QString	url,
		QByteArray	startup_id=QByteArray()
	)

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

invokeHelp	(	QString	anchor=QString(),
		QString	appname=QString(),
		QByteArray	startup_id=QByteArray()
	)

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

invokeMailer	(	QString	address,
		QString	subject,
		QByteArray	startup_id=QByteArray()
	)

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

invokeMailer	(	KUrl	mailtoURL,
		QByteArray	startup_id=QByteArray(),
		bool	allowAttachments=0
	)

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

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

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

invokeTerminal	(	QString	command,
		QString	workdir=QString(),
		QByteArray	startup_id=""
	)

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

int, int pid kdeinitExec	(	QString	name,
		QStringList	args=QStringList(),
		QString	error=0,
		QByteArray	startup_id=QByteArray()
	)

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

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

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

KToolInvocation self

(

)

int, int pid startServiceByDesktopName	(	QString	_name,
		QString	URL,
		QString	error=0,
		QString	serviceName=0,
		QByteArray	startup_id=QByteArray(),
		bool	noWait=0
	)

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

int, int pid startServiceByDesktopName	(	QString	_name,
		QStringList	URLs=QStringList(),
		QString	error=0,
		QString	serviceName=0,
		QByteArray	startup_id=QByteArray(),
		bool	noWait=0
	)

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

int, int pid startServiceByDesktopPath	(	QString	_name,
		QString	URL,
		QString	error=0,
		QString	serviceName=0,
		QByteArray	startup_id=QByteArray(),
		bool	noWait=0
	)

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

int, int pid startServiceByDesktopPath	(	QString	_name,
		QStringList	URLs=QStringList(),
		QString	error=0,
		QString	serviceName=0,
		QByteArray	startup_id=QByteArray(),
		bool	noWait=0
	)

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

int, int pid startServiceByName	(	QString	_name,
		QString	URL,
		QString	error=0,
		QString	serviceName=0,
		QByteArray	startup_id=QByteArray(),
		bool	noWait=0
	)

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

int, int pid startServiceByName	(	QString	_name,
		QStringList	URLs=QStringList(),
		QString	error=0,
		QString	serviceName=0,
		QByteArray	startup_id=QByteArray(),
		bool	noWait=0
	)

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

• Full Index

Modules

• akonadi
• dnssd
• kdecore
• kdeui
• khtml
• kio
• knewstuff
• kparts
• kutils
• nepomuk
• phonon
• plasma
• polkitqt
• solid
• soprano

This documentation is maintained by Simon Edwards.
KDE^® and the K Desktop Environment^® logo are registered trademarks of KDE e.V. | Legal