KRunner 5.109.0
|
An abstract base class for Plasma Runner plugins. More...
#include <KRunner/AbstractRunner>
Public Types | |
typedef QList< AbstractRunner * > | List |
An ordered list of runners. | |
enum | Priority { LowestPriority = 0 , LowPriority , NormalPriority , HighPriority , HighestPriority } |
Specifies a priority for the runner. More... | |
enum | Speed { SlowSpeed , NormalSpeed } |
Specifies a nominal speed for the runner. More... | |
Properties | |
QString | description |
QIcon | icon |
QString | id |
bool | matchingSuspended |
QRegularExpression | matchRegex |
int | minLetterCount |
QString | name |
Signals | |
void | matchingSuspended (bool suspended) |
Emitted when the runner enters or exits match suspension. | |
void | prepare () |
This signal is emitted when matching is about to commence, giving runners an opportunity to prepare themselves, e.g. | |
void | 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. | |
Public Member Functions | |
virtual QStringList | categories () const |
Return a list of categories that this runner provides. | |
virtual QIcon | categoryIcon (const QString &category) const |
Returns the icon which accurately describes the category category . | |
virtual void | createRunOptions (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. | |
RunnerSyntax * | defaultSyntax () const |
QString | description () const |
bool | hasMatchRegex () const |
If the runner has a valid regex and non empty regex. | |
bool | 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. | |
QIcon | icon () const |
QString | id () const |
RunnerContext::Types | ignoredTypes () const |
Returns the OR'ed value of all the Information types (as defined in RunnerContext::Type) this runner is not interested in. | |
bool | isMatchingSuspended () const |
virtual void | match (Plasma::RunnerContext &context) |
This is the main query method. | |
QRegularExpression | matchRegex () const |
If this regex is set with a not empty pattern it must match the query in order for the performMatch/match being called. | |
KPluginInfo | metadata () const |
KPluginMetaData | metadata (RunnerReturnPluginMetaDataConstant) const |
int | minLetterCount () const |
This is the minimum letter count for the query. | |
QString | name () const |
Package | package () const |
Accessor for the associated Package object if any. | |
void | performMatch (Plasma::RunnerContext &context) |
Triggers a call to match. | |
Priority | priority () const |
The priority of the runner. | |
virtual void | reloadConfiguration () |
Signal runner to reload its configuration. | |
virtual void | run (const Plasma::RunnerContext &context, const Plasma::QueryMatch &match) |
Called whenever an exact or possible match associated with this runner is triggered. | |
void | setIgnoredTypes (RunnerContext::Types types) |
Sets the types this runner will ignore. | |
void | setMatchRegex (const QRegularExpression ®ex) |
Set the matchRegex property. | |
void | setMinLetterCount (int count) |
Set the minLetterCount property. | |
void | setTriggerWords (const QStringList &triggerWords) |
Constructs internally a regex which requires the query to start with the trigger words. | |
Speed | speed () const |
The nominal speed of the runner. | |
QList< RunnerSyntax > | syntaxes () const |
Protected Member Functions | |
AbstractRunner (const KPluginMetaData &pluginMetaData, QObject *parent=nullptr) | |
AbstractRunner (const KService::Ptr service, QObject *parent=nullptr) | |
AbstractRunner (QObject *parent, const KPluginMetaData &pluginMetaData, const QVariantList &args) | |
Constructor for a KRunner plugin. | |
AbstractRunner (QObject *parent, const QVariantList &args) | |
AbstractRunner (QObject *parent=nullptr, const QString &path=QString()) | |
QAction * | action (const QString &id) const |
Returns the action associated with the id. | |
QHash< QString, QAction * > | actions () const |
Returns all registered actions. | |
virtual QList< QAction * > | actionsForMatch (const Plasma::QueryMatch &match) |
A given match can have more than action that can be performed on it. | |
QAction * | addAction (const QString &id, const QIcon &icon, const QString &text) |
Creates and then adds an action to the action registry. | |
void | addAction (const QString &id, QAction *action) |
Adds an action to the runner's action registry. | |
void | addSyntax (const QString &exampleQuery, const QString &description) |
Utility overload for creating a syntax based on the given parameters. | |
void | addSyntax (const QStringList &exampleQueries, const QString &description) |
Utility overload for creating a syntax based on the given parameters. | |
void | addSyntax (const RunnerSyntax &syntax) |
Adds a registered syntax that this runner understands. | |
void | clearActions () |
Clears the action registry. | |
KConfigGroup | config () const |
Provides access to the runner's configuration object. | |
DataEngine * | dataEngine (const QString &name) const |
Loads the given DataEngine. | |
virtual void | init () |
Reimplement this slot to run any initialization routines on first load. | |
virtual QMimeData * | mimeDataForMatch (const Plasma::QueryMatch &match) |
Reimplement this slot if you want your runner to support serialization and drag and drop. | |
void | removeAction (const QString &id) |
Removes the action from the action registry. | |
void | setDefaultSyntax (const 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. | |
void | setHasRunOptions (bool hasRunOptions) |
Sets whether or not the runner has options for matches. | |
void | setPriority (Priority newPriority) |
Sets the priority of the runner. | |
void | setSpeed (Speed newSpeed) |
Sets the nominal speed of the runner. | |
void | setSyntaxes (const QList< RunnerSyntax > &syns) |
Sets the list of syntaxes; passing in an empty list effectively clears the syntaxes. | |
void | suspendMatching (bool suspend) |
Sets whether or not the runner is available for match requests. | |
Related Symbols | |
(Note that these are not member symbols.) | |
#define | K_EXPORT_PLASMA_RUNNER(libname, classname) |
Registers a runner plugin. | |
#define | K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) K_PLUGIN_FACTORY_WITH_JSON(classname ## Factory, jsonFile, registerPlugin<classname>();) |
Registers a runner plugin with JSON metadata. | |
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.
typedef QList<AbstractRunner *> Plasma::AbstractRunner::List |
An ordered list of runners.
Specifies a priority for the runner.
Specifies a nominal speed for the runner.
|
protected |
Constructor for a KRunner plugin.
parent | parent object for this runner |
pluginMetaData | metadata that was embedded in the runner |
args | for compatibility with KPluginFactory, should be passed on to the parent constructor |
|
explicitprotected |
|
explicitprotected |
|
protected |
|
protected |
Returns the action associated with the id.
|
protected |
Returns all registered actions.
|
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.
|
protected |
Creates and then adds an action to the action registry.
AbstractRunner assumes ownership of the created action.
id | A unique identifier string |
icon | The icon to display |
text | The text to display |
|
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.
id | A unique identifier string |
action | The QAction to be stored |
|
inlineprotected |
Utility overload for creating a syntax based on the given parameters.
|
inlineprotected |
Utility overload for creating a syntax based on the given parameters.
|
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.
syntax | the syntax to register |
|
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.
|
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
|
protected |
Clears the action registry.
The action pool deletes the actions.
|
protected |
Provides access to the runner's configuration object.
|
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.
widget | the parent of the options widgets. |
|
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.
name | Name of the data engine to load |
RunnerSyntax * Plasma::AbstractRunner::defaultSyntax | ( | ) | const |
nullptr
if no default syntax has been definedQString Plasma::AbstractRunner::description | ( | ) | const |
bool Plasma::AbstractRunner::hasMatchRegex | ( | ) | const |
If the runner has a valid regex and non empty regex.
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.
QIcon Plasma::AbstractRunner::icon | ( | ) | const |
QString Plasma::AbstractRunner::id | ( | ) | const |
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.
|
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.
bool Plasma::AbstractRunner::isMatchingSuspended | ( | ) | const |
|
virtual |
This is the main query method.
It should trigger creation of QueryMatch instances through RunnerContext::addMatch and RunnerContext::addMatches.
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:
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.
|
signal |
Emitted when the runner enters or exits match suspension.
QRegularExpression Plasma::AbstractRunner::matchRegex | ( | ) | const |
If this regex is set with a not empty pattern it must match the query in order for the performMatch/match being called.
Just like the minLetterCount property this check is ignored when the runner is in the singleRunnerMode. In case both the regex and the letter count is set the letter count is checked first.
KPluginInfo Plasma::AbstractRunner::metadata | ( | ) | const |
KPluginMetaData Plasma::AbstractRunner::metadata | ( | RunnerReturnPluginMetaDataConstant | ) | const |
Overload to get non-deprecated metadata format. Use like this:
If you disable the deprecated version using the KRUNNER_DISABLE_DEPRECATED_BEFORE_AND_AT macro, then you can omit Plasma::RunnerReturnPluginMetaDataConstant and use it like this:
|
protectedvirtual |
Reimplement this slot if you want your runner to support serialization and drag and drop.
int Plasma::AbstractRunner::minLetterCount | ( | ) | const |
This is the minimum letter count for the query.
If the query is shorter than this value and KRunner is not in the singleRunnerMode, the performMatch and consequently match method is not called. This can be set using the X-Plasma-Runner-Min-Letter-Count property or the setMinLetterCount method.
QString Plasma::AbstractRunner::name | ( | ) | 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.
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. |
|
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().
Priority Plasma::AbstractRunner::priority | ( | ) | const |
The priority of the runner.
|
virtual |
Signal runner to reload its configuration.
|
protected |
Removes the action from the action registry.
AbstractRunner deletes the action once removed.
id | The id of the action to be removed |
|
virtual |
Called whenever an exact or possible match associated with this runner is triggered.
context | The context in which the match is triggered, i.e. for which the match was created. |
match | The actual match to run/execute. |
|
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
syntax | the syntax to register and to set as default |
|
protected |
Sets whether or not the runner has options for matches.
void Plasma::AbstractRunner::setIgnoredTypes | ( | RunnerContext::Types | types | ) |
Sets the types this runner will ignore.
If the value from RunnerContext::type() is contained in the ignored types the match() method won't be called. This way there is no unnecessary thread spawned. The same RunnerContext from which the type gets read is later passed into the match(Plasma::RunnerContext &context) method call.
types | OR'ed listed of ignored types |
The minLetterCount and matchRegex can be set with a similar version check or added to the desktop file. If an older KRunner version loads such a desktop file these unknown properties are just ignored.
void Plasma::AbstractRunner::setMatchRegex | ( | const QRegularExpression & | regex | ) |
Set the matchRegex property.
regex |
void Plasma::AbstractRunner::setMinLetterCount | ( | int | count | ) |
Set the minLetterCount property.
count |
|
protected |
Sets the priority of the runner.
Lower priority runners are executed only after higher priority runners.
|
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.
|
protected |
Sets the list of syntaxes; passing in an empty list effectively clears the syntaxes.
the | syntaxes to register for this runner |
void Plasma::AbstractRunner::setTriggerWords | ( | const QStringList & | triggerWords | ) |
Constructs internally a regex which requires the query to start with the trigger words.
Multiple words are concatenated with or, for instance: "^word1|word2|word3". The trigger words are internally escaped. Also the minLetterCount is set to the shortest word in the list.
|
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.
QList< RunnerSyntax > Plasma::AbstractRunner::syntaxes | ( | ) | const |
|
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.
|
related |
Registers a runner plugin.
|
related |
Registers a runner plugin with JSON metadata.
classname | name of the AbstractRunner derived class. |
jsonFile | name of the JSON file to be compiled into the plugin as metadata |