AbstractRunner Class Reference

from PyKDE4.plasma import *

Inherits: QObject
Namespace: Plasma

Detailed Description

AbstractRunner plasma/abstractrunner.h <Plasma/AbstractRunner>

An abstract base class for Plasma Runner plugins.

Be aware that runners have to be thread-safe. This is due to the fact that each runner is executed in its own thread for each new term. Thus, a runner may be executed more than once at the same time. See match() for details. To let krunner expose a global shortcut for the single runner query mode, the runner must set the "X-Plasma-AdvertiseSingleRunnerMode" key to true in the .desktop file and set a default syntax. See setDefaultSyntax() for details.

Enumerations
Priority	{ LowestPriority, LowPriority, NormalPriority, HighPriority, HighestPriority }
Speed	{ SlowSpeed, NormalSpeed }
Signals
	matchingSuspended (bool suspended)
	prepare ()
	teardown ()
Methods
	__init__ (self, QObject parent=0, QString path=QString())
	__init__ (self, QObject parent, [QVariant] args)
	__init__ (self, KSharedPtr service, QObject parent=0)
QAction	action (self, QString id)
{QString:QAction}	actions (self)
[QAction]	actionsForMatch (self, Plasma.QueryMatch match)
QAction	addAction (self, QString id, QIcon icon, QString text)
	addAction (self, QString id, QAction action)
	addSyntax (self, Plasma.RunnerSyntax syntax)
	clearActions (self)
KConfigGroup	config (self)
	createRunOptions (self, QWidget widget)
Plasma.DataEngine	dataEngine (self, QString name)
Plasma.RunnerSyntax	defaultSyntax (self)
QString	description (self)
bool	hasRunOptions (self)
QIcon	icon (self)
QString	id (self)
Plasma.RunnerContext.Types	ignoredTypes (self)
	init (self)
bool	isMatchingSuspended (self)
	match (self, Plasma.RunnerContext context)
QMimeData	mimeDataForMatch (self, Plasma.QueryMatch match)
QString	name (self)
Plasma.Package	package (self)
	performMatch (self, Plasma.RunnerContext context)
Plasma.AbstractRunner.Priority	priority (self)
	reloadConfiguration (self)
	removeAction (self, QString id)
	run (self, Plasma.RunnerContext context, Plasma.QueryMatch match)
[KSharedPtr]	serviceQuery (self, QString serviceType, QString constraint=QString())
	setDefaultSyntax (self, Plasma.RunnerSyntax syntax)
	setHasRunOptions (self, bool hasRunOptions)
	setIgnoredTypes (self, Plasma.RunnerContext.Types types)
	setPriority (self, Plasma.AbstractRunner.Priority newPriority)
	setSpeed (self, Plasma.AbstractRunner.Speed newSpeed)
	setSyntaxes (self, [Plasma.RunnerSyntax] syns)
Plasma.AbstractRunner.Speed	speed (self)
	suspendMatching (self, bool suspend)
[Plasma.RunnerSyntax]	syntaxes (self)
Static Methods
QMutex	bigLock ()

Signal Documentation

matchingSuspended	(	bool	suspended
	)

Emitted when the runner enters or exits match suspension

See also:: matchingSuspended

Since:: 4.6

Signal syntax:: QObject.connect(source, SIGNAL("matchingSuspended(bool)"), target_slot)

prepare ( )

This signal is emitted when matching is about to commence, giving runners an opportunity to prepare themselves, e.g. loading data sets or preparing IPC or network connections. This method should be fast so as not to cause slow downs. Things that take longer or which should be loaded once and remain extant for the lifespan of the AbstractRunner should be done in init().

See also:: init()

Since:: 4.4

Signal syntax:: QObject.connect(source, SIGNAL("prepare()"), target_slot)

teardown ( )

This signal is emitted when a session of matches is complete, giving runners the opportunity to tear down anything set up as a result of the prepare() method.

Since:: 4.4

Signal syntax:: QObject.connect(source, SIGNAL("teardown()"), target_slot)

Method Documentation

__init__	(	self,
		QObject	parent=0,
		QString	path=QString()
	)

__init__	(	self,
		QObject	parent,
		[QVariant]	args
	)

__init__	(	self,
		KSharedPtr	service,
		QObject	parent=0
	)

QAction action	(	self,
		QString	id
	)

Returns the action associated with the id

{QString:QAction} actions ( self )

Returns all registered actions

[QAction] actionsForMatch	(	self,
		Plasma.QueryMatch	match
	)

A given match can have more than action that can be performed on it. For example, a song match returned by a music player runner can be queued, added to the playlist, or played.

Call this method to add actions that can be performed by the runner. Actions must first be added to the runner's action registry. Note: execution of correct action is left up to the runner.

QAction addAction	(	self,
		QString	id,
		QIcon	icon,
		QString	text
	)

Adds an action to the runner's action registry.

The QAction must be created within the GUI thread; do not create it within the match method of AbstractRunner.

Parameters:

	id	A unique identifier string
	action	The QAction to be stored

addAction	(	self,
		QString	id,
		QAction	action
	)

Adds an action to the runner's action registry.

The QAction must be created within the GUI thread; do not create it within the match method of AbstractRunner.

Parameters:

	id	A unique identifier string
	action	The QAction to be stored

addSyntax	(	self,
		Plasma.RunnerSyntax	syntax
	)

Adds a registered syntax that this runner understands. This is used to display to the user what this runner can understand and how it can be used.

Parameters:

syntax

the syntax to register

Since:: 4.3

clearActions ( self )

Clears the action registry. The action pool deletes the actions.

KConfigGroup config ( self )

Provides access to the runner's configuration object.

createRunOptions	(	self,
		QWidget	widget
	)

If hasRunOptions() returns true, this method may be called to get a widget displaying the options the user can interact with to modify the behaviour of what happens when a given match is selected.

Parameters:

widget

the parent of the options widgets.

Plasma.DataEngine dataEngine	(	self,
		QString	name
	)

Loads the given DataEngine

Tries to load the data engine given by name. Each engine is only loaded once, and that instance is re-used on all subsequent requests.

If the data engine was not found, an invalid data engine is returned (see DataEngine.isValid()).

Note that you should <em>not</em> delete the returned engine.

Parameters:

name

Name of the data engine to load

Returns:: pointer to the data engine if it was loaded, or an invalid data engine if the requested engine could not be loaded

Since:: 4.4

Plasma.RunnerSyntax defaultSyntax ( self )

Returns:: the default syntax for the runner or 0 if no default syntax has been defined

Since:: 4.4

QString description ( self )

Returns:: the description of this Runner

bool hasRunOptions ( self )

If the runner has options that the user can interact with to modify what happens when run or one of the actions created in match is called, the runner should return true

QIcon icon ( self )

Returns:: the icon for this Runner

QString id ( self )

Returns:: an id string for the Runner

Plasma.RunnerContext.Types ignoredTypes ( self )

Returns the OR'ed value of all the Information types (as defined in RunnerContext.Type) this runner is not interested in.

Returns:: OR'ed value of black listed types

init ( self )

Reimplement this slot to run any initialization routines on first load. By default, it calls reloadConfiguration(); for scripted Runners this method also sets up the ScriptEngine.

bool isMatchingSuspended ( self )

Returns:: true if the runner is currently busy with non-interuptable work, signaling that new threads should not be created for it at this time

Since:: 4.6

match	(	self,
		Plasma.RunnerContext	context
	)

This is the main query method. It should trigger creation of QueryMatch instances through RunnerContext.addMatch and RunnerContext.addMatches. It is called internally by performMatch().

If the runner can run precisely the requested term (RunnerContext.query()), it should create an exact match by setting the type to RunnerContext.ExactMatch. The first runner that creates a QueryMatch will be the default runner. Other runner's matches will be suggested in the interface. Non-exact matches should be offered via RunnerContext.PossibleMatch.

The match will be activated via run() if the user selects it.

Each runner is executed in its own thread. Whenever the user input changes this method is called again. Thus, it needs to be thread-safe. Also, all matches need to be reported once this method returns. Asyncroneous runners therefore need to make use of a local event loop to wait for all matches.

It is recommended to use local status data in async runners. The simplest way is to have a separate class doing all the work like so:

 void MyFancyAsyncRunner.match( RunnerContext& context )
 {
     QEventLoop loop;
     MyAsyncWorker worker( context );
     connect( &worker, SIGNAL(finished()),
              &loop, SLOT(quit()) );
     worker.work();
     loop.exec();
 }

Here MyAsyncWorker creates all the matches and calls RunnerContext.addMatch in some internal slot. It emits the finished() signal once done which will quit the loop and make the match() method return. The local status is kept entirely in MyAsyncWorker which makes match() trivially thread-safe.

If a particular match supports multiple actions, set up the corresponding actions in the actionsForMatch method. Do not call any of the action methods within this method!

Execution of the correct action should be handled in the run method. @caution This method needs to be thread-safe since KRunner will simply start a new thread for each new term.

Warning:: Returning from this method means to end execution of the runner.

@sa run(), RunnerContext.addMatch, RunnerContext.addMatches, QueryMatch

QMimeData mimeDataForMatch	(	self,
		Plasma.QueryMatch	match
	)

Reimplement this slot if you want your runner to support serialization and drag and drop

Since:: 4.5

QString name ( self )

Returns:: the user visible engine name for the Runner

Plasma.Package package ( self )

Accessor for the associated Package object if any.

Note that the returned pointer is only valid for the lifetime of the runner.

Returns:: the Package object, or 0 if none

performMatch	(	self,
		Plasma.RunnerContext	context
	)

Triggers a call to match. This will call match() internally.

Parameters:

context

the search context used in executing this match.

Plasma.AbstractRunner.Priority priority ( self )

The priority of the runner.

See also:: setPriority

reloadConfiguration ( self )

Signal runner to reload its configuration.

removeAction	(	self,
		QString	id
	)

Removes the action from the action registry. AbstractRunner deletes the action once removed.

Parameters:

The id of the action to be removed

run	(	self,
		Plasma.RunnerContext	context,
		Plasma.QueryMatch	match
	)

Called whenever an exact or possible match associated with this runner is triggered.

Parameters:

	context	The context in which the match is triggered, i.e. for which the match was created.
	match	The actual match to run/execute.

[KSharedPtr] serviceQuery	(	self,
		QString	serviceType,
		QString	constraint=QString()
	)

Deprecated:: A blocking method to do queries of installed Services which can provide a measure of safety for runners running their own threads. This should be used instead of calling KServiceTypeTrader.query(..) directly.

Parameters:

	serviceType	a service type like "Plasma/Applet" or "KFilePlugin"
	constraint	a constraint to limit the choices returned.

See also:: KServiceTypeTrader.query(const QString&, const QString&)

Returns:: a list of services that satisfy the query.

setDefaultSyntax	(	self,
		Plasma.RunnerSyntax	syntax
	)

Set syntax as the default syntax for the runner; the default syntax will be substituted to the empty query in single runner mode. This is also used to display to the user what this runner can understand and how it can be used. The default syntax is automatically added to the list of registered syntaxes, there is no need to add it using addSyntax. Note that there can be only one default syntax; if called more than once, the last call will determine the default syntax. A default syntax (even trivial) is required to advertise single runner mode

Parameters:

syntax

the syntax to register and to set as default

Since:: 4.4

setHasRunOptions	(	self,
		bool	hasRunOptions
	)

Sets whether or not the runner has options for matches

setIgnoredTypes	(	self,
		Plasma.RunnerContext.Types	types
	)

Sets the types this runner will ignore

Parameters:

types

OR'ed listed of ignored types

setPriority	(	self,
		Plasma.AbstractRunner.Priority	newPriority
	)

Sets the priority of the runner. Lower priority runners are executed only after higher priority runners.

setSpeed	(	self,
		Plasma.AbstractRunner.Speed	newSpeed
	)

Sets the nominal speed of the runner. Only slow runners need to call this within their constructor because the default speed is NormalSpeed. Runners that use DBUS should call this within their constructors.

setSyntaxes	(	self,
		[Plasma.RunnerSyntax]	syns
	)

Sets the list of syntaxes; passing in an empty list effectively clears the syntaxes.

Parameters:

the

syntaxes to register for this runner

Since:: 4.3

Plasma.AbstractRunner.Speed speed ( self )

The nominal speed of the runner.

See also:: setSpeed

suspendMatching	(	self,
		bool	suspend
	)

Sets whether or not the runner is available for match requests. Useful to prevent more thread spawning when the thread is in a busy state.

[Plasma.RunnerSyntax] syntaxes ( self )

Returns:: the syntaxes the runner has registered that it accepts and understands

Since:: 4.3

Static Method Documentation

QMutex bigLock ( )

Access to a shared lock that all runners (and code that manages/interacts with them) can share to protect access to non-thread-safe shared code or data. Access of KSycoca records, for instance, is one place this lock should be used.

Common usage:

{ QMutexLocker lock(bigLock()); .. do something that isn't thread safe .. }

Enumeration Documentation

Priority

Specifies a priority for the runner

Enumerator:

LowestPriority = 0
LowPriority
NormalPriority
HighPriority
HighestPriority

Speed

Specifies a nominal speed for the runner

Enumerator:

SlowSpeed
NormalSpeed

AbstractRunner Class Reference

Detailed Description

Enumerations

Signals

Methods

Static Methods

Signal Documentation

Method Documentation

Static Method Documentation

Enumeration Documentation

Modules