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

KDECore

KToolInvocation Class Reference

KToolInvocation: for starting other programs. More...

#include <ktoolinvocation.h>

Inheritance diagram for KToolInvocation:
QObject

List of all members.

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 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
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 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
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 ignored
serviceName 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 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 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 ignored
serviceName 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 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 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 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 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 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 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 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 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:
  • ktoolinvocation.h
  • ktoolinvocation.cpp
  • ktoolinvocation_win.cpp
  • ktoolinvocation_x11.cpp

KDECore

Skip menu "KDECore"
  • Main Page
  • Modules
  • 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