KRun Class Reference

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

#include <krun.h>

Inheritance diagram for KRun:


Signals
void	error ()
void	finished ()
Public Member Functions
void	abort ()
bool	autoDelete () const
bool	hasError () const
bool	hasFinished () const
	KRun (const KURL &url, QWidget *window, mode_t mode=0, bool isLocalFile=false, bool showProgressInfo=true)
	KRun (const KURL &url, mode_t mode=0, bool isLocalFile=false, bool showProgressInfo=true)
void	setAutoDelete (bool b)
void	setEnableExternalBrowser (bool b)
void	setPreferredService (const QString &desktopEntryName)
void	setRunExecutables (bool b)
void	setSuggestedFileName (const QString &fileName)
virtual	~KRun ()
Static Public Member Functions
static QString	binaryName (const QString &execLine, bool removePath)
static bool	checkStartupNotify (const QString &binName, const KService service, bool silent_arg, QCString *wmclass_arg)
static bool	displayOpenWithDialog (const KURL::List &lst, bool tempFiles, const QString &suggestedFileName)
static bool	displayOpenWithDialog (const KURL::List &lst)
static bool	displayOpenWithDialog (const KURL::List &lst, bool tempFiles)
static bool	isExecutable (const QString &serviceType)
static bool	isExecutableFile (const KURL &url, const QString &mimetype)
static QStringList	processDesktopExec (const KService &_service, const KURL::List &_urls, bool has_shell, bool tempFiles, const QString &suggestedFileName)
static QStringList	processDesktopExec (const KService &_service, const KURL::List &_urls, bool has_shell)
static QStringList	processDesktopExec (const KService &_service, const KURL::List &_urls, bool has_shell, bool tempFiles)
static pid_t	run (const QString &_exec, const KURL::List &_urls, const QString &_name=QString::null, const QString &_icon=QString::null, const QString &_obsolete1=QString::null, const QString &_obsolete2=QString::null)
static pid_t	run (const KService &_service, const KURL::List &_urls, QWidget *window, bool tempFiles, const QString &suggestedFileName)
static pid_t	run (const KService &_service, const KURL::List &_urls)
static pid_t	run (const KService &_service, const KURL::List &_urls, bool tempFiles)
static pid_t	run (const KService &_service, const KURL::List &_urls, QWidget *window, bool tempFiles=false)
static pid_t	runCommand (const QString &cmd, const QString &execName, const QString &icon)
static pid_t	runCommand (QString cmd)
static pid_t	runURL (const KURL &_url, const QString &_mimetype, bool tempFile, bool runExecutables, const QString &suggestedFileName)
static pid_t	runURL (const KURL &_url, const QString &_mimetype)
static pid_t	runURL (const KURL &_url, const QString &_mimetype, bool tempFile)
static pid_t	runURL (const KURL &_url, const QString &_mimetype, bool tempFile, bool runExecutables)
static void	shellQuote (QString &_str)
Protected Slots
void	slotScanFinished (KIO::Job *)
void	slotScanMimeType (KIO::Job *, const QString &type)
virtual void	slotStatResult (KIO::Job *)
void	slotTimeout ()
Protected Member Functions
virtual void	foundMimeType (const QString &_type)
virtual void	init ()
virtual void	killJob ()
virtual void	scanFile ()
virtual void	virtual_hook (int id, void *data)
Protected Attributes
bool	m_bAutoDelete
bool	m_bFault
bool	m_bFinished
bool	m_bInit
bool	m_bIsDirectory
bool	m_bIsLocalFile
bool	m_bProgressInfo
bool	m_bScanFile
KIO::Job *	m_job
mode_t	m_mode
KURL	m_strURL
QTimer	m_timer

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

Definition at line 58 of file krun.h.

Constructor & Destructor Documentation

KRun::KRun	(	const KURL &	url,
		mode_t	mode = `0`,
		bool	isLocalFile = `false`,
		bool	showProgressInfo = `true`
	)

Create a KRun object to run the preferred application for a file/URL.

KRun will first determine the type of the file, and will then run the associated application.

Parameters:

	url	the URL of the file or directory to 'run'
	mode	The `st_mode` field of `struct stat`. 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.

Definition at line 816 of file krun.cpp.

KRun::KRun	(	const KURL &	url,
		QWidget *	window,
		mode_t	mode = `0`,
		bool	isLocalFile = `false`,
		bool	showProgressInfo = `true`
	)

BIC: Combine with the above ctor for KDE 4.0.

Parameters:

	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.
	url	the URL of the file or directory to 'run'
	mode	The `st_mode` field of `struct stat`. 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.

Definition at line 822 of file krun.cpp.

KRun::~KRun ( ) [virtual]

Destructor.

Don't call it yourself, since a KRun object auto-deletes itself.

Definition at line 987 of file krun.cpp.

Member Function Documentation

void KRun::abort ( )

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)

Definition at line 1274 of file krun.cpp.

bool KRun::autoDelete ( ) const [inline]

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

Definition at line 150 of file krun.h.

QString KRun::binaryName	(	const QString &	execLine,
		bool	removePath
	)			`[static]`

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

Since:: 3.1

Definition at line 527 of file krun.cpp.

bool KRun::checkStartupNotify	(	const QString &	binName,
		const KService *	service,
		bool *	silent_arg,
		QCString *	wmclass_arg
	)			`[static]`

For internal use only.

Since:: 3.4

Definition at line 594 of file krun.cpp.

bool KRun::displayOpenWithDialog	(	const KURL::List &	lst,
		bool	tempFiles,
		const QString &	suggestedFileName
	)			`[static]`

Since:: 3.5.3

For internal use only.

Definition at line 198 of file krun.cpp.

bool KRun::displayOpenWithDialog ( const KURL::List & lst ) [static]

Definition at line 188 of file krun.cpp.

bool KRun::displayOpenWithDialog	(	const KURL::List &	lst,
		bool	tempFiles
	)			`[static]`

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

Parameters:

	lst	the list of applications to run
	tempFiles	if true and lst are local files, they will be deleted when the application exits.

Returns:: false if the dialog was canceled

Definition at line 193 of file krun.cpp.

void KRun::error ( ) [signal]

Emitted when the operation had an error.

See also:: hasError()

void KRun::finished ( ) [signal]

Emitted when the operation finished.

See also:: hasFinished()

void KRun::foundMimeType ( const QString & _type ) [protected, virtual]

Called if the mimetype has been detected.

The function checks whether the document and appends the gzip protocol to the URL. Otherwise runURL is called to finish the job.

Note: the line above means that if that service failed, we'll go to runURL to maybe find another service, even though a dialog box was displayed. That's good if runURL tries another service, but it's not good if it tries the same one :}

Definition at line 1164 of file krun.cpp.

bool KRun::hasError ( ) const [inline]

Returns true if the KRun instance has an error.

Returns:: true when an error occurred

See also:: error()

Definition at line 134 of file krun.h.

bool KRun::hasFinished ( ) const [inline]

Returns true if the KRun instance has finished.

Returns:: true if the KRun instance has finished

See also:: finished()

Definition at line 141 of file krun.h.

void KRun::init ( ) [protected, virtual]

Definition at line 858 of file krun.cpp.

bool KRun::isExecutable ( const QString & serviceType ) [static]

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

Since:: 3.2

Definition at line 1314 of file krun.cpp.

bool KRun::isExecutableFile	(	const KURL &	url,
		const QString &	mimetype
	)			`[static]`

Returns wether 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.
Since:
3.3

Definition at line 97 of file krun.cpp.

void KRun::killJob ( ) [protected, virtual]

Definition at line 1264 of file krun.cpp.

QStringList KRun::processDesktopExec	(	const KService &	_service,
		const KURL::List &	_urls,
		bool	has_shell,
		bool	tempFiles,
		const QString &	suggestedFileName
	)			`[static]`

Since:: 3.5.3

For internal use only.

compatibility hack -- KDE 4: remove

Definition at line 363 of file krun.cpp.

QStringList KRun::processDesktopExec	(	const KService &	_service,
		const KURL::List &	_urls,
		bool	has_shell
	)			`[static]`

Definition at line 354 of file krun.cpp.

QStringList KRun::processDesktopExec	(	const KService &	_service,
		const KURL::List &	_urls,
		bool	has_shell,
		bool	tempFiles
	)			`[static]`

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

Parameters:

	_service	the service to extract information from.
	_urls	The urls the service should open.
	has_shell	If true, the arguments are going to be fed into a shell e.g by using system(). If false, the arguments are going to be fed into a exec() kind call. If the arguments are intended for an exec() kind of call and the Exec line contains shell commands then "/bin/sh -c" is added.
	tempFiles	if true and _urls are local files, they will be deleted when the application exits.

Returns:: a list of arguments suitable for either system() or exec().

Definition at line 358 of file krun.cpp.

pid_t KRun::run	(	const QString &	_exec,
		const KURL::List &	_urls,
		const QString &	_name = `QString::null`,
		const QString &	_icon = `QString::null`,
		const QString &	_obsolete1 = `QString::null`,
		const QString &	_obsolete2 = `QString::null`
	)			`[static]`

Open a list of URLs with.

Parameters:

	_exec	the name of the executable, for example "/usr/bin/netscape".
	_urls	the list of URLs to open, can be empty (app launched without argument)
	_name	the logical name of the application, for example "Netscape 4.06".
	_icon	the icon which should be used by the application.
	_obsolete1	Do not use!
	_obsolete2	Do not use!

Returns:: the process id, or 0 on error

Definition at line 793 of file krun.cpp.

pid_t KRun::run	(	const KService &	_service,
		const KURL::List &	_urls,
		QWidget *	window,
		bool	tempFiles,
		const QString &	suggestedFileName
	)			`[static]`

Since:: 3.5.3

For internal use only.

Definition at line 740 of file krun.cpp.

pid_t KRun::run	(	const KService &	_service,
		const KURL::List &	_urls
	)			`[static]`

Definition at line 725 of file krun.cpp.

pid_t KRun::run	(	const KService &	_service,
		const KURL::List &	_urls,
		bool	tempFiles
	)			`[static]`

Open a list of URLs with a certain service (application).

Parameters:

	_service	the service to run
	_urls	the list of URLs, can be empty (app launched without argument)
	tempFiles	if true and _urls are local files, they will be deleted when the application exits.

Returns:: the process id, or 0 on error

Definition at line 730 of file krun.cpp.

pid_t KRun::run	(	const KService &	_service,
		const KURL::List &	_urls,
		QWidget *	window,
		bool	tempFiles = `false`
	)			`[static]`

Open a list of URLs with a certain service (application).

Parameters:

	_service	the service to run
	_urls	the list of URLs, can be empty (app launched without argument)
	window	The top-level widget of the app that invoked this object.
	tempFiles	if true and _urls are local files, they will be deleted when the application exits.

Returns:: the process id, or 0 on error

Since:: 3.5.2

Definition at line 735 of file krun.cpp.

pid_t KRun::runCommand	(	const QString &	cmd,
		const QString &	execName,
		const QString &	icon
	)			`[static]`

Same as the other runCommand(), but it also takes the name of the binary, to display an error message in case it couldn't find it.

Parameters:

	cmd	must be a shell command. You must not append "&" to it, since the function will do that for you.
	execName	the name of the executable
	icon	icon for app starting notification

Returns:: PID of running command, 0 if it could not be started, 0 - (PID of running command) if command was unsafe for map notification.

Definition at line 806 of file krun.cpp.

pid_t KRun::runCommand ( QString cmd ) [static]

Run the given shell command and notifies kicker of the starting of the application.

If the program to be called doesn't exist, an error box will be displayed.

Use only when you know the full command line. Otherwise use the other static methods, or KRun's constructor.

_cmd must be a shell command. You must not append "&" to it, since the function will do that for you.

Returns:: PID of running command, 0 if it could not be started, 0 - (PID of running command) if command was unsafe for map notification.

Definition at line 801 of file krun.cpp.

pid_t KRun::runURL	(	const KURL &	_url,
		const QString &	_mimetype,
		bool	tempFile,
		bool	runExecutables,
		const QString &	suggestedFileName
	)			`[static]`

Since:: 3.5.3

For internal use only.

Definition at line 113 of file krun.cpp.

pid_t KRun::runURL	(	const KURL &	_url,
		const QString &	_mimetype
	)			`[static]`

Definition at line 82 of file krun.cpp.

pid_t KRun::runURL	(	const KURL &	_url,
		const QString &	_mimetype,
		bool	tempFile
	)			`[static]`

Definition at line 87 of file krun.cpp.

pid_t KRun::runURL	(	const KURL &	_url,
		const QString &	_mimetype,
		bool	tempFile,
		bool	runExecutables
	)			`[static]`

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

Returns:: the process id, or 0 on error

Definition at line 92 of file krun.cpp.

void KRun::scanFile ( ) [protected, virtual]

Definition at line 997 of file krun.cpp.

void KRun::setAutoDelete ( bool b ) [inline]

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:

b

true to enable auto deletion, false to disable

Definition at line 160 of file krun.h.

void KRun::setEnableExternalBrowser ( 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:

b

whether to enable the external browser or not.

Since:: 3.4

Definition at line 1291 of file krun.cpp.

void KRun::setPreferredService ( const 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, for the recent documents list.

Parameters:

desktopEntryName

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

Definition at line 1299 of file krun.cpp.

void KRun::setRunExecutables ( bool b )

Sets whether executables, .desktop files or shell scripts should be run by KRun.

This is enabled by default.

Parameters:

b

whether to run executable files or not.

See also:: isExecutable()

Since:: 3.2

Definition at line 1304 of file krun.cpp.

void KRun::setSuggestedFileName ( const 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.

Since:: 3.5.3

Definition at line 1309 of file krun.cpp.

void KRun::shellQuote ( QString & _str ) [static]

Quotes a string for the shell.

Parameters:

_str

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

Definition at line 220 of file krun.cpp.

void KRun::slotScanFinished ( KIO::Job * job ) [protected, slot]

Definition at line 1145 of file krun.cpp.

void KRun::slotScanMimeType	(	KIO::Job *	,
		const QString &	type
	)			`[protected, slot]`

Definition at line 1137 of file krun.cpp.

void KRun::slotStatResult ( KIO::Job * job ) [protected, virtual, slot]

Definition at line 1077 of file krun.cpp.

void KRun::slotTimeout ( ) [protected, slot]

Definition at line 1038 of file krun.cpp.

void KRun::virtual_hook	(	int	id,
		void *	data
	)			`[protected, virtual]`

Definition at line 1416 of file krun.cpp.

Member Data Documentation

bool KRun::m_bAutoDelete [protected]

Definition at line 415 of file krun.h.

bool KRun::m_bFault [protected]

Definition at line 414 of file krun.h.

bool KRun::m_bFinished [protected]

Definition at line 417 of file krun.h.

bool KRun::m_bInit [protected]

USed to indicate that the next action is to initialize.

This action is invoked from slotTimeout

Definition at line 432 of file krun.h.

bool KRun::m_bIsDirectory [protected]

Definition at line 426 of file krun.h.

bool KRun::m_bIsLocalFile [protected]

Definition at line 434 of file krun.h.

bool KRun::m_bProgressInfo [protected]

Definition at line 416 of file krun.h.

bool KRun::m_bScanFile [protected]

Used to indicate that the next action is to scan the file.

This action is invoked from slotTimeout.

Definition at line 425 of file krun.h.

KIO::Job* KRun::m_job [protected]

Definition at line 418 of file krun.h.

mode_t KRun::m_mode [protected]

Definition at line 435 of file krun.h.

KURL KRun::m_strURL [protected]

Definition at line 413 of file krun.h.

QTimer KRun::m_timer [protected]

Definition at line 419 of file krun.h.

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

kio

KRun Class Reference

Signals

Public Member Functions

Static Public Member Functions

Protected Slots

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

kio

API Reference