KRunner

View on LXR

Plasma
AbstractRunner

#include <KRunner/AbstractRunner>

Inheritance diagram for Plasma::AbstractRunner:

Public Types
typedef QList< AbstractRunner * >	List

enum	Priority { LowestPriority = 0, LowPriority, NormalPriority, HighPriority, HighestPriority }

enum	Speed { SlowSpeed, NormalSpeed }

Properties
QString	description

QIcon	icon

QString	id

bool	matchingSuspended

QString	name

Properties inherited from QObject
	objectName

Signals
void	matchingSuspended (bool suspended)

void	prepare ()

void	teardown ()

Public Member Functions
virtual QStringList	categories () const

virtual QIcon	categoryIcon (const QString &category) const

virtual void	createRunOptions (QWidget *widget)

RunnerSyntax *	defaultSyntax () const

QString	description () const

bool	hasRunOptions ()

QIcon	icon () const

QString	id () const

RunnerContext::Types	ignoredTypes () const

bool	isMatchingSuspended () const

virtual void	match (Plasma::RunnerContext &context)

KPluginInfo	metadata () const

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

Public Member Functions inherited from QObject
	QObject (QObject *parent)

bool	blockSignals (bool block)

const QObjectList &	children () const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const

bool	disconnect (const QObject receiver, const char method) const

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QByteArray >	dynamicPropertyNames () const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, QFlags< Qt::FindChildOption > options) const

QList< T >	findChildren (const QString &name, QFlags< Qt::FindChildOption > options) const

QList< T >	findChildren (const QRegExp &regExp, QFlags< Qt::FindChildOption > options) const

QList< T >	findChildren (const QRegularExpression &re, QFlags< Qt::FindChildOption > options) const

bool	inherits (const char *className) const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const

bool	isWindowType () const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

QString	objectName () const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const

QVariant	property (const char *name) const

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval, Qt::TimerType timerType)

QThread *	thread () const

Protected Member Functions
	AbstractRunner (QObject *parent=nullptr, const QString &path=QString())

	AbstractRunner (const KService::Ptr service, QObject *parent=nullptr)

	AbstractRunner (QObject *parent, const QVariantList &args)

QAction *	action (const QString &id) const

QHash< QString, QAction * >	actions () const

virtual QList< QAction * >	actionsForMatch (const Plasma::QueryMatch &match)

QAction *	addAction (const QString &id, const QIcon &icon, const QString &text)

void	addAction (const QString &id, QAction *action)

void	addSyntax (const RunnerSyntax &syntax)

void	clearActions ()

KConfigGroup	config () const

Q_INVOKABLE DataEngine *	dataEngine (const QString &name) const

virtual void	init ()

virtual QMimeData *	mimeDataForMatch (const Plasma::QueryMatch &match)

void	removeAction (const QString &id)

void	setDefaultSyntax (const RunnerSyntax &syntax)

void	setHasRunOptions (bool hasRunOptions)

void	setPriority (Priority newPriority)

void	setSpeed (Speed newSpeed)

void	setSyntaxes (const QList< RunnerSyntax > &syns)

void	suspendMatching (bool suspend)

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const

int	receivers (const char *signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Additional Inherited Members
Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

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

Definition at line 62 of file abstractrunner.h.

Member Typedef Documentation

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

An ordered list of runners.

Definition at line 87 of file abstractrunner.h.

Member Enumeration Documentation

enum Plasma::AbstractRunner::Priority

Specifies a priority for the runner.

Definition at line 78 of file abstractrunner.h.

enum Plasma::AbstractRunner::Speed

Specifies a nominal speed for the runner.

Definition at line 72 of file abstractrunner.h.

Member Function Documentation

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

protected

Returns the action associated with the id.

Definition at line 185 of file abstractrunner.cpp.

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

protected

Returns all registered actions.

Definition at line 190 of file abstractrunner.cpp.

QList< QAction * > Plasma::AbstractRunner::actionsForMatch ( const Plasma::QueryMatch & match )

protectedvirtual

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 160 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 167 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 174 of file abstractrunner.cpp.

void Plasma::AbstractRunner::addSyntax ( const RunnerSyntax & syntax )

protected

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

Definition at line 91 of file abstractrunner.cpp.

QStringList Plasma::AbstractRunner::categories ( ) const

virtual

Return a list of categories that this runner provides.

By default this list just contains the runners name. It is used by the runner manager to disable certain runners if all the categories they provide have been disabled.

This list of categories is also used to provide a better way to configure the runner instead of the typical on / off switch.

Definition at line 273 of file abstractrunner.cpp.

QIcon Plasma::AbstractRunner::categoryIcon ( const QString & category ) const

virtual

Returns the icon which accurately describes the category category.

This is meant to be used in a configuration dialog when showing all the categories.

By default this returns the icon of the AbstractRunner

Definition at line 278 of file abstractrunner.cpp.

void Plasma::AbstractRunner::clearActions ( )

protected

Clears the action registry.

The action pool deletes the actions.

Definition at line 195 of file abstractrunner.cpp.

KConfigGroup Plasma::AbstractRunner::config ( ) const

protected

Provides access to the runner's configuration object.

Definition at line 76 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 221 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 339 of file abstractrunner.cpp.

RunnerSyntax * Plasma::AbstractRunner::defaultSyntax ( ) const

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

Since: 4.4

Definition at line 112 of file abstractrunner.cpp.

QString Plasma::AbstractRunner::description ( ) const

Returns: the description of this Runner

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 211 of file abstractrunner.cpp.

QIcon Plasma::AbstractRunner::icon ( ) const

Returns: the icon for this Runner

QString Plasma::AbstractRunner::id ( ) const

Returns: an id string for the Runner

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 257 of file abstractrunner.cpp.

void Plasma::AbstractRunner::init ( )

protectedvirtual

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.

Definition at line 334 of file abstractrunner.cpp.

bool Plasma::AbstractRunner::isMatchingSuspended ( ) const

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

Definition at line 344 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. Asynchronous 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 283 of file abstractrunner.cpp.

void Plasma::AbstractRunner::matchingSuspended ( bool suspended )

signal

Emitted when the runner enters or exits match suspension.

See also: matchingSuspended

Since: 4.6

KPluginInfo Plasma::AbstractRunner::metadata ( ) const

Returns: the plugin info for this runner

Definition at line 323 of file abstractrunner.cpp.

QMimeData * Plasma::AbstractRunner::mimeDataForMatch ( const Plasma::QueryMatch & match )

protectedvirtual

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

Since: 4.5

Definition at line 201 of file abstractrunner.cpp.

QString Plasma::AbstractRunner::name ( ) const

Returns: the user visible engine name for the Runner

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, which may be invalid

Definition at line 328 of file abstractrunner.cpp.

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

Triggers a call to match.

This will call match() internally.

Parameters

context the search context used in executing this match.

Definition at line 117 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 247 of file abstractrunner.cpp.

void Plasma::AbstractRunner::reloadConfiguration ( )

virtual

Signal runner to reload its configuration.

Definition at line 87 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 179 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 267 of file abstractrunner.cpp.

void Plasma::AbstractRunner::setDefaultSyntax ( const RunnerSyntax & syntax )

protected

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

Definition at line 96 of file abstractrunner.cpp.

void Plasma::AbstractRunner::setHasRunOptions ( bool hasRunOptions )

protected

Sets whether or not the runner has options for matches.

Definition at line 216 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 262 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 252 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 D-Bus should call this within their constructors.

Definition at line 240 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 102 of file abstractrunner.cpp.

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

The nominal speed of the runner.

See also: setSpeed

Definition at line 226 of file abstractrunner.cpp.

void Plasma::AbstractRunner::suspendMatching ( bool suspend )

protected

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.

Definition at line 349 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 107 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:

KDE's Doxygen guidelines are available online.

Quick Links

Class Picker

About

Public Types

Properties

Signals

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation