• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KIO

KRun Class Reference

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

#include <krun.h>

Inheritance diagram for KRun:
QObject

List of all members.

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, const QByteArray &asn=QByteArray())
void setAutoDelete (bool b)
void setEnableExternalBrowser (bool b)
void setPreferredService (const QString &desktopEntryName)
void setRunExecutables (bool b)
void setSuggestedFileName (const QString &fileName)
QString suggestedFileName () const
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, QByteArray *wmclass_arg)
static bool displayOpenWithDialog (const KUrl::List &lst, QWidget *window, bool tempFiles=false, const QString &suggestedFileName=QString(), const QByteArray &asn=QByteArray())
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 tempFiles=false, const QString &suggestedFileName=QString())
static bool run (const QString &exec, const KUrl::List &urls, QWidget *window, const QString &name=QString(), const QString &icon=QString(), const QByteArray &asn=QByteArray())
static bool run (const KService &service, const KUrl::List &urls, QWidget *window, bool tempFiles=false, const QString &suggestedFileName=QString(), const QByteArray &asn=QByteArray())
static bool runCommand (const QString &cmd, const QString &execName, const QString &icon, QWidget *window, const QByteArray &asn=QByteArray())
static bool runCommand (const QString &cmd, QWidget *window)
static bool runUrl (const KUrl &url, const QString &mimetype, QWidget *window, bool tempFile=false, bool runExecutables=true, const QString &suggestedFileName=QString(), const QByteArray &asn=QByteArray())
static KDE_DEPRECATED void shellQuote (QString &str)

Protected Slots

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

Protected Member Functions

KDE_DEPRECATED bool doScanFile () const
virtual void foundMimeType (const QString &type)
virtual void init ()
KDE_DEPRECATED bool initializeNextAction () const
bool isDirectory () const
bool isLocalFile () const
KIO::Job * job ()
virtual void killJob ()
mode_t mode () const
bool progressInfo () const
virtual void scanFile ()
KDE_DEPRECATED void setDoScanFile (bool scanFile)
void setError (bool error)
void setFinished (bool finished)
KDE_DEPRECATED void setInitializeNextAction (bool initialize)
KDE_DEPRECATED void setIsDirecory (bool isDirectory)
void setIsLocalFile (bool isLocalFile)
void setJob (KIO::Job *job)
void setMode (mode_t mode)
void setProgressInfo (bool progressInfo)
void setUrl (const KUrl &url)
QTimer & timer ()
KUrl url () const

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


Constructor & Destructor Documentation

KRun::KRun ( const KUrl &  url,
QWidget *  window,
mode_t  mode = 0,
bool  isLocalFile = false,
bool  showProgressInfo = true,
const 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 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.
asn Application startup notification id, if available (otherwise "").

Definition at line 1031 of file krun.cpp.

KRun::~KRun (  )  [virtual]

Destructor.

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

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

bool KRun::autoDelete (  )  const

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

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

Definition at line 507 of file krun.cpp.

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

For internal use only.

Definition at line 588 of file krun.cpp.

bool KRun::displayOpenWithDialog ( const KUrl::List &  lst,
QWidget *  window,
bool  tempFiles = false,
const QString &  suggestedFileName = QString(),
const QByteArray &  asn = QByteArray() 
) [static]

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

Definition at line 185 of file krun.cpp.

bool KRun::doScanFile (  )  const [protected]

Returns whether the file shall be scanned.

Deprecated:
not useful in public API

Definition at line 1609 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 runs the application associated with this mimetype. Reimplement this method to implement a different behavior, like opening the component for displaying the URL embedded.

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

bool KRun::hasError (  )  const

Returns true if the KRun instance has an error.

Returns:
true when an error occurred
See also:
error()

Definition at line 1500 of file krun.cpp.

bool KRun::hasFinished (  )  const

Returns true if the KRun instance has finished.

Returns:
true if the KRun instance has finished
See also:
finished()

Definition at line 1505 of file krun.cpp.

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

All following protected methods are used by subclasses of KRun!

Initializes the krun object.

Definition at line 1069 of file krun.cpp.

bool KRun::initializeNextAction (  )  const [protected]
Deprecated:
not useful in public API

Definition at line 1629 of file krun.cpp.

bool KRun::isDirectory (  )  const [protected]

Returns whether it is a directory.

Definition at line 1619 of file krun.cpp.

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

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

Definition at line 1550 of file krun.cpp.

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

Returns whether 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.

Definition at line 98 of file krun.cpp.

bool KRun::isLocalFile (  )  const [protected]

Returns whether it is a local file.

Definition at line 1639 of file krun.cpp.

KIO::Job * KRun::job (  )  [protected]

Returns the job.

Definition at line 1594 of file krun.cpp.

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

Kills the file scanning job.

Definition at line 1473 of file krun.cpp.

void KRun::mimeTypeDetermined ( const QString &  mimeType  )  [protected, slot]

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

Definition at line 1353 of file krun.cpp.

mode_t KRun::mode (  )  const [protected]

Returns the file mode.

Definition at line 1649 of file krun.cpp.

QStringList KRun::processDesktopExec ( const KService &  _service,
const KUrl::List &  _urls,
bool  tempFiles = false,
const QString &  suggestedFileName = QString() 
) [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.
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().

Definition at line 360 of file krun.cpp.

bool KRun::progressInfo (  )  const [protected]

Returns whether progress information are shown.

Definition at line 1578 of file krun.cpp.

bool KRun::run ( const QString &  exec,
const KUrl::List &  urls,
QWidget *  window,
const QString &  name = QString(),
const QString &  icon = QString(),
const QByteArray &  asn = QByteArray() 
) [static]

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

Definition at line 1000 of file krun.cpp.

bool KRun::run ( const KService &  service,
const KUrl::List &  urls,
QWidget *  window,
bool  tempFiles = false,
const QString &  suggestedFileName = QString(),
const QByteArray &  asn = QByteArray() 
) [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.
suggestedFileName see setSuggestedFileName
asn Application startup notification id, if any (otherwise "").
Returns:
true on success, false on error

Definition at line 935 of file krun.cpp.

bool KRun::runCommand ( const QString &  cmd,
const QString &  execName,
const QString &  icon,
QWidget *  window,
const QByteArray &  asn = QByteArray() 
) [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
window The top-level widget of the app that invoked this object.
asn Application startup notification id, if any (otherwise "").
Returns:
true on success, false on error

Definition at line 1018 of file krun.cpp.

bool KRun::runCommand ( const QString &  cmd,
QWidget *  window 
) [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.

Parameters:
window The top-level widget of the app that invoked this object.
Returns:
true on success, false on error

Definition at line 1008 of file krun.cpp.

bool KRun::runUrl ( const KUrl &  url,
const QString &  mimetype,
QWidget *  window,
bool  tempFile = false,
bool  runExecutables = true,
const QString &  suggestedFileName = QString(),
const QByteArray &  asn = QByteArray() 
) [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
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

Definition at line 120 of file krun.cpp.

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

Start scanning a file.

Definition at line 1200 of file krun.cpp.

void KRun::setAutoDelete ( 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:
b true to enable auto deletion, false to disable

Definition at line 1515 of file krun.cpp.

void KRun::setDoScanFile ( bool  scanFile  )  [protected]

Indicate that the next action is to scan the file.

Deprecated:
not useful in public API

Definition at line 1604 of file krun.cpp.

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.

Definition at line 1520 of file krun.cpp.

void KRun::setError ( bool  error  )  [protected]

Sets whether an error has occurred.

Definition at line 1568 of file krun.cpp.

void KRun::setFinished ( bool  finished  )  [protected]

Marks this 'KRun' instance as finished.

Definition at line 1583 of file krun.cpp.

void KRun::setInitializeNextAction ( bool  initialize  )  [protected]
Deprecated:
not useful in public API

Definition at line 1624 of file krun.cpp.

void KRun::setIsDirecory ( bool  isDirectory  )  [protected]

Sets whether it is a directory.

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

Definition at line 1614 of file krun.cpp.

void KRun::setIsLocalFile ( bool  isLocalFile  )  [protected]

Sets whether it is a local file.

Definition at line 1634 of file krun.cpp.

void KRun::setJob ( KIO::Job *  job  )  [protected]

Sets the job.

Definition at line 1589 of file krun.cpp.

void KRun::setMode ( mode_t  mode  )  [protected]

Sets the file mode.

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

void KRun::setProgressInfo ( bool  progressInfo  )  [protected]

Sets whether progress information shall be shown.

Definition at line 1573 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()

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

Definition at line 1540 of file krun.cpp.

void KRun::setUrl ( const KUrl &  url  )  [protected]

Sets the url.

Definition at line 1558 of file krun.cpp.

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

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

Definition at line 214 of file krun.cpp.

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

This slot is called when the scan job is finished.

Definition at line 1335 of file krun.cpp.

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

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

Definition at line 1326 of file krun.cpp.

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

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

Definition at line 1273 of file krun.cpp.

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

All following protected slots are used by subclasses of KRun!

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

Definition at line 1239 of file krun.cpp.

QString KRun::suggestedFileName (  )  const

Suggested file name given by the server (e.g.

HTTP content-disposition)

Definition at line 1545 of file krun.cpp.

QTimer & KRun::timer (  )  [protected]

Returns the timer object.

Definition at line 1599 of file krun.cpp.

KUrl KRun::url (  )  const [protected]

Returns the url.

Definition at line 1563 of file krun.cpp.


The documentation for this class was generated from the following files:
  • krun.h
  • krun.cpp

KIO

Skip menu "KIO"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal