KRun Class Reference

`#include <krun.h>`

Inherits QObject.

## Signals

void | finished ()
void | error ()

## Public Member Functions

| KRun (const KURL &url, mode_t mode=0, bool isLocalFile=false, bool showProgressInfo=true)
| KRun (const KURL &url, QWidget *window, mode_t mode=0, bool isLocalFile=false, bool showProgressInfo=true)
virtual | ~KRun ()
void | abort ()
bool | hasError () const
bool | hasFinished () const
bool | autoDelete () const
void | setAutoDelete (bool b)
void | setPreferredService (const QString &desktopEntryName)
void | setRunExecutables (bool b)
void | setEnableExternalBrowser (bool b)
void | setSuggestedFileName (const QString &fileName)

## Static Public Member Functions

static pid_t | run (const KService &_service, const KURL::List &_urls, QWidget *window, bool tempFiles=false)
static pid_t | run (const KService &_service, const KURL::List &_urls, bool tempFiles)
static pid_t | run (const KService &_service, const KURL::List &_urls)
static pid_t | run (const KService &_service, const KURL::List &_urls, QWidget *window, bool tempFiles, const QString &suggestedFileName)
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 | runURL (const KURL &_url, const QString &_mimetype, bool tempFile, bool runExecutables)
static pid_t | runURL (const KURL &_url, const QString &_mimetype, bool tempFile)
static pid_t | runURL (const KURL &_url, const QString &_mimetype)
static pid_t | runURL (const KURL &_url, const QString &_mimetype, bool tempFile, bool runExecutables, const QString &suggestedFileName)
static pid_t | runCommand (QString cmd)
static pid_t | runCommand (const QString &cmd, const QString &execName, const QString &icon)
static bool | displayOpenWithDialog (const KURL::List &lst, bool tempFiles)
static bool | displayOpenWithDialog (const KURL::List &lst)
static bool | displayOpenWithDialog (const KURL::List &lst, bool tempFiles, const QString &suggestedFileName)
static void | shellQuote (QString &_str)
static QStringList | processDesktopExec (const KService &_service, const KURL::List &_urls, bool has_shell, bool tempFiles)
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, const QString &suggestedFileName)
static QString | binaryName (const QString &execLine, bool removePath)
static bool | isExecutable (const QString &serviceType)
static bool | isExecutableFile (const KURL &url, const QString &mimetype)
static bool | checkStartupNotify (const QString &binName, const KService *service, bool *silent_arg, QCString *wmclass_arg)

## Protected Slots

void | slotTimeout ()
void | slotScanFinished (KIO::Job *)
void | slotScanMimeType (KIO::Job *, const QString &type)
virtual void | slotStatResult (KIO::Job *)

## Protected Member Functions

virtual void | init ()
virtual void | scanFile ()
virtual void | foundMimeType (const QString &_type)
virtual void | killJob ()
virtual void | virtual_hook (int id, void *data)

## Protected Attributes

KURL | m_strURL
bool | m_bFault
bool | m_bAutoDelete
bool | m_bProgressInfo
bool | m_bFinished
KIO::Job * | m_job
QTimer | m_timer
bool | m_bScanFile
bool | m_bIsDirectory
bool | m_bInit
bool | m_bIsLocalFile
mode_t | m_mode

## 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::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.

bool KRun::displayOpenWithDialog | ( | const KURL::List & | lst,
|  | bool | tempFiles,
|  | const QString & | suggestedFileName
| ) |  |

static

Since
  3.5.3

Definition at line 198 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.

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:

1. Must reside on the local filesystem.
2. Must be marked as executable for the user by the filesystem.
3. 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.

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.

QStringList KRun::processDesktopExec | ( | const KService & | _service,
|  | const KURL::List & | _urls,
|  | bool | has_shell,
|  | bool | tempFiles,
|  | const QString & | suggestedFileName
| ) |  |

static

Since
  3.5.3

compatibility hack – KDE 4: remove

Definition at line 363 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::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,
|  | const QString & | suggestedFileName
| ) |  |

static

Since
  3.5.3

Definition at line 740 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::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::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::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.

pid_t KRun::runURL | ( | const KURL & | _url,
|  | const QString & | _mimetype,
|  | bool | tempFile,
|  | bool | runExecutables,
|  | const QString & | suggestedFileName
| ) |  |

static

Since
  3.5.3

Definition at line 113 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.

## Member Data Documentation

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

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

- krun.h
- krun.cpp

KDE Home | KDE Accessibility Home | Description of Access Keys