.TH "KRun" kde3 "11 Jun 2005" "Version Version 3.4.1" "kio Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KRun \- To open files with their associated applications in \fBKDE\fP, use KRun. Opens files with their associated applications in \fBKDE\fP.  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <krun.h>\fP
.PP
Inherits \fBQObject\fP.
.PP
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBfinished\fP ()"
.br
.ti -1c
.RI "void \fBerror\fP ()"
.br
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBKRun\fP (const \fBKURL\fP &url, mode_t mode=0, bool isLocalFile=false, bool showProgressInfo=true)"
.br
.ti -1c
.RI "\fBKRun\fP (const \fBKURL\fP &url, \fBQWidget\fP *window, mode_t mode=0, bool isLocalFile=false, bool showProgressInfo=true)"
.br
.ti -1c
.RI "virtual \fB~KRun\fP ()"
.br
.ti -1c
.RI "void \fBabort\fP ()"
.br
.ti -1c
.RI "bool \fBhasError\fP () const "
.br
.ti -1c
.RI "bool \fBhasFinished\fP () const "
.br
.ti -1c
.RI "bool \fBautoDelete\fP () const "
.br
.ti -1c
.RI "void \fBsetAutoDelete\fP (bool b)"
.br
.ti -1c
.RI "void \fBsetPreferredService\fP (const \fBQString\fP &desktopEntryName)"
.br
.ti -1c
.RI "void \fBsetRunExecutables\fP (bool b)"
.br
.ti -1c
.RI "void \fBsetEnableExternalBrowser\fP (bool b)"
.br
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "static pid_t \fBrun\fP (const \fBKService\fP &_service, const \fBKURL::List\fP &_urls, bool tempFiles)"
.br
.ti -1c
.RI "static pid_t \fBrun\fP (const \fBKService\fP &_service, const \fBKURL::List\fP &_urls)"
.br
.ti -1c
.RI "static pid_t \fBrun\fP (const \fBQString\fP &_exec, const \fBKURL::List\fP &_urls, const \fBQString\fP &_name=QString::null, const \fBQString\fP &_icon=QString::null, const \fBQString\fP &_obsolete1=QString::null, const \fBQString\fP &_obsolete2=QString::null)"
.br
.ti -1c
.RI "static pid_t \fBrunURL\fP (const \fBKURL\fP &_url, const \fBQString\fP &_mimetype, bool tempFile, bool runExecutables)"
.br
.ti -1c
.RI "static pid_t \fBrunURL\fP (const \fBKURL\fP &_url, const \fBQString\fP &_mimetype, bool tempFile)"
.br
.ti -1c
.RI "static pid_t \fBrunURL\fP (const \fBKURL\fP &_url, const \fBQString\fP &_mimetype)"
.br
.ti -1c
.RI "static pid_t \fBrunCommand\fP (\fBQString\fP cmd)"
.br
.ti -1c
.RI "static pid_t \fBrunCommand\fP (const \fBQString\fP &cmd, const \fBQString\fP &execName, const \fBQString\fP &icon)"
.br
.ti -1c
.RI "static bool \fBdisplayOpenWithDialog\fP (const \fBKURL::List\fP &lst, bool tempFiles)"
.br
.ti -1c
.RI "static bool \fBdisplayOpenWithDialog\fP (const \fBKURL::List\fP &lst)"
.br
.ti -1c
.RI "static void \fBshellQuote\fP (\fBQString\fP &_str)"
.br
.ti -1c
.RI "static \fBQStringList\fP \fBprocessDesktopExec\fP (const \fBKService\fP &_service, const \fBKURL::List\fP &_urls, bool has_shell, bool tempFiles)"
.br
.ti -1c
.RI "static \fBQStringList\fP \fBprocessDesktopExec\fP (const \fBKService\fP &_service, const \fBKURL::List\fP &_urls, bool has_shell)"
.br
.ti -1c
.RI "static \fBQString\fP \fBbinaryName\fP (const \fBQString\fP &execLine, bool removePath)"
.br
.ti -1c
.RI "static bool \fBisExecutable\fP (const \fBQString\fP &serviceType)"
.br
.ti -1c
.RI "static bool \fBisExecutableFile\fP (const \fBKURL\fP &url, const \fBQString\fP &mimetype)"
.br
.ti -1c
.RI "static bool \fBcheckStartupNotify\fP (const \fBQString\fP &binName, const \fBKService\fP *service, bool *silent_arg, \fBQCString\fP *wmclass_arg)"
.br
.in -1c
.SS "Protected Slots"

.in +1c
.ti -1c
.RI "void \fBslotTimeout\fP ()"
.br
.ti -1c
.RI "void \fBslotScanFinished\fP (\fBKIO::Job\fP *)"
.br
.ti -1c
.RI "void \fBslotScanMimeType\fP (\fBKIO::Job\fP *, const \fBQString\fP &type)"
.br
.ti -1c
.RI "virtual void \fBslotStatResult\fP (\fBKIO::Job\fP *)"
.br
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "virtual void \fBinit\fP ()"
.br
.ti -1c
.RI "virtual void \fBscanFile\fP ()"
.br
.ti -1c
.RI "virtual void \fBfoundMimeType\fP (const \fBQString\fP &_type)"
.br
.ti -1c
.RI "virtual void \fBkillJob\fP ()"
.br
.ti -1c
.RI "virtual void \fBvirtual_hook\fP (int id, void *data)"
.br
.in -1c
.SS "Protected Attributes"

.in +1c
.ti -1c
.RI "\fBKURL\fP \fBm_strURL\fP"
.br
.ti -1c
.RI "bool \fBm_bFault\fP"
.br
.ti -1c
.RI "bool \fBm_bAutoDelete\fP"
.br
.ti -1c
.RI "bool \fBm_bProgressInfo\fP"
.br
.ti -1c
.RI "bool \fBm_bFinished\fP"
.br
.ti -1c
.RI "\fBKIO::Job\fP * \fBm_job\fP"
.br
.ti -1c
.RI "\fBQTimer\fP \fBm_timer\fP"
.br
.ti -1c
.RI "bool \fBm_bScanFile\fP"
.br
.ti -1c
.RI "bool \fBm_bIsDirectory\fP"
.br
.ti -1c
.RI "bool \fBm_bInit\fP"
.br
.ti -1c
.RI "bool \fBm_bIsLocalFile\fP"
.br
.ti -1c
.RI "mode_t \fBm_mode\fP"
.br
.in -1c
.SH "Detailed Description"
.PP 
To open files with their associated applications in \fBKDE\fP, use KRun. Opens files with their associated applications in \fBKDE\fP. 

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).
.PP
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.
.PP
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.
.PP
Definition at line 57 of file krun.h.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "KRun::KRun (const \fBKURL\fP & url, mode_t mode = \fC0\fP, bool isLocalFile = \fCfalse\fP, bool showProgressInfo = \fCtrue\fP)"
.PP
Create a KRun object to run the preferred application for a file/URL. 
.PP
KRun will first determine the type of the file, and will then run the associated application.
.PP
\fBParameters:\fP
.RS 4
\fIurl\fP the URL of the file or directory to 'run'
.br
\fImode\fP The \fCst_mode\fP field of \fCstruct stat\fP. If you don't know this set it to 0.
.br
\fIisLocalFile\fP If this parameter is set to \fCfalse\fP then \fCurl\fP is examined to find out whether it is a local URL or not. This flag is just used to improve speed, since the function \fBKURL::isLocalFile\fP is a bit slow.
.br
\fIshowProgressInfo\fP Whether to show progress information when determining the type of the file (i.e. when using \fBKIO::stat\fP and \fBKIO::mimetype\fP) 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. 
.RE
.PP

.PP
Definition at line 729 of file krun.cpp.
.SS "KRun::KRun (const \fBKURL\fP & url, \fBQWidget\fP * window, mode_t mode = \fC0\fP, bool isLocalFile = \fCfalse\fP, bool showProgressInfo = \fCtrue\fP)"
.PP
BIC: Combine with the above ctor for \fBKDE\fP 4.0. 
.PP
\fBParameters:\fP
.RS 4
\fIwindow\fP 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. 
.br
\fIurl\fP the URL of the file or directory to 'run'
.br
\fImode\fP The \fCst_mode\fP field of \fCstruct stat\fP. If you don't know this set it to 0.
.br
\fIisLocalFile\fP If this parameter is set to \fCfalse\fP then \fCurl\fP is examined to find out whether it is a local URL or not. This flag is just used to improve speed, since the function \fBKURL::isLocalFile\fP is a bit slow.
.br
\fIshowProgressInfo\fP Whether to show progress information when determining the type of the file (i.e. when using \fBKIO::stat\fP and \fBKIO::mimetype\fP) 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. 
.RE
.PP

.PP
Definition at line 735 of file krun.cpp.
.SS "KRun::~\fBKRun\fP ()\fC [virtual]\fP"
.PP
Destructor. 
.PP
Don't call it yourself, since a KRun object auto-deletes itself. 
.PP
Definition at line 900 of file krun.cpp.
.PP
References endl(), kdDebug(), and QTimer::stop().
.SH "Member Function Documentation"
.PP 
.SS "void KRun::abort ()"
.PP
Abort this KRun. 
.PP
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) 
.PP
Definition at line 1169 of file krun.cpp.
.PP
References endl(), kdDebug(), m_bInit, m_bScanFile, and QTimer::start().
.SS "bool KRun::hasError () const\fC [inline]\fP"
.PP
Returns true if the KRun instance has an error. 
.PP
\fBReturns:\fP
.RS 4
true when an error occurred 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBerror()\fP 
.RE
.PP

.PP
Definition at line 133 of file krun.h.
.SS "bool KRun::hasFinished () const\fC [inline]\fP"
.PP
Returns true if the KRun instance has finished. 
.PP
\fBReturns:\fP
.RS 4
true if the KRun instance has finished 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBfinished()\fP 
.RE
.PP

.PP
Definition at line 140 of file krun.h.
.SS "bool KRun::autoDelete () const\fC [inline]\fP"
.PP
Checks whether auto delete is activated. 
.PP
Auto-deletion causes the KRun instance to delete itself when it finished its task. By default auto deletion is on. 
.PP
\fBReturns:\fP
.RS 4
true if auto deletion is on, false otherwise 
.RE
.PP

.PP
Definition at line 149 of file krun.h.
.SS "void KRun::setAutoDelete (bool b)\fC [inline]\fP"
.PP
Enables or disabled auto deletion. 
.PP
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. 
.PP
\fBParameters:\fP
.RS 4
\fIb\fP true to enable auto deletion, false to disable 
.RE
.PP

.PP
Definition at line 159 of file krun.h.
.SS "void KRun::setPreferredService (const \fBQString\fP & desktopEntryName)"
.PP
Set the preferred service for opening this URL, after its mimetype will have been found by KRun. 
.PP
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. 
.PP
\fBParameters:\fP
.RS 4
\fIdesktopEntryName\fP the desktopEntryName of the service, e.g. 'kate'. 
.RE
.PP

.PP
Definition at line 1194 of file krun.cpp.
.SS "void KRun::setRunExecutables (bool b)"
.PP
Sets whether executables, .desktop files or shell scripts should be run by KRun. 
.PP
This is enabled by default. 
.PP
\fBParameters:\fP
.RS 4
\fIb\fP whether to run executable files or not. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBisExecutable()\fP 
.RE
.PP
\fBSince:\fP
.RS 4
3.2 
.RE
.PP

.PP
Definition at line 1199 of file krun.cpp.
.SS "void KRun::setEnableExternalBrowser (bool b)"
.PP
Sets whether the external webbrowser setting should be honoured. 
.PP
This is enabled by default. This should only be disabled in webbrowser applications. 
.PP
\fBParameters:\fP
.RS 4
\fIb\fP whether to enable the external browser or not. 
.RE
.PP
\fBSince:\fP
.RS 4
3.4 
.RE
.PP

.PP
Definition at line 1186 of file krun.cpp.
.SS "pid_t KRun::run (const \fBKService\fP & _service, const \fBKURL::List\fP & _urls, bool tempFiles)\fC [static]\fP"
.PP
Open a list of URLs with a certain service (application). 
.PP
\fBParameters:\fP
.RS 4
\fI_service\fP the service to run 
.br
\fI_urls\fP the list of URLs, can be empty (app launched without argument) 
.br
\fItempFiles\fP if true and _urls are local files, they will be deleted when the application exits. 
.RE
.PP
\fBReturns:\fP
.RS 4
the process id, or 0 on error 
.RE
.PP

.PP
Definition at line 656 of file krun.cpp.
.PP
References KRecentDocument::add(), endl(), error(), KDesktopFile::isAuthorizedDesktopFile(), kdDebug(), kdWarning(), KMessageBox::sorry(), and KApplication::startServiceByDesktopPath().
.PP
Referenced by displayOpenWithDialog(), KFileOpenWithHandler::displayOpenWithDialog(), KDEDesktopMimeType::executeService(), foundMimeType(), run(), and runURL().
.SS "pid_t KRun::run (const \fBQString\fP & _exec, const \fBKURL::List\fP & _urls, const \fBQString\fP & _name = \fCQString::null\fP, const \fBQString\fP & _icon = \fCQString::null\fP, const \fBQString\fP & _obsolete1 = \fCQString::null\fP, const \fBQString\fP & _obsolete2 = \fCQString::null\fP)\fC [static]\fP"
.PP
Open a list of URLs with. 
.PP
\fBParameters:\fP
.RS 4
\fI_exec\fP The name of the executable, for example '/usr/bin/netscape'. 
.br
\fI_name\fP The logical name of the application, for example 'Netscape 4.06'. 
.br
\fI_icon\fP The icon which should be used by the application. 
.br
\fI_obsolete1\fP Do not use! 
.br
\fI_obsolete2\fP Do not use! 
.RE
.PP
\fBReturns:\fP
.RS 4
the process id, or 0 on error 
.RE
.PP

.PP
Definition at line 706 of file krun.cpp.
.PP
References run().
.SS "pid_t KRun::runURL (const \fBKURL\fP & _url, const \fBQString\fP & _mimetype, bool tempFile, bool runExecutables)\fC [static]\fP"
.PP
Open the given URL. 
.PP
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 \fBrun()\fP afterwards. 
.PP
\fBParameters:\fP
.RS 4
\fI_url\fP the URL to open 
.br
\fI_mimetype\fP the mime type of the resource 
.br
\fItempFile\fP if true and _url is a local file, it will be deleted when the launched application exits. 
.br
\fIrunExecutables\fP if false then local .desktop files, executables and shell scripts will not be run. See also \fBisExecutable()\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
the process id, or 0 on error 
.RE
.PP

.PP
Definition at line 104 of file krun.cpp.
.PP
References QValueList::append(), displayOpenWithDialog(), isExecutable(), isExecutableFile(), KServiceTypeProfile::preferredService(), run(), KDEDesktopMimeType::run(), runCommand(), shellQuote(), KMessageBox::sorry(), and KGlobal::staticQString().
.PP
Referenced by foundMimeType().
.SS "pid_t KRun::runCommand (\fBQString\fP cmd)\fC [static]\fP"
.PP
Run the given shell command and notifies kicker of the starting of the application. 
.PP
If the program to be called doesn't exist, an error box will be displayed.
.PP
Use only when you know the full command line. Otherwise use the other static methods, or KRun's constructor.
.PP
\fC_cmd\fP must be a shell command. You must not append '&' to it, since the function will do that for you.
.PP
\fBReturns:\fP
.RS 4
PID of running command, 0 if it could not be started, 0 - (PID of running command) if command was unsafe for map notification. 
.RE
.PP

.PP
Definition at line 714 of file krun.cpp.
.PP
Referenced by KMimeTypeChooser::editMimeType(), and runURL().
.SS "pid_t KRun::runCommand (const \fBQString\fP & cmd, const \fBQString\fP & execName, const \fBQString\fP & icon)\fC [static]\fP"
.PP
Same as the other \fBrunCommand()\fP, but it also takes the name of the binary, to display an error message in case it couldn't find it. 
.PP
\fC_cmd\fP must be a shell command. You must not append '&' to it, since the function will do that for you. 
.PP
\fBParameters:\fP
.RS 4
\fIexecName\fP the name of the executable 
.br
\fIicon\fP icon for app starting notification 
.RE
.PP
\fBReturns:\fP
.RS 4
PID of running command, 0 if it could not be started, 0 - (PID of running command) if command was unsafe for map notification. 
.RE
.PP

.PP
Definition at line 719 of file krun.cpp.
.PP
References binaryName(), KSharedPtr< T >::data(), endl(), kdDebug(), KService::serviceByDesktopName(), and KProcess::setUseShell().
.SS "bool KRun::displayOpenWithDialog (const \fBKURL::List\fP & lst, bool tempFiles)\fC [static]\fP"
.PP
Display the Open-With dialog for those URLs, and run the chosen application. 
.PP
\fBParameters:\fP
.RS 4
\fIlst\fP the list of applications to run 
.br
\fItempFiles\fP if true and lst are local files, they will be deleted when the application exits. 
.RE
.PP
\fBReturns:\fP
.RS 4
false if the dialog was canceled 
.RE
.PP

.PP
Definition at line 184 of file krun.cpp.
.PP
References endl(), QDialog::exec(), kdDebug(), run(), KOpenWithDlg::service(), KMessageBox::sorry(), and KOpenWithDlg::text().
.PP
Referenced by runURL().
.SS "void KRun::shellQuote (\fBQString\fP & _str)\fC [static]\fP"
.PP
Quotes a string for the shell. 
.PP
\fBParameters:\fP
.RS 4
\fI_str\fP the string to quote. The quoted string will be written here 
.RE
.PP

.PP
Definition at line 206 of file krun.cpp.
.PP
Referenced by processDesktopExec(), and runURL().
.SS "\fBQStringList\fP KRun::processDesktopExec (const \fBKService\fP & _service, const \fBKURL::List\fP & _urls, bool has_shell, bool tempFiles)\fC [static]\fP"
.PP
Processes a Exec= line as found in .desktop files. 
.PP
\fBParameters:\fP
.RS 4
\fI_service\fP the service to extract information from. 
.br
\fI_urls\fP The urls the service should open. 
.br
\fIhas_shell\fP 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. 
.br
\fItempFiles\fP if true and _urls are local files, they will be deleted when the application exits. 
.RE
.PP
\fBReturns:\fP
.RS 4
a list of arguments suitable for either system() or exec(). 
.RE
.PP

.PP
Definition at line 344 of file krun.cpp.
.PP
References QRegExp::cap(), KGlobal::config(), endl(), QString::find(), KProtocolInfo::isHelperProtocol(), KShell::joinArgs(), kdWarning(), QString::length(), QString::prepend(), KConfigBase::readPathEntry(), QString::remove(), QRegExp::search(), shellQuote(), KShell::splitArgs(), and QString::unicode().
.SS "\fBQString\fP KRun::binaryName (const \fBQString\fP & execLine, bool removePath)\fC [static]\fP"
.PP
Given a full command line (e.g. 
.PP
the Exec= line from a .desktop file), extract the name of the binary being run. 
.PP
\fBParameters:\fP
.RS 4
\fIexecLine\fP the full command line 
.br
\fIremovePath\fP if true, remove a (relative or absolute) path. E.g. /usr/bin/ls becomes ls. 
.RE
.PP
\fBReturns:\fP
.RS 4
the name of the binary to run 
.RE
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP

.PP
Definition at line 504 of file krun.cpp.
.PP
References KShell::splitArgs().
.PP
Referenced by runCommand().
.SS "bool KRun::isExecutable (const \fBQString\fP & serviceType)\fC [static]\fP"
.PP
Returns whether \fCserviceType\fP refers to an executable program instead of a data file. 
.PP
\fBSince:\fP
.RS 4
3.2 
.RE
.PP

.PP
Definition at line 1204 of file krun.cpp.
.PP
Referenced by runURL().
.SS "bool KRun::isExecutableFile (const \fBKURL\fP & url, const \fBQString\fP & mimetype)\fC [static]\fP"
.PP
Returns wether the \fCurl\fP of \fCmimetype\fP is executable. 
.PP
To be executable the file must pass the following rules:
.IP "1." 4
Must reside on the local filesystem.
.IP "2." 4
Must be marked as executable for the user by the filesystem.
.IP "3." 4
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 
.PP
.nf
 X-KDE-IsAlso=application/x-executable-script

.fi
.PP
 to the mimetype's desktop file. 
.PP
\fBSince:\fP
.RS 4
3.3 
.RE
.PP

.PP

.PP
Definition at line 88 of file krun.cpp.
.PP
References KMimeType::mimeType().
.PP
Referenced by runURL().
.SS "void KRun::finished ()\fC [signal]\fP"
.PP
Emitted when the operation finished. 
.PP
\fBSee also:\fP
.RS 4
\fBhasFinished()\fP 
.RE
.PP

.SS "void KRun::error ()\fC [signal]\fP"
.PP
Emitted when the operation had an error. 
.PP
\fBSee also:\fP
.RS 4
\fBhasError()\fP 
.RE
.PP

.PP
Referenced by run().
.SS "void KRun::foundMimeType (const \fBQString\fP & _type)\fC [protected, virtual]\fP"
.PP
Called if the mimetype has been detected. 
.PP
The function checks whether the document and appends the gzip protocol to the URL. Otherwise runURL is called to finish the job. 
.PP
Definition at line 1066 of file krun.cpp.
.PP
References QValueList::append(), endl(), QObject::inherits(), kdDebug(), KIO::Scheduler::publishSlaveOnHold(), KIO::SimpleJob::putOnHold(), run(), runURL(), KService::serviceByDesktopName(), and QTimer::start().
.SH "Member Data Documentation"
.PP 
.SS "bool \fBKRun::m_bScanFile\fP\fC [protected]\fP"
.PP
Used to indicate that the next action is to scan the file. 
.PP
This action is invoked from slotTimeout. 
.PP
Definition at line 389 of file krun.h.
.PP
Referenced by abort().
.SS "bool \fBKRun::m_bInit\fP\fC [protected]\fP"
.PP
USed to indicate that the next action is to initialize. 
.PP
This action is invoked from slotTimeout 
.PP
Definition at line 396 of file krun.h.
.PP
Referenced by abort().

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