KRun Class Reference

from PyKDE4.kio import *

Detailed Description

To open files with their associated applications in KDE, use KRun.

It can execute any desktop entry, as well as any file, using the default application or another application "bound" to the file type (or URL protocol).

In that example, the mimetype of the file is not known by the application, so a KRun instance must be created. It will determine the mimetype by itself. If the mimetype is known, or if you even know the service (application) to use for this file, use one of the static methods.

By default KRun uses auto deletion. It causes the KRun instance to delete itself when the it finished its task. If you allocate the KRun object on the stack you must disable auto deletion, otherwise it will crash.

Opens files with their associated applications in KDE

Signals
	error ()
	finished ()
Methods
	__init__ (self, KUrl url, QWidget window, long mode=0, bool isLocalFile=0, bool showProgressInfo=1, QByteArray asn=QByteArray())
	abort (self)
bool	autoDelete (self)
bool	doScanFile (self)
	foundMimeType (self, QString type)
bool	hasError (self)
bool	hasFinished (self)
	init (self)
bool	initializeNextAction (self)
bool	isDirectory (self)
bool	isLocalFile (self)
KIO.Job	job (self)
	killJob (self)
	mimeTypeDetermined (self, QString mimeType)
long	mode (self)
bool	progressInfo (self)
	scanFile (self)
	setAutoDelete (self, bool b)
	setDoScanFile (self, bool scanFile)
	setEnableExternalBrowser (self, bool b)
	setError (self, bool error)
	setFinished (self, bool finished)
	setInitializeNextAction (self, bool initialize)
	setIsDirecory (self, bool isDirectory)
	setIsLocalFile (self, bool isLocalFile)
	setJob (self, KIO.Job job)
	setMode (self, long mode)
	setPreferredService (self, QString desktopEntryName)
	setProgressInfo (self, bool progressInfo)
	setRunExecutables (self, bool b)
	setSuggestedFileName (self, QString fileName)
	setUrl (self, KUrl url)
	slotScanFinished (self, KJob a0)
	slotScanMimeType (self, KIO.Job a0, QString type)
	slotStatResult (self, KJob a0)
	slotTimeout (self)
QString	suggestedFileName (self)
QTimer	timer (self)
KUrl	url (self)
Static Methods
QString	binaryName (QString execLine, bool removePath)
bool	displayOpenWithDialog (KUrl.List lst, QWidget window, bool tempFiles=0, QString suggestedFileName=QString(), QByteArray asn=QByteArray())
bool	isExecutable (QString serviceType)
bool	isExecutableFile (KUrl url, QString mimetype)
QStringList	processDesktopExec (KService _service, KUrl.List _urls, bool tempFiles=0, QString suggestedFileName=QString())
bool	run (KService service, KUrl.List urls, QWidget window, bool tempFiles=0, QString suggestedFileName=QString(), QByteArray asn=QByteArray())
bool	run (QString exec, KUrl.List urls, QWidget window, QString name=QString(), QString icon=QString(), QByteArray asn=QByteArray())
bool	runCommand (QString cmd, QWidget window)
bool	runCommand (QString cmd, QString execName, QString icon, QWidget window, QByteArray asn=QByteArray())
bool	runCommand (QString cmd, QWidget window, QString workingDirectory)
bool	runCommand (QString cmd, QString execName, QString icon, QWidget window, QByteArray asn, QString workingDirectory)
bool	runUrl (KUrl url, QString mimetype, QWidget window, bool tempFile=0, bool runExecutables=1, QString suggestedFileName=QString(), QByteArray asn=QByteArray())
	shellQuote (QString str)

Signal Documentation

error ( )

Emitted when the operation had an error.

See also:: hasError()

Signal syntax:: QObject.connect(source, SIGNAL("error()"), target_slot)

finished ( )

Emitted when the operation finished. This signal is emitted in all cases of completion, whether successful or with error.

See also:: hasFinished()

Signal syntax:: QObject.connect(source, SIGNAL("finished()"), target_slot)

Method Documentation

__init__	(	self,
		KUrl	url,
		QWidget	window,
		long	mode=0,
		bool	isLocalFile=0,
		bool	showProgressInfo=1,
		QByteArray	asn=QByteArray()
	)

Parameters:

	url	the URL of the file or directory to 'run'
	window	The top-level widget of the app that invoked this object. It is used to make sure private information like passwords are properly handled per application.
	mode	The st_mode field of <tt>struct stat</tt>. If you don't know this set it to 0.
	isLocalFile	If this parameter is set to false then url is examined to find out whether it is a local URL or not. This flag is just used to improve speed, since the function KUrl.isLocalFile is a bit slow.
	showProgressInfo	Whether to show progress information when determining the type of the file (i.e. when using KIO.stat and KIO.mimetype) Before you set this to false to avoid a dialog box, think about a very slow FTP server... It is always better to provide progress info in such cases.
	asn	Application startup notification id, if available (otherwise "").

abort ( self )

Abort this KRun. This kills any jobs launched by it, and leads to deletion if auto-deletion is on. This is much safer than deleting the KRun (in case it's currently showing an error dialog box, for instance)

bool autoDelete ( self )

Checks whether auto delete is activated. Auto-deletion causes the KRun instance to delete itself when it finished its task. By default auto deletion is on.

Returns:: true if auto deletion is on, false otherwise

bool doScanFile ( self )

Returns whether the file shall be scanned.

Deprecated:: not useful in public API

foundMimeType	(	self,
		QString	type
	)

Called if the mimetype has been detected. The function runs the application associated with this mimetype. Reimplement this method to implement a different behavior, like opening the component for displaying the URL embedded.

Important: call setFinished(true) once you are done! Usually at the end of the foundMimeType reimplementation, but if the reimplementation is asynchronous (e.g. uses KIO jobs) then it can be called later instead.

bool hasError ( self )

Returns true if the KRun instance has an error.

Returns:: true when an error occurred

See also:: error()

bool hasFinished ( self )

Returns true if the KRun instance has finished.

Returns:: true if the KRun instance has finished

See also:: finished()

init ( self )

Initializes the krun object.

bool initializeNextAction ( self )

Deprecated:: not useful in public API

bool isDirectory ( self )

Returns whether it is a directory.

bool isLocalFile ( self )

Returns whether it is a local file.

KIO.Job job ( self )

Returns the job.

killJob ( self )

Kills the file scanning job.

mimeTypeDetermined	(	self,
		QString	mimeType
	)

Call this from subclasses when you have determined the mimetype. It will call foundMimeType, but also sets up protection against deletion during message boxes.

Since:: 4.0.2

long mode ( self )

Returns the file mode.

bool progressInfo ( self )

Returns whether progress information are shown.

scanFile ( self )

Start scanning a file.

setAutoDelete	(	self,
		bool	b
	)

Enables or disabled auto deletion. Auto deletion causes the KRun instance to delete itself when it finished its task. If you allocate the KRun object on the stack you must disable auto deletion. By default auto deletion is on.

Parameters:

true to enable auto deletion, false to disable

setDoScanFile	(	self,
		bool	scanFile
	)

Indicate that the next action is to scan the file.

Deprecated:: not useful in public API

setEnableExternalBrowser	(	self,
		bool	b
	)

Sets whether the external webbrowser setting should be honoured. This is enabled by default. This should only be disabled in webbrowser applications.

Parameters:

whether to enable the external browser or not.

setError	(	self,
		bool	error
	)

Sets whether an error has occurred.

setFinished	(	self,
		bool	finished
	)

Marks this 'KRun' instance as finished.

setInitializeNextAction	(	self,
		bool	initialize
	)

Deprecated:: not useful in public API

setIsDirecory	(	self,
		bool	isDirectory
	)

Sets whether it is a directory.

Deprecated:: typo in the name, and not useful as a public method

setIsLocalFile	(	self,
		bool	isLocalFile
	)

Sets whether it is a local file.

setJob	(	self,
		KIO.Job	job
	)

Sets the job.

setMode	(	self,
		long	mode
	)

Sets the file mode.

setPreferredService	(	self,
		QString	desktopEntryName
	)

Set the preferred service for opening this URL, after its mimetype will have been found by KRun. IMPORTANT: the service is only used if its configuration says it can handle this mimetype. This is used for instance for the X-KDE-LastOpenedWith key in the recent documents list, or for the app selection in KParts.BrowserOpenOrSaveQuestion.

Parameters:

desktopEntryName

the desktopEntryName of the service, e.g. "kate".

setProgressInfo	(	self,
		bool	progressInfo
	)

Sets whether progress information shall be shown.

setRunExecutables	(	self,
		bool	b
	)

Sets whether executables, .desktop files or shell scripts should be run by KRun. This is enabled by default.

Parameters:

whether to run executable files or not.

See also:: isExecutable()

setSuggestedFileName	(	self,
		QString	fileName
	)

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

setUrl	(	self,
		KUrl	url
	)

Sets the url.

slotScanFinished	(	self,
		KJob	a0
	)

This slot is called when the scan job is finished.

slotScanMimeType	(	self,
		KIO.Job	a0,
		QString	type
	)

This slot is called when the scan job has found out the mime type.

slotStatResult	(	self,
		KJob	a0
	)

This slot is called when the 'stat' job has finished.

slotTimeout ( self )

This slot is called whenever the internal timer fired, in order to move on to the next step.

QString suggestedFileName ( self )

Suggested file name given by the server (e.g. HTTP content-disposition)

QTimer timer ( self )

Returns the timer object.

Deprecated:: setFinished(true) now takes care of the timer().start(0), so this can be removed.

KUrl url ( self )

Returns the url.

Static Method Documentation

QString binaryName	(	QString	execLine,
		bool	removePath
	)

Given a full command line (e.g. the Exec= line from a .desktop file), extract the name of the binary being run.

Parameters:

	execLine	the full command line
	removePath	if true, remove a (relative or absolute) path. E.g. /usr/bin/ls becomes ls.

Returns:: the name of the binary to run

bool displayOpenWithDialog	(	KUrl.List	lst,
		QWidget	window,
		bool	tempFiles=0,
		QString	suggestedFileName=QString(),
		QByteArray	asn=QByteArray()
	)

Display the Open-With dialog for those URLs, and run the chosen application.

Parameters:

	lst	the list of applications to run
	window	The top-level widget of the app that invoked this object.
	tempFiles	if true and lst are local files, they will be deleted when the application exits.
	suggestedFileName	see setSuggestedFileName
	asn	Application startup notification id, if any (otherwise "").

Returns:: false if the dialog was canceled

bool isExecutable	(	QString	serviceType
	)

Returns whether serviceType refers to an executable program instead of a data file.

bool isExecutableFile	(	KUrl	url,
		QString	mimetype
	)

Returns whether the url of mimetype is executable. To be executable the file must pass the following rules:

Must reside on the local filesystem.
Must be marked as executable for the user by the filesystem.
The mime type must inherit application/x-executable or application/x-executable-script. To allow a script to run when the above rules are satisfied add the entry

 X-KDE-IsAlso=application/x-executable-script

to the mimetype's desktop file.

QStringList processDesktopExec	(	KService	_service,
		KUrl.List	_urls,
		bool	tempFiles=0,
		QString	suggestedFileName=QString()
	)

Processes a Exec= line as found in .desktop files.

Parameters:

	_service	the service to extract information from.
	_urls	The urls the service should open.
	tempFiles	if true and urls are local files, they will be deleted when the application exits.
	suggestedFileName	see setSuggestedFileName

Returns:: a list of arguments suitable for KProcess.setProgram().

bool run	(	KService	service,
		KUrl.List	urls,
		QWidget	window,
		bool	tempFiles=0,
		QString	suggestedFileName=QString(),
		QByteArray	asn=QByteArray()
	)

Open a list of URLs with an executable.

Parameters:

	exec	the name of the executable, for example "/usr/bin/netscape %u". Don't forget to include the %u if you know that the applications supports URLs. Otherwise, non-local urls will first be downloaded to a temp file (using kioexec).
	urls	the list of URLs to open, can be empty (app launched without argument)
	window	The top-level widget of the app that invoked this object.
	name	the logical name of the application, for example "Netscape 4.06".
	icon	the icon which should be used by the application.
	asn	Application startup notification id, if any (otherwise "").

Returns:: true on success, false on error

bool run	(	QString	exec,
		KUrl.List	urls,
		QWidget	window,
		QString	name=QString(),
		QString	icon=QString(),
		QByteArray	asn=QByteArray()
	)

Open a list of URLs with an executable.

Parameters:

	exec	the name of the executable, for example "/usr/bin/netscape %u". Don't forget to include the %u if you know that the applications supports URLs. Otherwise, non-local urls will first be downloaded to a temp file (using kioexec).
	urls	the list of URLs to open, can be empty (app launched without argument)
	window	The top-level widget of the app that invoked this object.
	name	the logical name of the application, for example "Netscape 4.06".
	icon	the icon which should be used by the application.
	asn	Application startup notification id, if any (otherwise "").

Returns:: true on success, false on error

bool runCommand	(	QString	cmd,
		QWidget	window
	)

Overload that also takes a working directory, so that a command like "kwrite file.txt" finds file.txt from the right place.

Parameters:

workingDirectory

the working directory for the started process. The default (if passing an empty string) is the user's document path.

Since:: 4.4

bool runCommand	(	QString	cmd,
		QString	execName,
		QString	icon,
		QWidget	window,
		QByteArray	asn=QByteArray()
	)

Overload that also takes a working directory, so that a command like "kwrite file.txt" finds file.txt from the right place.

Parameters:

workingDirectory

the working directory for the started process. The default (if passing an empty string) is the user's document path.

Since:: 4.4

bool runCommand	(	QString	cmd,
		QWidget	window,
		QString	workingDirectory
	)

Overload that also takes a working directory, so that a command like "kwrite file.txt" finds file.txt from the right place.

Parameters:

workingDirectory

the working directory for the started process. The default (if passing an empty string) is the user's document path.

Since:: 4.4

bool runCommand	(	QString	cmd,
		QString	execName,
		QString	icon,
		QWidget	window,
		QByteArray	asn,
		QString	workingDirectory
	)

Overload that also takes a working directory, so that a command like "kwrite file.txt" finds file.txt from the right place.

Parameters:

workingDirectory

the working directory for the started process. The default (if passing an empty string) is the user's document path.

Since:: 4.4

bool runUrl	(	KUrl	url,
		QString	mimetype,
		QWidget	window,
		bool	tempFile=0,
		bool	runExecutables=1,
		QString	suggestedFileName=QString(),
		QByteArray	asn=QByteArray()
	)

Open the given URL.

This function is used after the mime type is found out. It will search for all services which can handle the mime type and call run() afterwards.

Parameters:

	url	the URL to open
	mimetype	the mime type of the resource
	window	The top-level widget of the app that invoked this object.
	tempFile	if true and url is a local file, it will be deleted when the launched application exits.
	runExecutables	if false then local .desktop files, executables and shell scripts will not be run. See also isExecutable().
	suggestedFileName	see setSuggestedFileName
	asn	Application startup notification id, if any (otherwise "").

Returns:: true on success, false on error

shellQuote	(	QString	str
	)

Quotes a string for the shell. An empty string will not be quoted.

Deprecated:: Use KShell.quoteArg() instead. Note that this function behaves differently for empty arguments and returns the result differently.

Parameters:

str

the string to quote. The quoted string will be written here

KRun Class Reference

Detailed Description

Signals

Methods

Static Methods

Signal Documentation

Method Documentation

Static Method Documentation

Modules