KService Class Reference

#include <KService>

Inheritance diagram for KService:

Public Types
enum	DBusStartupType { DBusNone = 0, DBusUnique, DBusMulti }
typedef QList< Ptr >	List
typedef QExplicitlySharedDataPointer< KService >	Ptr
Public Types inherited from KSycocaEntry
typedef QList< Ptr >	List
typedef QExplicitlySharedDataPointer< KSycocaEntry >	Ptr

Public Member Functions
	KService (const KDesktopFile *config, const QString &entryPath=QString())
	KService (const KService &other)
	KService (const QString &fullpath)
	KService (const QString &name, const QString &exec, const QString &icon)
QList< KServiceAction >	actions () const
QString	aliasFor () const
bool	allowAsDefault () const
bool	allowMultipleFiles () const
QStringList	categories () const
QString	comment () const
DBusStartupType	dbusStartupType () const
QString	desktopEntryName () const
QString	docPath () const
QString	exec () const
QString	genericName () const
bool	hasMimeType (const QString &mimeType) const
bool	hasServiceType (const QString &serviceTypePtr) const
QString	icon () const
int	initialPreference () const
bool	isApplication () const
QStringList	keywords () const
QString	library () const
QString	locateLocal () const
QString	menuId () const
QStringList	mimeTypes () const
bool	noDisplay () const
QString	parentApp () const
QString	path () const
QString	pluginKeyword () const
QVariant	property (const QString &_name, QMetaType::Type t) const
QVariant	property (const QString &_name, QVariant::Type t) const
QVariant	property (const QString &name) const
bool	runOnDiscreteGpu () const
QStringList	serviceTypes () const
void	setExec (const QString &exec)
void	setMenuId (const QString &menuId)
void	setTerminal (bool b)
void	setTerminalOptions (const QString &options)
void	setWorkingDirectory (const QString &workingDir)
bool	showInCurrentDesktop () const
bool	showInKDE () const
bool	showOnCurrentPlatform () const
QString	storageId () const
bool	substituteUid () const
QStringList	supportedProtocols () const
bool	terminal () const
QString	terminalOptions () const
QString	untranslatedGenericName () const
QString	username () const
QString	workingDirectory () const
Public Member Functions inherited from KSycocaEntry
QString	entryPath () const
bool	isDeleted () const
bool	isSeparator () const
bool	isType (KSycocaType t) const
bool	isValid () const
QString	name () const
QVariant	property (const QString &name) const
QStringList	propertyNames () const
void	setDeleted (bool deleted)
QString	storageId () const
KSycocaType	sycocaType () const
Public Member Functions inherited from QSharedData
	QSharedData (const QSharedData &)

Static Public Member Functions
static List	allServices ()
static QString	newServicePath (bool showInMenu, const QString &suggestedName, QString *menuId=nullptr, const QStringList *reservedMenuIds=nullptr)
static Ptr	serviceByDesktopName (const QString &_name)
static Ptr	serviceByDesktopPath (const QString &_path)
static Ptr	serviceByMenuId (const QString &_menuId)
static Ptr	serviceByStorageId (const QString &_storageId)

Additional Inherited Members
Protected Member Functions inherited from KSycocaEntry
	KSycocaEntry (KSycocaEntryPrivate &d)
Protected Attributes inherited from KSycocaEntry
const std::unique_ptr< KSycocaEntryPrivate >	d_ptr
Related Functions inherited from KSycocaEntry
enum	KSycocaType

Detailed Description

Represent a service, like an application or plugin bound to one or several MIME types (or servicetypes) as written in its desktop entry file.

The starting point you need is often the static methods, like createInstance(). The types of service a plugin provides is taken from the accompanying desktop file where the 'X-KDE-ServiceTypes=' field is used.

For a tutorial on how to build a plugin-loading mechanism and how to write plugins in general, see http://techbase.kde.org/Development/Tutorials#Services:_Applications_and_Plugins

See also

KServiceType

KServiceGroup

Author

Torben Weis

Definition at line 50 of file kservice.h.

Member Typedef Documentation

List

typedef QList<Ptr> KService::List

A list of shared data pointers for KService.

Definition at line 60 of file kservice.h.

Ptr

typedef QExplicitlySharedDataPointer<KService> KService::Ptr

A shared data pointer for KService.

Definition at line 56 of file kservice.h.

Member Enumeration Documentation

DBusStartupType

enum KService::DBusStartupType

Describes the D-Bus Startup type of the service.

• None - This service has no D-Bus support
• Unique - This service provides a unique D-Bus service. The service name is equal to the desktopEntryName.
• Multi - This service provides a D-Bus service which can be run with multiple instances in parallel. The service name of an instance is equal to the desktopEntryName + "-" + the PID of the process.

Definition at line 192 of file kservice.h.

Constructor & Destructor Documentation

KService() [1/3]

KService::KService	(	const QString &	name,
		const QString &	exec,
		const QString &	icon
	)

Construct a temporary service with a given name, exec-line and icon.

Parameters

name	the name of the service
exec	the executable
icon	the name of the icon

Definition at line 383 of file kservice.cpp.

KService() [2/3]

KService::KService ( const QString &  fullpath )

explicit

Construct a service and take all information from a config file.

Parameters

fullpath

Full path to the config file.

Definition at line 396 of file kservice.cpp.

KService() [3/3]

KService::KService ( const KDesktopFile *  config, const QString &  entryPath = QString()  )

explicit

Construct a service and take all information from a desktop file.

Parameters

config	the desktop file to read
optional	relative path to store for findByName

Definition at line 405 of file kservice.cpp.

Member Function Documentation

actions()

QList< KServiceAction > KService::actions

(

)

const

Returns the actions defined in this desktop file.

Definition at line 1136 of file kservice.cpp.

aliasFor()

QString KService::aliasFor

(

)

const

A desktop file name that this service is an alias for.

This is used when a NoDisplay service is used to enforce specific handling for an application. In that case the NoDisplay service is an AliasFor another service and be considered roughly equal to the AliasFor service (which should not be NoDisplay=true) For example okular supplies a desktop file for each supported format (e.g. PDF), all of which NoDisplay and merely there to selectively support specific file formats. A UI may choose to display the aliased entry org.kde.okular instead of the NoDisplay entries.

Since

5.96

Returns

QString desktopName of the aliased service (excluding .desktop suffix)

Definition at line 1159 of file kservice.cpp.

allowAsDefault()

bool KService::allowAsDefault

(

)

const

Set to true if it is allowed to use this service as the default (main) action for the files it supports (e.g.

Left Click in a file manager, or KRun in general).

If not, then this service is only available in RMB popups, so it must be selected explicitly by the user in order to be used. Note that servicemenus supersede this functionality though, at least in konqueror.

Returns

true if the service may be used as the default (main) handler

Deprecated:

since 5.67 due to no known use case

Definition at line 1085 of file kservice.cpp.

allowMultipleFiles()

bool KService::allowMultipleFiles

(

)

const

Checks whether this service can handle several files as startup arguments.

Returns

true if multiple files may be passed to this service at startup. False if only one file at a time may be passed.

Definition at line 845 of file kservice.cpp.

allServices()

KService::List KService::allServices ( )

static

Returns the whole list of services.

Useful for being able to to display them in a list box, for example. More memory consuming than the ones above, don't use unless really necessary.

Returns

the list of all services

Definition at line 643 of file kservice.cpp.

categories()

QStringList KService::categories

(

)

const

Returns a list of VFolder categories.

Returns

the list of VFolder categories

Definition at line 855 of file kservice.cpp.

comment()

QString KService::comment

(

)

const

Returns the descriptive comment for the service, if there is one.

Returns

the descriptive comment for the service, or QString() if not set

Definition at line 1006 of file kservice.cpp.

dbusStartupType()

KService::DBusStartupType KService::dbusStartupType

(

)

const

Returns the DBUSStartupType supported by this service.

Returns

the DBUSStartupType supported by this service

Deprecated:

since 5.102, no known users.

Definition at line 985 of file kservice.cpp.

desktopEntryName()

QString KService::desktopEntryName

(

)

const

Returns the filename of the service desktop entry without any extension.

E.g. "kppp"

Returns

the name of the desktop entry without path or extension, or QString() if not set

Definition at line 978 of file kservice.cpp.

docPath()

QString KService::docPath

(

)

const

The path to the documentation for this service.

Since

4.2

Returns

the documentation path, or QString() if not set

Definition at line 826 of file kservice.cpp.

exec()

QString KService::exec

(

)

const

Returns the executable.

Returns

the command that the service executes, or QString() if not set

Definition at line 934 of file kservice.cpp.

genericName()

QString KService::genericName

(

)

const

Returns the generic name for the service, if there is one (e.g.

"Mail Client").

Returns

the generic name, or QString() if not set

Definition at line 1012 of file kservice.cpp.

hasMimeType()

bool KService::hasMimeType

(

const QString &

mimeType

)

const

Checks whether the service supports this MIME type.

Parameters

mimeType

The name of the MIME type you are interested in determining whether this service supports.

Since

4.6

Definition at line 477 of file kservice.cpp.

hasServiceType()

bool KService::hasServiceType

(

const QString &

serviceTypePtr

)

const

Checks whether the service supports this service type.

Parameters

serviceTypePtr

The name of the service type you are interested in determining whether this service supports.

Returns

true if the service type you specified is supported, otherwise false.

  @deprecated since 5.104, service types are deprecated. Read the

X-KDE-ServiceType[s] key manually if really needed.

Definition at line 433 of file kservice.cpp.

icon()

QString KService::icon

(

)

const

Returns the name of the icon.

Returns

the icon associated with the service, or QString() if not set

Definition at line 949 of file kservice.cpp.

initialPreference()

int KService::initialPreference

(

)

const

What preference to associate with this service initially (before the user has had any chance to define a profile for it).

The bigger the value, the most preferred the service is.

Returns

the service preference level of the service

Definition at line 1092 of file kservice.cpp.

isApplication()

bool KService::isApplication

(

)

const

Services are either applications (executables) or dlopened libraries (plugins).

Returns

true if this service is an application, i.e. it has Type=Application in its .desktop file and exec() will not be empty.

Definition at line 928 of file kservice.cpp.

keywords()

QStringList KService::keywords

(

)

const

Returns a list of descriptive keywords the service, if there are any.

Returns

the list of keywords

Definition at line 1018 of file kservice.cpp.

library()

QString KService::library

(

)

const

Returns the name of the service's library.

Returns

the name of the library that contains the service's implementation, or QString() if not set

Definition at line 943 of file kservice.cpp.

locateLocal()

QString KService::locateLocal

(

)

const

Returns a path that can be used for saving changes to this service.

Returns

path that can be used for saving changes to this service

Definition at line 880 of file kservice.cpp.

menuId()

QString KService::menuId

(

)

const

Returns the menu ID of the service desktop entry.

The menu ID is used to add or remove the entry to a menu.

Returns

the menu ID

Definition at line 861 of file kservice.cpp.

mimeTypes()

QStringList KService::mimeTypes

(

)

const

Returns the list of MIME types that this service supports.

Note that this doesn't include inherited MIME types, only the MIME types listed in the .desktop file.

Since

4.8.3

Definition at line 1045 of file kservice.cpp.

newServicePath()

QString KService::newServicePath ( bool  showInMenu, const QString &  suggestedName, QString *  menuId = nullptr, const QStringList *  reservedMenuIds = nullptr  )

static

Returns a path that can be used to create a new KService based on suggestedName.

Parameters

showInMenu	true, if the service should be shown in the KDE menu false, if the service should be hidden from the menu This argument isn't used anymore, use NoDisplay=true to hide the service.
suggestedName	name to base the file on, if a service with such a name already exists, a suffix will be added to make it unique (e.g. foo.desktop, foo-1.desktop, foo-2.desktop).
menuId	If provided, menuId will be set to the menu id to use for the KService
reservedMenuIds	If provided, the path and menu id will be chosen in such a way that the new menu id does not conflict with any of the reservedMenuIds

Returns

The path to use for the new KService.

Definition at line 892 of file kservice.cpp.

noDisplay()

bool KService::noDisplay

(

)

const

Whether the entry should be suppressed in the K menu.

Returns

true to suppress this service

Such services still appear in trader queries, i.e. in "Open With" popup menus for instance.

Definition at line 770 of file kservice.cpp.

parentApp()

QString KService::parentApp

(

)

const

Name of the application this service belongs to.

(Useful for e.g. plugins)

Returns

the parent application, or QString() if not set

Deprecated:

Since 5.87, the concept of parent apps is deprecated. Plugins should use KPluginMetaData instead of KService and a dedicated namespace if the plugins are only for one app relevant.

Definition at line 798 of file kservice.cpp.

path()

QString KService::path

(

)

const

Returns

the working directory to run the program in, or QString() if not set

Deprecated:

since 5.63, use workingDirectory() instead

Definition at line 993 of file kservice.cpp.

pluginKeyword()

QString KService::pluginKeyword

(

)

const

The keyword to be used when constructing the plugin using KPluginFactory.

The keyword is defined with X-KDE-PluginKeyword in the .desktop file and with registerPlugin<T>(keyword) in the K_PLUGIN_FACTORY macro when implementing the plugin.

Deprecated:

Since 5.87, the metadata should be embedded in the actual plugin. Consequently this property is obsolete. In case there is only one plugin in the library the usage is not needed. In case there are different base classes registered the keyword is not needed too. If there are multiple classes of a common base class registered they should be split up in separate libs.

Definition at line 814 of file kservice.cpp.

property() [1/3]

QVariant KService::property	(	const QString &	_name,
		QMetaType::Type	t
	)		const

Returns the requested property.

Parameters

_name	the name of the property
t	the assumed type of the property

Returns

the property, or invalid if not found

See also

KServiceType

Since

5.102

Definition at line 536 of file kservice.cpp.

property() [2/3]

QVariant KService::property	(	const QString &	_name,
		QVariant::Type	t
	)		const

Returns the requested property.

Parameters

_name	the name of the property
t	the assumed type of the property

Returns

the property, or invalid if not found

See also

KServiceType

Deprecated:

since 5.102, use property(QString, QMetaType::Type) instead.

Definition at line 529 of file kservice.cpp.

property() [3/3]

QVariant KSycocaEntry::property

Returns the requested property.

Some often used properties have convenience access functions like exec(), serviceTypes etc.

Parameters

name	the name of the property

Returns

the property, or invalid if not found

Definition at line 102 of file ksycocaentry.cpp.

runOnDiscreteGpu()

bool KService::runOnDiscreteGpu

(

)

const

Returns true if the service inidicates that it's preferred to run the application on a discrete graphics card, otherwise return false.

In releases older than 5.86 this methoed checked for the X-KDE-RunOnDiscreteGpu key in the .desktop file represented by this service; starting from 5.86 this method now also checks for PrefersNonDefaultGPU key (added to the Freedesktop.org desktop entry spec in version 1.4 of the spec).

Since

5.30

Definition at line 967 of file kservice.cpp.

serviceByDesktopName()

KService::Ptr KService::serviceByDesktopName ( const QString &  _name )

static

Find a service by the name of its desktop file, not depending on its actual location (as long as it's under the applications or service directories).

For instance "konqbrowser" or "kcookiejar". Note that the ".desktop" extension is implicit.

This is the recommended method (safe even if the user moves stuff) but note that it assumes that no two entries have the same filename.

Parameters

_name

the name of the configuration file

Returns

a pointer to the requested service or nullptr if the service is unknown. Very important: Don't store the result in a KService* !

Definition at line 655 of file kservice.cpp.

serviceByDesktopPath()

KService::Ptr KService::serviceByDesktopPath ( const QString &  _path )

static

Find a service based on its path as returned by entryPath().

It's usually better to use serviceByStorageId() instead.

Parameters

_path

the path of the configuration file

Returns

a pointer to the requested service or nullptr if the service is unknown. Very important: Don't store the result in a KService* !

Definition at line 649 of file kservice.cpp.

serviceByMenuId()

KService::Ptr KService::serviceByMenuId ( const QString &  _menuId )

static

Find a service by its menu-id.

Parameters

_menuId

the menu id of the service

Returns

a pointer to the requested service or nullptr if the service is unknown. Very important: Don't store the result in a KService* !

Definition at line 661 of file kservice.cpp.

serviceByStorageId()

KService::Ptr KService::serviceByStorageId ( const QString &  _storageId )

static

Find a service by its storage-id or desktop-file path.

This function will try very hard to find a matching service.

Parameters

_storageId

the storage id or desktop-file path of the service

Returns

a pointer to the requested service or nullptr if the service is unknown. Very important: Don't store the result in a KService* !

Definition at line 667 of file kservice.cpp.

serviceTypes()

QStringList KService::serviceTypes

(

)

const

Returns the service types that this service supports.

Returns

the list of service types that are supported Note that this doesn't include inherited servicetypes or MIME types, only the service types listed in the .desktop file.

Deprecated:

since 5.104, service types are deprecated. Read the X-KDE-ServiceType[s] key manually if really needed.

Definition at line 1038 of file kservice.cpp.

setExec()

void KService::setExec

(

const QString &

exec

)

Overrides the "Exec=" line of the service.

If exec is not empty, its value will override the one the one set when this service was created.

Please note that entryPath is also cleared so the service will no longer be associated with a specific config file.

Since

4.11

Definition at line 1110 of file kservice.cpp.

setMenuId()

void KService::setMenuId

(

const QString &

menuId

)

Set the menu id

Definition at line 867 of file kservice.cpp.

setTerminal()

void KService::setTerminal

(

bool

b

)

Sets whether to use a terminal or not

Definition at line 1098 of file kservice.cpp.

setTerminalOptions()

void KService::setTerminalOptions

(

const QString &

options

)

Sets the terminal options to use

Definition at line 1104 of file kservice.cpp.

setWorkingDirectory()

void KService::setWorkingDirectory

(

const QString &

workingDir

)

Overrides the "Path=" line of the service.

If workingDir is not empty, its value will override the one the one set when this service was created.

Please note that entryPath is also cleared so the service will no longer be associated with a specific config file.

Parameters

workingDir

Since

5.79

Definition at line 1120 of file kservice.cpp.

showInCurrentDesktop()

bool KService::showInCurrentDesktop

(

)

const

Whether the service should be shown in the current desktop (including in context menus).

Returns

true if the service should be shown.

KApplicationTrader honors this and removes such services from its results.

Since

5.0

Definition at line 694 of file kservice.cpp.

showInKDE()

bool KService::showInKDE ( ) const

inline

Whether the service should be shown in KDE at all (including in context menus).

Returns

true if the service should be shown.

KMimeTypeTrader honors this and removes such services from its results.

Since

4.5

Deprecated:

since 5.0, use showInCurrentDesktop()

Definition at line 376 of file kservice.h.

showOnCurrentPlatform()

bool KService::showOnCurrentPlatform

(

)

const

Whether the service should be shown on the current platform (e.g.

on xcb or on wayland).

Returns

true if the service should be shown

Since

5.0

Definition at line 744 of file kservice.cpp.

storageId()

QString KService::storageId

(

)

const

Returns a normalized ID suitable for storing in configuration files.

It will be based on the menu-id when available and otherwise falls back to entryPath()

Returns

the storage ID

Definition at line 873 of file kservice.cpp.

substituteUid()

bool KService::substituteUid

(

)

const

Checks whether the service runs with a different user id.

Returns

true if the service has to be run under a different uid.

See also

username()

Definition at line 673 of file kservice.cpp.

supportedProtocols()

QStringList KService::supportedProtocols

(

)

const

Returns the list of protocols this service supports.

This is taken from the x-scheme-handler MIME types listed in the .destkop file as well as the 'X-KDE-Protocols' entry

For example a web browser could return {"http", "https"}.

Since

5.104

Definition at line 1062 of file kservice.cpp.

terminal()

bool KService::terminal

(

)

const

Checks whether the service should be run in a terminal.

Returns

true if the service is to be run in a terminal.

Definition at line 961 of file kservice.cpp.

terminalOptions()

QString KService::terminalOptions

(

)

const

Returns any options associated with the terminal the service runs in, if it requires a terminal.

The service must be a tty-oriented program.

Returns

the terminal options, or QString() if not set

Definition at line 955 of file kservice.cpp.

untranslatedGenericName()

QString KService::untranslatedGenericName

(

)

const

Returns the untranslated (US English) generic name for the service, if there is one (e.g.

"Mail Client").

Returns

the generic name, or QString() if not set

Definition at line 791 of file kservice.cpp.

username()

QString KService::username

(

)

const

Returns the user name, if the service runs with a different user id.

Returns

the username under which the service has to be run, or QString() if not set

See also

substituteUid()

Definition at line 679 of file kservice.cpp.

workingDirectory()

QString KService::workingDirectory

(

)

const

Returns

the working directory to run the program in, or QString() if not set

Since

5.63

Definition at line 1000 of file kservice.cpp.

---

The documentation for this class was generated from the following files:

• kservice.h
• kservice.cpp