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

A match returned by an AbstractRunner in response to a given RunnerContext. More...

#include <KRunner/QueryMatch>

Public Types

enum  Type {
  NoMatch = 0 , CompletionMatch = 10 , PossibleMatch = 30 , HelperMatch = 70 ,
  ExactMatch = 100
}
 The type of match. More...
 

Public Member Functions

 QueryMatch (AbstractRunner *runner=nullptr)
 Constructs a PossibleMatch associated with a given RunnerContext and runner.
 
 QueryMatch (const QueryMatch &other)
 Copy constructor.
 
QList< QAction * > actions () const
 List of actions set for this match.
 
void addAction (QAction *actions)
 Adds an action to this match.
 
QVariant data () const
 
QIcon icon () const
 
QString iconName () const
 
QString id () const
 
bool isEnabled () const
 
bool isMultiLine () const
 If the text should be displayed as a multiLine string If no explicit value is set set using setMultiline it will default to false.
 
bool isValid () const
 
QString matchCategory () const
 Extra information about the match which can be used to categorize the type.
 
bool operator!= (const QueryMatch &other) const
 
bool operator< (const QueryMatch &other) const
 
QueryMatchoperator= (const QueryMatch &other)
 
bool operator== (const QueryMatch &other) const
 
qreal relevance () const
 The relevance of this action to the search.
 
void run (const RunnerContext &context) const
 Requests this match to activae using the given context.
 
AbstractRunnerrunner () const
 
QAction * selectedAction () const
 The current action.
 
void setActions (const QList< QAction * > &actions)
 Set the actions for this match.
 
void setData (const QVariant &data)
 Sets data to be used internally by the associated AbstractRunner.
 
void setEnabled (bool enable)
 Sets whether or not this match can be activited.
 
void setIcon (const QIcon &icon)
 Sets the icon associated with this match.
 
void setIconName (const QString &iconName)
 Sets the icon name associated with this match.
 
void setId (const QString &id)
 Sets the id for this match; useful if the id does not match data().toString().
 
void setMatchCategory (const QString &category)
 Sets information about the type of the match which can be used to categorize the match.
 
void setMultiLine (bool multiLine)
 Set if the text should be displayed as a multiLine string.
 
void setRelevance (qreal relevance)
 Sets the relevance of this action for the search it was created for.
 
void setSelectedAction (QAction *action)
 Sets the selected action.
 
void setSubtext (const QString &text)
 Sets the descriptive text for this match; can be longer than the main title text.
 
void setText (const QString &text)
 Sets the main title text for this match; should be short enough to fit nicely on one line in a user interface.
 
void setType (Type type)
 Sets the type of match this action represents.
 
void setUrls (const QList< QUrl > &urls)
 Sets the urls, if any, associated with this match.
 
QString subtext () const
 
QString text () const
 
Type type () const
 The type of action this is.
 
QList< QUrl > urls () const
 

Detailed Description

A match returned by an AbstractRunner in response to a given RunnerContext.

Member Enumeration Documentation

◆ Type

The type of match.

Value is important here as it is used for sorting

Enumerator
NoMatch 

Null match.

CompletionMatch 

Possible completion for the data of the query.

PossibleMatch 

Something that may match the query.

HelperMatch 

A match that represents an action not directly related to activating the given search term, such as a search in an external tool or a command learning trigger.

Helper matches tend to be generic to the query and should not be autoactivated just because the user hits "Enter" while typing. They must be explicitly selected to be activated, but unlike InformationalMatch cause an action to be triggered.

ExactMatch 

An exact match to the query.

Constructor & Destructor Documentation

◆ QueryMatch() [1/2]

Plasma::QueryMatch::QueryMatch ( AbstractRunner runner = nullptr)
explicit

Constructs a PossibleMatch associated with a given RunnerContext and runner.

Parameters
runnerthe runner this match belongs to

◆ QueryMatch() [2/2]

Plasma::QueryMatch::QueryMatch ( const QueryMatch other)

Copy constructor.

Member Function Documentation

◆ actions()

QList< QAction * > Plasma::QueryMatch::actions ( ) const

List of actions set for this match.

Returns
actions
Since
5.75

◆ addAction()

void Plasma::QueryMatch::addAction ( QAction *  actions)

Adds an action to this match.

Since
5.75
See also
setActions

◆ data()

QVariant Plasma::QueryMatch::data ( ) const
Returns
the data associated with this match; usually runner-specific

◆ icon()

QIcon Plasma::QueryMatch::icon ( ) const
Returns
the icon for this match

◆ iconName()

QString Plasma::QueryMatch::iconName ( ) const
Returns
the name of the icon for this match
Since
5.24

◆ id()

QString Plasma::QueryMatch::id ( ) const
Returns
a string that can be used as an ID for this match, even between different queries. It is based in part on the source of the match (the AbstractRunner) and distinguishing information provided by the runner, ensuring global uniqueness as well as consistency between query matches.

◆ isEnabled()

bool Plasma::QueryMatch::isEnabled ( ) const
Returns
true if the match is enabled and therefore runnable, otherwise false

◆ isMultiLine()

bool Plasma::QueryMatch::isMultiLine ( ) const

If the text should be displayed as a multiLine string If no explicit value is set set using setMultiline it will default to false.

Returns
bool
Since
5.82

◆ isValid()

bool Plasma::QueryMatch::isValid ( ) const
Returns
true if the match is valid and can therefore be run, an invalid match does not have an associated AbstractRunner

◆ matchCategory()

QString Plasma::QueryMatch::matchCategory ( ) const

Extra information about the match which can be used to categorize the type.

By default this returns the internal name of the runner which returned this result

◆ relevance()

qreal Plasma::QueryMatch::relevance ( ) const

The relevance of this action to the search.

By default, the relevance is 1.

Returns
a number between 0 and 1

◆ run()

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

Requests this match to activae using the given context.

Parameters
contextthe context to use in conjunction with this run
See also
AbstractRunner::run

◆ runner()

AbstractRunner * Plasma::QueryMatch::runner ( ) const
Returns
the runner associated with this action

◆ selectedAction()

QAction * Plasma::QueryMatch::selectedAction ( ) const

The current action.

◆ setActions()

void Plasma::QueryMatch::setActions ( const QList< QAction * > &  actions)

Set the actions for this match.

This method allows you to set the actions inside of the AbstractRunner::match() method and the default implementation of AbstractRunner::actionsForMatch() will return these.

Since
5.75

◆ setData()

void Plasma::QueryMatch::setData ( const QVariant &  data)

Sets data to be used internally by the associated AbstractRunner.

When set, it is also used to form part of the id() for this match. If that is inappropriate as an id, the runner may generate its own id and set that with setId(const QString&) directly after calling setData

◆ setEnabled()

void Plasma::QueryMatch::setEnabled ( bool  enable)

Sets whether or not this match can be activited.

Parameters
enabletrue if the match is enabled and therefore runnable

◆ setIcon()

void Plasma::QueryMatch::setIcon ( const QIcon &  icon)

Sets the icon associated with this match.

Prefer using setIconName.

Parameters
iconthe icon to show along with the match

◆ setIconName()

void Plasma::QueryMatch::setIconName ( const QString &  iconName)

Sets the icon name associated with this match.

Parameters
iconthe name of the icon to show along with the match
Since
5.24

◆ setId()

void Plasma::QueryMatch::setId ( const QString &  id)

Sets the id for this match; useful if the id does not match data().toString().

The id must be unique to all matches from this runner, and should remain constant for the same query for best results.

Parameters
idthe new identifying string to use to refer to this entry

◆ setMatchCategory()

void Plasma::QueryMatch::setMatchCategory ( const QString &  category)

Sets information about the type of the match which can be used to categorize the match.

This string should be translated as it can be displayed in an UI

◆ setMultiLine()

void Plasma::QueryMatch::setMultiLine ( bool  multiLine)

Set if the text should be displayed as a multiLine string.

Parameters
multiLine
Since
5.82

◆ setRelevance()

void Plasma::QueryMatch::setRelevance ( qreal  relevance)

Sets the relevance of this action for the search it was created for.

Parameters
relevancea number between 0 and 1.

◆ setSelectedAction()

void Plasma::QueryMatch::setSelectedAction ( QAction *  action)

Sets the selected action.

◆ setSubtext()

void Plasma::QueryMatch::setSubtext ( const QString &  text)

Sets the descriptive text for this match; can be longer than the main title text.

Parameters
textthe text to use as the description

◆ setText()

void Plasma::QueryMatch::setText ( const QString &  text)

Sets the main title text for this match; should be short enough to fit nicely on one line in a user interface.

Parameters
textthe text to use as the title

◆ setType()

void Plasma::QueryMatch::setType ( Type  type)

Sets the type of match this action represents.

◆ setUrls()

void Plasma::QueryMatch::setUrls ( const QList< QUrl > &  urls)

Sets the urls, if any, associated with this match.

◆ subtext()

QString Plasma::QueryMatch::subtext ( ) const
Returns
the descriptive text for this match

◆ text()

QString Plasma::QueryMatch::text ( ) const
Returns
the title text for this match

◆ type()

Type Plasma::QueryMatch::type ( ) const

The type of action this is.

Defaults to PossibleMatch.

◆ urls()

QList< QUrl > Plasma::QueryMatch::urls ( ) const
Returns
the mimtype for this match, or QString() is none