Plasma::AbstractRunner Class Reference

An abstract base class for Plasma Runner plugins. More...

#include <Plasma/AbstractRunner>

Inheritance diagram for Plasma::AbstractRunner:

Public Types
typedef QList< AbstractRunner * >	List
enum	Priority { LowestPriority = 0, LowPriority, NormalPriority, HighPriority, HighestPriority }
enum	Speed { SlowSpeed, NormalSpeed }
Signals
void	prepare ()
void	teardown ()
Public Member Functions
virtual	~AbstractRunner ()
virtual void	createRunOptions (QWidget *widget)
QString	description () const
bool	hasRunOptions ()
QIcon	icon () const
QString	id () const
RunnerContext::Types	ignoredTypes () const
virtual void	match (Plasma::RunnerContext &context)
QString	name () const
const Package *	package () const
void	performMatch (Plasma::RunnerContext &context)
Priority	priority () const
virtual void	reloadConfiguration ()
virtual void	run (const Plasma::RunnerContext &context, const Plasma::QueryMatch &match)
void	setIgnoredTypes (RunnerContext::Types types)
Speed	speed () const
QList< RunnerSyntax >	syntaxes () const
Static Public Member Functions
static QMutex *	bigLock ()
Protected Slots
void	init ()
Protected Member Functions
	AbstractRunner (QObject *parent, const QVariantList &args)
	AbstractRunner (QObject *parent=0, const QString &serviceId=QString())
QAction *	action (const QString &id) const
QHash< QString, QAction * >	actions () const
virtual QList< QAction * >	actionsForMatch (const Plasma::QueryMatch &match)
void	addAction (const QString &id, QAction *action)
QAction *	addAction (const QString &id, const QIcon &icon, const QString &text)
void	addSyntax (const RunnerSyntax &syntax)
void	clearActions ()
KConfigGroup	config () const
Q_INVOKABLE DataEngine *	dataEngine (const QString &name) const
void	removeAction (const QString &id)
KService::List	serviceQuery (const QString &serviceType, const QString &constraint=QString()) const
void	setHasRunOptions (bool hasRunOptions)
void	setPriority (Priority newPriority)
void	setSpeed (Speed newSpeed)
void	setSyntaxes (const QList< RunnerSyntax > &syns)

Detailed Description

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.

Definition at line 58 of file abstractrunner.h.

Member Typedef Documentation

typedef QList<AbstractRunner*> Plasma::AbstractRunner::List

An ordered list of runners.

Definition at line 79 of file abstractrunner.h.

Member Enumeration Documentation

enum Plasma::AbstractRunner::Priority

Specifies a priority for the runner.

Enumerator:

LowestPriority
LowPriority
NormalPriority
HighPriority
HighestPriority

Definition at line 70 of file abstractrunner.h.

enum Plasma::AbstractRunner::Speed

Specifies a nominal speed for the runner.

Enumerator:

SlowSpeed
NormalSpeed

Definition at line 64 of file abstractrunner.h.

Constructor & Destructor Documentation

Plasma::AbstractRunner::~AbstractRunner ( ) [virtual]

Definition at line 59 of file abstractrunner.cpp.

Plasma::AbstractRunner::AbstractRunner	(	QObject *	parent = `0`,
		const QString &	serviceId = `QString()`
	)			`[explicit, protected]`

Constructs a Runner object.

Since AbstractRunner has pure virtuals, this constructor can not be called directly. Rather a subclass must be created

Definition at line 47 of file abstractrunner.cpp.

Plasma::AbstractRunner::AbstractRunner	(	QObject *	parent,
		const QVariantList &	args
	)			`[protected]`

Definition at line 53 of file abstractrunner.cpp.

Member Function Documentation

QAction * Plasma::AbstractRunner::action ( const QString & id ) const [protected]

Returns the action associated with the id.

Definition at line 160 of file abstractrunner.cpp.

QHash< QString, QAction * > Plasma::AbstractRunner::actions ( ) const [protected]

Returns all registered actions.

Definition at line 165 of file abstractrunner.cpp.

QList< QAction * > Plasma::AbstractRunner::actionsForMatch ( const Plasma::QueryMatch & match ) [protected, virtual]

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.

Definition at line 132 of file abstractrunner.cpp.

void Plasma::AbstractRunner::addAction	(	const QString &	id,
		QAction *	action
	)			`[protected]`

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

Definition at line 149 of file abstractrunner.cpp.

QAction * Plasma::AbstractRunner::addAction	(	const QString &	id,
		const QIcon &	icon,
		const QString &	text
	)			`[protected]`

Creates and then adds an action to the action registry.

AbstractRunner assumes ownership of the created action.

Parameters:

	id	A unique identifier string
	icon	The icon to display
	text	The text to display

Returns:: the created QAction

Definition at line 142 of file abstractrunner.cpp.

void Plasma::AbstractRunner::addSyntax ( const RunnerSyntax & syntax ) [protected]

Adds a registed 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

Definition at line 82 of file abstractrunner.cpp.

QMutex * Plasma::AbstractRunner::bigLock ( ) [static]

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 .. }

Definition at line 239 of file abstractrunner.cpp.

void Plasma::AbstractRunner::clearActions ( ) [protected]

Clears the action registry.

The action pool deletes the actions.

Definition at line 170 of file abstractrunner.cpp.

KConfigGroup Plasma::AbstractRunner::config ( ) const [protected]

Provides access to the runner's configuration object.

Definition at line 64 of file abstractrunner.cpp.

void Plasma::AbstractRunner::createRunOptions ( QWidget * widget ) [virtual]

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.

Definition at line 186 of file abstractrunner.cpp.

DataEngine * Plasma::AbstractRunner::dataEngine ( const QString & name ) const [protected]

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 not 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

Definition at line 306 of file abstractrunner.cpp.

QString Plasma::AbstractRunner::description ( ) const

Returns:: the description of this Runner

Definition at line 284 of file abstractrunner.cpp.

bool Plasma::AbstractRunner::hasRunOptions ( )

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.

Definition at line 176 of file abstractrunner.cpp.

QIcon Plasma::AbstractRunner::icon ( ) const

Returns:: the icon for this Runner

Definition at line 267 of file abstractrunner.cpp.

QString Plasma::AbstractRunner::id ( ) const

Returns:: an id string for the Runner

Definition at line 276 of file abstractrunner.cpp.

RunnerContext::Types Plasma::AbstractRunner::ignoredTypes ( ) const

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

Definition at line 224 of file abstractrunner.cpp.

void Plasma::AbstractRunner::init ( ) [protected, slot]

Definition at line 298 of file abstractrunner.cpp.

void Plasma::AbstractRunner::match ( Plasma::RunnerContext & context ) [virtual]

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. 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.

See also:: run(), RunnerContext::addMatch, RunnerContext::addMatches, QueryMatch

Definition at line 251 of file abstractrunner.cpp.

QString Plasma::AbstractRunner::name ( ) const

Returns:: the user visible engine name for the Runner

Definition at line 258 of file abstractrunner.cpp.

const Package * Plasma::AbstractRunner::package ( ) const

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

Definition at line 293 of file abstractrunner.cpp.

void Plasma::AbstractRunner::performMatch ( Plasma::RunnerContext & context )

Triggers a call to match.

This will call match() internally.

context the search context used in executing this match.

Definition at line 97 of file abstractrunner.cpp.

void Plasma::AbstractRunner::prepare ( ) [signal]

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

AbstractRunner::Priority Plasma::AbstractRunner::priority ( ) const

The priority of the runner.

See also:: setPriority

Definition at line 214 of file abstractrunner.cpp.

void Plasma::AbstractRunner::reloadConfiguration ( ) [virtual]

Signal runner to reload its configuration.

Definition at line 75 of file abstractrunner.cpp.

void Plasma::AbstractRunner::removeAction ( const QString & id ) [protected]

Removes the action from the action registry.

AbstractRunner deletes the action once removed.

Parameters:

id

The id of the action to be removed

Definition at line 154 of file abstractrunner.cpp.

void Plasma::AbstractRunner::run	(	const Plasma::RunnerContext &	context,
		const Plasma::QueryMatch &	match
	)			`[virtual]`

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.

Definition at line 244 of file abstractrunner.cpp.

KService::List Plasma::AbstractRunner::serviceQuery	(	const QString &	serviceType,
		const QString &	constraint = `QString()`
	)			const `[protected]`

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.

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.

Definition at line 234 of file abstractrunner.cpp.

void Plasma::AbstractRunner::setHasRunOptions ( bool hasRunOptions ) [protected]

Sets whether or not the runner has options for matches.

Definition at line 181 of file abstractrunner.cpp.

void Plasma::AbstractRunner::setIgnoredTypes ( RunnerContext::Types types )

Sets the types this runner will ignore.

Parameters:

types

OR'ed listed of ignored types

Definition at line 229 of file abstractrunner.cpp.

void Plasma::AbstractRunner::setPriority ( Priority newPriority ) [protected]

Sets the priority of the runner.

Lower priority runners are executed only after higher priority runners.

Definition at line 219 of file abstractrunner.cpp.

void Plasma::AbstractRunner::setSpeed ( Speed newSpeed ) [protected]

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.

Definition at line 207 of file abstractrunner.cpp.

void Plasma::AbstractRunner::setSyntaxes ( const QList< RunnerSyntax > & syns ) [protected]

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

Definition at line 87 of file abstractrunner.cpp.

AbstractRunner::Speed Plasma::AbstractRunner::speed ( ) const

The nominal speed of the runner.

See also:: setSpeed

Definition at line 193 of file abstractrunner.cpp.

QList< RunnerSyntax > Plasma::AbstractRunner::syntaxes ( ) const

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

Since:: 4.3

Definition at line 92 of file abstractrunner.cpp.

void Plasma::AbstractRunner::teardown ( ) [signal]

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

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

Plasma

Plasma::AbstractRunner Class Reference

Public Types

Signals

Public Member Functions

Static Public Member Functions

Protected Slots

Protected Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Plasma

kdelibs