Plasma
Plasma::AbstractRunner Class Reference
An abstract base class for Plasma Runner plugins. More...
#include <Plasma/AbstractRunner>

Public Types | |
typedef QList< AbstractRunner * > | List |
enum | Priority { LowestPriority = 0, LowPriority, NormalPriority, HighPriority, HighestPriority } |
enum | Speed { SlowSpeed, NormalSpeed } |
Public Member Functions | |
virtual void | createRunOptions (QWidget *widget) |
QString | description () const |
bool | hasRunOptions () |
QString | id () const |
RunnerContext::Types | ignoredTypes () const |
virtual void | match (Plasma::RunnerContext &context) |
QString | name () const |
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 |
virtual | ~AbstractRunner () |
Static Public Member Functions | |
static QMutex * | bigLock () |
Protected Slots | |
void | init () |
Protected Member Functions | |
AbstractRunner (QObject *parent, const QVariantList &args) | |
AbstractRunner (QObject *parent=0, const QString &serviceId=QString()) | |
QAction * | action (const QString &id) const |
QHash< QString, QAction * > | actions () const |
virtual QList< QAction * > | actionsForMatch (const Plasma::QueryMatch &match) |
void | addAction (const QString &id, QAction *action) |
QAction * | addAction (const QString &id, const QIcon &icon, const QString &text) |
void | clearActions () |
KConfigGroup | config () const |
void | removeAction (const QString &id) |
KService::List | serviceQuery (const QString &serviceType, const QString &constraint=QString()) const |
void | setHasRunOptions (bool hasRunOptions) |
void | setPriority (Priority newPriority) |
void | setSpeed (Speed newSpeed) |
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.
Definition at line 56 of file abstractrunner.h.
Member Typedef Documentation
typedef QList<AbstractRunner*> Plasma::AbstractRunner::List |
Member Enumeration Documentation
Constructor & Destructor Documentation
Plasma::AbstractRunner::~AbstractRunner | ( | ) | [virtual] |
Definition at line 115 of file abstractrunner.cpp.
Plasma::AbstractRunner::AbstractRunner | ( | QObject * | parent = 0 , |
|
const QString & | serviceId = QString() | |||
) | [explicit, protected] |
Constructs a Runner object.
Since AbstractRunner has pure virtuals, this constructor can not be called directly. Rather a subclass must be created
Definition at line 103 of file abstractrunner.cpp.
Plasma::AbstractRunner::AbstractRunner | ( | QObject * | parent, | |
const QVariantList & | args | |||
) | [protected] |
Definition at line 109 of file abstractrunner.cpp.
Member Function Documentation
QList< QAction * > Plasma::AbstractRunner::actionsForMatch | ( | const Plasma::QueryMatch & | match | ) | [protected, virtual] |
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 169 of file abstractrunner.cpp.
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 183 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 176 of file abstractrunner.cpp.
QMutex * Plasma::AbstractRunner::bigLock | ( | ) | [static] |
Access to a shared lock that all runners (and code that manages/interacts with them) can share to protect access to non-thread-safe shared code or data.
Access of KSycoca records, for instance, is one place this lock should be used.
Common usage:
{ QMutexLocker lock(bigLock()); .. do something that isn't thread safe .. }
Definition at line 261 of file abstractrunner.cpp.
void Plasma::AbstractRunner::clearActions | ( | ) | [protected] |
Clears the action registry.
The action pool deletes the actions.
Definition at line 204 of file abstractrunner.cpp.
KConfigGroup Plasma::AbstractRunner::config | ( | ) | const [protected] |
Provides access to the runner's configuration object.
Definition at line 120 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 220 of file abstractrunner.cpp.
QString Plasma::AbstractRunner::description | ( | ) | const |
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 fillMatches is called, the runner should return true.
Definition at line 210 of file abstractrunner.cpp.
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.
- Returns:
- OR'ed value of black listed types
Definition at line 245 of file abstractrunner.cpp.
void Plasma::AbstractRunner::init | ( | ) | [protected, slot] |
Definition at line 309 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. Asyncroneous 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.
Definition at line 273 of file abstractrunner.cpp.
QString Plasma::AbstractRunner::name | ( | ) | const |
Returns the user visible engine name for the Runner.
Definition at line 280 of file abstractrunner.cpp.
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.
- Returns:
- the Package object, or 0 if none
Definition at line 304 of file abstractrunner.cpp.
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.
Definition at line 135 of file abstractrunner.cpp.
AbstractRunner::Priority Plasma::AbstractRunner::priority | ( | ) | const |
void Plasma::AbstractRunner::reloadConfiguration | ( | ) | [virtual] |
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 188 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 266 of file abstractrunner.cpp.
KService::List Plasma::AbstractRunner::serviceQuery | ( | const QString & | serviceType, | |
const QString & | constraint = QString() | |||
) | const [protected] |
A blocking method to do queries of installed Services which can provide a measure of safety for runners running their own threads.
This should be used instead of calling KServiceTypeTrader::query(..) directly.
- serviceType a service type like "Plasma/Applet" or "KFilePlugin"
- constraint a constraint to limit the choices returned.
- See also:
- KServiceTypeTrader::query(const QString&, const QString&)
- Returns:
- a list of services that satisfy the query.
Definition at line 255 of file abstractrunner.cpp.
void Plasma::AbstractRunner::setHasRunOptions | ( | bool | hasRunOptions | ) | [protected] |
Sets whether or not the runner has options for matches.
Definition at line 215 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 250 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 240 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 DBUS should call this within their constructors.
Definition at line 230 of file abstractrunner.cpp.
AbstractRunner::Speed Plasma::AbstractRunner::speed | ( | ) | const |
The nominal speed of the runner.
- See also:
- setSpeed
Definition at line 225 of file abstractrunner.cpp.
The documentation for this class was generated from the following files: