kio Library API Documentation

KRun Class Reference

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

#include <krun.h>

Inheritance diagram for KRun:

QObject List of all members.

Signals

void finished ()
void error ()

Public Methods

 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)

Static Public Methods

pid_t run (const KService &_service, const KURL::List &_urls, bool tempFiles)
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)
pid_t runURL (const KURL &_url, const QString &_mimetype, bool tempFile, bool runExecutables)
pid_t runCommand (QString cmd)
pid_t runCommand (const QString &cmd, const QString &execName, const QString &icon)
bool displayOpenWithDialog (const KURL::List &lst, bool tempFiles)
void shellQuote (QString &_str)
QStringList processDesktopExec (const KService &_service, const KURL::List &_urls, bool has_shell, bool tempFiles)
QString binaryName (const QString &execLine, bool removePath)
bool isExecutable (const QString &serviceType)

Protected Methods

virtual void foundMimeType (const QString &_type)

Protected Attributes

bool m_bScanFile
bool m_bInit

Detailed Description

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

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.

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

Definition at line 680 of file krun.cpp.

KRun::~KRun   [virtual]
 

Destructor.

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

Definition at line 810 of file krun.cpp.

References QTimer::stop().


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 1073 of file krun.cpp.

References m_bInit, m_bScanFile, and QTimer::start().

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 117 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 124 of file krun.h.

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 133 of file krun.h.

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 143 of file krun.h.

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

See also:
isExecutable()
Since:
3.2

Definition at line 1095 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 602 of file krun.cpp.

References KRecentDocument::add(), KService::desktopEntryName(), KService::desktopEntryPath(), error(), KDesktopFile::isAuthorizedDesktopFile(), QString::isEmpty(), KMessageBox::sorry(), KApplication::startServiceByDesktopPath(), and KURL::List::toStringList().

Referenced by displayOpenWithDialog(), KFileOpenWithHandler::displayOpenWithDialog(), KDEDesktopMimeType::executeService(), foundMimeType(), run(), and runURL().

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".
_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 651 of file krun.cpp.

References run().

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 87 of file krun.cpp.

References displayOpenWithDialog(), KMessageBox::error(), KURL::htmlURL(), isExecutable(), KURL::isLocalFile(), KURL::path(), KServiceTypeProfile::preferredService(), run(), KDEDesktopMimeType::run(), runCommand(), shellQuote(), KMessageBox::sorry(), and KGlobal::staticQString().

Referenced by foundMimeType().

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 659 of file krun.cpp.

Referenced by runURL().

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.

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

Parameters:
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 664 of file krun.cpp.

References binaryName(), KSharedPtr< KService >::data(), KService::serviceByDesktopName(), and KProcess::setUseShell().

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 168 of file krun.cpp.

References QDialog::exec(), run(), KOpenWithDlg::service(), KMessageBox::sorry(), and KOpenWithDlg::text().

Referenced by runURL().

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 190 of file krun.cpp.

References QString::isEmpty(), and QString::replace().

Referenced by processDesktopExec(), and runURL().

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 328 of file krun.cpp.

References QRegExp::cap(), KGlobal::config(), KService::exec(), KMacroExpanderBase::expandMacrosShellQuote(), QString::find(), KShell::joinArgs(), QString::length(), KService::name(), QString::prepend(), QString::remove(), QRegExp::search(), shellQuote(), KShell::splitArgs(), KService::substituteUid(), KService::terminal(), KService::terminalOptions(), KURL::List::toStringList(), QString::unicode(), and KService::username().

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 480 of file krun.cpp.

References KShell::splitArgs().

Referenced by runCommand().

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 1100 of file krun.cpp.

Referenced by runURL().

void KRun::finished   [signal]
 

Emitted when the operation finished.

See also:
hasFinished()

void KRun::error   [signal]
 

Emitted when the operation had an error.

See also:
hasError()

Referenced by run().

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.

Definition at line 970 of file krun.cpp.

References QObject::inherits(), KIO::Scheduler::publishSlaveOnHold(), KIO::SimpleJob::putOnHold(), run(), runURL(), KService::serviceByDesktopName(), and QTimer::start().


Member Data Documentation

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 341 of file krun.h.

Referenced by abort().

bool KRun::m_bInit [protected]
 

USed to indicate that the next action is to initialize.

This action is invoked from slotTimeout

Definition at line 348 of file krun.h.

Referenced by abort().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kio Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Thu Apr 22 14:24:19 2004 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2003