KService Class Reference

from PyKDE4.kdecore import *

Detailed Description

Represent a service, like an application or plugin bound to one or several mimetypes (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 '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

See also:: KServiceGroup

Author:: Torben Weis

Enumerations
DBusStartupType	{ DBusNone, DBusUnique, DBusMulti, DBusWait }
Methods
	__init__ (self, QString name, QString exec, QString icon)
	__init__ (self, QString fullpath)
	__init__ (self, KDesktopFile config)
	__init__ (self, QDataStream str, int offset)
	__init__ (self, KService other)
[KServiceAction]	actions (self)
bool	allowAsDefault (self)
bool	allowMultipleFiles (self)
QStringList	categories (self)
QString	comment (self)
KService.DBusStartupType	dbusStartupType (self)
QString	desktopEntryName (self)
QString	desktopEntryPath (self)
QString	docPath (self)
QString	exec_ (self)
QString	genericName (self)
bool	hasMimeType (self, KServiceType mimeTypePtr)
bool	hasMimeType (self, QString mimeType)
bool	hasServiceType (self, QString serviceTypePtr)
QString	icon (self)
int	initialPreference (self)
bool	isApplication (self)
QStringList	keywords (self)
QString	library (self)
QString	locateLocal (self)
QString	menuId (self)
QStringList	mimeTypes (self)
bool	noDisplay (self)
QString	parentApp (self)
QString	path (self)
QString	pluginKeyword (self)
QVariant	property (self, QString _name, QVariant::Type t)
QStringList	serviceTypes (self)
	setMenuId (self, QString menuId)
	setTerminal (self, bool b)
	setTerminalOptions (self, QString options)
bool	showInKDE (self)
QString	storageId (self)
bool	substituteUid (self)
bool	terminal (self)
QString	terminalOptions (self)
QString	type (self)
QString	untranslatedGenericName (self)
QString	username (self)
Static Methods
[KSharedPtr]	allServices ()
QString	newServicePath (bool showInMenu, QString suggestedName, QString menuId=0, QStringList reservedMenuIds=0)
KSharedPtr	serviceByDesktopName (QString _name)
KSharedPtr	serviceByDesktopPath (QString _path)
KSharedPtr	serviceByMenuId (QString _menuId)
KSharedPtr	serviceByName (QString _name)
KSharedPtr	serviceByStorageId (QString _storageId)

Method Documentation

__init__	(	self,
		QString	name,
		QString	exec,
		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

__init__	(	self,
		QString	fullpath
	)

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

Parameters:

fullpath

Full path to the config file.

__init__	(	self,
		KDesktopFile	config
	)

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

Parameters:

config

the desktop file to read

__init__	(	self,
		QDataStream	str,
		int	offset
	)

Internal:: Construct a service from a stream. The stream must already be positionned at the correct offset.

__init__	(	self,
		KService	other
	)

[KServiceAction] actions ( self )

Returns the actions defined in this desktop file

bool allowAsDefault ( self )

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

bool allowMultipleFiles ( self )

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.

QStringList categories ( self )

Returns a list of VFolder categories.

Returns:: the list of VFolder categories

QString comment ( self )

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

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

KService.DBusStartupType dbusStartupType ( self )

Returns the DBUSStartupType supported by this service.

Returns:: the DBUSStartupType supported by this service

QString desktopEntryName ( self )

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

QString desktopEntryPath ( self )

Returns the path to the location where the service desktop entry is stored.

This is a relative path if the desktop entry was found in any of the locations pointed to by $KDEDIRS (e.g. "Internet/kppp.desktop") It is a full path if the desktop entry originates from another location.

Deprecated:: use entryPath() instead

Returns:: the path of the service's desktop file, or QString() if not set

QString docPath ( self )

The path to the documentation for this service.

Since:: 4.2

Returns:: the documentation path, or QString() if not set

QString exec_ ( self )

Returns the executable.

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

QString genericName ( self )

Returns the generic name for the service, if there is one (e.g. "Mail Client").

Returns:: the generic name, or QString() if not set

bool hasMimeType	(	self,
		KServiceType	mimeTypePtr
	)

Checks whether the service supports this mime type

Parameters:

mimeTypePtr

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

Since:: 4.6

bool hasMimeType	(	self,
		QString	mimeType
	)

Checks whether the service supports this mime type

Parameters:

mimeTypePtr

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

Since:: 4.6

bool hasServiceType	(	self,
		QString	serviceTypePtr
	)

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.

QString icon ( self )

Returns the name of the icon.

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

int initialPreference ( self )

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

bool isApplication ( self )

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.

QStringList keywords ( self )

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

Returns:: the list of keywords

QString library ( self )

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

QString locateLocal ( self )

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

QString menuId ( self )

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

QStringList mimeTypes ( self )

Returns the list of mime types that this service supports. Note that this doesn't include inherited mimetypes, only the mimetypes types listed in the .desktop file.

Since:: 4.8.3

bool noDisplay ( self )

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.

QString parentApp ( self )

Name of the application this service belongs to. (Useful for e.g. plugins)

Returns:: the parent application, or QString() if not set

QString path ( self )

Returns the working directory to run the program in.

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

QString pluginKeyword ( self )

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 K_REGISTER_PLUGIN_WITH_KEYWORD when implementing the plugin.

QVariant property	(	self,
		QString	_name,
		QVariant::Type	t
	)

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

QStringList serviceTypes ( self )

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 mimetypes, only the service types listed in the .desktop file.

setMenuId	(	self,
		QString	menuId
	)

Internal:: Set the menu id

setTerminal	(	self,
		bool	b
	)

Internal:: Sets whether to use a terminal or not

setTerminalOptions	(	self,
		QString	options
	)

Internal:: Sets the terminal options to use

bool showInKDE ( self )

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

QString storageId ( self )

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

bool substituteUid ( self )

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()

bool terminal ( self )

Checks whethe the service should be run in a terminal.

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

QString terminalOptions ( self )

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

QString type ( self )

Returns the type of the service.

Returns:: the type of the service ("Application" or "Service")

Deprecated:: use isApplication()

QString untranslatedGenericName ( self )

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

QString username ( self )

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()

Static Method Documentation

[KSharedPtr] allServices ( )

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

QString newServicePath	(	bool	showInMenu,
		QString	suggestedName,
		QString	menuId=0,
		QStringList	reservedMenuIds=0
	)

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 name already exists, a prefix will be added to make it unique.
	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.

KSharedPtr serviceByDesktopName	(	QString	_name
	)

Find a service by the name of its desktop file, not depending on its actual location (as long as it's under the applnk 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 0 if the service is unknown.

Very important: Don't store the result in a KService* !

KSharedPtr serviceByDesktopPath	(	QString	_path
	)

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 0 if the service is unknown.

Very important: Don't store the result in a KService* !

KSharedPtr serviceByMenuId	(	QString	_menuId
	)

Find a service by its menu-id

Parameters:

_menuId

the menu id of the service

Returns:: a pointer to the requested service or 0 if the service is unknown.

Very important: Don't store the result in a KService* !

KSharedPtr serviceByName	(	QString	_name
	)

Find a service by name, i.e. the translated Name field. Don't use this. Use serviceByDesktopPath or serviceByStorageId instead.

Parameters:

_name

the name to search

Returns:: a pointer to the requested service or 0 if the service is unknown.

Very important: Don't store the result in a KService* !

Deprecated:: there is never a good reason to use this method.

KSharedPtr serviceByStorageId	(	QString	_storageId
	)

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 0 if the service is unknown.

Very important: Don't store the result in a KService* !

Enumeration Documentation

DBusStartupType

Describes the DBUS Startup type of the service.

None - This service has no DBUS support

Unique - This service provides a unique DBUS service.

The service name is equal to the desktopEntryName.

Multi - This service provides a DBUS 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.

Wait - This service has no DBUS support, the launcher will wait

till it is finished.

Enumerator:

DBusNone = 0
DBusUnique
DBusMulti
DBusWait

KService Class Reference

Detailed Description

Enumerations

Methods

Static Methods

Method Documentation

Static Method Documentation

Enumeration Documentation

Modules