KDECore
KToolInvocation Class Reference
KToolInvocation: for starting other programs. More...
#include <ktoolinvocation.h>

Public Slots | |
static void | invokeBrowser (const QString &url, const QByteArray &startup_id=QByteArray()) |
static void | invokeHelp (const QString &anchor=QString(), const QString &appname=QString(), const QByteArray &startup_id=QByteArray()) |
static void | invokeMailer (const QString &to, const QString &cc, const QString &bcc, const QString &subject, const QString &body, const QString &messageFile=QString(), const QStringList &attachURLs=QStringList(), const QByteArray &startup_id=QByteArray()) |
static void | invokeMailer (const KUrl &mailtoURL, const QByteArray &startup_id=QByteArray(), bool allowAttachments=false) |
static void | invokeMailer (const QString &address, const QString &subject, const QByteArray &startup_id=QByteArray()) |
static void | invokeTerminal (const QString &command, const QString &workdir=QString(), const QByteArray &startup_id="") |
Signals | |
void | kapplication_hook (QStringList &env, QByteArray &startup_id) |
Public Member Functions | |
~KToolInvocation () | |
Static Public Member Functions | |
static int | kdeinitExec (const QString &name, const QStringList &args=QStringList(), QString *error=0, int *pid=0, const QByteArray &startup_id=QByteArray()) |
static int | kdeinitExecWait (const QString &name, const QStringList &args=QStringList(), QString *error=0, int *pid=0, const QByteArray &startup_id=QByteArray()) |
static OrgKdeKLauncherInterface * | klauncher () |
static KToolInvocation * | self () |
static int | startServiceByDesktopName (const QString &_name, const QStringList &URLs=QStringList(), QString *error=0, QString *serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false) |
static int | startServiceByDesktopName (const QString &_name, const QString &URL, QString *error=0, QString *serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false) |
static int | startServiceByDesktopPath (const QString &_name, const QStringList &URLs=QStringList(), QString *error=0, QString *serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false) |
static int | startServiceByDesktopPath (const QString &_name, const QString &URL, QString *error=0, QString *serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false) |
static int | startServiceByName (const QString &_name, const QStringList &URLs=QStringList(), QString *error=0, QString *serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false) |
static int | startServiceByName (const QString &_name, const QString &URL, QString *error=0, QString *serviceName=0, int *pid=0, const QByteArray &startup_id=QByteArray(), bool noWait=false) |
Detailed Description
KToolInvocation: for starting other programs.
Desktop files for startServiceBy
The way a service gets started depends on the 'X-DBUS-StartupType' entry in the desktop file of the service:
There are three possibilities:
- X-DBUS-StartupType=None (default) Always start a new service, don't wait till the service registers with dbus.
- X-DBUS-StartupType=Multi Always start a new service, wait until the service has registered with dbus.
- X-DBUS-StartupType=Unique Only start the service if it isn't already running, wait until the service has registered with dbus. The .desktop file can specify the name that the application will use when registering using X-DBUS-ServiceName=org.domain.mykapp. Otherwise org.kde.binaryname is assumed.
Multi-threading
The static members (apart from self()), have to be called from the QApplication main thread. Calls to members are only allowed if there is a Q(Core)Application object created If you call the members with signal/slot connections across threads, you can't use the return values If a function is called from the wrong thread and it has a return value -1 is returned Investigate if this is really needed or if DBUS is threadsafe anyway
For more details see techbase.
Definition at line 71 of file ktoolinvocation.h.
Constructor & Destructor Documentation
KToolInvocation::~KToolInvocation | ( | ) |
Definition at line 51 of file ktoolinvocation.cpp.
Member Function Documentation
void KToolInvocation::invokeBrowser | ( | const QString & | url, | |
const QByteArray & | startup_id = QByteArray() | |||
) | [static, slot] |
Invokes the user's preferred browser.
Note that you should only do this when you know for sure that the browser can handle the URL (i.e. its mimetype). In doubt, if the URL can point to an image or anything else than HTML, prefer to use new KRun( url ).
See also <a href=http://techbase.kde.org/Development/Architecture/KDE4/Starting_Other_Programs#KToolInvocation::invokeBrowser>techbase for a discussion of invokeBrowser vs KRun.
- Parameters:
-
url The destination address startup_id for app startup notification, "0" for none, "" ( empty string ) is the default
Definition at line 37 of file ktoolinvocation_win.cpp.
void KToolInvocation::invokeHelp | ( | const QString & | anchor = QString() , |
|
const QString & | appname = QString() , |
|||
const QByteArray & | startup_id = QByteArray() | |||
) | [static, slot] |
Invokes the KHelpCenter HTML help viewer from docbook sources.
- Parameters:
-
anchor This has to be a defined anchor in your docbook sources. If empty the main index is loaded appname This allows you to show the help of another application. If empty the current name() is used startup_id for app startup notification, "0" for none, "" ( empty string ) is the default
Definition at line 247 of file ktoolinvocation.cpp.
void KToolInvocation::invokeMailer | ( | const QString & | to, | |
const QString & | cc, | |||
const QString & | bcc, | |||
const QString & | subject, | |||
const QString & | body, | |||
const QString & | messageFile = QString() , |
|||
const QStringList & | attachURLs = QStringList() , |
|||
const QByteArray & | startup_id = QByteArray() | |||
) | [static, slot] |
Convenience method; invokes the standard email application.
All parameters are optional.
- Parameters:
-
to The destination address. cc The Cc field bcc The Bcc field subject Subject string body A string containing the body of the mail (exclusive with messageFile) messageFile A file (URL) containing the body of the mail (exclusive with body) - currently unsupported attachURLs List of URLs to be attached to the mail. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default
Definition at line 43 of file ktoolinvocation_win.cpp.
void KToolInvocation::invokeMailer | ( | const KUrl & | mailtoURL, | |
const QByteArray & | startup_id = QByteArray() , |
|||
bool | allowAttachments = false | |||
) | [static, slot] |
Invokes the standard email application.
- Parameters:
-
mailtoURL A mailto URL. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default allowAttachments whether attachments specified in mailtoURL should be honoured. The default is false; do not honor requests for attachments.
Definition at line 325 of file ktoolinvocation.cpp.
void KToolInvocation::invokeMailer | ( | const QString & | address, | |
const QString & | subject, | |||
const QByteArray & | startup_id = QByteArray() | |||
) | [static, slot] |
Convenience method; invokes the standard email application.
- Parameters:
-
address The destination address subject Subject string. Can be QString(). startup_id for app startup notification, "0" for none, "" ( empty string ) is the default
Definition at line 316 of file ktoolinvocation.cpp.
void KToolInvocation::invokeTerminal | ( | const QString & | command, | |
const QString & | workdir = QString() , |
|||
const QByteArray & | startup_id = "" | |||
) | [static, slot] |
Invokes the standard terminal application.
- Parameters:
-
command the command to execute, can be empty. workdir the initial working directory, can be empty. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default
- Since:
- 4.1
Definition at line 60 of file ktoolinvocation_win.cpp.
void KToolInvocation::kapplication_hook | ( | QStringList & | env, | |
QByteArray & | startup_id | |||
) | [signal] |
Hook for KApplication in kdeui.
For internal use only.
int KToolInvocation::kdeinitExec | ( | const QString & | name, | |
const QStringList & | args = QStringList() , |
|||
QString * | error = 0 , |
|||
int * | pid = 0 , |
|||
const QByteArray & | startup_id = QByteArray() | |||
) | [static] |
Starts a program via kdeinit.
program name and arguments are converted to according to the local encoding and passed as is to kdeinit.
- Parameters:
-
name Name of the program to start args Arguments to pass to the program error On failure, error
contains a description of the error that occurred. If the pointer is 0, the argument will be ignoredpid On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default
- Returns:
- an error code indicating success (== 0) or failure (> 0).
Definition at line 225 of file ktoolinvocation.cpp.
int KToolInvocation::kdeinitExecWait | ( | const QString & | name, | |
const QStringList & | args = QStringList() , |
|||
QString * | error = 0 , |
|||
int * | pid = 0 , |
|||
const QByteArray & | startup_id = QByteArray() | |||
) | [static] |
Starts a program via kdeinit and wait for it to finish.
Like kdeinitExec(), but it waits till the program is finished. As such it behaves similar to the system(...) function.
- Parameters:
-
name Name of the program to start args Arguments to pass to the program error On failure, error
contains a description of the error that occurred. If the pointer is 0, the argument will be ignoredpid On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default
- Returns:
- an error code indicating success (== 0) or failure (> 0).
Definition at line 237 of file ktoolinvocation.cpp.
static OrgKdeKLauncherInterface* KToolInvocation::klauncher | ( | ) | [static] |
Returns the DBus interface of the service launcher.
The returned object is owned by KApplication, do not delete it!
KToolInvocation * KToolInvocation::self | ( | ) | [static] |
Definition at line 41 of file ktoolinvocation.cpp.
int KToolInvocation::startServiceByDesktopName | ( | const QString & | _name, | |
const QStringList & | URLs = QStringList() , |
|||
QString * | error = 0 , |
|||
QString * | serviceName = 0 , |
|||
int * | pid = 0 , |
|||
const QByteArray & | startup_id = QByteArray() , |
|||
bool | noWait = false | |||
) | [static] |
Starts a service based on the desktop name of the service.
E.g. "konqueror"
- Parameters:
-
_name the desktop name of the service URLs if not empty these URLs will be passed to the service error On failure, error
contains a description of the error that occurred. If the pointer is 0, the argument will be ignoredserviceName On success, serviceName
contains the D-Bus service name under which this service is available. If empty, the service does not provide D-Bus services. If the pointer is 0 the argument will be ignoredpid On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default noWait if set, the function does not wait till the service is running.
- Returns:
- an error code indicating success (== 0) or failure (> 0).
Definition at line 213 of file ktoolinvocation.cpp.
int KToolInvocation::startServiceByDesktopName | ( | const QString & | _name, | |
const QString & | URL, | |||
QString * | error = 0 , |
|||
QString * | serviceName = 0 , |
|||
int * | pid = 0 , |
|||
const QByteArray & | startup_id = QByteArray() , |
|||
bool | noWait = false | |||
) | [static] |
Starts a service based on the desktop name of the service.
E.g. "konqueror"
- Parameters:
-
_name the desktop name of the service URL if not empty this URL is passed to the service error On failure, error
contains a description of the error that occurred. If the pointer is 0, the argument will be ignoredserviceName On success, serviceName
contains the D-Bus service name under which this service is available. If empty, the service does not provide D-Bus services. If the pointer is 0 the argument will be ignoredpid On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default noWait if set, the function does not wait till the service is running.
- Returns:
- an error code indicating success (== 0) or failure (> 0).
Definition at line 198 of file ktoolinvocation.cpp.
int KToolInvocation::startServiceByDesktopPath | ( | const QString & | _name, | |
const QStringList & | URLs = QStringList() , |
|||
QString * | error = 0 , |
|||
QString * | serviceName = 0 , |
|||
int * | pid = 0 , |
|||
const QByteArray & | startup_id = QByteArray() , |
|||
bool | noWait = false | |||
) | [static] |
Starts a service based on the desktop path of the service.
E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"
- Parameters:
-
_name the path of the desktop file URLs if not empty these URLs will be passed to the service error On failure, error
contains a description of the error that occurred. If the pointer is 0, the argument will be ignored *serviceName On success, serviceName
contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignoredpid On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default noWait if set, the function does not wait till the service is running.
- Returns:
- an error code indicating success (== 0) or failure (> 0).
Definition at line 186 of file ktoolinvocation.cpp.
int KToolInvocation::startServiceByDesktopPath | ( | const QString & | _name, | |
const QString & | URL, | |||
QString * | error = 0 , |
|||
QString * | serviceName = 0 , |
|||
int * | pid = 0 , |
|||
const QByteArray & | startup_id = QByteArray() , |
|||
bool | noWait = false | |||
) | [static] |
Starts a service based on the desktop path of the service.
E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"
- Parameters:
-
_name the path of the desktop file URL if not empty this URL is passed to the service error On failure, error
contains a description of the error that occurred. If the pointer is 0, the argument will be ignoredserviceName On success, serviceName
contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignoredpid On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default noWait if set, the function does not wait till the service is running.
- Returns:
- an error code indicating success (== 0) or failure (> 0).
Definition at line 171 of file ktoolinvocation.cpp.
int KToolInvocation::startServiceByName | ( | const QString & | _name, | |
const QStringList & | URLs = QStringList() , |
|||
QString * | error = 0 , |
|||
QString * | serviceName = 0 , |
|||
int * | pid = 0 , |
|||
const QByteArray & | startup_id = QByteArray() , |
|||
bool | noWait = false | |||
) | [static] |
Starts a service based on the (translated) name of the service.
E.g. "Web Browser"
- Parameters:
-
_name the name of the service URLs if not empty these URLs will be passed to the service error On failure, error
contains a description of the error that occurred. If the pointer is 0, the argument will be ignoredserviceName On success, serviceName
contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignoredpid On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default noWait if set, the function does not wait till the service is running.
- Returns:
- an error code indicating success (== 0) or failure (> 0).
Definition at line 159 of file ktoolinvocation.cpp.
int KToolInvocation::startServiceByName | ( | const QString & | _name, | |
const QString & | URL, | |||
QString * | error = 0 , |
|||
QString * | serviceName = 0 , |
|||
int * | pid = 0 , |
|||
const QByteArray & | startup_id = QByteArray() , |
|||
bool | noWait = false | |||
) | [static] |
Starts a service based on the (translated) name of the service.
E.g. "Web Browser"
- Parameters:
-
_name the name of the service URL if not empty this URL is passed to the service error On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored serviceName On success, serviceName contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored pid On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored. startup_id for app startup notification, "0" for none, "" ( empty string ) is the default noWait if set, the function does not wait till the service is running.
- Returns:
- an error code indicating success (== 0) or failure (> 0).
Definition at line 144 of file ktoolinvocation.cpp.
The documentation for this class was generated from the following files: