abort

KRun(3)                     Library Functions Manual                     KRun(3)



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


SYNOPSIS
       #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)
           Create a KRun object to run the preferred application for a file/URL.
       virtual ~KRun ()
           Destructor.
       void abort ()
           Abort this KRun.
       bool hasError () const
       bool hasFinished () const
       bool autoDelete () const
           By default auto deletion is on.
       void setAutoDelete (bool b)
       void setPreferredService (const  QString &desktopEntryName)
           Set the preferred service for opening this URL, after its mimetype
           will have been found by KRun.

   Static Public Member Functions
       pid_t run (const  KService &_service, const  KURL::List &_urls, bool
           tempFiles)
           Open a list of URLs with a certain service (application).
       pid_t run (const  KService &_service, const  KURL::List &_urls)
       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)
           Open a list of URLs with.
       pid_t runURL (const  KURL &_url, const  QString &_mimetype, bool
           tempFile)
           Open the given URL.
       pid_t runURL (const  KURL &_url, const  QString &_mimetype)
       pid_t runCommand (QString cmd)
           Run the given shell command and notifies kicker of the starting of
           the application.
       pid_t runCommand (const  QString &cmd, const  QString &execName, const
           QString &icon)
           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.
       bool displayOpenWithDialog (const  KURL::List &lst, bool tempFiles)
           Display the Open-With dialog for those URLs, and run the chosen
           application.
       bool displayOpenWithDialog (const  KURL::List &lst)
       void shellQuote (QString &_str)
           Quotes a string for the shell.
       QStringList processDesktopExec (const  KService &_service, const
           KURL::List &_urls, bool has_shell, bool tempFiles)
           Processes a Exec= line as found in .desktop files.
       QStringList processDesktopExec (const  KService &_service, const
           KURL::List &_urls, bool has_shell)
       QString binaryName (const  QString &execLine, bool removePath)
           Given a full command line (e.g.

   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)
           Called if the mimetype has been detected.
       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
           Used to indicate that the next action is to scan the file.
       bool m_bIsDirectory
       bool m_bInit
           USed to indicate that the next action is to initialize.
       bool m_bIsLocalFile
       mode_t m_mode

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.

       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.

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

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

   KRun::~KRun () [virtual]
       Destructor. Don't call it yourself, since a KRun object auto-deletes
       itself. Definition at line 857 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 1119 of file krun.cpp.

       References QTimer::start().

   bool KRun::autoDelete () const [inline]
       By default auto deletion is on. Definition at line 102 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 1134 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 664 of file krun.cpp.

       References KRecentDocument::add(), QValueList< KURL >::begin(),
       QValueList< KURL >::ConstIterator(), KService::desktopEntryName(),
       KService::desktopEntryPath(), QValueList< KURL >::end(), QValueList< KURL
       >::first(), KDesktopFile::isAuthorizedDesktopFile(), QValueList< KURL
       >::isEmpty(), 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!

       Definition at line 713 of file krun.cpp.

       References run().

   pid_t KRun::runURL (const KURL & _url, const QString & _mimetype, bool
       tempFile) [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.

       Returns:
           the process id, or 0 on error

       Definition at line 68 of file krun.cpp.

       References QValueList< KURL >::append(), displayOpenWithDialog(),
       KMessageBox::error(), KURL::htmlURL(), KURL::isLocalFile(), KURL::path(),
       KServiceTypeProfile::preferredService(), run(),
       KDEDesktopMimeType::run(), runCommand(), shellQuote(), 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.

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

       Use only when you know the full command line. Otherwise use the other
       static methods, or KRun's constructor. Definition at line 721 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. Parameters:
           icon icon for app starting notification

       Definition at line 726 of file krun.cpp.

       References binaryName(), KSharedPtr< T >::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 123 of file krun.cpp.

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

       Referenced by runURL().

   void KRun::shellQuote (QString & _str) [static]
       Quotes a string for the shell. Definition at line 138 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 417 of file krun.cpp.

       References QString::arg(), QValueList< KURL >::begin(),
       KGlobal::config(), QValueList< KURL >::ConstIterator(), QValueList< KURL
       >::end(), KService::exec(), QString::find(), QString::isEmpty(),
       QStringList::join(), KConfigBase::readPathEntry(), shellQuote(),
       KService::substituteUid(), KService::terminal(),
       KService::terminalOptions(), 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.

       Since:
           3.1

       Definition at line 535 of file krun.cpp.

       References QString::contains(), QString::findRev(), and QString::mid().

       Referenced by runCommand().

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

       References QValueList< KURL >::append(), 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 264 of file krun.h.

       Referenced by KRun().

   bool KRun::m_bInit [protected]
       USed to indicate that the next action is to initialize. This action is
       invoked from slotTimeout Definition at line 271 of file krun.h.

       Referenced by KRun().


Author
       Generated automatically by Doxygen for kio Library from the source code.




kio Library                        28 Jan 2004                           KRun(3)