KRunner 5.109.0
Public Types | Signals | Public Member Functions | List of all members
Plasma::RunnerContext

The RunnerContext class provides information related to a search, including the search term, metadata on the search term and collected matches. More...

#include <KRunner/RunnerContext>

Public Types

enum  Type {
  None = 0 , UnknownType = 1 , Directory = 2 , File = 4 ,
  NetworkLocation = 8 , Executable = 16 , ShellCommand = 32 , Help = 64 ,
  FileSystem = Directory | File | Executable | ShellCommand
}
 
typedef QFlags< Type > Types
 

Signals

void matchesChanged ()
 

Public Member Functions

 RunnerContext (QObject *parent=nullptr)
 
 RunnerContext (RunnerContext &other, QObject *parent=nullptr)
 Copy constructor.
 
bool addMatch (const QueryMatch &match)
 Appends a match to the existing list of matches.
 
bool addMatches (const QList< QueryMatch > &matches)
 Appends lists of matches to the list of matches.
 
void ignoreCurrentMatchForHistory () const
 Set this to true in the AbstractRunner::run method to prevent the entry from being saved to the history.
 
bool isValid () const
 
QList< QueryMatchmatches () const
 Retrieves all available matches for the current search term.
 
RunnerContextoperator= (const RunnerContext &other)
 Assignment operator.
 
QString query () const
 
void requestQueryStringUpdate (const QString &text, int cursorPosition) const
 Request that KRunner updates the query string and stasy open, even after running a match.
 
void reset ()
 Resets the search term for this object.
 
void restore (const KConfigGroup &config)
 Sets the launch counts for the associated match ids.
 
void run (const QueryMatch &match)
 Run a match using the information from this context.
 
void save (KConfigGroup &config)
 
void setQuery (const QString &term)
 Sets the query term for this object and attempts to determine the type of the search.
 
void setSingleRunnerQueryMode (bool enabled)
 Sets single runner query mode.
 
bool singleRunnerQueryMode () const
 

Detailed Description

The RunnerContext class provides information related to a search, including the search term, metadata on the search term and collected matches.

Constructor & Destructor Documentation

◆ RunnerContext()

Plasma::RunnerContext::RunnerContext ( RunnerContext other,
QObject *  parent = nullptr 
)

Copy constructor.

Member Function Documentation

◆ addMatch()

bool Plasma::RunnerContext::addMatch ( const QueryMatch match)

Appends a match to the existing list of matches.

If you are going to be adding multiple matches, use

See also
addMatches instead.
Parameters
matchthe match to add
Returns
true if the match was added, false otherwise.

◆ addMatches()

bool Plasma::RunnerContext::addMatches ( const QList< QueryMatch > &  matches)

Appends lists of matches to the list of matches.

Parameters
matchesthe matches to add
Returns
true if matches were added, false if matches were e.g. outdated

◆ ignoreCurrentMatchForHistory()

void Plasma::RunnerContext::ignoreCurrentMatchForHistory ( ) const

Set this to true in the AbstractRunner::run method to prevent the entry from being saved to the history.

Since
5.90

◆ isValid()

bool Plasma::RunnerContext::isValid ( ) const
Returns
true if this context is no longer valid and therefore matching using it should abort. Most useful as an optimization technique inside of AbstractRunner subclasses in the match method, e.g.:

while (.. a possibly large iteration) { if (!context.isValid()) { return; }

... some processing ... }

While not required to be used within runners, it provides a nice way to avoid unnecessary processing in runners that may run for an extended period (as measured in 10s of ms) and therefore improve the user experience.

Since
4.2.3

◆ matches()

QList< QueryMatch > Plasma::RunnerContext::matches ( ) const

Retrieves all available matches for the current search term.

Returns
a list of matches

◆ operator=()

RunnerContext & Plasma::RunnerContext::operator= ( const RunnerContext other)

Assignment operator.

Since
4.4

◆ query()

QString Plasma::RunnerContext::query ( ) const
Returns
the current search query term.

◆ requestQueryStringUpdate()

void Plasma::RunnerContext::requestQueryStringUpdate ( const QString &  text,
int  cursorPosition 
) const

Request that KRunner updates the query string and stasy open, even after running a match.

This method is const so it can be called in a const context.

Parameters
textText that will be displayed in the search field
cursorPositionPosition of the cursor, if this is different than the length of the text, the characters between the position and text will be selected
Since
5.90

◆ reset()

void Plasma::RunnerContext::reset ( )

Resets the search term for this object.

This removes all current matches in the process and turns off single runner query mode.

◆ restore()

void Plasma::RunnerContext::restore ( const KConfigGroup &  config)

Sets the launch counts for the associated match ids.

If a runner adds a match to this context, the context will check if the match id has been launched before and increase the matches relevance correspondingly. In this manner, any front end can implement adaptive search by sorting items according to relevance.

Parameters
configthe config group where launch data was stored

◆ run()

void Plasma::RunnerContext::run ( const QueryMatch match)

Run a match using the information from this context.

The context will also keep track of the number of times the match was launched to sort future matches according to user habits

Parameters
matchthe match to run

◆ save()

void Plasma::RunnerContext::save ( KConfigGroup &  config)
Parameters
configthe config group where launch data should be stored

◆ setQuery()

void Plasma::RunnerContext::setQuery ( const QString &  term)

Sets the query term for this object and attempts to determine the type of the search.

◆ setSingleRunnerQueryMode()

void Plasma::RunnerContext::setSingleRunnerQueryMode ( bool  enabled)

Sets single runner query mode.

Note that a call to reset() will turn off single runner query mode.

Note
This method is considered internal. To set the single runner mode you should pass in a runnerId to RunnerManager::launchQuery
See also
reset()

◆ singleRunnerQueryMode()

bool Plasma::RunnerContext::singleRunnerQueryMode ( ) const
Returns
true if the current query is a single runner query
Since
4.4