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

KDECore

KToolInvocation Class Reference

#include <ktoolinvocation.h>

Inheritance diagram for KToolInvocation:

Inheritance graph
[legend]

List of all members.


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 DCOP/DBUS is threadsafe anyway

Definition at line 68 of file 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)

Constructor & Destructor Documentation

KToolInvocation::~KToolInvocation (  ) 

Definition at line 50 of file ktoolinvocation.cpp.


Member Function Documentation

void KToolInvocation::invokeBrowser ( const QString &  url,
const QByteArray &  startup_id = QByteArray() 
) [static, slot]

Invokes the standard 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 directory or HTML, prefer to use new KRun( url ).

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 240 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 299 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 290 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.

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 218 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 230 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 40 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 206 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 191 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 179 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 164 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 152 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 137 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
  • Kross
  • KUtils
  • Nepomuk
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.4
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