KRunner::AbstractRunner Class

Member Function Documentation

[explicit protected, since 5.72] AbstractRunner::AbstractRunner(QObject *parent, const KPluginMetaData &pluginMetaData)

Constructor for a KRunner plugin

@note You should connect here to the prepare/teardown signals. However, avoid doing heavy initialization here in favor of doing it in AbstractRunner::init

parent parent object for this runner

pluginMetaData metadata that was embedded in the runner

args for compatibility with KPluginFactory, since 6.0 this can be omitted

This function was introduced in 5.72.

[protected] void AbstractRunner::addSyntax(const KRunner::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.

syntax the syntax to register

[protected, since 5.106] void AbstractRunner::addSyntax(const QString &exampleQuery, const QString &description)

Utility overload for creating a syntax based on the given parameters

This function was introduced in 5.106.

See also RunnerSyntax.

[protected] KConfigGroup AbstractRunner::config() const

Provides access to the runner's configuration object. This config is saved in the "krunnerrc" file in the [Runners][<pluginId>] config group Settings should be written in a KDE config module. See https://develop.kde.org/docs/plasma/krunner/#runner-configuration

QString AbstractRunner::id() const

Returns an id from the runner's metadata

[virtual protected] void AbstractRunner::init()

Reimplement this to run any initialization routines on first load. Because it is executed in the runner's thread, it will not block the UI and is thus preferred. By default, it calls reloadConfiguration();

Until the runner is initialized, it will not be queried by the RunnerManager.

bool AbstractRunner::isMatchingSuspended() const

Returns true if the runner is currently busy with non-interuptable work, signaling that the RunnerManager may not query it or read it's config properties

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

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.

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, &MyAsyncWorker::finished, &loop, &MyAsyncWorker::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.

Execution of the correct action should be handled in the run method.

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

[since 5.75] QRegularExpression AbstractRunner::matchRegex() const

If this regex is set with a non empty pattern it must match the query in order for 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.

Returns matchRegex property

This function was introduced in 5.75.

See also setMatchRegex() and hasMatchRegex.

KPluginMetaData AbstractRunner::metadata() const

Returns the plugin metadata for this runner that was passed in the constructor

[virtual protected] QMimeData *AbstractRunner::mimeDataForMatch(const KRunner::QueryMatch &match)

Reimplement this if you want your runner to support serialization and drag and drop. By default, this sets the QMimeData urls to the ones specified in QueryMatch::urls

[since 5.75] int 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, match method is not called. This can be set using the X-Plasma-Runner-Min-Letter-Count property or the setMinLetterCount method. The default value is 0.

This function was introduced in 5.75.

See also setMinLetterCount and match.

QString AbstractRunner::name() const

Returns the translated name from the runner's metadata

[signal] void AbstractRunner::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. Things that should be loaded once and remain extant for the lifespan of the AbstractRunner should be done in init().

See also init().

[virtual] void AbstractRunner::reloadConfiguration()

Reloads the runner's configuration. This is called when it's KCM in the PluginSelector is applied.

This function may be used to set for example using setMatchRegex, setMinLetterCount or setTriggerWords.

Also, syntaxes should be updated when this method is called.

While reloading the config, matching is suspended.

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

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.

[since 5.75] void AbstractRunner::setMatchRegex(const QRegularExpression &regex)

Set the matchRegex property

This function was introduced in 5.75.

See also matchRegex().

[since 5.75] void AbstractRunner::setMinLetterCount(int count)

Set the minLetterCount property

count

This function was introduced in 5.75.

See also minLetterCount().

[protected] void AbstractRunner::setSyntaxes(const QList<KRunner::RunnerSyntax> &syntaxes)

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

the syntaxes to register for this runner

See also syntaxes().

[since 5.75] void 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.

This function was introduced in 5.75.

See also matchRegex.

[protected] void AbstractRunner::suspendMatching(bool suspend)

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

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

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

See also setSyntaxes().

[signal] void AbstractRunner::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.